# Humanoid Robot SoC — Implementation Status

## Overview

A complete bipedal humanoid robot system-on-chip implemented in
Sparkle HDL (Lean 4 Signal DSL). All components synthesize to Verilog
and pass yosys `synth_xilinx` with zero errors.

Target FPGA: Zynq-7020 (53,200 LUT, 220 DSP48E1).

## Architecture

```
  ┌──────────┐  SPI   ┌──────────┐  targets  ┌──────────┐
  │ Encoders ├───────→│ Neural   ├──────────→│ Safety   │
  │  30ch    │        │ Motion   │           │Controller│
  └──────────┘        │ BitNet   │           └────┬─────┘
  ┌──────────┐  SPI   │ 30 ns    │                │
  │   IMU    ├───────→│          │           ┌────▼─────┐
  └──────────┘        └──────────┘           │ Servo    │
  ┌──────────┐                               │ 30ch PWM │──→ Joints
  │   Gait   ├──→ foot targets ──→ IK ──┐   └──────────┘
  │Generator │                           │
  └──────────┘                           │
  ┌──────────┐         ┌──────────┐      │
  │  Foot    ├────────→│   ZMP    ├──────┘
  │ Pressure │         │ Balance  │
  └──────────┘         └──────────┘
```

## Components

| Component | File | Function | Synthesis |
|---|---|---|---|
| Servo Driver (30ch) | `ServoDriver.lean` | 50 Hz PWM, 16-bit position, 5 × 6ch banks | ✅ |
| Encoder Reader (30ch) | `Encoder.lean` | SPI AS5047P, 14-bit, sequential polling ~77 μs | ✅ |
| Neural Motion Controller | `NeuralMotion.lean` | BitNet FFN × 2, 30 ns, 0 FF | ✅ 16 DSP |
| ZMP Balance Controller | `ZMPBalance.lean` | 8 pressure sensors, PD control, ankle correction | ✅ |
| Inverse Kinematics (6-DOF) | `InverseKinematics.lean` | 2-link planar IK + 3-DOF orientation | ✅ |
| Gait Generator | `GaitGenerator.lean` | Serpentine bipedal walk, configurable step | ✅ |
| Safety Controller | `SafetyController.lean` | Torque limit + collision + fall detection + E-stop | ✅ |
| **Top-Level SoC** | **`HumanoidSoC.lean`** | **All components wired** | ✅ |

## Synthesis Results

### Top-Level SoC (yosys synth_xilinx)

| Metric | Value |
|---|---|
| Generated Verilog | 3,572 lines |
| Flip-flops (FDCE) | 151 |
| LUT | ~700 |
| DSP48E1 | 16 |
| CARRY4 | 139 |
| External pins | 11 (135 bits) |
| Longest path | 222 |
| Errors | 0 |

### FPGA Fit

| FPGA | LUT available | LUT used | DSP available | DSP used | Fits? |
|---|---|---|---|---|---|
| Zynq-7010 | 17,600 | ~700 (4.0%) | 80 | 16 (20%) | ✅ |
| **Zynq-7020** | 53,200 | ~700 (1.3%) | 220 | 16 (7.3%) | **✅** |
| Zynq UltraScale+ ZU3 | 70,560 | ~700 (1.0%) | 360 | 16 (4.4%) | ✅ |

## Neural Motion Controller

Replaces traditional PD + IK + trajectory planning with a single
ternary neural network.

| Property | Traditional (PD + IK) | Neural Motion (BitNet) |
|---|---|---|
| Latency | ~1 ms (software loop) | **~30 ns** (combinational) |
| Adaptability | Fixed gains, manual tuning | Learned from motion data |
| Computation | Sequential (ARM CPU) | Parallel (LUT adder trees) |
| Resource | CPU core (100+ MHz) | **0 FF, ~600 LUT, 16 DSP** |
| Update rate | 1 kHz typical | **>30 MHz possible** |

Architecture: 12 inputs (6 encoders + 6 IMU) → dim=64 FFN × 2 layers → 6 servo outputs.
Full 30-joint version: 36 inputs → dim=64 FFN × 3 layers → 30 outputs.

## Joint Configuration

```
Head (3 DOF):
  ch0: pan     ch1: tilt    ch2: roll

Right Arm (6 DOF):
  ch3: shoulder pitch    ch4: shoulder roll    ch5: shoulder yaw
  ch6: elbow             ch7: wrist pitch      ch8: wrist roll

Left Arm (6 DOF):
  ch9-14: mirror of right arm

Right Leg (6 DOF):
  ch15: hip pitch    ch16: hip roll    ch17: hip yaw
  ch18: knee         ch19: ankle pitch ch20: ankle roll

Left Leg (6 DOF):
  ch21-26: mirror of right leg

Torso (3 DOF):
  ch27: waist yaw    ch28: waist pitch    ch29: waist roll
```

## Sensor Interfaces

### SPI Encoders (AS5047P / AS5600)

- SPI Mode 1, ~6.25 MHz
- 14-bit absolute angle (0.022° resolution)
- 30 encoders polled sequentially in ~77 μs
- Update rate: 13 kHz (exceeds 10 kHz control requirement)

### SPI IMU (MPU6050 / ICM-42688)

- Shared with drone SoC implementation
- 6-axis: accel XYZ + gyro XYZ
- 1 kHz read rate

### Foot Pressure Sensors

- 4 sensors per foot (8 total) at corners
- Analog input via ADC (external)
- Used for ZMP computation

## Control System

### ZMP Balance

Zero Moment Point controller for bipedal stability:

```
actual_ZMP = weighted_centroid(foot_pressure_sensors)
correction = Kp × (target_ZMP - actual_ZMP) + Kd × d(ZMP)/dt
```

Applied to ankle pitch (fore-aft balance) and ankle roll (lateral balance).
PD gains configurable at runtime.

### Inverse Kinematics

Geometric 6-DOF IK for each limb:

1. Shoulder/hip yaw: point toward target laterally
2. Planar 2-link IK: law of cosines for pitch + elbow/knee
3. Shoulder/hip roll: lateral tilt correction
4. Wrist/ankle: compensate to keep end-effector level

Small-angle approximations for trig (suitable for workspace).
CORDIC would improve accuracy for large-angle motions.

### Gait Generation

Alternating swing/stance phases for bipedal walking:

```
Right swing: right foot lifts → advances → lands
Left stance: left foot on ground, body moves forward
→ Switch legs → repeat
```

Parameters: step length (20 cm default), step height (5 cm),
stride period (configurable).

### Safety Controller

Multi-layer protection system:

| Priority | Condition | Detection | Action |
|---|---|---|---|
| 1 (highest) | E-stop pressed | External button | All motors to zero |
| 2 | Falling | Body tilt > 0.75 rad | Protective pose (crouch) |
| 3 | Collision | Torque spike > threshold | Compliance mode (25% torque) |
| 4 (normal) | — | — | Normal operation |

Fall direction detection: forward (1), backward (2), left (3), right (4).
Torque spike watchdog with configurable threshold.

## Comparison with Existing Humanoid Platforms

| Feature | Honda ASIMO | Boston Dynamics Atlas | **Sparkle Humanoid SoC** |
|---|---|---|---|
| Control latency | ~1 ms | ~0.5 ms (est.) | **~30 ns** |
| Balance sensor update | 1 kHz | 1-10 kHz | **13 kHz** |
| Control hardware | Custom ASIC | x86 + FPGA | **Pure FPGA (Zynq)** |
| Safety response time | ~1 ms | ~0.5 ms | **~30 ns** |
| Development time | Years | Years | **Hours (Sparkle HDL)** |

Note: Sparkle humanoid SoC has the hardware infrastructure but lacks
trained neural network weights and real-world testing. The comparison
is for hardware capability, not demonstrated walking ability.

## Remaining Work

| Task | Description |
|---|---|
| Trained motion weights | RL policy trained in simulation (MuJoCo/Isaac Gym) |
| EtherCAT master | Industrial servo communication (higher-end actuators) |
| Camera interface (MIPI CSI) | Visual perception |
| LiDAR interface | 3D environment mapping |
| Audio (I2S) | Microphone + speaker for interaction |
| Real-world testing | Actuator calibration, balance tuning |
| Full 30-DOF SoC integration | Scale from 6-DOF test to full body |

## File Structure

```
IP/Humanoid/
├── ServoDriver.lean       — 30-channel PWM servo (50 Hz, 16-bit)
├── Encoder.lean           — 30-channel SPI encoder (AS5047P, 14-bit)
├── NeuralMotion.lean      — BitNet motion controller (dim=64, 30 ns)
├── ZMPBalance.lean        — ZMP balance + foot pressure + PD control
├── InverseKinematics.lean — 6-DOF geometric IK (arm/leg)
├── GaitGenerator.lean     — Bipedal walking pattern
├── SafetyController.lean  — Torque limit + collision + fall + E-stop
└── HumanoidSoC.lean       — Top-level SoC (all wired)
```