Initial import of open-sent-c

SAE J2716 SENT protocol implementation in C, extracted from the
SENTToUSB STM32F042 firmware. Layout: public headers at root, sources
and platform ports under implementation/.

Author: Lukasz-Juranek

.github/workflows/test.yml

@@ -0,0 +1,54 @@
+name: tests
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc gcovr
+
+      - name: Build tests
+        working-directory: implementation/Tests
+        run: make all
+
+      - name: Run tests
+        working-directory: implementation/Tests
+        run: make run
+
+      - name: Coverage summary (gcov)
+        working-directory: implementation/Tests
+        run: make coverage
+
+      - name: Coverage report (gcovr)
+        working-directory: implementation/Tests
+        run: |
+          gcovr build/lib --root ../.. \
+                --exclude '.*hal_host\.c' \
+                --exclude '.*hal_stm32f042\.c' \
+                --exclude-lines-by-pattern '.*GCOV_EXCL_LINE.*' \
+                --exclude-branches-by-pattern '.*GCOV_EXCL_BR_LINE.*' \
+                --exclude-branches-by-pattern '.*SENT_ASSERT.*' \
+                --exclude-branches-by-pattern '.*manager != NULL.*' \
+                --gcov-ignore-errors=no_working_dir_found \
+                --print-summary \
+                --txt build/coverage.txt \
+                --xml build/coverage.xml
+          cat build/coverage.txt
+
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: implementation/Tests/build/coverage.*
+          retention-days: 90

.gitignore

@@ -0,0 +1,40 @@
+# Build artefacts
+*.o
+*.obj
+*.a
+*.lib
+*.so
+*.so.*
+*.dylib
+*.dll
+*.exe
+*.elf
+*.bin
+*.hex
+*.map
+*.lst
+*.d
+
+# Build directories
+build/
+out/
+dist/
+cmake-build-*/
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+*~
+.cache/
+compile_commands.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Coverage / debug
+*.gcno
+*.gcda
+*.gcov
+coverage/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ucandevices
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,91 @@
+# open-sent-c
+
+[![tests](https://github.com/ucandevices/open-sent-c/actions/workflows/test.yml/badge.svg)](https://github.com/ucandevices/open-sent-c/actions/workflows/test.yml)
+
+A portable C implementation of the SAE J2716 SENT (Single Edge Nibble Transmission)
+protocol for embedded systems and host-side tooling.
+
+## Layout
+
+```
+.
+├── *.h                 public API headers
+└── implementation/     library sources (.c) and platform ports
+```
+
+The protocol layer (`sent_protocol`, `sent_encoder`, `sent_decoder`, `sent_crc`)
+is MCU-agnostic and uses the `hal.h` function-pointer interface to talk to
+hardware. Platform-specific ports live alongside the protocol code:
+
+- `hal_stm32f042.{h,c}` — STM32F042 (TIM input-capture RX, software TX) port
+- `hal_host.{h,c}` — host-side stub for unit tests
+
+## Public API
+
+- `sent_protocol.h` — frame/config types, nibble packing
+- `sent_encoder.h` — frame → tick intervals → microsecond timestamps
+- `sent_decoder.h` — microsecond timestamps → decoded frame
+- `sent_crc.h` — SAE J2716 4-bit CRC
+- `mode_manager.h` — RX/TX/STOPPED state machine + statistics
+- `hal.h` / `hal_config.h` — RX/TX HAL interfaces a port must implement
+
+## Usage
+
+The library has no build system of its own — drop the headers on your
+include path and compile the relevant `.c` files in `implementation/`
+into your project. Pick the HAL port that matches your target (or write
+your own against `hal.h`).
+
+## Testing
+
+Unit tests live in `implementation/Tests/` and are built with plain GCC
+(`-std=c99`). They use a single-header framework (`test.h`) with no external
+dependencies.
+
+```sh
+cd implementation/Tests
+make run       # build and run all tests
+make coverage  # run tests + enforce 100% line and branch coverage
+```
+
+Coverage is measured with **gcov/gcovr**. The `make coverage` target requires
+both tools to be on `PATH` (`apt-get install gcc gcovr` on Debian/Ubuntu) and
+fails if either metric drops below 100%.
+
+### CI
+
+A GitHub Actions workflow (`.github/workflows/test.yml`) runs on every push
+and pull request to `master`/`main`:
+
+1. Builds the test binary with `-O0 --coverage`.
+2. Runs all 126 tests — the job fails on any failing test.
+3. Generates a gcovr XML + text report and uploads it as a build artifact.
+
+Genuinely unreachable branches (dead code protected by configuration
+invariants) are annotated with `/* GCOV_EXCL_BR_LINE */` or suppressed via
+gcovr pattern filters so they do not inflate the denominator.
+
+### Coverage artifacts
+
+After each CI run the coverage report is uploaded as a GitHub Actions artifact
+named **`coverage`** and retained for 90 days. To download it:
+
+1. Open the [Actions tab](https://github.com/ucandevices/open-sent-c/actions).
+2. Click any completed workflow run.
+3. Scroll to the **Artifacts** section at the bottom of the page and download `coverage.zip`.
+
+The zip contains:
+- `coverage.txt` — human-readable summary table
+- `coverage.xml` — Cobertura XML (compatible with SonarQube, Codecov, VS Code extensions)
+
+## Reference integration
+
+[**SENTToUSB**](https://github.com/ucandevices/SENTToUSB) is a reference
+firmware project that integrates this library on an STM32F042 to expose a
+SENT sensor as a USB CDC / CAN device. It demonstrates the full stack:
+HAL port (`hal_stm32f042`) wired to real hardware timers and CAN-frame
+transport over USB.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

hal.h

@@ -0,0 +1,59 @@
+#ifndef SENT_HAL_H
+#define SENT_HAL_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "sent/hal_config.h"
+#include "sent/sent_protocol.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef bool (*sent_rx_start_fn)(void* context);
+typedef void (*sent_rx_stop_fn)(void* context);
+typedef bool (*sent_rx_poll_timestamps_fn)(void* context,
+                                           uint32_t* out_timestamps_us,
+                                           size_t* inout_timestamp_count);
+/* Optional: update capture_batch_size when data_nibbles changes.
+ * Called by bridge config handler and bridge_start_rx. May be NULL. */
+typedef void (*sent_rx_set_data_nibbles_fn)(void* context, uint8_t data_nibbles);
+
+/* Optional: update sync-detection threshold [µs] to match the configured tick
+ * range.  Called by bridge when min/max_tick_x10_us changes.  May be NULL. */
+typedef void (*sent_rx_set_sync_min_us_fn)(void* context, uint32_t sync_min_us);
+
+typedef bool (*sent_tx_start_fn)(void* context);
+typedef void (*sent_tx_stop_fn)(void* context);
+typedef bool (*sent_tx_submit_frame_fn)(void* context,
+                                        const sent_frame_t* frame,
+                                        const sent_config_t* config,
+                                        uint16_t pause_ticks);
+/* Optional: set the TX tick period (HAL reprograms its timebase).
+ * tick_x10_us is in 0.1-us units (e.g. 30 = 3.0 us).  May be NULL. */
+typedef bool (*sent_tx_set_tick_fn)(void* context, uint16_t tick_x10_us);
+
+typedef struct {
+    void* context;
+    sent_rx_start_fn start_rx;
+    sent_rx_stop_fn stop_rx;
+    sent_rx_poll_timestamps_fn poll_timestamps_us;
+    sent_rx_set_data_nibbles_fn set_data_nibbles;  /* optional, NULL if not supported */
+    sent_rx_set_sync_min_us_fn  set_sync_min_us;   /* optional, NULL if not supported */
+} sent_rx_hal_t;
+
+typedef struct {
+    void* context;
+    sent_tx_start_fn start_tx;
+    sent_tx_stop_fn stop_tx;
+    sent_tx_submit_frame_fn submit_frame;
+    sent_tx_set_tick_fn set_tick_x10_us;  /* optional, NULL if not supported */
+} sent_tx_hal_t;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  /* SENT_HAL_H */

hal_config.h

@@ -0,0 +1,16 @@
+#ifndef SENT_HAL_CONFIG_H
+#define SENT_HAL_CONFIG_H
+
+#if defined(SENT_HAL_HOST) && defined(SENT_HAL_STM32F042)
+#error "Only one HAL backend can be enabled at a time."
+#endif
+
+#if !defined(SENT_HAL_HOST) && !defined(SENT_HAL_STM32F042)
+#if defined(STM32F042x6)
+#define SENT_HAL_STM32F042 1
+#else
+#define SENT_HAL_HOST 1
+#endif
+#endif
+
+#endif  /* SENT_HAL_CONFIG_H */

hal_host.h

@@ -0,0 +1,69 @@
+#ifndef SENT_HAL_HOST_H
+#define SENT_HAL_HOST_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "sent/hal.h"
+
+#if defined(SENT_HAL_HOST)
+#include <pthread.h>
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define SENT_HOST_RX_MAX_BATCHES 64U
+#define SENT_HOST_RX_MAX_TIMESTAMPS 32U
+
+typedef struct {
+    uint32_t timestamps_us[SENT_HOST_RX_MAX_TIMESTAMPS];
+    size_t count;
+} sent_host_rx_batch_t;
+
+typedef struct {
+#if defined(SENT_HAL_HOST)
+    pthread_mutex_t lock;
+#endif
+    bool running;
+    sent_host_rx_batch_t queue[SENT_HOST_RX_MAX_BATCHES];
+    size_t head;
+    size_t tail;
+} sent_host_rx_hal_t;
+
+typedef struct {
+#if defined(SENT_HAL_HOST)
+    pthread_mutex_t lock;
+#endif
+    bool running;
+    bool has_last_frame;
+    sent_frame_t last_frame;
+    uint16_t last_intervals_ticks[SENT_MAX_INTERVALS];
+    size_t last_intervals_count;
+} sent_host_tx_hal_t;
+
+void sent_host_rx_hal_init(sent_host_rx_hal_t* hal);
+void sent_host_rx_hal_deinit(sent_host_rx_hal_t* hal);
+bool sent_host_rx_hal_inject(sent_host_rx_hal_t* hal,
+                             const uint32_t* timestamps_us,
+                             size_t timestamp_count);
+bool sent_host_rx_hal_running(const sent_host_rx_hal_t* hal);
+size_t sent_host_rx_hal_pending_batches(const sent_host_rx_hal_t* hal);
+void sent_host_make_rx_hal(sent_host_rx_hal_t* impl, sent_rx_hal_t* out_hal);
+
+void sent_host_tx_hal_init(sent_host_tx_hal_t* hal);
+void sent_host_tx_hal_deinit(sent_host_tx_hal_t* hal);
+bool sent_host_tx_hal_running(const sent_host_tx_hal_t* hal);
+bool sent_host_tx_hal_last_frame(const sent_host_tx_hal_t* hal, sent_frame_t* out_frame);
+size_t sent_host_tx_hal_last_intervals(const sent_host_tx_hal_t* hal,
+                                       uint16_t* out_intervals,
+                                       size_t max_count);
+void sent_host_make_tx_hal(sent_host_tx_hal_t* impl, sent_tx_hal_t* out_hal);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  /* SENT_HAL_HOST_H */