Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agents/skills/change-strategy/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ to forget.

## 1. Branch

`strategy/<idea>` from `main`. In a git worktree run `tools/dev/setup_worktree.sh`, and symlink
`replays` from the main checkout so the match results store is shared.
`strategy/<idea>` from `main`. In a git worktree run `tools/dev/setup_worktree.sh` first (its own
pixi environment, `replays` shared with the main checkout); then `pixi run` works there as anywhere.

## 2. Change one thing

Expand Down
1 change: 1 addition & 0 deletions .agents/skills/debug-incident/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ Pick the tool by the question. `tools/debug/match_timeline.py`, `tools/debug/res
| Where did the referee override send everyone at this restart? Legal? | `tools/debug/restart_picture.py REPLAY --t S` (`--all-restarts`, `--side enemy`) |
| What did the planner decide on this tick? | `tools/debug/plan_snapshot.py REPLAY --t S --robot ID --target X Y` (`--side enemy`) |
| How did the plan evolve over a few seconds? | `tools/debug/plan_trace.py REPLAY --t0 S --t1 S --robot ID [--target X Y]` |
| A replay of one fresh match (to trace, or to watch on the dashboard) | `pixi run python -m tools.evaluation.match A B --duration 120` (prints the replay's path) |
| Run a fresh short match with my own traces | `tools/debug/debug_match.py --strategy A --opponent B --duration 60 --stop-on-goal`, with `ctx.match_log.trace(...)` calls added in the tactic |

All run as `pixi run python tools/<tool>.py ...`. Never conclude from a picture alone.
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,7 @@ outputs/
wandb/
mappo_*/
*.gif
!tutorials/img/**/*.gif

# macOS
.DS_Store
14 changes: 9 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ exists yet: say so in your change rather than guessing.
| Strategy / tactics | `utama_core/engine/`, `strategy/`, `tactics/`, `skills/` | `docs/strategy.md` | Engine changes are rare: a new primitive, not a new strategy |
| Strategy evaluation | `tools/evaluation/`, `utama_core/replay/`, `utama_core/analysis/` | `docs/strategy.md`, `docs/signals.md` | Change evaluation and strategy in separate commits, so results stay comparable |
| Referee | `utama_core/referee/` | `docs/referee.md` | |
| Motion planning | `utama_core/motion_planning/`, `tools/motion_planning_benchmark.py` | `docs/motion_planning.md` | |
| Motion planning | `utama_core/motion_planning/`, `tools/motion_planning_benchmark.py` | `tutorials/first_planner.md`, `docs/motion_planning.md` | |
| Simulation | `utama_core/simulator/`, `vendor/rSim/` | `vendor/rSim/FORK_NOTES.md` | `vendor/rSim` is the C++ physics fork; `utama_core/simulator` is the Python env on top of it |
| Real robots (radio, vision, controllers) | `utama_core/team_controller/`, `utama_core/data_processing/` | `tutorials/field_day.md`, `docs/real_robots.md` | |

Expand Down Expand Up @@ -148,8 +148,9 @@ declarations) — check there before reintroducing one of them.
- **Always pass `--headless`** when running any simulator/integration test:
`pixi run pytest utama_core/tests/ --headless`. Much faster; there is no reason to run
with graphics in an agent loop.
- A git worktree for a parallel agent: run `tools/dev/setup_worktree.sh` inside it (links `.pixi`,
copies the compiled planner/simulator `.so` files; without them tests differ).
- A git worktree for a parallel agent: run `tools/dev/setup_worktree.sh` inside it (its own pixi
environment, about 2 min the first time: pixi can't share one across directories; `replays` linked
to the main checkout's; the compiled planner/simulator `.so` files copied, without which tests differ).
- `pixi run test` runs the default suite; `pixi run lint` runs the full pre-commit stack
(black, ruff, isort) — run both before considering a change done.
- `--level quick|full` (defined in the root `conftest.py`, not `utama_core/tests/
Expand Down Expand Up @@ -186,8 +187,11 @@ need most:

- `.agents/skills/` — step-by-step playbooks over those scripts (see "Skills" below).

- `tutorials/first_strategy.md` — the beginner tutorial (a toy strategy, then evaluation). Keep it short,
simple and runnable: `tests/strategy/test_first_strategy_doc.py` builds its code.
- `tutorials/` — the beginner path: `first_strategy.md` (a toy strategy, then evaluation),
`first_tactic.md` (two tactics, a partitioner, a memory, tests), `debug_a_moment.md` (the open
keeper bug, from replay to a failing test), `first_planner.md` (a planner scored on the
benchmark). Keep them short, simple and runnable:
`tests/strategy/test_tutorial_code.py` runs their code.
- `docs/strategy.md` — tactic-kernel model, referee handling, writing a
`Tactic`, observability tooling. Read before any strategy-layer change.
- `docs/strategy_design.md` — kernel/Tactic/Partitioner design rationale.
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,9 @@ real robots are optional ([external setup](docs/real_robots.md#external-tools-gr

| Task | Start here |
|---|---|
| Your first strategy | [tutorials/first_strategy.md](tutorials/first_strategy.md) |
| Your first strategy | [tutorials/first_strategy.md](tutorials/first_strategy.md), then [first_tactic.md](tutorials/first_tactic.md) |
| Why did a robot do that? | [tutorials/debug_a_moment.md](tutorials/debug_a_moment.md) |
| Write a motion planner | [tutorials/first_planner.md](tutorials/first_planner.md) |
| Writing or changing a strategy, tactic or skill | [docs/strategy.md](docs/strategy.md) |
| Seeing what the robots did, and why | `pixi run dashboard` (every strategy's maps and replays); `tools/debug/find_bugs.py RUN_DIR` for a run's worst problems |
| Judging whether a strategy is better | [docs/strategy.md](docs/strategy.md), [docs/signals.md](docs/signals.md) |
Expand Down
5 changes: 4 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,10 @@

How the code works and why: look things up here. To learn by doing, start with the step-by-step
pages in [tutorials/](../tutorials/): [first_strategy.md](../tutorials/first_strategy.md) (new members
start there) and [field_day.md](../tutorials/field_day.md) (a test day with real robots). Docs that
start there), [first_tactic.md](../tutorials/first_tactic.md) (its part 2),
[debug_a_moment.md](../tutorials/debug_a_moment.md) (from a wrong move in a replay to its cause and a
test), [first_planner.md](../tutorials/first_planner.md) (a motion planner, scored on the
benchmark) and [field_day.md](../tutorials/field_day.md) (a test day with real robots). Docs that
code comments cite but that were deleted are in git history.

- [strategy.md](strategy.md): the strategy layer and its evaluation: the tactic-kernel model, referee restarts, lessons from past bugs, the debugging tools.
Expand Down
3 changes: 2 additions & 1 deletion docs/motion_planning.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

`tools/motion_planning_benchmark.py` runs `fpp`, `dwa` and `trajsample` through the same
`StrategyRunner` + headless rsim path and writes raw JSON plus a Markdown table to
`benchmark_results/` (gitignored). It is a benchmark/regression report, not a replacement for unit tests of
`benchmark_results/` (gitignored). `--schemes` takes any name in `CONTROL_SCHEME_MAP`, so a new planner
is benchmarked as soon as it is registered ([first_planner.md](../tutorials/first_planner.md) writes one). It is a benchmark/regression report, not a replacement for unit tests of
algorithm internals (bang-bang endpoint invariants, FPP collision-kernel equivalence, ...).

```bash
Expand Down
121 changes: 119 additions & 2 deletions docs/real_robots.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,123 @@ What we have measured on our two robots (radio 0 and radio 1), from field logs o
field check kept halting. When a run halts on vision gaps, check how the laptop gets vision before
touching code.

## Field-day reference

The steps of a test day are the tutorial [field_day.md](../tutorials/field_day.md); this is what
lies behind them.

### Vision: ssl-vision or TagVision

Both send `SSL_WrapperPacket`s to 224.5.23.2:10006, so nothing in this repo changes with the
choice. TagVision (`First-Order-RoboCup-SSL/tagvision`) is ours: ring markers instead of colour
patterns, calibration from the taped field lines, phones as extra cameras; its `docs/setup-guide.md`
and `docs/compat.md` (what it sends, byte for byte) are the reference. A TagVision marker plays the
part of an ssl-vision lid: `find-robots` pairs radios with marker IDs the same way, and a robot
profile's tag offset is its marker's. As of 2026-11-13 no registered field session
(`tools/field/field_sessions.json`) used TagVision.

**ssl-vision cameras.**
- FLIR: install the **Spinnaker SDK** ("Spinnaker SDK, 64-bit" for your Ubuntu from
[FLIR](https://www.flir.com/products/spinnaker-sdk)), its listed libraries, then
`sudo sh install_spinnaker.sh`: yes to the udev entry (add your user to `flirimaging`) and to
USB-FS 1000 MB. Exposure and gain are in its Spinnaker node and change live.
- USB webcam: cam idx is the `/dev/video` number of its image; the second node is metadata.
Use **MJPEG** (the RER camera: uncompressed YUYV 5 fps at 1280x960, MJPEG 60-90 fps). Lock white
balance after auto settles (`v4l2-ctl -d /dev/video0 --set-ctrl=white_balance_automatic=0` and
`white_balance_temperature=<what it picked>`): drifting colours break the colour calibration.
Exposure under about 10 ms (`exposure_time_absolute=100`) so the ball is not smeared.
- The **Lab Field** preset: 3 m x 2.25 m, goal 0.8 m, defense area 1 m x 0.5 m, two cameras. The
Division B button sets the camera count to 1: don't use it with two cameras.
- `./bin/graphicalClient` on the vision laptop shows what ssl-vision sends, before any network.
- **Checking a calibration:** `tools/field/vision_check.py --guided ball`, then `--guided "blue 2"`
(a robot facing +x), asks for the ball or robot on 9 points and prints each camera's error
(`replays/field/*_vision_truth_*.json`). Errors growing to the edges: distortion or focal
length; the same shift everywhere: the camera's position; more at one end: its tilt or height.
Ball right but robot not: the robot height.

**Networks.** With two networks on the robot laptop (Wi-Fi for internet, Ethernet to the switch),
our receiver listens on the one Windows uses for internet: use one. If WSL USB support is
missing (`tee: .../usbfs_memory_mb: No such file`), it loads only once a device is attached;
`/etc/modprobe.d/usbfs.conf` with `options usbcore usbfs_memory_mb=1000` sets it then.

### The radio and which robot is which

One radio drives every robot of either colour, addressed by radio ID only, so radio IDs must
differ across all robots on it. The radio port is `PORT` in `utama_core/config/settings.py`
(`/dev/ttyACM0`). `debug-robots`: Shift is fast (0.5 m/s, else 0.1), C chips.

A robot is its radio: the board stays with its motors, kicker and dribbler, and its profile goes
by it. The lid (or TagVision marker) is a separate shell and can be swapped. `pixi run
find-robots` (radios 0-7; `--radios 0 1 4`) turns each answering radio about 70° and back, and
the pattern that turned with it is its lid. The pairing is saved per machine
(`replays/field/robots_found.json`). Examples pick robots by radio (`RADIO_0`, `RADIO_1` in
`tools/field/shooting_drill.py`); on start they watch vision for 0.5 s and use the saved lids, or
find the robots again (`find_robots.confirm`). Two robots in use that swapped lids with each other
can't be told apart: run `find-robots` after such a swap. `field-check` cannot see batteries:
the robots don't report them.

### Demos and the operator panel

`pixi run demos` starts the shooting drill behind one dashboard; the Live tab's Demo panel
switches demos (Halt, pick, Run: the demo closes with its log saved, the next starts and the page
reloads). A demo that fails to start shows why under the panel. Calibration and `planner_ab.py`
stay their own commands.
- **Settings** apply from the next Run: *first robot* (the attacker, shooter, robot A), *camera*
(the part of the field in view, `CAMERA_HALF`) and *rules*, as editing the examples' config
blocks would, for this process only.
- **Field check** runs `field-check` without leaving the page, then restarts the demo.
- **Teleop** (`examples/teleop.py`): pick the robot, tick "keys drive", Force Start; W/S A/D Q/E,
Shift faster, B kicks, F the dribbler. A robot stops when its keys are let go, on Halt, and
0.3 s after the page stops sending.
- The Robots panel shows each robot's share of commands answered over the last 2 s; under 80%
(red) the link is poor, often a flat battery.
- The panel itself: [referee.md, "Operator panel"](referee.md#operator-panel).

Each run records `replays/field/<time>_<mode>_<name>.log` (every vision packet, the radio both
ways, the referee and which code ran) and, when it closes, a `.npz` replay of the world the
strategy saw. The runner adds a note whenever a robot's tactic or step changes.

### Calibrating a robot

`pixi run calibrate` (`tools/field/calibrate_robot.py`; `--radio N`, `--ball-only` for the ball
part again, `--check` to compare profiles, `--mode rsim --yes` to rehearse and write nothing).
Without `--robot colour:id` and `--radio` it finds the robot with `find-robots`. Once vision sees
the robot, put it near the middle facing +x, with 0.8 m clear ahead, 0.6 m to its left and a ball
at rest in view. It drives and turns for about 65 s, then the ball part
(`tools/field/ball_trials.py`), where the robot fetches the ball itself:

- **Carry ladder:** 0.5 m forward, backward, left, right and half a turn each way, at rising
speeds (0.2-1 m/s, 0.5-4 rad/s), twice each (`--repeats`). A direction stops at the first speed
that loses the ball (15 cm off the robot, or the ball sensor off for 0.3 s).
- **Kicks:** 10 (`--kicks`) along the field, each charged: a kick more than 30 s after the last
one is preceded by an empty kick.

It asks only when the ball is out of view or within 25 cm of the edge. At the end it analyses the
log (loop delay, speed gain and acceleration per axis, vision noise at rest, kick speed; written
as `.calibration.json`) and writes `utama_core/config/robots/radio_<radio>.json`:

- `tag_forward_m`, `tag_left_m`: where the tag sits on the robot, from its turns on the spot.
- `kick_bend_deg_per_cm`, `kick_bias_deg`: how far kicks leave the heading per cm the ball sits
off-centre, and with it centred. A tag stuck on turned shows in the bias.
- `kick_speed`, `kick_spread_deg`: those kicks' median speed and their scatter.
- `carry_speed`, `carry_turn`: the slowest direction's fastest speed that always kept the ball;
`move()` holds this robot to them (`RobotParams.CARRY_*` otherwise).

What it could not measure stays as it was; broken hardware (`kicker`, `dribbler`, `ir`) is set
in the file by hand. Kick bend and bias apply on real robots only; rsim keeps its own kick.

**Is the new profile better?** `--check` alternates it with the committed one in 4 blocks
(`--blocks`), carrying at each profile's caps and kicking 5 times (`--kicks`) at the far end, and
prints how often each carry kept the ball and how far kicks missed (mean |miss| ± SE). Commit if
it is no worse; ten kicks a side only separate differences of a few degrees. Calibrate every robot
twice per session (early and late): their disagreement is how far to trust them. An older log:
`pixi run python tools/field/robot_calibration.py replays/field/<run>.log --tag yellow:0 0 -0.002`.

**Kicker charge in play.** On real robots a robot that hasn't kicked for 25 s fires an empty kick
when the ball is neither on it nor within 30 cm, never in a HALT (`kicker_charge.py`). 2026-10-28:
radio 0 kicked about 2.2 m/s 1 s or 30 s after its last kick; radio 1 recharges far slower (a
median 0.41 m/s within 15 s of its last kick, 1.29 after 15-30 s): for the electronics team.

## Field logs

Recorded on the physical pitch during real robot test days: vision frames, referee commands,
Expand Down Expand Up @@ -183,5 +300,5 @@ Then run your own strategy. The GameController's web UI is at http://localhost:8

### SSL Vision and the radio for real robots

The whole procedure (vision laptop, WSL networking and USB, radio, the checks before a robot
moves) is in [field_day.md](../tutorials/field_day.md).
The steps are the tutorial [field_day.md](../tutorials/field_day.md); the details are in
[Field-day reference](#field-day-reference) above.
5 changes: 4 additions & 1 deletion docs/strategy.md
Original file line number Diff line number Diff line change
Expand Up @@ -450,6 +450,8 @@ whoever runs it.

### Debugging a foul or failure

A worked example for beginners: [debug_a_moment.md](../tutorials/debug_a_moment.md).

A foul or failure seen in a match is a symptom: the cause may be the robot, the shared referee
override, the planner, the referee itself, or the check that flagged it. Of the first six found
this way (table below), two were the referee or the check, not the robot. The steps alone, as a
Expand Down Expand Up @@ -597,7 +599,8 @@ caught 82-97% of the time, beyond 4 cm under 30%.
- **The keeper ignores a slow ball rolling through its own box.** `skills/goalkeep.py` fetches a
ball in the box only below `_RETRIEVE_BALL_SPEED` (0.3 m/s); a ball rolling slower than a shot but
faster than that, wide of the goal, is watched until it goes out. Seen in the v2.6.0 replays,
`pendulum_vs_wolfpack` at 3:52 (wolfpack's keeper). Left open on purpose as a first task.
`pendulum_vs_wolfpack` at 3:54 (wolfpack's keeper). Left open on purpose: it is the worked example
in [debug_a_moment.md](../tutorials/debug_a_moment.md) and a first task.

## Reading a round

Expand Down
Loading
Loading