# celrs

A C23 library and CLI tools for interfacing with ELRS TX modules (e.g.,
BAYCK Nano Dual Band) via serial USB using the CRSF (Crossfire Serial)
protocol.

All dependencies are fetched automatically via CMake `FetchContent`. No
manual installation required beyond the tools listed below.

## Requirements

| Tool         | Purpose                                               |
| ------------ | ----------------------------------------------------- |
| CMake ≥ 3.21 | Build system                                          |
| Ninja        | Build backend                                         |
| C23 compiler | GCC 14+, Clang 18+                                    |
| Ruby ≥ 3.0   | CMock mock generation                                 |
| gcovr ≥ 6.0  | Coverage reports - optional (`uv tool install gcovr`) |

## Build

Configure:
```sh
cmake -S . -B build -G Ninja
```

Build:
```sh
ninja -C build
```

## Test

Full Unity output with colors:
```sh
ninja -C build check
```

CTest summary only:
```sh
ninja -C build test
```

`check` builds all suites and runs CTest with `--output-on-failure`,
so assertion-level detail appears on any failure without running
binaries by hand.

## Coverage

Configure with coverage instrumentation:
```sh
cmake -S . -B build-cov -G Ninja -DENABLE_COVERAGE=ON
```

Generate the HTML report:
```sh
ninja -C build-cov coverage
```

Open `build-cov/coverage/index.html` in a browser to view results.

Only `celrs/` source files are measured. Unity, CMock, and generated
mock files are excluded. Requires GCC or Clang with gcov support, and
`gcovr` on `PATH`.

> **Windows note:** requires GCC (e.g. `scoop install gcc`) or a Clang
> build that includes compiler-rt. A custom Clang without compiler-rt
> will fail at link time.

## Architecture

```
celrs/
  crsf.h / crsf.c         CRSF protocol: CRC8/DVB-S2, frame build/parse
  crsf_telemetry.h/.c     Telemetry frame decoders (GPS, battery, link..)
  crsf_stream.h/.c        Incremental streaming frame reader
  crsf_param.h/.c         Parameter protocol (read/write/set_power)
  serial.h / serial.c     Serial port abstraction (Win/POSIX)
  logger.h / logger.c     Level-filtering logger
  log_write.h/.c          stdout log sink
tools/
  telemetry.c             Telemetry read tool
tests/
  test_crsf.c             CRSF CRC, parse, build tests
  test_serial.c           Serial open/close/stub tests
  test_logger.c           Logger level-filtering tests
deps/
  FindUnity.cmake         Fetches Unity v2.6.1 via ZIP
  FindCMock.cmake         Fetches CMock v2.6.0 via ZIP
```

## CRSF Protocol

CRSF (Crossfire Serial Protocol) is the serial protocol used by ELRS for
communication between ground station and TX/RX modules.

### Frame format (ELRS USB CRSF)

```
+--------+----------+--------+----------+-----+
| addr   | length   | type   | payload  | CRC |
+--------+----------+--------+----------+-----+
  1 byte   1 byte    1 byte    N bytes   1B
```

- **Address:** Frame sync byte (`0xC8` for host, `0xEE` for module, etc.)
- **Length:** Total bytes after this field (type + payload + CRC)
- **Type:** Frame type (RC channels, telemetry, parameter, etc.)
- **Payload:** Frame-specific data
- **CRC:** CRC8/DVB-S2 (poly `0xD5`) over type + payload

### Common device addresses

| Address | Device                        |
| ------- | ----------------------------- |
| 0x00    | FC Broadcast                  |
| 0x10    | Flight Controller             |
| 0x80    | TBS Ground Station            |
| 0xEA    | Custom Module (Radio)         |
| 0xEE    | ELRS TX Module                |
| 0xEF    | ELRS Lua (host script)        |

### Common frame types

| Type   | Name                        |
| ------ | --------------------------- |
| 0x01   | RC Channels Packed          |
| 0x02   | GPS                         |
| 0x08   | Battery                     |
| 0x0B   | Heartbeat                   |
| 0x14   | Link Stats                  |
| 0x16   | RC Channels                 |
| 0x28   | Device Ping                 |
| 0x29   | Device Info                 |
| 0x2B   | Parameter Entry             |
| 0x2C   | Parameter Read              |
| 0x2D   | Parameter Write             |
| 0x2E   | ELRS Status                 |