Metadata-Version: 2.4
Name: physicalai-openarm-plugin
Version: 0.1.0
Summary: Native SocketCAN/Damiao OpenArm robot plugin for PhysicalAI
Project-URL: Homepage, https://github.com/MarkRedeman/physicalai-plugins
Project-URL: Repository, https://github.com/MarkRedeman/physicalai-plugins
Project-URL: Issues, https://github.com/MarkRedeman/physicalai-plugins/issues
License-Expression: Apache-2.0
Requires-Python: >=3.12
Requires-Dist: motorbridge-smart-servo>=0.0.4
Requires-Dist: motorbridge>=0.4.4
Requires-Dist: numpy>=1.24
Requires-Dist: physicalai-studio-plugin>=0.2.0
Requires-Dist: physicalai>=0.1.1
Requires-Dist: pydantic>=2.0
Requires-Dist: python-can<5,>=4.2
Provides-Extra: tests
Requires-Dist: pytest; extra == 'tests'
Description-Content-Type: text/markdown

# PhysicalAI OpenArm Plugin

Direct [SocketCAN](https://docs.kernel.org/networking/can.html)/Damiao control for
[OpenArm](https://github.com/enactic/openarm) followers and hand-guided leaders
in [PhysicalAI](https://github.com/openvinotoolkit/physicalai). The plugin also
registers single-arm and bimanual OpenArm entries in Physical AI Studio.

## Safety and support

OpenArm moves powerful physical hardware. Secure each arm, provide clearance,
keep an emergency stop accessible, and follow OpenArm's official safety guide.
Only Linux SocketCAN is supported. Exactly one process may control a CAN
interface at a time: do not concurrently run this plugin with LeRobot, ROS 2,
or other CAN clients on the same bus.

This first release assumes hardware setup has already been completed. It does
not set motor IDs, write persistent parameters, calibrate, or zero encoders.
Before connecting, configure the documented motor IDs, provision CAN/CAN-FD,
and complete OpenArm's homing and closed-gripper initialization procedure.

## Installation

```bash
uv add physicalai-openarm-plugin
```

The package requires `python-can` and Linux SocketCAN. OpenArm's default
configuration uses CAN-FD at 1 Mbps arbitration and 5 Mbps data rate.

## CAN adapters

`can_adapter: socketcan` is the default and supported route. Use a Linux
SocketCAN channel such as `can0`; a USB-CAN adapter is supported when the host
exposes it as a SocketCAN interface. This includes adapters configured through
`slcand`, which usually appear as `slcan0` rather than `/dev/ttyUSB0`.

An experimental `can_adapter: damiao` proof of concept uses `motorbridge` to
open a Damiao USB-CAN serial adapter directly. Set `port` to its device path
and optionally set `dm_serial_baud` (default `921600`):

```yaml
port: /dev/ttyACM0
can_adapter: damiao
dm_serial_baud: 921600
```

This serial path has not been tested with OpenArm's eight-motor topology or
CAN-FD timing. Do not use it for unattended motion, and retain SocketCAN as the
recommended path until an adapter-specific hardware acceptance test succeeds.

## Runtime contract

Positions are **degrees**, in this fixed order:

```text
joint_1, joint_2, joint_3, joint_4, joint_5, joint_6, joint_7, gripper
```

Followers require `side: left` or `side: right`; the plugin applies the
side-specific conservative limits used by LeRobot's OpenArm support. Leaders
are read-only and default to torque-disabled manual control. Native bilateral
force feedback is not implemented.

## Run

Update the `can0` and `can1` placeholders, then run unilateral teleoperation:

```bash
uv run physicalai run --config packages/physicalai-openarm-plugin/examples/runtime/teleop.yaml
```

For two leaders and two followers on independent CAN interfaces:

```bash
uv run physicalai run --config packages/physicalai-openarm-plugin/examples/runtime/bimanual-teleop.yaml
```

To read and print a leader's joint positions without sending CAN position targets:

```bash
uv run physicalai run --config packages/physicalai-openarm-plugin/examples/runtime/read-joints.yaml
```

## Studio assets

The plugin includes lightweight parallel-link gripper URDF visualization models
for Studio. They are plugin-authored kinematic visualizations, not redistributed
OpenArm CAD or mesh assets. OpenArm software is Apache-2.0; hardware design data
has separate CERN-OHL-S-2.0 licensing.

## Development

```bash
uv sync
uv run pytest packages/physicalai-openarm-plugin/tests/
```
