# Protocol

The robot talks protobuf over UDP. You send commands, it sends back telemetry.

| Message | Direction | Port | Rate |
|---------|-----------|------|------|
| RobotCommand | You → Robot | 8888 | Send at ≥10 Hz |
| RobotState | Robot → You | (any) | 100 Hz |

Generate Python bindings:
```bash
protoc --python_out=. proto/asimov_command.proto
```

## Files

- `proto/asimov_command.proto` - The protobuf definitions
- `proto/asimov_command.pb.c` - Generated C code (nanopb)

---

## RobotCommand

Send this to port 8888 to control the robot.

### Control Mode

| Field | What to put |
|-------|-------------|
| `mode` | Which mode you want (see table below) |

### Velocity Commands

Only matter when `mode = MOVE`.

| Field | Range | Direction |
|-------|-------|-----------|
| `vx` | -0.5 to 1.0 m/s | + forward |
| `vy` | -0.3 to 0.3 m/s | + left |
| `vyaw` | -1.0 to 1.0 rad/s | + counter-clockwise |

### Control Flags

| Field | What it does |
|-------|--------------|
| `enable` | Must be `true` for motors to move |
| `emergency_stop` | Set `true` to kill motors immediately |
| `timestamp_us` | Your timestamp (for latency tracking) |

### Control Modes

| Value | Name | What happens |
|-------|------|--------------|
| 0 | `DAMP` | Motors go soft, safe default |
| 1 | `STAND` | Stands up over 2 seconds |
| 2 | `START` | Balances in place |
| 3 | `MOVE` | Walks using vx, vy, vyaw |
| 4 | `IMITATION` | Plays back recorded motion |

### Deadman Switch

You must send commands at least every 100ms. If the robot doesn't hear from you, it assumes something's wrong and disables the motors. This is intentional.

### Typical Sequence

1. Send `enable=true, mode=DAMP` - motors on but soft
2. Send `mode=STAND` - robot stands up (~2 seconds)
3. Send `mode=START` - robot balances in place
4. Send `mode=MOVE, vx=0.3` - robot walks forward
5. Send `mode=DAMP` - robot goes soft, sits down

```{mermaid}
stateDiagram-v2
    [*] --> DAMP : power on
    DAMP --> STAND : stand
    STAND --> START : start
    START --> MOVE : move
    MOVE --> DAMP : damp / e-stop
    START --> DAMP : damp / e-stop
    STAND --> DAMP : damp / e-stop
```

---

## RobotState (Telemetry)

The robot sends this back to you at 100 Hz.

### Timing

| Field | What it is |
|-------|------------|
| `timestamp_us` | Robot's clock (microseconds since boot) |
| `sequence` | Packet counter (use to detect drops) |

### Robot State

| Field | What it means |
|-------|---------------|
| `current_mode` | What mode the robot is in (0-4) |
| `motors_enabled` | Are motors powered? |
| `emergency_stop` | Is E-stop active? |

### Joint Data

12 motors, indexed 0-11.

| Field | Unit | What it is |
|-------|------|------------|
| `joint_pos[12]` | rad | Joint angles |
| `joint_vel[12]` | rad/s | Joint velocities |
| `joint_current[12]` | A | Motor current |
| `joint_temp[12]` | °C | Motor temperature (watch for >80°C) |

### IMU

| Field | Unit | What it is |
|-------|------|------------|
| `base_ang_vel[3]` | rad/s | Angular velocity [x, y, z] in body frame |
| `projected_gravity[3]` | - | Which way is down (normalized) |

### Power

| Field | What it means |
|-------|---------------|
| `battery_voltage` | Pack voltage (40-54V normal) |
| `battery_percent` | State of charge |
| `error_flags` | Bitmask of problems (see below) |

### Error Flags

| Bit | What's wrong |
|-----|--------------|
| 0 | CAN communication lost |
| 1 | Motor too hot (>80°C) |
| 2 | Overcurrent |
| 3 | IMU communication lost |
| 4 | Battery low (<42V) |
| 5 | Battery critical (<40V) |
| 6 | E-stop active |
| 7 | Policy took too long |