<h1 align="center">motorics</h1>

<p align="center">
  <strong>The actuator intelligence platform.</strong>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license MIT"></a>
  <a href="#"><img src="https://img.shields.io/badge/version-0.1.0-green.svg" alt="v0.1.0"></a>
</p>

Motorics is an open-core platform for building, distributing, and consuming executable actuator profiles. It helps actuator OEMs publish authoritative digital artifacts and robotics engineers integrate them into simulation, controls, firmware, telemetry, and service workflows — all from a single versioned source of truth.

```bash
pip install motorics
```

If you're looking for the hosted registry or enterprise features, see the
[Motorics Registry](https://motorics.ai) (coming soon).

---

**Documentation:**

- [docs.motorics.ai](https://docs.motorics.ai) -- Comprehensive documentation, including architecture and guides (coming soon).
- [Architecture](docs/ARCHITECTURE.md) -- System design, directory structure, and language strategy
- [CLI Reference](docs/CLI_REFERENCE.md) -- Full command documentation for publishers and consumers

**Guides:**

- [Publisher Guide](docs/PUBLISHER_GUIDE.md) -- For OEMs authoring and publishing actuator artifacts
- [Consumer Guide](docs/CONSUMER_GUIDE.md) -- For engineers discovering, installing, and using artifacts
- [Artifact Spec](docs/ARTIFACT_SPEC.md) -- The `.mra` format specification

---

## What is Motorics?

Actuator knowledge is trapped in static PDF datasheets. Robotics teams repeatedly
re-translate actuator specs into simulation models, control parameters, firmware
configs, and telemetry schemas. This causes slow integration, duplicated effort,
and inconsistent models across teams.

Motorics solves this by defining the **Motorics Runtime Artifact (`.mra`)** — a
single, versioned, machine-readable digital asset that replaces the static
datasheet. The `.mra` is not just data; it is an executable profile of the
actuator, usable at every stage of its lifecycle:

- **Simulation / Training** -- High-fidelity models built from canonical data
- **Controls Integration / Test** -- Automated checks derived from defined limits
- **Deployment / Telemetry** -- Field data structured by the artifact's schema
- **Service / Reliability** -- Fault taxonomies and performance data for maintenance

### What Motorics is

- A canonical **actuator specification format** (`actuator.yaml`) that replaces static datasheets with a machine-readable, versionable data contract.
- An open-core **CLI and toolchain** (`motorics`) for authoring, validating, packaging, exporting, and consuming actuator artifacts.
- A **trusted distribution layer** (Motorics Registry) for versioned, signed artifact delivery.
- A suite of **physics kernels** (electromagnetic, thermal, mechanical) for feasibility checking and simulation enrichment.
- **Export targets** for MuJoCo, Isaac Lab, Gazebo, FMU, firmware parameter bundles, and more.
- A **publisher-consumer workflow** that creates a clean loop: OEMs publish authoritative artifacts; engineers discover, install, and use them.

### What Motorics is not

- **Not a generic model zoo.** Every artifact is tied to a real actuator family with provenance and verification.
- **Not just a simulation exporter.** Export is one of many capabilities — the artifact serves the full lifecycle.
- **Not a replacement for your stack.** Motorics enriches the tools you already use — MuJoCo, ROS2, Isaac, firmware toolchains.
- **Not datasheet-as-a-service.** The artifact is executable and versionable, not a static file in a new wrapper.

Motorics is the **system of record and distribution layer** for executable actuator intelligence.

---

## Quick Start

### For Consumers (e.g. Simulation Engineers, Controls Engineers)

```bash
motorics search "frameless torque motor 48V" --verified
motorics install bosch-rexroth/ctrlx-actuator-a2@1.3.0
motorics plot bosch-rexroth/ctrlx-actuator-a2@1.3.0 --curve torque-speed
motorics check moog/msa-17@2.0.1 --trajectory elbow_cycle.csv --bus-voltage 48
motorics export moog/msa-17@2.0.1 --target mujoco --out ./sim/actuators/
```

### For Publishers (e.g. OEMs, Industry Experts)

```bash
motorics init actuator my-actuator-family
motorics ingest dyno_logs.csv --map schema.yaml
motorics validate my-actuator-family/
motorics pack my-actuator-family/ --out my-actuator-2.0.1.mra
motorics sign my-actuator-2.0.1.mra --publisher my-org
motorics publish my-actuator-2.0.1.mra --registry motorics-registry
```

---

## Building from Source

### Prerequisites

- Ubuntu 22.04+ (amd64)
- `sudo` access

### Install and Build

```bash
./build/install_packages.sh    # Install Bazel 8.3.1, Docker, Python deps
bazel build //...              # Build everything
```

### Verify Toolchains

```bash
bazel run //examples:hello_world_py      # Python
bazel run //examples:hello_world_cpp     # C++
bazel run //examples:hello_world_go      # Go
bazel run //examples:hello_world_rust    # Rust
```

### Motor Simulation & Catalog

```bash
bazel run //src/spec:catalog_demo        # See available motors
bazel run //src/math:example             # Run motor simulation
bazel test //src/math:motor_model_test   # Run tests
bazel test //src/spec:motor_catalog_test
```

For detailed usage:
- **Motor catalog** (specifications, factory pattern): See [`src/spec/README.md`](src/spec/README.md)
- **Motor simulation** (physics engine, control modes): See [`src/math/README.md`](src/math/README.md)

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards,
and the pull request process.

---

## License

MIT -- see [LICENSE](LICENSE) for details.
