celrs/AGENTS.md

# AGENTS.md

## Project Overview

`celrs` is a C23 project for interfacing with ELRS TX modules via serial
USB using the CRSF (Crossfire Serial) protocol. Wired for test-driven
development using Unity and CMock.

## Build System

- **Generator:** Ninja
- **CMake minimum:** 3.21
- **C standard:** C23

### Commands

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

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

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

Run tests (full Unity output, colored):
```sh
ninja -C build check
```

Run tests (CTest summary only):
```sh
ninja -C build test
```

Run tests and generate coverage HTML:
```sh
ninja -C build-cov coverage
```

### Dependencies

Dependencies are managed via custom `Find*.cmake` scripts in `deps/`.
These scripts use `FetchContent` under the hood to download and build
libraries automatically.

To add a new dependency:

1. Add the corresponding `Find<name>.cmake` to `deps/`
2. Add `find_package(<name> REQUIRED)` to `CMakeLists.txt`
3. Link with `<name>::<name>` in `target_link_libraries()`

### CMake Module Path

`deps/` is added to `CMAKE_MODULE_PATH` so `find_package()` resolves
to the custom scripts instead of system-installed packages.

## Coding Conventions

- **Language:** C23
- **Trailing return type** for function signatures (e.g. `auto fn() -> void`)
- **4-space indentation**
- `auto` for obvious types (e.g. `auto main(...) -> int`)
- **East const** (e.g. `char const*` not `const char*`)
- **Naming:** `snake_case` for variables, functions, and types
- **Naming:** `SCREAMING_SNAKE_CASE` only for macros and constants
- Include order:
  1. C standard library headers (`<stdlib.h>`, `<string.h>`, etc.)
  2. *(blank line)*
  3. OS-specific headers (Windows API, POSIX, etc.)
  4. *(blank line)*
  5. Local/project headers

## Shell Scripts

- Always use `#!/bin/sh` shebang for shell scripts
- Scripts must be POSIX compliant (no bashisms)
- When providing commands to users:
  - Windows/PowerShell: use `` ` `` for line continuation
  - Unix/Linux/macOS: use `\` for line continuation

## Commit Messages

- Follow the 50/72 rule:
  - Subject line: max 50 characters
  - Body lines: wrapped at 72 characters
- Use conventional commit prefixes (`feat:`, `fix:`, `docs:`, `chore:`,
  etc.)
- Separate subject from body with a blank line
- Do **not** add yourself as a co-author (`Co-Authored-By:` trailers are
  forbidden)

Example:

```
feat: add CRSF CRC8 calculation

Implement CRC8-CCITT (poly 0x07) for CRSF frame validation.
Added unit tests for empty, single-byte, and known-value cases.
```

## Tag Releases

Use annotated tags for releases. Write the release notes to a temporary
file, then use it as the tag message. Do **not** commit the release
notes file.

Write release notes (see previous tags for style reference):
```sh
cat > RELEASES.md << 'EOF'
# Releases

## 0.2.0 (2026-01-01)

Short summary.

### Library (`celrs`)

- **Feature**: description.
EOF
```

Create the annotated tag:
```sh
git tag -a v0.1.0 -F RELEASES.md
```

Verify:
```sh
git show v0.1.0
```

Remove the temporary file:
```sh
rm RELEASES.md
```

Release notes follow the same Markdown rules as `AGENTS.md` (80-column
wrap, no em dashes, etc.). Version format is `v<major>.<minor>.<patch>`.

## Documentation (Markdown)

- Wrap normal text and lists at **max 80 columns** (for readability in
  terminals and editors).
- **Exceptions**: Tables and code blocks (```` ``` ````) can exceed 80
  columns when formatting requires it (e.g. trees, alignment).
- Use standard Markdown: `**bold**`, `` `inline code` ``, `##` headings,
  `-` or numbered lists, fenced code blocks with language hints
  (```` ```c ````, ```` ```sh ````).
- Keep examples concise, up-to-date, and self-documenting.
- Do not use em dashes (`—`). Use a colon or rewrite the sentence.
- Each shell command gets its own fenced code block; do **not** combine
  multiple commands into one block. Precede each block with a short
  plain-text label describing what the command does:

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

- This file (`AGENTS.md`) follows its own rules.

## Source Layout

```text
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
```

## TDD Workflow

This project follows Red-Green-Refactor. All changes to testable source
files under `celrs/` should be test-driven: write a failing test first,
then implement.

### Adding a new module

1. Create `celrs/<module>.h` with the public prototype.
2. Create `tests/test_<module>.c`. Set CMock expectations for any
  dependency calls, then assert the result.
3. Register the test in `tests/CMakeLists.txt`:

```cmake
add_executable(test_module test_module.c)
target_include_directories(test_module PRIVATE "${CMAKE_SOURCE_DIR}")
target_link_libraries(test_module PRIVATE celrs_module Unity::Unity CMock::CMock)
target_compile_features(test_module PRIVATE c_std_23)
cmock_generate_mock(test_module "${CMAKE_SOURCE_DIR}/celrs/dep.h")
add_test(NAME test_module COMMAND test_module)
list(APPEND TEST_TARGETS test_module)
```

4. Stub `celrs/<module>.c` with a dummy return, confirm RED, implement,
  confirm GREEN:

```sh
ninja -C build check
```

### Mocking a dependency

Use `cmock_generate_mock` in the test target to generate a mock from a
header. Include `Mock<name>.h` in the test and use the generated API:

```c
#include "Mockdep.h"

void setUp(void)    { Mockdep_Init(); }
void tearDown(void) { Mockdep_Verify(); Mockdep_Destroy(); }

void test_something(void) {
    dep_fn_ExpectAndReturn(arg, expected);
    TEST_ASSERT_TRUE(module_do_thing());
}
```

## Behavioral Guidelines

Reduce common LLM coding mistakes. Bias toward caution over speed.
For trivial tasks, use judgment.

### Think Before Coding

- State assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them, don't pick silently.
- If something is unclear, stop. Name what's confusing. Ask.

### Simplicity First

Minimum code that solves the problem. Nothing speculative.

- No features beyond what was asked.
- No abstractions for single-use code.
- If you write 200 lines and it could be 50, rewrite it.

### Surgical Changes

Touch only what you must. Clean up only your own mess.

- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

### Goal-Driven Execution

Transform tasks into verifiable goals:

- "Add validation" means: write tests for invalid inputs, then pass.
- "Fix the bug" means: write a test that reproduces it, then pass.
- "Refactor X" means: ensure tests pass before and after.

## Platform Support

The project supports Windows, Linux, macOS, Emscripten, and Android via
`Platform.cmake` and `Flags.cmake` in `deps/`.

## CRSF Protocol Notes

CRSF is the Crossfire Serial Protocol used by ELRS. Key points:

- Frame format: [addr][length][type][payload...][crc]
- CRC8/DVB-S2 with polynomial `0xD5`, init `0x00`
- CRC is computed over: type + payload
- Address byte varies: `0xC8` (host), `0xEE` (module), `0xEF` (lua)
- Standard baud rate for ELRS CRSF is 400000 bps (probe 921600 first)