# Agricultural Spray Drone SoC — Implementation Status

## Overview

A complete drone system-on-chip for autonomous crop spraying, implemented
in Sparkle HDL (Lean 4 Signal DSL). All components synthesize to Verilog
and pass yosys `synth_xilinx` with zero errors.

Target FPGA: Zynq-7010 (17,600 LUT, 80 DSP48E1).

## Architecture

```
  ┌─────────┐   SPI    ┌──────────┐         ┌──────────────┐
  │  IMU    ├──────────→│State Est.│────────→│  Neural FC   │
  │MPU6050  │  1 kHz   │comp.filt.│         │ BitNet FFN×2 │
  └─────────┘          └──────────┘         │   15 ns      │
  ┌─────────┐   UART   ┌──────────┐        └──────┬───────┘
  │  GPS    ├──────────→│UBX Parse │────┐          │
  │NEO-M8N  │  9600bd  └──────────┘    │   ┌──────▼───────┐
  └─────────┘                           │   │  Failsafe    │
  ┌─────────┐   SBUS   ┌──────────┐    │   │  Override    │
  │  RC RX  ├──────────→│ 8ch+FS  │────┘   └──────┬───────┘
  └─────────┘  100kbd   └──────────┘               │
  ┌─────────┐                                      │
  │ YOLOv8  ├─→ obstacle ─→ thrust ÷2 ────────────┤
  └─────────┘                                      │
  ┌─────────┐          ┌──────────┐         ┌──────▼───────┐
  │ Path    ├─────────→│spray en. │────────→│  4× PWM Pump │──→ Nozzles
  │Planner  │ serpent. └──────────┘         └──────────────┘
  └─────────┘                               ┌──────────────┐
                                            │  4× DShot    │──→ Motors
                                            └──────────────┘
```

## Components

| Component | File | Function | Synthesis |
|---|---|---|---|
| Neural Flight Controller | `FlightController.lean` | BitNet FFN × 2 layers, 15 ns latency, 0 FF | ✅ 324 LC, 16 DSP |
| Vision Avoidance | `VisionFC.lean` | YOLOv8 obstacle → thrust ÷2 | ✅ |
| DShot ESC (4ch) | `DShot.lean` | DShot600 motor protocol, 37.5 kHz | ✅ 24 FF |
| SPI IMU Driver | `SPIIMU.lean` | MPU6050/ICM-42688 burst read | ✅ |
| UART GPS | `UARTGPS.lean` | 9600 baud UART + UBX-NAV-PVT parser | ✅ |
| PWM Pump (4ch) | `PWMPump.lean` | Spray nozzle control with soft start | ✅ |
| SBUS RC Receiver | `SBUS.lean` | 8ch + failsafe, inverted UART 100 kbaud | ✅ |
| State Estimator | `StateEstimator.lean` | Complementary filter (IMU + GPS fusion) | ✅ |
| Path Planner | `PathPlanner.lean` | Serpentine spray pattern over rectangular field | ✅ |
| Failsafe Controller | `Failsafe.lean` | 5-condition priority override | ✅ |
| **Top-Level SoC** | **`SprayDroneSoC.lean`** | **All components wired** | ✅ |

## Synthesis Results

### Top-Level SoC (yosys synth_xilinx)

| Metric | Value |
|---|---|
| Generated Verilog | 5,615 lines |
| Flip-flops (FDCE) | 216 |
| LUT | ~600 |
| DSP48E1 | 16 |
| CARRY4 | 123 |
| External pins | 10 (all 1-bit) |
| Longest path | 206 |
| Errors | 0 |

### FPGA Fit

| FPGA | LUT available | LUT used | DSP available | DSP used | Fits? |
|---|---|---|---|---|---|
| **Zynq-7010** | 17,600 | ~600 (3.4%) | 80 | 16 (20%) | **✅** |
| Zynq-7020 | 53,200 | ~600 (1.1%) | 220 | 16 (7%) | ✅ |
| iCE40 UP5K | 5,280 | ~600 (11%) | 0 (use LUT) | — | ✅ (tight) |
| ECP5-25K | 24,000 | ~600 (2.5%) | 28 | 16 (57%) | ✅ |

## Neural Flight Controller

The flight controller uses a ternary BitNet neural network instead
of a traditional PID controller.

| Property | PID Controller | Neural FC (BitNet) |
|---|---|---|
| Latency | ~1 ms (software loop) | **~15 ns** (combinational) |
| Adaptability | Fixed gains, manual tuning | Learned from flight data |
| Nonlinearity | Linear (or cascaded) | Arbitrary nonlinear |
| Resource | CPU (ARM Cortex-M) | **0 FF, 324 LUT, 16 DSP** |
| Update rate | 1 kHz typical | **>50 MHz possible** |

Architecture: dim=16, 2 FFN layers, all ternary weights.
6 sensor inputs (accelXYZ + gyroXYZ) → 4 motor outputs.

## Sensor Interfaces

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

- SPI Mode 0, ~6 MHz clock (200 MHz / 32)
- Burst read: register 0x3B, 12 bytes (6 × 16-bit sensors)
- Read rate: 1 kHz (triggered by internal counter)
- Output: accelX/Y/Z, gyroX/Y/Z (16-bit signed)

### UART GPS (u-blox NEO-M8N)

- 9600 baud, 8N1
- UBX-NAV-PVT packet parser (92-byte payload)
- Output: latitude, longitude, altitude (32-bit signed, 1e-7 degrees)
- Update rate: 10 Hz (GPS module default)

### SBUS RC Receiver (Futaba)

- Inverted UART, 100 kbaud, 8E2
- 25-byte frame, 16 channels × 11-bit
- Signal inversion in hardware (no external inverter)
- Failsafe flag detection for emergency override
- Channel mapping: roll, pitch, throttle, yaw, aux1-4

## Actuator Interfaces

### DShot600 ESC (4 channels)

- Digital motor control, 600 kbit/s
- 16-bit frame: [11-bit throttle][1-bit telemetry][4-bit CRC]
- CRC: XOR of nibbles (computed at Signal level)
- Frame rate: ~37.5 kHz
- Supports: disarm (0), min-max thrust (48-2047)

### PWM Pump (4 nozzles)

- 16-bit PWM resolution
- Soft start ramp (prevent pump surge)
- Independent enable and duty per nozzle
- Variable-rate spraying capability

## Control System

### State Estimation

Complementary filter fusing IMU and GPS:

```
attitude = 0.98 × (gyro integration) + 0.02 × (accelerometer angle)
position = 0.98 × (accel double integration) + 0.02 × (GPS position)
```

Outputs: roll, pitch, yaw (Q16.16 radians) + posX, posY, posZ (Q16.16 meters)

### Path Planning

Serpentine (lawn-mower) spray pattern:

```
Start → fly north → turn east (swath width) → fly south → turn east → ...
```

Parameters: field width/length, swath width (default 5 m), spray altitude (default 3 m).
Maximum 20 passes per mission.

### Failsafe

Priority-based override system:

| Priority | Condition | Action |
|---|---|---|
| 1 (highest) | IMU failure (2.5 ms watchdog) | Emergency land |
| 2 | Low battery | Return to Home + land |
| 3 | RC signal loss (SBUS failsafe) | Return to Home |
| 4 | Geofence violation | Return to Home |
| 5 (lowest) | GPS loss | Position hold (hover) |

4-bit failsafe code output for diagnostics.

## Remaining Work

### Required for Flight

| Task | Description |
|---|---|
| Trained FC weights | Replace all-+1 test weights with flight-data-trained model |
| ESC calibration | DShot throttle range calibration per motor |
| IMU calibration | Accelerometer/gyro offset and scale calibration |
| GPS coordinate transform | Convert lat/lon to local meters for path planner |
| Waypoint arrival detection | Compare current position vs target for path planner |
| Magnetometer (compass) | Yaw reference — currently no heading correction |
| Barometer (altitude) | Pressure-based altitude — GPS altitude is noisy |
| Battery ADC | Voltage sensing for low-battery failsafe |
| Return-to-Home navigation | Navigate from current position to launch point |

### Required for Certification

| Task | Description |
|---|---|
| Japan UAV registration | Drone registration with MLIT |
| Agricultural chemical permit | Pesticide application permit |
| Flight area approval | Airspace coordination |
| Safety equipment | Parachute, geofence, ADS-B (depending on weight class) |

## Development Speed

The entire drone SoC (11 modules, 5,615 lines Verilog) was designed
and synthesized in a single session using Sparkle HDL.

| Metric | Sparkle | Estimated Verilog |
|---|---|---|
| Lines of code | ~2,000 Lean | ~6,000+ Verilog + testbench |
| Time | ~2 hours | ~2-4 weeks |
| Synthesis verification | Per-module `#synthesizeVerilog` | End-to-end Vivado run |
| Type safety | Compile-time bit-width check | Simulation-time lint |

## File Structure

```
IP/Drone/
├── FlightController.lean  — Neural FC (BitNet FFN × 2, 15 ns)
├── VisionFC.lean          — YOLOv8 obstacle → FC thrust modulation
├── DShot.lean             — DShot600 ESC protocol (4ch)
├── SPIIMU.lean            — SPI IMU driver (MPU6050/ICM-42688)
├── UARTGPS.lean           — UART GPS + UBX-NAV-PVT parser
├── PWMPump.lean           — PWM pump controller (4 nozzles)
├── SBUS.lean              — SBUS RC receiver (8ch + failsafe)
├── StateEstimator.lean    — Complementary filter (IMU + GPS)
├── PathPlanner.lean       — Serpentine spray pattern
├── Failsafe.lean          — 5-condition failsafe controller
└── SprayDroneSoC.lean     — Top-level SoC (all wired)
```