# 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.

```bash
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.

```bash
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

```bash
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 |
|-------|--------|
| &lt;40C | Normal |
| 40-60C | Elevated, monitor closely |
| 60-80C | Warning, reduce load |
| &gt;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

```bash
# View all traffic
candump can0

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

# Log to file
candump -l can0
```

### Using the Python Parser

```python
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

```bash
# 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.

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

Panels:
1. Position tracking (command vs feedback)
2. Position error
3. Current draw
4. Velocity
5. Temperature

### Policy Observation Plotter

Visualize what the neural network policy observes.

```bash
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.

```bash
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

```bash
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