diff --git a/docs/README.md b/docs/README.md index 12b98934..100fdee1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,7 +12,8 @@ Every doc in this folder, by kind. New to the repo: the [README](../README.md) f - [motion_planning_results.md](motion_planning_results.md): its latest full run. - [tools.md](tools.md): every script and pixi task, by purpose. - [visual_guide.md](visual_guide.md): the game drawn on the pitch from real replays (how each strategy plays, one match over time, a restart, the motion planner), what each picture has shown us, and how to draw it. -- [setup_external.md](setup_external.md): grSim, the official GameController and AutoReferee, SSL Vision for real robots. +- [setup_external.md](setup_external.md): grSim, the official GameController and AutoReferee. +- [real_robot_setup.md](real_robot_setup.md): a test day with real robots: ssl-vision on its own laptop, WSL networking and USB, the radio, and the checks before a robot moves. - [contributing.md](contributing.md): editor setup, commits, pull requests and releases. ## Design rationale @@ -34,6 +35,7 @@ Every doc in this folder, by kind. New to the repo: the [README](../README.md) f - [roadmap.md](roadmap.md): larger open workstreams, and one-line pointers to finished ones. - [sim_realism.md](sim_realism.md): how far rsim is from real matches, the realism scorecard, and the plan to close the gap with measured, randomized physics. +- [in_house_vision.md](in_house_vision.md): our own vision stack for lab days (per-session tag calibration, tags on robots), the experiments that decide it, and the 2026-10-22 test day's vision findings. - [testing_gaps.md](testing_gaps.md): kinds of testing gap that let bugs through, numbered (code cites them by number). - [investigation_default_vs_lowblock_stalemate.md](investigation_default_vs_lowblock_stalemate.md): why `default` vs `low_block` stays 0-0; partly fixed. - [investigation_ball_contact_orientation_divergence.md](investigation_ball_contact_orientation_divergence.md): a robot pinned against the ball rotates away from contact; localized, not fixed. diff --git a/docs/custom_referee_gui.md b/docs/custom_referee_gui.md index ce944e73..48fd7a5a 100644 --- a/docs/custom_referee_gui.md +++ b/docs/custom_referee_gui.md @@ -33,6 +33,12 @@ With vision from a camera (real robots or grSim) the Live tab also shows the fie | ` ` (any other) | | seen inside `field_bounds` but not configured: our planners cannot see it, often a wrong ID | | Ball | | not seen, or outside `field_bounds` | +Before it gets that far, the runner keeps our robots inside `field_bounds` on camera runs +(`utama_core/run/field_fence.py`): each robot's speed towards an edge is capped to what it can +stop from before the line, whatever tactic sent the command, so a robot chasing a ball out of the +camera's area stops at the line. The planners' walls at `field_bounds` are only obstacles to plan +around, and did not stop it (0.5–0.9 m out in grSim before the fence). + Only the red and amber rows are listed; the green ones fold into an "N ok" line that opens on click. On real robots any red row forces `HALT`, whatever the command and whether or not the page is open; the red banner says why. Pressing Force Start while a row is red halts again at once, so @@ -41,6 +47,22 @@ with everything outside `field_bounds` dimmed, so a half-field test shows which expects. Space halts; nothing on the keyboard starts the robots. The Kickoff and Free Kick buttons are hidden when the profile has no rule that sets up a restart (goal detection only). +## Strategy panel + +A script can let the page change what each side plays, or restart it, without restarting the +run (`utama_core/dashboard/views/strategy.py`): + +```python +strategy_view.attach(server, runner, + choices={"my": {"lead": make_lead, "press": make_press}}, # name -> builds a fresh AbstractStrategy + running={"my": "lead"}) +``` + +The Live tab then lists the choices per side with a Run button; Run on the one running restarts +it. `StrategyRunner.replace_strategy` takes the new strategy at the next tick and only while +halted, so the page refuses otherwise. `examples/real_attacker_defender.py` offers its attacker +and defender tactics this way. + ## Commands and what robots do | Button | Command | Use | Robots | diff --git a/docs/in_house_vision.md b/docs/in_house_vision.md new file mode 100644 index 00000000..fbafccb8 --- /dev/null +++ b/docs/in_house_vision.md @@ -0,0 +1,306 @@ +# In-house vision: plan, experiments and findings + +Status: plan, 2026-10-24; on 2026-10-25 the team chose the full in-house stack (below, +"Plan now"). Nothing below is built unless it says so. Written after the 2026-10-22 test day, +where vision took most of the day. + +The goal is less time spent on vision each test day, and robot positions accurate to about +1 cm instead of 3–9 cm. This applies to **lab and test days only**: at competitions the league +runs ssl-vision with the standard colour patterns, and our stack only receives its packets. + +## What went wrong on 2026-10-22 + +The setup: two cameras, ssl-vision on its own Linux laptop sending 224.5.23.2:10006 at 61 fps +per camera, our stack in WSL on the robot laptop (`docs/real_robot_setup.md`). + +- **The cameras disagree.** The same robot was reported 13–20 cm apart by the two cameras + early on; after the distortion was retuned in ssl-vision, 5 cm, then 85 mm later in the day + (`replays/field/20261022_211142_real_score_goal.log`, constant 83–85 mm in every frame). + Something moved between those checks, and nothing tells us when. +- **Against known spots** (`vision_check.py --guided ball`, + `replays/field/20261022_212332_vision_truth_ball.json`): camera 0 saw 7 of 9 points, 33 mm + mean error, 61 mm worst; camera 1 saw 5 of 9, 55 mm mean, 92 mm worst. Neither saw the ball + at (1500, 0), right in front of the +x goal. +- **Camera height is unknown.** Nobody has a good measurement of it, and ssl-vision's + calibration leans on it. A wrong robot height shifts each camera's robots along its own line + of sight, in opposite directions for the two cameras. +- **Camera 1 never sent its calibration** in the geometry packet, so our camera weighting + (`CameraCombiner`, below) ran with equal weights all day. +- **Colour calibration is slow and noisy at the edges and corners.** Yellow detection + collapsed after a change to the robot tops (1.3 to 0.1 detections per packet), and one + yellow robot came out as IDs 1, 2 and 3 at the same spot. Camera 0 detected no ball at all + in one 2,010-packet run. +- **Stray orange objects became balls.** Camera 0 saw 1–4 fake balls in a line about 15 cm + outside the +y touchline, each at confidence 1.00. Our stack picked a fake 22% of the time + and switched between balls 107 times in 6 s: the flickering ball. +- **Focus and zoom can't be locked** on our cameras, so the lens changes whenever a camera is + packed up, and every calibration starts from zero. + +## What our stack already does about it + +Built during the test day; it hides the cameras' disagreement but cannot remove it. + +- `CameraCombiner` (`utama_core/data_processing/refiners/position.py`) weights each camera by + how steeply it sees a robot (cos⁴ of the view angle) once every camera's position is known, + and drops a detection more than `CAMERA_AGREEMENT` (0.1 m) from the best camera's. +- The ball is fused across cameras by the same rule, and each camera's ball is first moved by + that camera's own error at the robot nearest it (`BALL_ROBOT_SHIFT_RANGE`), so a ball at the + dribbler stays at the dribbler. When a camera loses the robot for a frame or two, it places + the robot from another camera plus the gap between them just before: the 2.4% of frames of + the log above that put the ball inside the robot are gone. +- `PositionRefiner` takes a ball inside the field or a goal over one outside them, then the one + nearest the last ball. Replayed, `20261022_213347_real_score_goal.log`'s ball jumps of over 0.3 m in one frame went + from 5,439 to 4. +- `tools/vision_check.py` prints where each camera puts each robot and ball and the gap + between them, and with `--guided` checks each camera against 9 known spots and saves the + result as a baseline. + +## Options considered + +| | Time per test day | Build cost | Risk | +|---|---|---|---| +| 1. ssl-vision, more tuning and better fusion | stays high | none | what we have now | +| 2. Our own stack, with tags (and patterns) | low | weeks | most work, but ours to fix | +| 3. Modify ssl-vision's own code | medium | high: a large C++/Qt codebase and a fork to maintain | avoid | + +Improving ssl-vision from the outside (our own calibration tool writing its settings) gets most +of what option 3 would, without a fork. So the real choice is 1 or 2, and two experiments +decide it (below). + +## Decision, under working assumptions + +The plan below assumes three things, each to be confirmed by an experiment: + +1. **The cameras can't be locked** (focus and zoom change between sessions). +2. **Proper calibration alone doesn't remove the position error** (experiment 1). +3. **Tags are better than colour patterns** for robots (experiment 2; early indications say so). + +Under those, **build our own stack, tag-only for robots, and recalibrate it automatically at +the start of every session**. Pattern mode is not rebuilt: when we want to practise with +patterns (as at competitions), we run ssl-vision. If an experiment contradicts an assumption, +revisit this section before building past the step it gates. + +What the assumptions imply: + +- Cameras that can't be locked: the lens changes each session, so calibration must run every + session, in about a minute, with nothing done by hand, and keep checking during the session. +- Calibration that doesn't fix the error: don't rely on a correct camera model. Fit the + image-to-field mapping each session from measurements, then correct what is left. +- Tags better than patterns: identify robots and their heading from tags, so robots need no + colour at all. The ball is the only thing left that needs colour. + +## Design + +``` +cameras -> capture -> [calibration each session] -> tag detector + ball detector -> SSL_WrapperPacket -> our stack (unchanged) +``` + +### 1. Calibration each session: one button + +- About 20 A4 tags (AprilTag 36h11) on the floor; 3 of them on measured spots (the centre and + two corners, lined up with the field lines) that fix the field's axes. The rest go anywhere: + the solver finds where they are. +- A few tags on boxes at robot-top height (about 14 cm). A flat floor alone cannot tell a longer + lens from a higher camera, which is today's camera-height problem; tags off the floor + separate the two, and they calibrate exactly the plane the robot positions come from. +- Tags are told apart by ID. A small config file gives each tag's height and names the + anchors, for example tags 0–19 on the floor (z = 0), tags 20–24 on boxes (z = 0.143 m, + box plus paper, measured once with a ruler), tags 0–2 on the anchor spots. Only the + height is given: the solver finds each loose tag's x, y and rotation. The box height and + the printed tag size are the only things measured by hand. +- Press calibrate: one fit of all the numbers at once (bundle adjustment). Unknowns: + - per camera, about 11: focal length, image centre, 1–2 distortion terms, position + (x, y, height) and tilt; + - per loose tag, 3: x, y and rotation on its plane. + + Measurements: each tag's 4 corners in each image, about 200 coordinates per camera for 25 + tags. The fit moves every number until each tag, projected from its place through its + camera, lands on the corners seen. Both cameras see shared tags, so they agree with each + other by construction. Put a box or two where the cameras overlap, so they are tied at + robot height too. +- Why raised tags fix the camera height: a raised tag is nearer the camera, so it appears + pushed outward, away from the spot under the camera. A tag at height h, a distance d out, + looks like a floor point at about d × H / (H − h). With the camera at H = 3 m, a 14 cm box + 1.5 m out appears about 73 mm further out; were the camera 10 cm higher, about 2.5 mm less. + Corners are found to about 1 mm, so the fit pins the height down. With the camera model + known, a pixel's line of sight gives the field position at any height: robots at the tag's + height (about 14 cm), the ball at its centre (about 2 cm). Tags at a single height, all at + robot height for example, would leave the ball's height poorly fixed. +- The fit prints each tag's error (where its corners land against where they were seen), so + a tag set up wrongly, at a height the config doesn't say, stands out straight away. +- Because the camera model alone isn't trusted (assumption 2), fit a smooth correction map from + the residual error at the tags: one for robot-top height, one for ball height (about 21 mm). +- It ends by running the guided check itself and prints the error per camera. +- Expected accuracy: the field is about 3 m in roughly 1,300 pixels, 2–3 mm per pixel; tag + corners are found to a fraction of a pixel and averaged over hundreds, so a few mm. + +### 2. Watching for camera movement during the session + +A few tags stay just outside the field lines all session. Every few seconds the tool +re-estimates each camera's position from them, corrects for a small move and raises an alarm +for a large one (a bumped or sagging mount). This answers "something moved between 52 mm and +85 mm" from the test day. + +### 3. Robots: tags + +- One tag per robot top; a config file maps tag ID to team and robot ID. +- `cv2.aruco` has AprilTag 36h11 built in; each detection gives position and heading from the + tag's 4 corners. +- When a moving robot's tag is found but can't be decoded, tracking keeps its ID. +- Short exposure: motion blur is the main weakness of tags. + +### 4. Ball: colour, but the easy kind + +- Only inside the field mask that calibration gives, plus a margin: that alone would have + removed the test day's fake balls. +- Flat-field correction from an empty-field frame (the median over a few seconds), so the ball + looks the same colour in the corners as in the centre. +- Orange by hue, not brightness; blobs on a robot tag are ignored. + +### 5. Output: standard SSL packets + +The same `SSL_WrapperPacket` on the same multicast address, so `CameraCombiner`, the refiners +and everything above stay unchanged. While both run, send on a second port so the two can be +compared side by side on the same scene with `vision_check`. + +### A session, start to finish + +1. Set up the cameras; the program sets fixed exposure (about 2 ms, so moving tags don't + blur), gain and white balance, and timestamps each frame at capture. +2. Lay out the tags, press calibrate (about a minute), check the error it prints, and pick + up the floor tags, leaving the few just outside the field lines for the movement watch. +3. Play: per frame, robots from tags and the ball from colour inside the field mask, sent as + SSL packets. Calibration also outputs the field mask and the empty-field picture for + flat-field correction. + +### Code + +A handful of Python modules on OpenCV and numpy, roughly 1,000–1,500 lines: +- `capture` (one backend per camera type); +- `calibrate` (the hardest part); +- `robots`; +- `ball`; +- `send`; +- a config holding camera settings, tag heights and anchors, and the tag-to-robot map. + +### Practical + +- Python and OpenCV; move to C++ only if measured latency forces it. Tag detection at 60 fps is + fine with decimation. +- Runs on the vision laptop. FLIR cameras through PySpin (Spinnaker's Python API), webcams + through OpenCV directly. +- Roughly 2–4 weeks part-time to step 4 of the order below. The calibration tool is the hardest + part and the most valuable. + +## Experiments + +Run on recorded frames where possible, so they need no test-day time beyond the recording. + +### Experiment 1: does proper calibration fix the position error? + +- Checkerboard on A4, about 20 stills per camera, tilted, all over the image; OpenCV computes + focal length and distortion. +- Tags or checkerboards on known spots for each camera's position and height; feed the result + into ssl-vision. +- Rerun `vision_check.py --guided ball` and compare with the 2026-10-22 baseline above. +- **Down to about 1 cm:** calibration was the main problem. Stay on ssl-vision with our + calibration tool (option 1), and assumption 2 is wrong. +- **Not down:** the error is elsewhere (colour, ssl-vision's simpler camera model), which + points to our own stack. + +### Experiment 2: are tags better than colour patterns? + +- An AprilTag (8–10 cm) taped on one robot; record both cameras while pushing it slowly across + the field, corners included. +- Offline, compare the tag detector with ssl-vision's pattern on the same frames: detection + rate, position and heading jitter, ID swaps, corners against the centre, moving against still. +- Whether tags are big enough in pixels depends on the camera resolution; this answers it. + +### Results + +None yet. Record each result here with its date, the recording it used and the numbers. + +## Plan now (team decision, 2026-10-25) + +The team chose the full in-house stack. The guided check by hand (`vision_check.py --guided`) +took too long to run every session, and we have one ball, which rolls off its spot. So +experiments 1 and 2 no longer decide anything: their questions become pass marks below. Every +step is measured on recordings, so most of the work happens off test days. + +### Before the next test day (no hardware) + +- **Facts to collect:** + - the camera models, resolution, frame rate and interface (USB/V4L2 or FLIR Spinnaker); + - whether we can SSH into the vision laptop and run Python there. + + Resolution decides whether robot tags are big enough. A robot top fits a tag of about + 100 mm; at 2–3 mm per pixel that is 35–50 pixels, 4–5 pixels per tag cell, which is + marginal. Exposure decides motion blur: 1 m/s for 10 ms is 1 cm, about 4 pixels, so + exposure must be about 2 ms. +- **Vision scorecard** (`tools/vision_bench.py`, to build): replays `replays/field/*.log` + through our vision layer and gives one table: + - robot and ball jitter at rest; + - dropped frames; + - camera disagreement where the cameras overlap; + - how far rolling balls stray from a straight line; + - the spread of the IR-on ball offset (ball in the mouth); + - ball jumps, balls off the field, balls inside a robot, ID swaps. + + Its first run is the ssl-vision baseline from 2026-10-22 that every step below must beat. + Our own stack sends the same `SSL_WrapperPacket`s, so the same scorecard judges it. +- **Calibration solver, offline:** `cv2.aruco` AprilTag 36h11 detection, then a least-squares + fit of each camera's lens, position and tilt and of every loose tag's position (design 1). + It is tested on synthetic images rendered from a known camera, so it is right before it + meets a real one. +- **Print** about 20 A4 tags, 3 with crosshairs for the anchor spots (centre and two + corners), plus a few robot-top tags and boxes about 14 cm high for raised tags. + +### Next test day (about 30 minutes of vision) + +1. **Recorder:** a small script on the vision laptop that saves frames from both cameras to + disk, with ssl-vision stopped, since a camera opens for one program at a time. Needs the + facts above. +2. **Record:** + - the tag layout, still: calibration; + - one robot with a top tag driving a scripted path over the whole field: tag + detection while moving, blur and corners; + - the ball rolled across the field: ball detection and straight-line checks; + - the empty field: flat-field correction. + +### Then, offline on those recordings, each with a pass mark + +3. **Calibration from the tag frames.** Pass: + - the anchors land within 3 mm of their spots; + - the two cameras agree within 1 cm on shared tags; + - raised tags fit as well as floor tags. + + This answers experiment 1 for our own model. +4. **Robot tag detector, sending SSL packets** on a second port, replayed from the robot + recording. Pass: beats the ssl-vision baseline on the scorecard for jitter, dropouts and + ID swaps, corners included. This is experiment 2's question. +5. **Ball detector**, inside the field mask, after flat-field correction. Pass: + - no false balls on the empty field; + - the ball tracked while a robot moves it; + - straight-line error under 1 cm. +6. **Live on a test day**, side by side with ssl-vision, then retire ssl-vision on lab days. + Calibration and the movement watch (design 2) then run every session. + +The IR offset correction (`docs/sim_realism.md`, the IR finding) sits above either stack and +is judged by the same scorecard. It waits until our own calibration shows how much offset is +left. + +## Risks + +- Tags blur on fast robots, and may be too few pixels at the far corners. Experiment 2's + recordings show both early; the fixes are a shorter exposure or bigger tags. +- A lens that changes during a session (focus hunting) breaks the calibration mid-run; the + movement watch (design 2) is meant to catch it. +- Lab-only: the team still needs ssl-vision and patterns working for competitions, so the + patterns on the robots stay usable alongside the tags. + +## Open questions + +- Camera models, lenses and resolutions of both cameras (the RER webcam is 1280x960 MJPEG). +- Whether the cameras' focus and zoom are software controls (`v4l2-ctl`) that a startup script + can set, even if they can't be locked physically. +- SSH access to the vision laptop, and which ssl-vision commit it runs. diff --git a/docs/real_robot_setup.md b/docs/real_robot_setup.md new file mode 100644 index 00000000..179d7d14 --- /dev/null +++ b/docs/real_robot_setup.md @@ -0,0 +1,148 @@ +# Real robots: setting up and checking vision and radio + +The procedure for a test day with real robots: ssl-vision on its own Linux laptop sending vision +over the network, and our stack on a Windows laptop in WSL with the radio dongle. Each part is +checked on its own before anything drives a robot: vision with `tools/vision_check.py`, the radio +with teleop, then both together in the field check of `examples/real_attacker_defender.py`. + +``` +vision laptop (Linux) robot laptop (Windows + WSL) + cameras -> ssl-vision --multicast--> tools/vision_check.py, then the runner + 224.5.23.2:10006 radio dongle (USB, passed into WSL) -> robots +``` + +## Once per machine + +### Vision laptop (Linux) + +1. Build [ssl-vision](https://github.com/RoboCup-SSL/ssl-vision) (its README). For a FLIR + camera install FLIR's **Spinnaker SDK** first: on the + [download page](https://www.flir.com/products/spinnaker-sdk) take "Spinnaker SDK, 64-bit" + for your Ubuntu (not ARM64 unless the laptop is ARM). Unpack it, install the libraries its + README lists, then `sudo sh install_spinnaker.sh`: yes to the udev entry (add your user to + `flirimaging`) and to USB-FS 1000 MB. Build ssl-vision with + `cmake -B build -DUSE_SPINNAKER=true -DUSE_V4L=true && make -C build`. +2. Add our field as a preset: `git apply tools/ssl-vision-lab-field.patch` in the ssl-vision + checkout (copy the file over), then rebuild. Field Configuration gets a **Lab Field** button + (3 m x 2.25 m, goal 0.8 m, defense area 1 m x 0.5 m, two cameras). Do not use the Division B + button with two cameras: it sets the camera count to 1. +3. USB webcams (the RER camera is one) need your user in `video`: + `sudo usermod -aG video $USER`, then log in again. + +### Robot laptop (Windows + WSL) + +1. **USB into WSL:** in admin PowerShell, `winget install --exact dorssel.usbipd-win`. The + `usbipd` you can run inside WSL is an unrelated Linux tool: always run it in PowerShell. +2. **Share the radio once, by its hardware ID** (stays the same whatever port it is in, unlike + the bus ID): `usbipd list`, note the radio's `VID:PID`, then + `usbipd bind --hardware-id `. +3. **WSL on the real network:** in `%USERPROFILE%\.wslconfig`, under `[wsl2]`, add + `networkingMode=mirrored`. Without it WSL sits on a private network that never sees the + vision laptop's multicast. +4. **Let vision in:** in admin PowerShell, open UDP 10006 to WSL in the Hyper-V firewall: + ``` + New-NetFirewallHyperVRule -Name SSLVision -DisplayName "SSL Vision multicast" -Direction Inbound -VMCreatorId '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -Protocol UDP -LocalPorts 10006 + ``` + (`40E0AC32-...` is WSL's fixed ID in that firewall.) Then `wsl --shutdown`. +5. **Radio permission in WSL:** `sudo usermod -aG dialout $USER`, then `newgrp dialout` in the + terminal you run from (or restart WSL). + +## Each test day + +### 1. Network + +Both laptops on the same network, by Ethernet to one switch or router if possible: many Wi-Fi +routers drop or throttle multicast. If the robot laptop has two networks (Wi-Fi for internet, +Ethernet to the switch), our receiver listens on the one Windows uses for internet: use one. + +### 2. Vision + +On the vision laptop: `./bin/vision -c 2` (the number of cameras) in the ssl-vision checkout. +For each camera under **Image Capture**: the capture module (**Spinnaker** for FLIR, **Video 4 +Linux** for a USB webcam), then **Capture Control → Start**. Settings save on a clean exit or +with **Save Settings**, not on a crash. + +- **USB webcam:** cam idx is the `/dev/video` number of its image; a camera shows up as two + nodes and the second is metadata ("Inappropriate ioctl" means the wrong one). Use **MJPEG**: + the RER camera's uncompressed YUYV is 5 fps at 1280x960, MJPEG 60-90 fps. Its controls: + `v4l2-ctl -d /dev/video0 --list-ctrls`. Let auto white balance settle + (`--set-ctrl=white_balance_automatic=1`), then lock it (`=0` and + `--set-ctrl=white_balance_temperature=`): colours that drift break the colour + calibration. Keep exposure under about 10 ms (`exposure_time_absolute=100`) so the ball is + not smeared. +- **FLIR:** exposure and gain are in its Spinnaker node and change live. +- Field Configuration: **Lab Field → Apply**, then each camera's calibration, then colours per + camera. +- `./bin/graphicalClient` on the vision laptop shows what ssl-vision sends, before any network. + +On the robot laptop, in WSL: + +``` +pixi run python tools/vision_check.py +``` + +Expect each camera at about its frame rate and the field at 3000 x 2250 mm. Nothing at all +means the network or the firewall (steps 3-4 above, step 1 here); one camera missing means its +capture is not running. + +After a calibration, check it against known spots: `tools/vision_check.py --guided ball`, then +`--guided "blue 2"` (any robot, facing +x). It asks for the ball or robot on the 9 points +(corners, edge midpoints, centre) and prints each camera's error there; the results land in +`replays/field/*_vision_truth_*.json` to compare with the next setup. The pattern points at the +cause: errors growing towards the edges are the distortion or focal length, the same shift +everywhere the camera's position, more at one end than the other its tilt or height. The ball +right but the robot not is the robot height in ssl-vision. + +### 3. Radio + +Plug the dongle in, then in admin PowerShell (leave it open: it re-attaches after a replug): + +``` +usbipd attach --wsl --hardware-id --auto-attach +``` + +In WSL `ls /dev/ttyACM*` shows it; the code uses `PORT` in `utama_core/config/settings.py` +(`/dev/ttyACM0`). Then drive each robot by hand: + +``` +pixi run debug-robots +``` + +Number keys choose the robot by its **radio (firmware) ID**, WASD moves, Q/E turns, Shift is +fast (0.5 m/s, else 0.1), Space dribbles, B/C kick/chip, Esc stops every robot and quits. Hold +the robot off the floor for the first presses and check each key moves it the way it says. +Note each robot's radio ID and the pattern on top (its vision ID): the runner needs both. + +One radio drives every robot, of either colour: robots are addressed by radio ID only, so the +radio IDs must differ across all robots on it. + +### 4. Both together + +Set the "Test-day configuration" block of `examples/real_attacker_defender.py`: `FIELD`, +`CAMERA_HALF` (`"full"` when the cameras cover the whole field), each robot's vision and radio +ID and working hardware. Then `pixi run python examples/real_attacker_defender.py`, open +http://localhost:8080 and go through the Live tab's field check +([custom_referee_gui.md](custom_referee_gui.md#field-check-camera-runs)): every row green or +amber, each robot under its own ID and colour, a ball in each corner inside the area in play, +and a robot pushed by hand across the cameras' overlap moving smoothly (a jump there means the +two calibrations disagree). Only then Force Start. + +Each run records `replays/field/