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):

cmake -S . -B build -G Ninja

Configure with coverage:

cmake -S . -B build-cov -G Ninja -DENABLE_COVERAGE=ON

Build:

ninja -C build

Run tests (full Unity output, colored):

ninja -C build check

Run tests (CTest summary only):

ninja -C build test

Run tests and generate coverage HTML:

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):

cat > RELEASES.md << 'EOF'
# Releases

## 0.2.0 (2026-01-01)

Short summary.

### Library (`celrs`)

- **Feature**: description.
EOF

Create the annotated tag:

git tag -a v0.1.0 -F RELEASES.md

Verify:

git show v0.1.0

Remove the temporary file:

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:

  cmake -S . -B build -G Ninja
  

• This file (AGENTS.md) follows its own rules.

Source Layout

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:

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:

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:

#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)