diff --git a/.agents/skills/change-strategy/SKILL.md b/.agents/skills/change-strategy/SKILL.md index 0aabe31d..a3848c27 100644 --- a/.agents/skills/change-strategy/SKILL.md +++ b/.agents/skills/change-strategy/SKILL.md @@ -12,8 +12,8 @@ to forget. ## 1. Branch -`strategy/` 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/` 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 diff --git a/.agents/skills/debug-incident/SKILL.md b/.agents/skills/debug-incident/SKILL.md index 786d38c5..ec73a590 100644 --- a/.agents/skills/debug-incident/SKILL.md +++ b/.agents/skills/debug-incident/SKILL.md @@ -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/.py ...`. Never conclude from a picture alone. diff --git a/.gitignore b/.gitignore index 8a0b0514..05ec5635 100644 --- a/.gitignore +++ b/.gitignore @@ -224,6 +224,7 @@ outputs/ wandb/ mappo_*/ *.gif +!tutorials/img/**/*.gif # macOS .DS_Store diff --git a/AGENTS.md b/AGENTS.md index 78a20085..dc1f6f98 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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` | | @@ -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/ @@ -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. diff --git a/README.md b/README.md index fc49c6f8..5aa856e5 100644 --- a/README.md +++ b/README.md @@ -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) | diff --git a/docs/README.md b/docs/README.md index 3caea196..2a5d8cc6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/motion_planning.md b/docs/motion_planning.md index af03df3d..376ab5d8 100644 --- a/docs/motion_planning.md +++ b/docs/motion_planning.md @@ -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 diff --git a/docs/real_robots.md b/docs/real_robots.md index 96146400..ef7f4ded 100644 --- a/docs/real_robots.md +++ b/docs/real_robots.md @@ -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=`): 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/