# Hardware

| What | How many | Interface |
|------|----------|-----------|
| Leg motors | 12 | CAN (buses 0-1) |
| IMU | 1 | I2C bus 8 |

The arms, torso, hands, and head are defined but not enabled yet.

---

## Motors

30 DOF total, but only the legs (12 motors) are enabled right now.

| Part | Motors | CAN Bus |
|------|--------|---------|
| Left Leg | 6 | 0 |
| Right Leg | 6 | 1 |
| Left Arm | 6 | 2 (disabled) |
| Right Arm | 6 | 3 (disabled) |
| Torso | 2 | 4 (disabled) |
| Hands + Head | 4 | 5 (disabled) |

### Left Leg (CAN Bus 0)

| ID | Name | CAN ID | Joint | Min | Max | Max Torque |
|----|------|--------|-------|-----|-----|------------|
| 0 | `L_Hip_Pitch` | `0x01` | Hip flexion/extension | -120° | +57° | 120 Nm |
| 1 | `L_Hip_Roll` | `0x02` | Hip abduction/adduction | -45° | +45° | 90 Nm |
| 2 | `L_Hip_Yaw` | `0x03` | Hip rotation | -45° | +45° | 60 Nm |
| 3 | `L_Knee_Pitch` | `0x04` | Knee flexion/extension | 0° | +86° | 70 Nm |
| 4 | `L_Ankle_Pitch` | `0x05` | Ankle dorsi/plantarflexion | -70° | +70° | 30 Nm |
| 5 | `L_Ankle_Roll` | `0x06` | Ankle inversion/eversion | -70° | +70° | 30 Nm |

### Right Leg (CAN Bus 1)

| ID | Name | CAN ID | Joint | Min | Max | Max Torque |
|----|------|--------|-------|-----|-----|------------|
| 6 | `R_Hip_Pitch` | `0x07` | Hip flexion/extension | -57° | +120° | 120 Nm |
| 7 | `R_Hip_Roll` | `0x08` | Hip abduction/adduction | -45° | +45° | 90 Nm |
| 8 | `R_Hip_Yaw` | `0x09` | Hip rotation | -45° | +45° | 60 Nm |
| 9 | `R_Knee_Pitch` | `0x0A` | Knee flexion/extension | -86° | 0° | 70 Nm |
| 10 | `R_Ankle_Pitch` | `0x0B` | Ankle dorsi/plantarflexion | -70° | +70° | 30 Nm |
| 11 | `R_Ankle_Roll` | `0x0C` | Ankle inversion/eversion | -70° | +70° | 30 Nm |

Note: Left and right leg angles are mirrored. Left knee extends positive, right knee extends negative.

### Control Gains

The RL policy uses these PD gains:

| Joint Type | Kp (N·m/rad) | Kd (N·m·s/rad) |
|------------|--------------|----------------|
| Hip Pitch | 257.4 | 5.0 |
| Hip Roll | 394.8 | 5.0 |
| Hip Yaw | 135.4 | 5.0 |
| Knee | 130.3 | 5.0 |
| Ankle Pitch | 93.2 | 5.0 |
| Ankle Roll | 93.2 | 5.0 |

### Action Scaling

Policy outputs get scaled before becoming motor commands:

| Joint | Offset (rad) | Scale |
|-------|--------------|-------|
| Hip Pitch | 0.0 | 0.140 |
| Hip Roll | 0.0 | 0.068 |
| Hip Yaw | 0.0 | 0.133 |
| Knee | 0.0 | 0.173 |
| Ankle Pitch | 0.0 | 0.116 |
| Ankle Roll | 0.0 | 0.116 |

---

## CAN Buses

6 CAN buses, but only 0 and 1 are enabled (legs).

| Bus | Thread | CPU | Motors | Status |
|-----|--------|-----|--------|--------|
| CAN0 | `can0` | 6 | Left leg (0-5) | Enabled |
| CAN1 | `can1` | 5 | Right leg (6-11) | Enabled |
| CAN2 | `can2` | 5 | Left arm (12-17) | Disabled |
| CAN3 | `can3` | 5 | Right arm (18-23) | Disabled |
| CAN4 | `can4` | 6 | Torso (24-25) | Disabled |
| CAN5 | `can5` | 6 | Hands + Head (26-29) | Disabled |

### Protocol

500 kbps, standard SocketCAN.

### Command Frame (Host → Motor)

| Byte | Field | Type | Description |
|------|-------|------|-------------|
| 0-3 | `target_pos` | float | Target position (rad) |
| 4-7 | `target_vel` | float | Target velocity (rad/s) |
| 8-11 | `target_torque` | float | Feedforward torque (Nm) |
| 12-13 | `kp` | uint16 | Position gain (scaled) |
| 14-15 | `kd` | uint16 | Velocity gain (scaled) |

### Feedback Frame (Motor → Host)

| Byte | Field | Type | Description |
|------|-------|------|-------------|
| 0-3 | `position` | float | Measured position (rad) |
| 4-7 | `velocity` | float | Measured velocity (rad/s) |
| 8-11 | `current` | float | Phase current (A) |
| 12-13 | `temperature` | int16 | Motor temp (0.1°C units) |
| 14-15 | `error_code` | uint16 | Motor error flags |

### Update Rates

| Bus | Rate |
|-----|------|
| CAN0-1 | 200 Hz |
| CAN2-5 | 250 Hz (disabled) |

---

## IMU

BNO085 on I2C bus 8. Runs at 500 Hz with built-in 9-DOF sensor fusion.

| Thing | Value |
|-------|-------|
| Sensor | BNO085 |
| Bus | `/dev/i2c-8` |
| Address | 0x4A |
| Rate | 500 Hz |
| Protocol | SHTP via official CEVA SH2 library |

### What It Outputs

| Field | Type | Unit | Description |
|-------|------|------|-------------|
| `quat[4]` | float | - | Orientation quaternion [w,x,y,z] |
| `ang_vel[3]` | float | rad/s | Angular velocity in body frame |
| `accel[3]` | float | m/s² | Linear acceleration (gravity removed) |
| `gravity[3]` | float | - | Normalized gravity vector pointing DOWN (0,0,-1 when upright) |

### Calibration

BNO085 handles calibration internally using Dynamic Calibration Data (DCD). No manual calibration required.

### Error Recovery

The driver automatically recovers from I2C errors and sensor resets:
- **I2C failure** → HAL sends soft reset, sensor reinitializes
- **SH2_RESET event** → Driver re-enables all configured sensors

---

## Coordinate Frames

All frames follow ROS REP-103: **X forward, Y left, Z up** (right-handed).

### Body Frame

```
              Z (up)
              │
              │    X (forward)
              │   /
              │  /
              │ /
              └──────── Y (left)

        Top-down view:
              X (forward)
              ▲
              │
        ┌─────┼─────┐
        │     │     │
  Y ◄───┼─────●─────┼  (robot facing up)
        │           │
        │   L   R   │
        └───┼───┼───┘
            │   │
           legs
```

### IMU → Body Frame

The IMU is mounted so its axes align with the body frame.

| IMU Output | Body Frame | Description |
|------------|------------|-------------|
| `ang_vel[0]` | ωx | Roll rate (rotation about X) |
| `ang_vel[1]` | ωy | Pitch rate (rotation about Y) |
| `ang_vel[2]` | ωz | Yaw rate (rotation about Z) |
| `gravity[0]` | gx | Gravity X component |
| `gravity[1]` | gy | Gravity Y component |
| `gravity[2]` | gz | Gravity Z component |

### Joint Sign Conventions

```
    Hip Pitch:   + = leg forward     - = leg backward
    Hip Roll:    + = leg outward     + = leg outward
    Hip Yaw:     + = toe outward     + = toe outward
    Knee:        + = extend          - = extend       ← MIRRORED!
    Ankle Pitch: + = toe up          + = toe up
    Ankle Roll:  + = sole outward    + = sole outward
```

### Left/Right Mirroring

The legs are **mirrored** about the sagittal plane:

| Joint | Left Leg (+) | Right Leg (+) |
|-------|--------------|---------------|
| Hip Pitch | Leg forward | Leg forward |
| Hip Roll | Leg outward (left) | Leg outward (right) |
| Hip Yaw | Toe points left | Toe points right |
| **Knee** | **Extend (straighten)** | **Flex (bend)** |
| Ankle Pitch | Toe up | Toe up |
| Ankle Roll | Sole faces left | Sole faces right |

**Key point:** Knee signs are opposite! Left knee extends positive, right knee extends negative.

For symmetric standing: `L_Knee = -R_Knee`

---

## Source Files

| File | What it does |
|------|--------------|
| `source/hal/hardware/motor/motor_map.h` | Motor IDs, limits, gains |
| `source/hal/can/can_interface.c` | CAN bus interface |
| `source/hal/hardware/imu/bno085_driver.c` | BNO085 driver |
| `source/app/imu/imu_thread.c` | 500 Hz IMU thread |