-
Ground in the repo with rg, git status --short, and targeted file reads.
-
Discover the WPILib JDK and any required sim-mode override:
ls ~/wpilib
rg -n "RobotMode|robotMode|SIM|simulation|JAVA_HOME|wpilib" <repo>
-
Run normal tests before or after risky changes:
JAVA_HOME=<wpilib-jdk> ./gradlew test
-
Run normal sim when a human/live tool will drive the robot:
JAVA_HOME=<wpilib-jdk> ./gradlew simulateJava
-
Run headless sim when an agent needs to automate checks without opening GUI windows:
JAVA_HOME=<wpilib-jdk> \
./gradlew --init-script .agents/skills/wpilib-sim/references/headless-sim.gradle simulateJava
-
In headless automated runs, the robot still needs DriverStation/joystick state. The bundled scripts write NT state under /SimAgent/..., which is a SimAgentBridge-style contract. This repo's robot code does not currently consume those topics, so automated runs require an agent-side bridge before relying on the scripts. For manual simulation, run ./gradlew simulateJava directly and control DriverStation state through the Sim GUI DriverStation tab.
-
Verify outputs from existing logged topics, preferably IO-layer applied voltage, velocity, position, current, and command/reference topics. Avoid custom test-only outputs unless the user asked for a harness.
-
For log inspection, use $wpilog-decode. Compatibility wrappers remain in this skill for older command paths.
-
Run a full auto through the real NT Auto Chooser (bridge-gated; see "Agent Sim Control"):
python3 .agents/skills/wpilib-sim/scripts/run_auto_sim.py \
--repo . \
--auto <auto-name> \
--alliance <alliance-station> \
--duration <auto-duration> \
--buffer 1
The script launches headless simulateJava, waits for the real chooser options, writes the selected auto over NT, enables autonomous, disables/exits cleanly, and prints latestLog=<path>.
-
Write live teleop/joystick state to a running sim:
python3 .agents/skills/wpilib-sim/scripts/sim_nt_control.py \
--repo . \
--alliance <alliance-station> \
--enabled \
--port 0 \
--axes "0,0,0,1" \
--buttons "false,false,false,false"
Use --exit to request clean shutdown.
-
Run a bounded headless teleop simulation with a fixed Xbox joystick state and a clean WPILOG:
python3 .agents/skills/wpilib-sim/scripts/run_teleop_sim.py \
--repo . \
--alliance Blue1 \
--duration 5 \
--port 0 \
--axes "0,-1,0,0,0,0"
-
For visualization-specific work, use $advantagescope when that skill is available. This skill remains responsible for running WPILib sim, choosing robot/log topics, and producing WPILOG/NT data summaries.
-
Prefer vanilla AdvantageScope for manual inspection and a fork only when its opt-in agent hooks are available.
-
Detect the fork by checking for documented agent flags or a known fork checkout/build before relying on automation. If only vanilla AdvantageScope is installed, open logs/layouts manually and provide WPILOG summaries instead of promising robust screenshots or recordings.
-
Keep robot-specific choices outside AdvantageScope:
- topic names
- preferred layouts
- auto names
- artifact paths
- comparison/assertion logic
-
The fork's intended flags are:
AdvantageScope --agent-control
AdvantageScope --agent-export --log <log.wpilog> --layout <layout.json> --out <output-dir> --start <seconds> --end <seconds> --fps 30
-
Agent control must be local-only, opt-in, and token-protected. Prefer commands like status, openLog, applyLayout, setTime, capture, export, and close; do not drive the UI by clicking screen coordinates.
-
For video previews, prefer the fork's realtime canvas recording path. Frame-by-frame PNG export is only a debugging fallback because it is much slower than the auto duration.
-
Always pair visual artifacts with a data summary from the WPILOG, such as robot mode/type, selected auto, enabled interval, pose movement, final pose, and notable state transitions.
-
For auto-review videos, do not start at timestamp 0 unless that is the actual auto start. Derive the start from logged DriverStation state, usually the first timestamp where both /DriverStation/Autonomous and /DriverStation/Enabled are true, then export the requested game/task auto duration from that point.
-
$wpilog-decode owns WPILOG listing, value summaries, struct decoding, latest-log lookup, and boolean-window lookup. Prefer:
python3 .agents/skills/wpilog-decode/scripts/read_wpilog_values.py \
--repo . \
--log <log.wpilog> \
--topic <topic>
-
Backward-compatible wrappers remain in this skill:
scripts/find_latest_simlog.py <repo-or-log-dir>scripts/list_wpilog_topics.py --repo <repo> [--log <path-or-log-dir>] [--filter <text>]scripts/read_wpilog_values.py --repo <repo> --topic <topic> [--topic <topic> ...] [--log <path-or-log-dir>]scripts/find_wpilog_window.py --repo <repo> --log <path> --all-true <boolean-topic> [--all-true <boolean-topic> ...] [--duration <seconds>]
-
scripts/run_auto_sim.py --repo <repo> --auto <chooser-option> --alliance <station> [--duration <seconds>] [--buffer 1] runs headless sim, selects the auto through the NT Auto Chooser, enables autonomous through /SimAgent topics (bridge-gated), exits cleanly, and prints the latest log path.
-
scripts/run_teleop_sim.py --repo <repo> --alliance <station> --duration <seconds> --axes <comma-separated-axes> [--port 0] runs headless sim, sets a simulated Xbox joystick through /SimAgent topics (bridge-gated), enables teleop for the duration, exits cleanly, and prints the latest log path. For Xbox full forward left stick, use --axes "0,-1,0,0,0,0".
-
scripts/run_teleop_sim.py also supports timed joystick sequences with --sequence "duration:axes;duration:axes". For a rectangle with Xbox joystick 0:
python3 .agents/skills/wpilib-sim/scripts/run_teleop_sim.py \
--repo . \
--alliance Blue1 \
--port 0 \
--sequence "1.2:0,-1,0,0,0,0;1.0:-1,0,0,0,0,0;1.2:0,1,0,0,0,0;1.0:1,0,0,0,0,0;0.5:0,0,0,0,0,0"
-
Timed sequences also support per-segment joystick ports, buttons, and POVs with duration:port:axes:buttons:povs. Port state persists until changed, which is useful for setting a secondary sim control port while driving with port 0. Example fuel intake/shoot sequence:
python3 .agents/skills/wpilib-sim/scripts/run_teleop_sim.py \
--repo . \
--alliance Blue1 \
--port 0 \
--sequence "1.5:0:0,0,0,0,0,0:false,false,false,false,false,false,false,false,false,false:-1;2.0:0:0,-1,0,0,0,0:false,false,false,false,false,false,false,false,false,false:-1;3.0:0:0,0,0,1,0,0:false,false,false,false,false,false,false,false,false,false:-1"
The decode scripts may create temporary Java helpers using the OS temp directory and compile them directly with the discovered WPILib JDK plus local WPILib jars. They do not edit robot source.
