Inital commit

2026-06-14 19:48:37 +02:00
commit cd7d411332
30 changed files with 1645 additions and 0 deletions
@@ -0,0 +1,147 @@
+# celrs
+
+A C23 project for interfacing with ELRS TX modules (e.g., BAYCK Nano Dual
+Band) via serial USB using the CRSF (Crossfire Serial) protocol.
+
+Built on the same TDD foundation as [ctdd](https://github.com/PorterSky/ctdd)
+using [Unity](https://github.com/ThrowTheSwitch/Unity) and
+[CMock](https://github.com/ThrowTheSwitch/CMock).
+
+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.
+
+## Run
+
+Connect your ELRS TX module via USB, then run:
+
+Windows:
+```sh
+./build/main.exe COM3
+```
+
+Linux / macOS:
+```sh
+./build/main /dev/ttyUSB0
+```
+
+## Architecture
+
+```
+celrs/
+  crsf.h / crsf.c      CRSF protocol: CRC8, frame parse/build
+  serial.h / serial.c  Serial port abstraction (Win/POSIX)
+  logger.h / logger.c  Level-filtering logger
+  log_write.h/.c       stdout log sink
+main.c                 Entry point — demo heartbeat + read
+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
+
+```
+------+------+------+------+-------+-------+
+| 0xC8 | dest | src  | type | size  | ...   |  CRC  |
+------+------+------+------+-------+-------+
+  1 byte  1B     1B     1B     1B     N B     1 byte
+```
+
+- **Header:** Always `0xC8`
+- **Destination:** Target device address
+- **Source:** Sender device address
+- **Type:** Frame type (heartbeat, RC channels, telemetry, etc.)
+- **Size:** Payload length in bytes
+- **Payload:** Frame-specific data
+- **CRC:** CRC8-CCITT over dest+src+type+size+payload
+
+### Common device addresses
+
+| Address | Device                        |
+| ------- | ----------------------------- |
+| 0x00    | FC Broadcast                  |
+| 0x10    | Flight Controller             |
+| 0x80    | TBS Ground Station            |
+| 0xEA    | Custom Module                 |
+| 0xDD    | RC Device                     |
+
+### Common frame types
+
+| Type   | Name                        |
+| ------ | --------------------------- |
+| 0x01   | RC Channels Packed          |
+| 0x02   | Packet Link Telemetry       |
+| 0x03   | Heartbeat                   |
+| 0x08   | Device Info                 |
+| 0x09   | Parameter List              |
+| 0x17   | MSP Read                    |
+| 0x18   | MSP Write                   |