Debugging

Quick Reference

Live Monitoring (CAN)

Tool	Use Case	Output
`monitoring/terminal_monitor.py`	Real-time status check	Terminal dashboard
`monitoring/live_graph.py`	Visual analysis	Matplotlib plots
`monitoring/monitor_logger.py`	Data capture + analysis	CSV + summary stats

Post-Processing Visualization

Tool	Input	Use Case
`visualization/csv_viewer.py`	CSV from logger	Motor data analysis
`visualization/plot_observations.py`	Firmware log	Policy input visualization
`visualization/plot_actions.py`	Firmware log	NN output + tracking analysis
`visualization/plot_imu.py`	Firmware log	IMU sensor analysis

All tools are in the tools/ directory.

Live Monitoring

Terminal Monitor

Real-time ASCII dashboard showing all 12 motors at a glance.

cd tools/monitoring
python3 -m monitoring.terminal_monitor can0 can1

Output shows:

Status: OK, TIMEOUT, or error code
Cmd: Commanded position (rad)
Pos: Actual position (rad)
Err: Position error (rad)
Vel: Velocity (rad/s)
Cur: Current (A)
Tmp: Temperature (C)
Sparkline: Position history visualization
Error Bar: Command vs feedback position

Graphical Monitor

Matplotlib-based 4x3 grid showing position and current for all motors.

cd tools/monitoring
python3 -m monitoring.live_graph can0

Features:

Blue dashed line: commanded position
Colored solid line: actual position
Red overlay: motor current
10-second rolling window (configurable with --history)

Data Logging

Capturing Data

cd tools/monitoring
python3 -m monitoring.monitor_logger can0 can1 --log session.csv

Press Ctrl+C to stop and generate summary statistics.

CSV Format

Column	Description
timestamp	Seconds since start
motor_id	CAN ID (`0x01`-`0x0C`)
motor_name	Human-readable name
cmd_pos	Commanded position (rad)
fb_pos	Feedback position (rad)
fb_vel	Feedback velocity (rad/s)
fb_cur	Feedback current (A)
fb_temp	Motor temperature (C)
error_code	0=OK, see error table

Session Statistics

On exit, the logger shows per-motor statistics:

Tracking Error: Min, max, average, RMS
Position: Range and average
Current: Peak and average draw
Temperature: Range during session

Diagnosing Motor Issues

Error Codes

Code	Name	Meaning	Action
`0x00`	OK	No error	-
`0x01`	OVERHEAT	Motor temp >80C	Let cool, check ventilation
`0x02`	OVERCUR	Current limit exceeded	Check for mechanical binding
`0x03`	UNDERVOLT	Supply <18V	Check battery/power supply
`0x04`	ENCODER	Position sensor fault	Recalibrate or replace motor
`0x05`	BRK_OVOLT	Brake circuit overvoltage	Check regenerative braking
`0x06`	DRV_FAULT	Driver IC fault	Hardware issue, contact support

Tracking Performance

Good tracking:

Position error < 0.05 rad (3 degrees)
Error bar shows X (command matches feedback)

Poor tracking symptoms:

Large position error
Oscillation in sparkline
High current with little movement

Common causes:

Mechanical binding or obstruction
Incorrect PD gains for the load
Motor temperature too high (torque derating)

Temperature Monitoring

Range	Status
<40C	Normal
40-60C	Elevated, monitor closely
60-80C	Warning, reduce load
>80C	Overheat protection triggers

CAN Protocol Reference

Motor IDs

ID	Motor
`0x01`	L_Hip_Pitch
`0x02`	L_Hip_Roll
`0x03`	L_Hip_Yaw
`0x04`	L_Knee_Pitch
`0x05`	L_Ankle_Pitch
`0x06`	L_Ankle_Roll
`0x07`	R_Hip_Pitch
`0x08`	R_Hip_Roll
`0x09`	R_Hip_Yaw
`0x0A`	R_Knee_Pitch
`0x0B`	R_Ankle_Pitch
`0x0C`	R_Ankle_Roll

Raw CAN Debugging

# View all traffic
candump can0

# Filter to specific motor
candump can0,001:7FF

# Log to file
candump -l can0

Using the Python Parser

from tools.monitoring.protocol_parser import parse_feedback_type1

# Example feedback message
data = bytes([0x20, 0x81, 0xF9, 0x7F, 0xD7, 0xF4, 0x5E, 0x60])
result = parse_feedback_type1(data)

print(f"Error: {result['error_name']}")
print(f"Position: {result['position_rad']:.3f} rad")
print(f"Velocity: {result['speed_rad_s']:.3f} rad/s")
print(f"Current: {result['current_a']:.2f} A")
print(f"Motor Temp: {result['motor_temp_c']:.1f} C")

Visualization Tools

Interactive Plotly-based visualization for post-mortem analysis.

Capturing Firmware Logs

# Run firmware and capture output
sudo ./bazel-bin/asimov-firmware > /tmp/humanoid_io.log 2>&1 &

# Or with tee to see output live
sudo ./bazel-bin/asimov-firmware 2>&1 | tee /tmp/humanoid_io.log

Motor CSV Viewer

Interactive 5-panel visualization of motor data.

cd tools/visualization
python3 csv_viewer.py session.csv
# Opens: session_overlay.html

Panels:

Position tracking (command vs feedback)
Position error
Current draw
Velocity
Temperature

Policy Observation Plotter

Visualize what the neural network policy observes.

cd tools/visualization
python3 plot_observations.py /tmp/humanoid_io.log

6-panel visualization:

Base angular velocity (gyroscope)
Projected gravity (accelerometer)
Velocity commands (vx, vy, wz)
Joint positions (12 joints)
Joint velocities (12 joints)
Actions (NN output)

Action/Target Plotter

Compare what the policy commanded vs what motors did.

cd tools/visualization
python3 plot_actions.py /tmp/humanoid_io.log

Use this to diagnose:

Poor motor tracking (large error)
Action scaling issues (raw vs target mismatch)
Policy oscillation (rapid action changes)

IMU Plotter

cd tools/visualization
python3 plot_imu.py /tmp/humanoid_io.log

2-panel visualization:

Gyroscope (angular velocity X, Y, Z)
Accelerometer (projected gravity X, Y, Z + magnitude)

Workflow Summary

CAN Motor Analysis:

monitor_logger.py → session.csv → csv_viewer.py → HTML

Policy Analysis:

asimov-firmware → /tmp/humanoid_io.log → plot_observations.py → HTML
                                       → plot_actions.py → HTML
                                       → plot_imu.py → HTML

Source Files

Monitoring (`tools/monitoring/`)

protocol_parser.py - CAN protocol decoder
terminal_monitor.py - ASCII dashboard
live_graph.py - Matplotlib visualization
monitor_logger.py - CSV logging + statistics

Visualization (`tools/visualization/`)

csv_viewer.py - Interactive Plotly motor viewer
plot_observations.py - Policy observation visualization
plot_actions.py - Action/target comparison
plot_imu.py - IMU data visualization