AdvantageKit Logging and Simulation Separation
Separate hardware access from control logic so one robot program can run with real, simulated, or replayed inputs.
Motion, sensing, control loops, and plans made visible as a field of forces and trajectories.
Interactive model
Replay a moment in robot state
Move through a synthetic replay timestamp and watch input, output, and derived signals change.
Live HTML simulation · adjust the controls and watch the computed output respond.
Interactive
Log replay turns recorded inputs into repeatable debugging
This is a simplified teaching model. Its displayed values are computed from the controls; the article explains where the model stops.
Site connection
Team 1257 adopted AdvantageKit to analyze robot behavior in AdvantageScope and to improve the separation between real hardware and simulation. The core idea is an IO boundary: acquire and log inputs once per loop, then let deterministic control logic consume that snapshot.
A robot match is too chaotic to debug only by memory. Logging turns sensor readings, commands, estimated poses, setpoints, and mechanism states into a timeline that can be inspected after the robot leaves the field.
What the IO Boundary Separates
AdvantageKit's recommended structure moves direct hardware calls into an IO layer. Each subsystem's real implementation talks to motor controllers and sensors, a simulation implementation produces simulated measurements, and replay replaces the live input snapshot with values from a log.
Control logic reads only the inputs object. This is more precise than saying that simulation and the robot are identical: vendor behavior, timing, friction, wiring faults, and mechanical damage may still differ. What stays shared is the decision-making code above the IO boundary.
Mental model: the IO layer is an adapter, while the logged inputs object is a time-stamped snapshot consumed by the rest of the subsystem.
One Periodic Loop, Three Modes
In a real loop, updateInputs reads hardware and Logger.processInputs records the snapshot. In simulation, a simulation IO implementation updates the same fields. During replay, processInputs restores the recorded fields instead of asking nonexistent hardware for new values.
Outputs such as requested voltage, pose, setpoint, or command state are calculated values. Recording them makes comparisons possible: replay can show what the current code would calculate from the old inputs alongside what the original code calculated during the match.
| Mode | Input source | What the control logic sees | Primary use |
|---|---|---|---|
| Real | Sensors and controllers | Current hardware snapshot | Operate and capture evidence |
| Simulation | Physics or simplified models | Synthetic snapshot in the same fields | Test behavior before hardware is ready |
| Replay | A recorded log | Historical snapshot at each timestamp | Reproduce and inspect a past run |
Worked Example: Diagnosing a Slow Swerve Module
Suppose the back-left module reaches only 2.1 m/s while the other three reach a 3.0 m/s setpoint. Log the module's measured velocity as an input and the desired velocity and commanded voltage as outputs.
If replay shows a 3.0 m/s request and high commanded voltage while the measured input remains 2.1 m/s, the decision logic is asking for speed but the real system is not delivering it. That evidence points toward hardware, configuration, power, friction, or the sensor path. Team 1257's source post describes using logs while investigating slow swerve behavior and also finding physical causes such as worn tread and bumper fabric; a log narrows the search, but does not prove a single mechanical cause by itself.
If a code change makes replay request only 2.1 m/s from those same recorded inputs, compare the new replay output with the original output. The difference is evidence that the changed decision logic affects the command, although hardware validation is still required.
What to Log and How to Read It
Log raw observations needed by control logic as inputs: connectivity flags, positions, velocities, currents, temperatures, and timestamps where relevant. Log derived values and actuator requests as outputs: pose estimates, state-machine states, setpoints, feedforward terms, and voltages.
Use consistent names and units, then graph cause and effect together. A useful trace often pairs request, measurement, error, actuator output, and a validity signal. More data is not automatically better if names are ambiguous or signals are sampled at incompatible times.
| Signal group | Question it answers |
|---|---|
| Gyro yaw + connected | Was heading plausible and available? |
| Module desired + measured state | Did steering and speed follow their requests? |
| Pose + vision update status | When and why did the estimate move? |
| Shooter setpoint + velocity + voltage | Was the mechanism ready before feeding? |
| Command or state-machine state | Which behavior owned the output? |
Limits and Common Misconceptions
Replay is deterministic only to the extent that all relevant external inputs and timing-dependent values were captured. Direct hardware reads, unlogged NetworkTables values, wall-clock calls, random values, or mutable global state can make a replay diverge.
Simulation validates the model and integration, not the complete robot. A simulated motor cannot reveal a loose connector or shredded wheel tread unless the model explicitly represents that fault. Logs are evidence, not diagnosis by themselves; align timestamps, check units, and corroborate software traces with inspection and controlled tests.
A replay can answer 'what did the code see and calculate?' It cannot reconstruct an input that was never logged.
Common Pitfalls
- Reading hardware outside the IO layer, so replay cannot substitute the value.
- Logging a derived value but omitting the raw inputs needed to explain it.
- Assuming a passing simulation rules out wiring, friction, or configuration faults.
- Comparing signals without checking units, timestamps, or connection status.