Skip to content

Commit d7be32e

Browse files
committed
Improve camera viewing, developer tooling and packaged robot assets
Use the LiveKit room viewer for camera previews. Add development commands for setup, validation and contract generation, bundle pinned SO-101 assets, and simplify installation and integration guides.
1 parent 4284dfb commit d7be32e

111 files changed

Lines changed: 5289 additions & 5630 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env.example‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ LIVEKIT_URL=
66
LIVEKIT_API_KEY=
77
LIVEKIT_API_SECRET=
88
# HEBBIAN_PHONE_PAGE_URL=https://your-trusted-page.example/
9+
# HEBBIAN_STATION_URL=http://127.0.0.1:8792

‎.github/workflows/check.yml‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ permissions:
1111

1212
jobs:
1313
python:
14+
if: github.repository == 'Hebbian-Robotics/rua'
1415
runs-on: ubuntu-24.04
1516
steps:
1617
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
@@ -21,13 +22,11 @@ jobs:
2122
version: "0.13.6"
2223
python-version: "3.14"
2324
- run: uv sync --locked
24-
- run: uv run ruff check
25-
- run: uv run ruff format --check
26-
- run: uv run ty check
27-
- run: uv run pytest
25+
- run: uv run rua-dev validate --lane python
2826
- run: uv lock --check --project examples/python
2927

3028
rust:
29+
if: github.repository == 'Hebbian-Robotics/rua'
3130
runs-on: ubuntu-24.04
3231
timeout-minutes: 60
3332
env:
@@ -43,7 +42,14 @@ jobs:
4342
echo 'deb [signed-by=/usr/share/keyrings/llvm.gpg] https://apt.llvm.org/noble/ llvm-toolchain-noble-21 main' | sudo tee /etc/apt/sources.list.d/llvm.list
4443
sudo apt-get update
4544
sudo apt-get install -y pkg-config mold libudev-dev libglib2.0-dev clang-21 libclang-21-dev ffmpeg
45+
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
46+
with:
47+
version: "0.13.6"
48+
python-version: "3.14"
49+
- name: Prepare pinned robot assets
50+
run: uv run rua-dev setup
4651
- run: rustup show active-toolchain
4752
- run: cargo fmt --all -- --check
4853
- run: cargo clippy --locked --all-targets --all-features
4954
- run: cargo test --locked --workspace --all-features
55+
- run: uv run rua-dev contracts --check

‎.gitignore‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ __pycache__/
99
*.key
1010
.ruff_cache/
1111
.ty_cache/
12+
/diagnostics/
1213
/recordings/*
1314
!/recordings/Cargo.toml
1415
!/recordings/README.md
@@ -29,12 +30,20 @@ __pycache__/
2930

3031
# Credentials
3132
.gemini-key*
33+
/station/wheel-data/
34+
/livekit-cameras/wheel-data/
3235

33-
/runs/
36+
# Agent server run records
37+
/.agent-runs/
3438

39+
/runs/
40+
.claude/worktrees/
3541

36-
# Local metadata
42+
# Local export provenance, not part of the release source.
3743
/EXPORT.json
3844

3945
# Example application runs: camera frames and model moves
4046
/examples/applications/*/runs/
47+
48+
# Generated from the pinned SO-101 release during source setup.
49+
/robots/so101/

‎AGENTS.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,9 @@
1-
Read [CONTRIBUTING.md](./CONTRIBUTING.md).
1+
# Agent guide
2+
3+
- Follow [CONTRIBUTING.md](./CONTRIBUTING.md) for code style and validation. Use targeted checks first; avoid redundant environment syncs, builds and full test runs.
4+
- We also maintain the public [livekit-cameras](https://github.com/Hebbian-Robotics/livekit-cameras) repository. Make coordinated changes there when the camera integration needs them, and update this repository's pinned Git revision. Keep the public repository generic and free of private project details.
5+
- We also maintain [mcap-tools](https://github.com/Hebbian-Robotics/mcap-tools), which owns generic MCAP grouping and standard message encodings. Make coordinated changes there and update the pinned Git revision here; recording policy and robot-specific topics stay in this repository.
6+
- We also maintain [so101](https://github.com/Hebbian-Robotics/so101), which owns the SO-101 driver, calibration/setup tool and model helpers. Make changes there, validate its standalone packages, and update the pinned Rust/TypeScript revisions and Python wheel here. Keep per-arm data in the separate config repository.
7+
- For SO-101 hardware, use the [per-arm setup guide](./docs/hardware.md). Every arm needs its own serial port and LeRobot calibration. The station loads calibrated joint limits at startup; the bundled URDF supplies geometry. Check signs, offsets and gripper endpoints on that arm with torque off.
8+
- If an SO-101 tracks poorly, moves jerkily or runs hot, gather evidence before changing anything: the arm's command outcomes, the target and measured angle of each joint, load, temperature, supply voltage and mechanical clearance. Then compare the servos' actual PID registers with the profile (`expected_position_gains` only verifies them; it does not write them). Servos differ between arms, so tune per arm from measurements; do not copy another arm's gains or loosen safety limits to hide a problem.
9+
- A station or hardware-profile change takes effect only after `hebbian-robot-use-server serve` restarts (it is the control process). Support the arm and disable it before restarting; when the viewer is included, changes to it alone do not need a restart, since the station reads `dist/viewer` from disk.

‎CLAUDE.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,9 @@
1-
Read [AGENTS.md](./AGENTS.md).
1+
# Agent guide
2+
3+
- Follow [CONTRIBUTING.md](./CONTRIBUTING.md) for code style and validation. Use targeted checks first; avoid redundant environment syncs, builds and full test runs.
4+
- We also maintain the public [livekit-cameras](https://github.com/Hebbian-Robotics/livekit-cameras) repository. Make coordinated changes there when the camera integration needs them, and update this repository's pinned Git revision. Keep the public repository generic and free of private project details.
5+
- We also maintain [mcap-tools](https://github.com/Hebbian-Robotics/mcap-tools), which owns generic MCAP grouping and standard message encodings. Make coordinated changes there and update the pinned Git revision here; recording policy and robot-specific topics stay in this repository.
6+
- We also maintain [so101](https://github.com/Hebbian-Robotics/so101), which owns the SO-101 driver, calibration/setup tool and model helpers. Make changes there, validate its standalone packages, and update the pinned Rust/TypeScript revisions and Python wheel here. Keep per-arm data in the separate config repository.
7+
- For SO-101 hardware, use the [per-arm setup guide](./docs/hardware.md). Every arm needs its own serial port and LeRobot calibration. The station loads calibrated joint limits at startup; the bundled URDF supplies geometry. Check signs, offsets and gripper endpoints on that arm with torque off.
8+
- If an SO-101 tracks poorly, moves jerkily or runs hot, gather evidence before changing anything: the arm's command outcomes, the target and measured angle of each joint, load, temperature, supply voltage and mechanical clearance. Then compare the servos' actual PID registers with the profile (`expected_position_gains` only verifies them; it does not write them). Servos differ between arms, so tune per arm from measurements; do not copy another arm's gains or loosen safety limits to hide a problem.
9+
- A station or hardware-profile change takes effect only after `hebbian-robot-use-server serve` restarts (it is the control process). Support the arm and disable it before restarting; when the viewer is included, changes to it alone do not need a restart, since the station reads `dist/viewer` from disk.

‎CONTRIBUTING.md‎

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@
33
This is an early release of part of our robotics stack. Feedback and issue reports
44
are welcome.
55

6-
For development, follow [source setup](docs/getting-started.md#from-source), then
7-
run `uv sync --locked` from the checkout root. The pinned Rust toolchain includes
6+
For development, follow [source setup](docs/install-from-source.md). The pinned Rust toolchain includes
87
Clippy and rustfmt. Python checks run on 3.14; the package supports Python 3.12+.
98
Python dependencies keep a three-day minimum release age.
109

@@ -17,6 +16,10 @@ uv run ty check
1716
uv run pytest
1817
```
1918

19+
`uv run rua-dev validate --lane python` runs the Python checks and tests together.
20+
Use `uv run rua-dev contracts --check` to verify schemas and the Python SDK, or
21+
omit `--check` to regenerate them. Targets default to SDKs present in the checkout.
22+
2023
For Rust changes:
2124

2225
```sh
@@ -25,8 +28,14 @@ cargo clippy --all-targets --all-features
2528
cargo test --workspace --all-features
2629
```
2730

28-
Check documentation links with `lychee --offline -v .`; use `lychee -v .` to
29-
include external links. CI checks Python and Rust on Ubuntu 24.04.
31+
`uv run rua-dev validate` checks all included components. Native prerequisites
32+
are required for its Rust checks. To verify a built wheel outside the checkout,
33+
use `uv run rua-dev package check /path/to/hebbian_rua.whl`.
34+
35+
Check guide links with `lychee --offline -v README.md CONTRIBUTING.md docs`;
36+
use the same command without `--offline` for external links. Check export
37+
templates in an assembled checkout, where their relative links resolve. Automatic CI runs only in `Hebbian-Robotics/rua`;
38+
other checkouts use the same commands locally.
3039

3140
The media build needs the prerequisites in [camera setup](docs/cameras.md).
3241
Rust workspace tests also need [FFmpeg](docs/recording.md) on `PATH`.
@@ -36,6 +45,9 @@ For camera changes, verify a real USB or phone stream with LiveKit: browser
3645
video, SDK snapshots, simultaneous readers, reconnection and shutdown. Simulator
3746
checks do not cover a physical camera or arm.
3847

48+
Additional component commands appear in `uv run rua-dev --help` when included.
49+
Use targeted checks first. Simulation does not validate physical hardware.
50+
3951
## Code style
4052

4153
- Use descriptive function and variable names, even when they are verbose.
@@ -46,7 +58,18 @@ checks do not cover a physical camera or arm.
4658
- Comment on non-obvious decisions rather than restating the code.
4759
- Test observable outcomes and real business logic, not mocks or library internals.
4860
- Use uv for Python. Keep changes scoped and run targeted checks first.
61+
- Keep control and SDK boundaries reusable; examples do not restrict downstream workflows.
62+
- Enforce each limit once, clamp or degrade valid requests, and trip on physical evidence.
63+
Diagnose hardware from measurements; do not loosen limits to conceal a problem.
4964

5065
Use the workspace's existing Clippy allowances and Python lint settings. The
5166
release uses `panic = "abort"`; default test builds retain unwinding. Configure
5267
sccache in your own Cargo settings rather than requiring it for contributors.
68+
69+
## Documentation boundaries
70+
71+
Keep setup commands, configuration and behavior specific to RUA here. Link to
72+
[SO-101](https://github.com/Hebbian-Robotics/so101),
73+
[LiveKit Cameras](https://github.com/Hebbian-Robotics/livekit-cameras) and
74+
[MCAP Tools](https://github.com/Hebbian-Robotics/mcap-tools) for their workflows,
75+
APIs and internals. Keep a complete RUA quickstart; avoid copying their guides.

‎Cargo.lock‎

Lines changed: 31 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[workspace]
22
resolver = "3"
3-
members = ["contracts", "executor", "station", "station-access", "recordings", "livekit-cameras"]
4-
default-members = ["contracts", "executor", "station", "station-access", "recordings"]
3+
members = ["robot-geometry", "contracts", "executor", "station", "station-access", "recordings", "livekit-cameras"]
4+
default-members = ["robot-geometry", "contracts", "executor", "station", "station-access", "recordings"]
55
# livekit-cameras links libwebrtc (needs clang 21); build it with `-p livekit-cameras`.
66

77
[workspace.lints.clippy]

‎README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ parts of our stack that make that loop easy to build. More coming soon.
88

99
- Rust server
1010
- Python SDK and a small agent loop
11-
- [LiveKit camera preview](https://hebbian-robotics.github.io/livekit-cameras/)
11+
- [LiveKit camera preview](docs/cameras.md)
1212

1313
Start a project with [uv](https://docs.astral.sh/uv/):
1414

@@ -25,6 +25,7 @@ See [getting started](docs/getting-started.md) and the [Python examples](example
2525
and the [example applications](examples/applications/README.md) for example toy projects.
2626

2727
See [connecting a simulator](docs/simulators.md) to try in simulation.
28+
To watch your cameras, follow the [LiveKit web preview setup](docs/cameras.md#watch-a-usb-camera).
2829

2930
## Build an agent
3031

@@ -59,6 +60,12 @@ Use `AnthropicRobotTools` from `hebbian_rua.anthropic` or `GeminiRobotTools` fro
5960
`hebbian_rua.gemini` with the corresponding SDK. See the
6061
[Python examples](examples/python/README.md).
6162

63+
Hardware setup, camera tools and recording utilities have their own guides:
64+
[SO-101](https://github.com/Hebbian-Robotics/so101),
65+
[LiveKit Cameras](https://github.com/Hebbian-Robotics/livekit-cameras) and
66+
[MCAP Tools](https://github.com/Hebbian-Robotics/mcap-tools). RUA handles their
67+
integration with your robot and agent.
68+
6269
## Coming soon
6370

6471
- TypeScript and Rust SDKs

‎THIRD_PARTY_NOTICES.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,15 @@ RUA code is MIT licensed. Models and dependencies retain their own licenses.
55
The SO-101 robot models derive from
66
[TheRobotStudio/SO-ARM100](https://github.com/TheRobotStudio/SO-ARM100), commit
77
`a758567c3978dfeefe282ede0500085a48fe8f78`, under Apache-2.0.
8-
See [model attribution](robots/so101/README.md) and its included license files.
8+
See [model attribution](https://github.com/Hebbian-Robotics/so101/blob/main/setup/src/so101_setup/assets/robot/so101/README.md) and its included license files.
99

1010
Camera components use the separately maintained
1111
[livekit-cameras](https://github.com/Hebbian-Robotics/livekit-cameras) and
1212
[mcap-tools](https://github.com/Hebbian-Robotics/mcap-tools) repositories.
1313
Recording-schema license texts are in [licenses/recording-schema](licenses/recording-schema/).
1414
Additional Rust dependency license sources are in [licenses/rust](licenses/rust/README.md).
1515
The dependency manifests and lockfiles identify the source dependencies and versions.
16+
17+
RUA distributions include the model license and attribution beside the bundled
18+
assets in `robots/so101`. Source checkouts prepare them from the checksum-pinned
19+
release in `robots/so101-assets.toml`.

0 commit comments

Comments
 (0)