Development¶
Tatbot is a collection of independently buildable components. You can work on the web app, replay tools or the mock arm without access to robot hardware.
Prerequisites¶
Git
Python 3.12 and
uvA C++ toolchain and CMake for teleoperation work
Rust and Cargo for the vision service
Node.js 22 or newer for Inkmap
Clone the repository, then choose the component you need. There is no required root-level install.
Component builds¶
Component |
Directory |
Check |
|---|---|---|
Teleoperation |
|
|
Vision service |
|
|
LeRobot environment |
|
|
Body-surface readers |
|
|
Inkmap |
|
|
E-stop firmware |
|
see the component README |
Working on a development machine¶
Every session works in its own worktree on its own pushed branch, and lands with one command; see Work. In short:
tatbot work start --task fix-the-thing # ~/tatbot-work/<session>, branch agent/<node>/<session>
# ... edit, commit as usual; every commit is pushed to the agent branch ...
tatbot work land # rebase, land gate (lint, disclosure, export), push to main
The shared checkout is a mirror that refuses commits. tatbot work status
shows what is unlanded on this node; tatbot work park "why" leaves work
unlanded on purpose. tatbot work init sets a machine up once.
Repository checks¶
Run the same checks used by the project before opening a change:
scripts/check
The bare command is the fast tier and finishes in minutes: lint, the
complexity and disclosure ratchets, the CLI and configuration contracts, the
docs build, and the light test profile without slow-marked tests. Pytest jobs
use every core by default, except the fast and light scripts tests, which use
four workers; PYTEST_WORKERS=N picks a count and 0 forces one.
Each process defaults OMP_NUM_THREADS, OPENBLAS_NUM_THREADS and
MKL_NUM_THREADS to one inner thread, preserving explicit settings. This
avoids multiplying pytest concurrency by a separate numerical worker pool.
scripts/check --full runs every job this node can; scripts/check rust (one
workspace build, every crate’s tests once) is the one to run by name for a
change in that root, and a project’s own job pack (below) names its jobs in
scripts/check --list. A job whose inputs are
unchanged since its last PASS on this machine reports PASS (cached ...);
TATBOT_CHECK_NO_CACHE=1 reruns it.
A project under python/ can add jobs without editing scripts/check: a
check-jobs.sh beside its pyproject.toml is sourced before options are read,
appends to ALL_JOBS (and FAST_JOBS or JOB_HEAVY if it chooses), sets a
JOB_DESC entry and defines job_<name> for each job. Such a project’s
tests/ is left out of the scripts tests’ cache key, since its own jobs run
them; the rest of it stays in, because the CLI those tests exercise can read
it. TATBOT_SIM_PASS_DIR gives its PASS markers a directory of their own.
Light scripts tests (the fast tier and scripts/check --light tests) default
OpenBLAS, OpenMP and MKL to one thread per native pool, since pytest workers
already run in parallel. The defaults apply before Python starts, including
collection and test subprocesses. Explicit OPENBLAS_NUM_THREADS,
OMP_NUM_THREADS and MKL_NUM_THREADS values take precedence. Full offline
tests and direct pytest invocations use the caller’s native thread settings.
The command reports unavailable optional toolchains as SKIP; a FAIL is an
actionable defect. For docs-only work, run scripts/check docs as well.
A passing test whose call phase exceeds the per-test budget (60 s of wall time, set by
TATBOT_TEST_BUDGET_S) fails its job. Mark it @pytest.mark.slow – the fast
tier then skips it and --full still runs it – or make it cheaper.
Expensive shared fixture setup also belongs in the slow tier: mark every test
that consumes it. Named scripts/check tests and CI include the slow tests.
Workflow boundaries¶
Use the public docs for reproducible, hardware-independent work. Deployment
configuration, private topology, experiment evidence, and powered acceptance
remain in the private internal/ tree and are not prerequisites for a public
contribution.
Test profiles and coverage¶
scripts/check --light tests installs scripts/tests/requirements-light.txt
for core offline tests. scripts/check tests installs the full offline profile
from scripts/tests/requirements.txt, including vision, dataset and
training dependencies. A named profile fails if a required dependency is absent.
scripts/check tests-integration runs the LeRobot-dependent scripts test
modules and validates the patch catalog against copies of the installed sources
in the locked plugin environment. It is a heavy job and is omitted by
--light. CI reports offline and integration coverage separately; a fast result
does not imply either job ran. The plugin’s own suite remains scripts/check plugin.
Omitted collection coverage is printed even with quiet pytest output and appears
as separate SKIP entries in the check summary. A passed test job with omitted
coverage is not a complete acceptance run. Tool geometry and wrist-tag generation
also report separately when NumPy is unavailable.
LeRobot patch ownership¶
The ordered compatibility catalog lives in scripts/lib/lerobot_patches.py.
scripts/il_patch_lerobot.py remains the launcher entry point after environment
sync; scripts/lib/lerobot_patch_engine.py owns application and verification.
It plans all available targets in memory, resolves historical overlapping patches,
rejects ambiguous sites and invalid Python, and only then replaces installed
files without modifying uv’s shared cache. Missing targets are recorded; broken
imports inside an installed target fail validation.
A successful CLI application writes
<venv>/share/tatbot/lerobot-patches.json, containing the catalog hash, upstream
version, final module hashes, and omitted targets. Compare this manifest alongside
the locked dependency revision when diagnosing differences between environments.
The manifest is local source verification, not hardware qualification or a
replacement for behavior tests. Apply patches before starting consumers; replacing
multiple module files is not atomic for an already running process.
Rust production profiles¶
scripts/check rust is one workspace build: locked Clippy (warnings are
errors) and every crate’s tests once, with every feature whose native
dependency this node has. A feature whose dependency is absent is left out and
named as a SKIP: realsense2 (through pkg-config) for the RealSense
cameras, the pinned vendor SDK for the arm adapter. A compilation or test failure remains FAIL.
Tests use offline fixtures; no capture command is launched.
Under scripts/check --full, or when TATBOT_RUST_PROFILES selects a
comma-separated subset, visiond is also built on its own for each profile in
rust/check-profiles.json (cargo build --release --bins with only that
profile’s features), so another workspace member cannot silently enable a
feature a deployment lacks. Profile builds are compile checks; nothing is
re-tested. The profiles cover core, viewer and RealSense capture, including
the Zenoh-enabled deployment variants, and deployment inventory tests
fail when a service or the visualizer launcher introduces a feature combination
absent from the matrix.
A profile whose native dependency is missing is a named SKIP, unless
TATBOT_RUST_REQUIRED_PROFILES names it: then it fails, as does a missing Rust
toolchain. Unknown names and required profiles excluded from the selection fail
validation. For example, on a capture build host with the RealSense SDK:
TATBOT_RUST_PROFILES=vision-wrist,vision-wrist-bus \
TATBOT_RUST_REQUIRED_PROFILES=vision-wrist,vision-wrist-bus scripts/check rust
Passing these checks establishes build and offline-test coverage, not camera or robot qualification.
Development CI requires the core and both viewer profiles on x86_64, and both wrist profiles on a native aarch64 worker with the RealSense SDK. A job covers only its declared profiles; the general build cannot stand in for native wrist coverage. Changed snapshots receive affected checks and a daily full sweep refreshes all required profiles.
Cargo defaults native C compilation to GNU C17 through .cargo/config.toml.
The pinned AprilTag sources use pre-C23 function declarations; this keeps newer
GCC defaults from breaking their bundled build. An explicit CFLAGS overrides
the default.