# Getting Started

This guide covers building, flashing, and basic operation of the AddVantage PPG firmware.

## Prerequisites

### Toolchain

Install the ARM GCC toolchain:

**macOS:**
```bash
brew install arm-none-eabi-gcc
```

**Linux:**
```bash
apt install gcc-arm-none-eabi
```

**Windows:**
Download from [Arm Developer](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)

### Build Tools

- CMake 3.20+
- Ninja (recommended) or Make

```bash
# macOS
brew install cmake ninja

# Linux
apt install cmake ninja-build
```

### Hardware

- SEGGER J-Link debugger (J-Link EDU or commercial)
- USB-serial adapter for UART (57600 baud)
- PCAN-USB adapter for CAN validation (optional)

## Building the Firmware

### Quick Build

```bash
mkdir build && cd build
cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../arm-gcc-toolchain.cmake ..
ninja
```

This produces:
- `build/addvantage3.elf` - Debug symbols for debugging
- `build/addvantage3.hex` - Flash image

### Build Options

| Option | Description |
|--------|-------------|
| `-DCMAKE_BUILD_TYPE=Release` | Optimized build |
| `-DCMAKE_BUILD_TYPE=Debug` | Debug symbols, no optimization |

## Flashing

### Using the Flash Script

```bash
python tools/flash.py build/addvantage3.hex
```

The script uses J-Link serial `50114603` to avoid the GUI picker dialog.

### Manual J-Link Commands

```bash
JLinkExe -device MKE06Z128xxx4 -if SWD -speed 4000 -autoconnect 1

# In J-Link commander:
loadfile build/addvantage3.hex
r  # reset
g  # go
```

## Serial Console

Connect to the UART at **57600 baud**:

```bash
# macOS
screen /dev/cu.usbmodem* 57600

# Linux
screen /dev/ttyUSB0 57600

# Windows
putty -serial COM3 -sercfg 57600,8,n,1
```

### Boot Output

After reset, you'll see:

```
addvantage PPG V3.2.7 250kbit
d0g0e99p0r0t0c0v0k0b250f327w1x0y100z0V3.2.7
Password required:
```

### Password

Default password: `tribune`

After authentication, commands are available:
- `f` - Factory reset + engine profile selection
- `g` - Toggle gas flow enable
- `m` - Memory dump
- `v` - Toggle VT100 display
- `o` - Output configuration

## First Run Checklist

1. Flash firmware
2. Connect serial console
3. Verify boot message shows correct version
4. Enter password
5. Press `f` for factory reset
6. Select engine profile (1-18)
7. Verify telemetry output shows sensor readings

## Troubleshooting

### No Serial Output

- Check baud rate (57600)
- Verify TX/RX connections (TX from MCU → RX on adapter)
- Try different USB-serial adapter

### Boot Loops

If the device continuously resets (multiple version strings in output):
- Watchdog may not be disabled properly
- Check `startup_wdog.S` is correctly included in build

### J-Link Connection Failed

- Verify SWD connections (SWDIO, SWCLK, GND, VTref)
- Try lower speed: `-speed 1000`
- Check target voltage (3.3V)

## Next Steps

- Read the [CAN Protocol](can_protocol.md) guide for J1939 integration
- See [Telemetry Format](telemetry.md) for data interpretation
- Use the [Test Harness](testing.md) for automated validation