Skip to content

Commit 907123b

Browse files
committed
Share package metadata, contributor tooling and simulator defaults
1 parent 6258cd7 commit 907123b

20 files changed

Lines changed: 231 additions & 84 deletions

File tree

‎.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: 2 additions & 0 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
@@ -25,6 +26,7 @@ jobs:
2526
- run: uv lock --check --project examples/python
2627

2728
rust:
29+
if: github.repository == 'Hebbian-Robotics/rua'
2830
runs-on: ubuntu-24.04
2931
timeout-minutes: 60
3032
env:

‎.gitignore‎

Lines changed: 8 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,11 +30,16 @@ __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

‎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: 11 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 run rua-dev setup` 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

@@ -33,8 +32,10 @@ cargo test --workspace --all-features
3332
are required for its Rust checks. To verify a built wheel outside the checkout,
3433
use `uv run rua-dev package check /path/to/hebbian_rua.whl`.
3534

36-
Check documentation links with `lychee --offline -v .`; use `lychee -v .` to
37-
include external links. CI checks Python and Rust on Ubuntu 24.04.
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.
3839

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

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+
4751
## Code style
4852

4953
- Use descriptive function and variable names, even when they are verbose.
@@ -54,6 +58,9 @@ checks do not cover a physical camera or arm.
5458
- Comment on non-obvious decisions rather than restating the code.
5559
- Test observable outcomes and real business logic, not mocks or library internals.
5660
- 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.
5764

5865
Use the workspace's existing Clippy allowances and Python lint settings. The
5966
release uses `panic = "abort"`; default test builds retain unwinding. Configure

‎docs/getting-started.md‎

Lines changed: 1 addition & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -24,19 +24,5 @@ Use `from hebbian_rua import StationClient` in your Python program. See the
2424

2525
## From source
2626

27-
Contributors need Rust 1.92+, Python 3.12+ and uv. On Ubuntu, install
28-
`build-essential`, `pkg-config`, `libudev-dev` and `mold`, then:
29-
30-
```sh
31-
uv run rua-dev setup
32-
cargo build -p hebbian-station
33-
uv sync --project examples/python --locked
34-
uv run --project examples/python rua serve --profile ./robot.toml
35-
```
36-
37-
Source setup prepares the pinned SO-101 models in the ignored `robots/so101`
38-
directory and caches its release archive under `.cache/so101`. Do this once
39-
before building; later builds and runs need no asset download. The installed
40-
wheel already includes the models, license and attribution.
41-
27+
Follow [source installation](install-from-source.md), then return here.
4228
For cameras and the web preview, see [cameras](cameras.md).

‎docs/install-from-source.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Install from source
2+
3+
The published `hebbian-rua` wheel includes the SDK, native binaries and robot
4+
models. Source development additionally needs Rust, Python and uv. This workflow
5+
is exercised on Ubuntu 24.04 x86-64; macOS and Windows are not validated for RUA.
6+
7+
Install [uv](https://docs.astral.sh/uv/), the pinned Rust toolchain and, on Ubuntu,
8+
`build-essential`, `pkg-config`, `libudev-dev` and `mold`. From the checkout root:
9+
10+
```sh
11+
uv run rua-dev setup
12+
cargo build -p hebbian-station
13+
uv sync --project examples/python --locked
14+
```
15+
16+
Setup prepares the checksum-pinned SO-101 models in ignored `robots/so101` and
17+
caches their release archive under `.cache/so101`. Once prepared, model assets
18+
need no network access for builds or runs. Installed wheels need no setup step.
19+
20+
Run the station with your calibrated profile or simulator connected:
21+
22+
```sh
23+
uv run rua serve --profile ./robot.toml
24+
```
25+
26+
See [hardware setup](hardware.md), [simulator integration](simulators.md) and
27+
[cameras](cameras.md) for the RUA connection steps. `uv run rua-dev --help` lists
28+
checks and commands for the components included in your checkout.
29+
30+
## Optional viewer
31+
32+
If your checkout includes the TypeScript viewer, install Node.js and pnpm, then:
33+
34+
```sh
35+
pnpm install --frozen-lockfile
36+
pnpm build
37+
```
38+
39+
The station serves the resulting viewer assets from disk. Camera builds have
40+
additional [native prerequisites](cameras.md#rua-configuration); recording needs
41+
[FFmpeg](recording.md). Building the Rust server alone needs neither frontend
42+
nor media build tools.

‎examples/python/uv.lock‎

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

‎executor/src/profile/tests.rs‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,16 @@ fn an_external_profile_inherits_bundled_defaults_and_resolves_its_own_assets() {
1616
let path = directory.join("my-arm.toml");
1717
std::fs::write(
1818
&path,
19-
"extends = \"so101-sim\"\nname = \"my-arm\"\nurdf = \"custom.urdf\"\n[mujoco]\narm_model = \"custom.xml\"\n",
19+
r#"extends = "so101-sim"
20+
name = "my-arm"
21+
urdf = "custom.urdf"
22+
driver = "mujoco"
23+
[mujoco]
24+
arm_model = "custom.xml"
25+
start_pose_radians = [0.0, -1.0, 1.0, 0.5, 0.0]
26+
target_block_position_meters = [0.25, 0.0, 0.015]
27+
rated_actuator_force = 3.35
28+
"#,
2029
)
2130
.unwrap();
2231
let profile = load_robot_profile(&bundled_profiles(), path.to_str().unwrap()).unwrap();
@@ -40,13 +49,12 @@ fn a_profile_given_as_json_matches_its_toml() {
4049
assert!(parse_robot_profile_json("{\"name\": \"x\"}", &root).is_err());
4150
}
4251

43-
const BUNDLED_PROFILES: [&str; 8] = [
52+
const BUNDLED_PROFILES: [&str; 7] = [
4453
"so101",
4554
"so101-bimanual",
4655
"so101-manual",
4756
"so101-policy",
4857
"so101-sim",
49-
"so101-sim-2ms",
5058
"so101-bimanual-sim",
5159
"so101-sim-policy",
5260
];

0 commit comments

Comments
 (0)