Metadata-Version: 2.4
Name: forge-robot
Version: 1.0.1
Summary: Reusable robot driver protocols, base classes, and Dora node helpers for Forge.
Author: X-ERA
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Dist: dora-rs==0.4.1
Requires-Dist: forge-msgs>=1.0.0,<2
Requires-Python: >=3.12
Project-URL: Changelog, https://gitlab.ex-ai.cn/PhyAgentOS/framework/forge/-/blob/master/CHANGELOG.md
Project-URL: Issues, https://gitlab.ex-ai.cn/PhyAgentOS/framework/forge/-/issues
Project-URL: Repository, https://gitlab.ex-ai.cn/PhyAgentOS/framework/forge
Description-Content-Type: text/markdown

# forge_robot

Common robot driver protocol and node runner helpers for Forge robots.

- **RobotDriver**: `typing.Protocol` with `connect`, `disconnect`, `get_state`, and `set_command`.
- **LocomotionRobotDriver**: optional protocol for drivers that accept `forge_msgs.LocomotionCommand`.
- **BaseRobotDriver**: abstract base class with an optional `joint_order` property.
- **ActuatorSpec**: driver-facing joint/actuator metadata for limits and safety clipping.
- **device_tools**: shared JSON envelope helpers for device CLI commands.

Message payloads use `forge_msgs.JointState`, `forge_msgs.JointCommand`, and optional `forge_msgs.LocomotionCommand`.

The standard Dora node loop uses fixed input semantics:

- input `tick` to publish `state`
- input `action` or `action/<source>` as a sparse low-level `JointCommand`; drivers update only joints listed in `name` and retain targets for omitted joints. Namespaced inputs allow disjoint arm and gripper controller streams, while overlapping writers still require explicit arbitration
- input `master_state` as a leader `JointState` mirrored to a low-level position `JointCommand`
- input `locomotion_command` as a high-level `LocomotionCommand` when the driver implements `LocomotionRobotDriver`

Device tool JSON includes `ok`, `capability`, `supported`, and `message`. `list-devices` returns address objects shaped as `{ name, address, status }` with optional `role`.
