# Development Guide

## Prerequisites

- VS Code
- PlatformIO extension (recommended) or PlatformIO CLI
- Python 3.10+
- USB serial driver for Teensy

Python packages:

```powershell
pip install pyqt5 pyqtgraph pyserial
```

## Build Firmware

PlatformIO extension flow:

1. Open project workspace.
2. Select env teensy41.
3. Build.
4. Upload.

CLI flow:

```powershell
pio run -e teensy41
pio run -e teensy41 -t upload
```

## Run Desktop Stack

Start simulator:

```powershell
python simulator.py --host 0.0.0.0 --port 8765 --mode long --rate 10
```

Start dashboard:

```powershell
python full_dashboard.py --tcp localhost:8765
```

## Debug Workflow

1. Validate simulator output first.
2. Validate dashboard command send/ack.
3. Move to serial hardware mode.
4. Validate state transitions with inert pyros.
5. Enable deployment channels only after full bench pass.

## Coding Conventions

- Keep timing logic rollover-safe with subtraction comparisons.
- Prefer non-blocking operations in control/event loops.
- Keep telemetry schema backward compatible when possible.
- Add small, high-value comments only around non-obvious control logic.

## Suggested Test Matrix

1. Parse and command protocol tests:
   - malformed command
   - unknown command
   - valid command with ack
2. State-machine tests:
   - ascent trigger threshold
   - apogee confirmation frames
   - main deployment gate
3. Dashboard runtime tests:
   - replay mode on/off transitions
   - shutdown while TCP connected
   - logging start/stop and file integrity
4. Simulator tests:
   - mode/rate command updates
   - override reset behavior

## Release Checklist

1. Update docs and protocol changes.
2. Build firmware in clean environment.
3. Run simulator/dashboard smoke test.
4. Bench-test command path on hardware.
5. Verify continuity and safety checklist.