Metadata-Version: 2.4
Name: os3-robot
Version: 0.1.7
Summary: os3-robot: a robot's identity with the OS3 platform: enroll its credential, report its heartbeat, connect to its endpoint.
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: websockets<18,>=16
Requires-Dist: msgpack<2,>=1.2

# os3-robot

`os3-robot`, a robot's identity with the OS3 platform: it stores the robot's credential, keeps
the robot reporting to the platform and connects it to the endpoint it is deployed to. Install it on the robot (Python 3.10 or
later; websockets and msgpack only):

```bash
sudo apt install -y python3-venv   # Debian/Ubuntu: venv (python3.10-venv on 22.04)
sudo python3 -m venv /opt/os3-robot
sudo /opt/os3-robot/bin/pip install https://api.os3robotics.com/downloads/os3_robot-0.1.7-py3-none-any.whl
sudo ln -sf /opt/os3-robot/bin/os3-robot /usr/local/bin/os3-robot
curl -fsSL https://tailscale.com/install.sh | sh   # Tailscale, left logged out (below)
```

To upgrade, run the `pip install` line again (each change has a new version), then
`sudo os3-robot install-service`, which restarts the heartbeat service on the new code.

- `sudo os3-robot enroll --platform https://api.os3robotics.com --robot <robot id>` asks for the
  credential Add robot (POST /robots) showed once and keeps it, with the platform URL and robot
  id, in `/etc/os3/robot-credential` (root only, `0600`; `OS3_ROBOT_CREDENTIAL_FILE` names another
  file). The credential never goes on a command line. It then checks in once
  (`POST /robots/heartbeat`), so the platform sees the robot and its page shows Enrolled; if the
  platform refuses, the credential stays stored and the command says why and exits 1.
- `sudo os3-robot install-service`, once after enroll, keeps the robot reporting every 30 s so it
  shows as connected (the platform calls a robot online for 90 s after its last heartbeat). It
  installs the systemd service `os3-robot-heartbeat`
  (`/etc/systemd/system/os3-robot-heartbeat.service`), enables it and starts it: from boot, with
  no login, it runs `os3-robot heartbeat`, which sends `POST /robots/heartbeat` every 30 s with
  the enrolled credential (read again for each beat, so a new enrollment needs no restart) and no
  endpoint, so it works before any model is deployed. A beat a lost network or a platform error
  loses is logged and the next one follows on time; systemd restarts the service if it stops.
  A check-in only marks the robot seen: the endpoint, latency and voice health a robot agent
  reported stay. The platform takes a robot credential for 60 days from its issue, so the service
  rotates it (`POST /robots/rotate`): a credential enroll stored right after the first beat the
  platform takes (when it was issued is not known on the robot: Add robot may have shown it weeks
  before), then every 30 days from the rotation that got it. It saves the new one as enroll does
  (a new `0600` file, fsynced, renamed over the old, under a lock enroll takes too), unless the
  robot was enrolled again while the rotation was on the way: that enrollment stays. The old one
  stays valid until the next rotation, so a rotation that fails is tried again after the next
  beat, and the beats go on.
  `systemctl status os3-robot-heartbeat` and `journalctl -u os3-robot-heartbeat` show it.
  Without an enrollment it refuses and says to run enroll first.
- `sudo os3-robot connect <endpoint id>` sends that credential and the robot's handshake,
  `/etc/os3/robot-handshake.json` (`OS3_ROBOT_HANDSHAKE_FILE`): the `handshake` object the portal's
  Deploy > Connect a robot shows under Technical details, to the platform's `POST /connect`. It
  then opens the policy server the answer names, checks its certificate against the answer's pin
  before it sends the answer's token, and checks that the server serves the model the answer
  names. It prints the connection, or why the platform or the server refused it.
- OS3 serves robot endpoints over its private network (Tailscale; the grant's URL is then
  `wss://os3-ep-<id>.<network>:8000`). Install Tailscale on the robot and leave it logged out.
  After each beat the heartbeat service, and `connect` before it asks for a grant, joins a
  logged-out robot (`tailscale status`: NeedsLogin, or NoState before its first login). It asks
  `POST /robots/tailnet` for a one-use key, then runs `tailscale up --reset` with that key (read
  from a `0600` file, never on the command line), the robot's tag and its node name
  `os3-robot-<robot id>`. The robot then reaches its own organization's endpoints and nothing
  else on that network. A robot whose Tailscale already runs, on OS3's network or on one of its
  own, is left as it is (Tailscale runs one login at a time). So is a robot whose platform has no
  such network (`404 tailnet_off`): its endpoints are reached directly. An owner's revoke,
  delete or credential reset of the robot takes it off the network, and the service joins
  again once the robot is enrolled again.

The API serves this wheel at `/downloads/`, built from its own commit
(`infra/controlplane/Dockerfile`); it is not on PyPI. A robot OS3 installed already has the same
command, robotcontrol's, at `/opt/os3/agent/bin/os3-robot`, and its agent (`os3-agent.service`)
sends the heartbeat: it does not need `install-service`.

## Reporting physical hardware

For a standalone heartbeat service, set `OS3_ROBOT_SPECS_COMMAND` in
`/etc/os3/robot-heartbeat.env` to a command that prints a `RobotSpecs` JSON object:

```ini
OS3_ROBOT_SPECS_COMMAND="/path/to/lerobot/bin/python /opt/os3-robot/lib/python3.10/site-packages/os3_robot/openarm_specs.py --rig /path/to/robot/config/profiles/rigs/os3.yaml"
```

Use the actual Python and installed package paths on the robot, then rerun
`sudo os3-robot install-service`. The optional environment file is loaded by systemd.
The command runs on each heartbeat with a 10-second limit, without a shell; a discovery
failure sends a presence-only heartbeat and leaves the previously reported specs in place.
The client fills `agent_version` with its own version. The provider receives no robot credential.

The included `openarm_specs.py` runs in the existing robot environment with its LeRobot fork,
PyYAML and Orbbec SDK. It counts the physical motors from the rig and LeRobot configuration
(including the two head motors), independently of a policy's action width. It enumerates attached
Orbbec devices and matches serials to logical camera names, reporting their configured RGB
resolution and FPS. Missing cameras are omitted. It does not open a CAN bus, change torque,
start a camera stream, or substitute the SDK's default camera profile for the rig's profile.
Robot firmware stays unset; a camera's firmware version is not the robot's firmware version.

A heartbeat with specs sets the specs alone: the endpoint, latency and voice health a robot agent
reported stay.
Reported hardware does not change the registered policy identity or its 16-value action contract.
