# CI/CD Pipeline

This project uses **Gitea Actions** for continuous integration and continuous deployment.

## Workflows

### 1. Main CI Pipeline (`ci.yml`)

Runs on every push to `main` and pull requests. Includes:

- **Lint Check** — Validates code formatting with `pre-commit` (clang-format, markdownlint, etc.)
- **Build Matrix** — Compiles all 21 hardware targets
- **Unit Tests** — Runs integration test suite (when available)
- **Summary** — Reports overall status

**Status**: ✅ All builds must pass before merging to main

### 2. Detailed Build Matrix (`build-matrix.yml`)

Comprehensive build configuration with per-target metadata:

- Target name and description
- Chip architecture (ESP32, ESP32-S3, nRF52, RP2040)
- Parallel builds with caching
- Detailed reporting

**Builds**:

- **ESP32 targets** (7): Heltec v2, v4, CT62, E213, E290, Mesh Solar, T190 + LilyGo T-Beam variants
- **ESP32-S3 targets** (7): Heltec V3, T114, Tracker, Tracker V2 + Seeed Xiao S3 + LilyGo T-Beam Supreme
- **nRF52 targets** (4): RAK4631, RAK3112, RAK3401, RAK3x72
- **RP2040 targets** (1): RAK11310

## Hardware Targets Supported

| Board                            | Vendor | SoC      | LoRa Chip | Status      |
| -------------------------------- | ------ | -------- | --------- | ----------- |
| Heltec WiFi LoRa 32 V2           | Heltec | ESP32    | SX1276    | ✅          |
| Heltec WiFi LoRa 32 V3           | Heltec | ESP32-S3 | SX1262    | ✅ Verified |
| Heltec WiFi LoRa 32 V4           | Heltec | ESP32-S3 | SX1262    | ✅          |
| Heltec CT62                      | Heltec | ESP32    | SX1262    | ✅          |
| Heltec E213                      | Heltec | ESP32    | SX1262    | ✅          |
| Heltec E290                      | Heltec | ESP32    | SX1262    | ✅          |
| Heltec Mesh Solar                | Heltec | ESP32    | SX1262    | ✅          |
| Heltec T114                      | Heltec | ESP32-S3 | SX1262    | ✅          |
| Heltec T190                      | Heltec | ESP32    | SX1262    | ✅          |
| Heltec Tracker                   | Heltec | ESP32-S3 | SX1262    | ✅          |
| Heltec Tracker V2                | Heltec | ESP32-S3 | SX1262    | ✅          |
| LilyGo T-Beam 1W                 | LilyGo | ESP32    | SX1262    | ✅          |
| LilyGo T-Beam SX1262             | LilyGo | ESP32    | SX1262    | ✅          |
| LilyGo T-Beam SX1276             | LilyGo | ESP32    | SX1276    | ✅          |
| LilyGo T-Beam Supreme            | LilyGo | ESP32-S3 | SX1262    | ✅          |
| RAK4631 WisBlock                 | RAK    | nRF52840 | SX1262    | ✅          |
| RAK3112                          | RAK    | nRF52840 | SX1262    | ✅          |
| RAK3401                          | RAK    | nRF52840 | SX1262    | ✅          |
| RAK3x72                          | RAK    | nRF52840 | SX1262    | ✅          |
| RAK11310                         | RAK    | RP2040   | SX1262    | ✅          |
| Seeed XIAO ESP32-S3 + Wio SX1262 | Seeed  | ESP32-S3 | SX1262    | ✅ Verified |

## Local Testing

### Build a single target

```bash
pio run -e heltec_v3
```

### Run linting

```bash
pre-commit run --all-files
```

### Run unit tests

```bash
python3 test/test_integration.py
```

## CI/CD Configuration Files

- `.gitea/workflows/ci.yml` — Main CI pipeline
- `.gitea/workflows/build-matrix.yml` — Detailed build matrix with per-target metadata
- `.pre-commit-config.yaml` — Pre-commit hooks (clang-format, markdownlint, etc.)
- `.clang-format` — Code formatting rules (LLVM style, 88-char lines)
- `.clang-tidy` — Static analysis rules (C++ naming, magic numbers, etc.)
- `platformio.ini` — Build configuration for all targets

## Caching

PlatformIO dependencies are cached per SoC architecture:

- `esp32`, `esp32s3` — Share cache
- `nrf52` — Separate cache
- `rp2040` — Separate cache

Cache is keyed by `platformio.ini` to invalidate on dependency changes.

## Build Status Badge

Add to README.md:

```markdown
[![Build Status](https://gitea.example.com/path/to/loramodem/badges/build.svg)](https://gitea.example.com/path/to/loramodem/actions)
```

## Troubleshooting

### Build fails for all targets

1. Check `platformio.ini` syntax: `pio run -e heltec_v3 -vv`
2. Clear cache: `rm -rf ~/.platformio`
3. Check pre-commit: `pre-commit run --all-files`

### Build fails for specific target

1. Check board configuration: `hardware/<vendor>/<board>/platformio.ini`
2. Verify pin definitions
3. Check SoC configuration: `soc/<soc>/platformio.ini`

### Tests fail in CI but pass locally

1. Check Python version: CI uses 3.11, ensure local is compatible
2. Check environment: CI runs on Ubuntu, may differ from macOS/Windows
3. Run tests with verbose: `pytest -vv test/`

## Next Steps

- [ ] Hardware flashing job (needs USB device access)
- [ ] Integration tests with modem simulator
- [ ] Firmware size reports per target
- [ ] Documentation generation
- [ ] Release artifact creation