Metadata-Version: 2.4
Name: asimov-protocol
Version: 1.3.0rc4
Summary: Asimov robot protocol buffers (Python, generated — do not hand-edit)
Author: Menlo Research
License-Expression: MIT
Project-URL: Homepage, https://github.com/menloresearch/asimov-protocol
Project-URL: Repository, https://github.com/menloresearch/asimov-protocol
Project-URL: Issues, https://github.com/menloresearch/asimov-protocol/issues
Project-URL: Changelog, https://github.com/menloresearch/asimov-protocol/releases
Keywords: asimov,robotics,protobuf,menlo
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: protobuf>=5.29.3
Dynamic: license-file

<p align="center">
  <a href="https://menlo.ai"><img src="https://docs.menlo.ai/menlo-logo.svg" alt="Menlo" width="160"></a>
</p>

# asimov-protocol

The wire contract of the Asimov robot, as generated Python protobuf bindings: the
`RobotCommand` a controller sends, the `RobotState` the robot reports, and the messages
around them. Every Menlo component that talks to the robot imports this package, so one
process holds one set of descriptors.

```bash
pip install asimov-protocol
```

```python
from asimov_protocol.v1 import asimov_command_pb2, asimov_common_pb2, asimov_state_pb2

cmd = asimov_command_pb2.RobotCommand()
cmd.mode = asimov_common_pb2.CONTROL_MODE_MOVE
payload = cmd.SerializeToString()

state = asimov_state_pb2.RobotState()
state.ParseFromString(payload_from_the_robot)
```

Use generated symbolic IDs when producing alerts. Look up display text without
copying or rewriting the protobuf alert received from Firmware:

```python
from typing import cast

from asimov_protocol import AlertId, get_alert_definition

assert AlertId.BMS_LOW_SOC == 27

alert = robot_state.active_alerts[0]
print(alert.severity, get_alert_definition(cast(AlertId, alert.id)))
```

Decode the firmware's critical-only sticky safety-fault word separately:

```python
from asimov_protocol import get_error_report

report = get_error_report(robot_state.error_flags)
for fault in report.faults:
    print(fault.alert_id, fault.description)
```

`SafetyFault.alert_id` is `None` only when an unexpected or future
`error_flags` bit has no critical alert mapping. Warning and info alerts are
reported through `active_alerts`, not through the sticky safety word.

Ships `.pyi` stubs + `py.typed` (mypy/pyright work out of the box). The
`protobuf` dependency floor tracks the generator version pinned in
`buf.gen.yaml` (repo root) — bump both together.

## Versioning

- **MAJOR** follows the wire directory: `1.x` is `asimov_protocol.v1`. A breaking wire
  change is a new `v2/` and a `2.0`, never an edit to `v1/`.
- **MINOR** is an additive schema change (a new field, message or enum value); **PATCH** is
  regenerated code or packaging with no schema change.
- Pin `asimov-protocol>=1.2,<2` and you get every compatible release of the wire you speak.

Pre-releases use PEP 440 spelling (`1.3.0rc1`) and install only with `pip install --pre`
or an explicit pin.

## Modules

| Module | What is in it |
|---|---|
| `asimov_common_pb2` | `ControlMode` and the other shared enums |
| `asimov_command_pb2` | `RobotCommand`: mode, policy velocity, joint setpoints |
| `asimov_state_pb2` | `RobotState`: mode, joints, IMU, alerts, battery, `protocol_version` |
| `asimov_diagnostics_pb2` | diagnostics frames |
| `edge_pb2` | the edge's controller-facing observation lane (`EdgeMessage`, `EdgeState`) |
| `edge_cloud_pb2`, `edge_eol_pb2` | edge to cloud, and end-of-line test |

## Source

Generated from the `.proto` files in
[menloresearch/asimov-protocol](https://github.com/menloresearch/asimov-protocol) by that
repository's toolchain; do not edit the installed modules. Higher-level Python clients:
[`menlo-sdk`](https://pypi.org/project/menlo-sdk/) drives the robot,
[`menlo-robot-sdk`](https://pypi.org/project/menlo-robot-sdk/) talks to the Robot Control Service.

MIT.
