native runner

.gitignore

@@ -9,6 +9,7 @@
 
 # PlatformIO
 .pio/
+__pycache__/
 
 # Local design scratch (chat transcript, not a repo artifact)
 /STRUCTURE.md

README.md

@@ -93,6 +93,19 @@ cc -std=c99 -Wall -Wextra -Isrc \
    examples-linux/tty_bridge/meshcore_tty.c src/meshcore_companion.c -o meshcore_tty
 ```
 
+### Host test via PlatformIO
+
+The repo also ships a `platformio.ini` with a host `native` environment, so you
+can run the same codec test through PlatformIO with no hardware:
+
+```sh
+pio test -e native
+```
+
+This compiles only the portable C core (`src/*.c`) plus `test/test_codec.c`; the
+C++ Arduino wrapper is excluded (it needs `<Arduino.h>`). Pass/fail is driven by
+the test program's exit code via a tiny custom runner (`test/test_custom_runner.py`).
+
 ## Other platform examples (same C core)
 
 Each example compiles `src/meshcore_companion.c` directly and supplies only a

platformio.ini

@@ -0,0 +1,18 @@
+; PlatformIO project manifest.
+;
+; This repo is primarily a *library* (see library.json / library.properties),
+; but this manifest also defines a host "native" environment so the portable C
+; core can be built and unit-tested on your computer with no hardware:
+;
+;     pio test -e native
+;
+; It compiles only the portable C core (src/*.c) plus the test in test/. The C++
+; Arduino wrapper (src/*.cpp) is excluded here because it needs <Arduino.h>,
+; which only exists in a real Arduino/PlatformIO board build.
+
+[env:native]
+platform = native
+test_framework = custom
+test_build_src = yes
+build_src_filter = +<*.c> -<*.cpp>
+build_flags = -std=c99 -Wall -Wextra -Isrc

test/test_custom_runner.py

@@ -0,0 +1,17 @@
+# PlatformIO custom test runner for the host "native" environment.
+#
+# test_codec.c is a plain C program with its own main() that prints results and
+# returns a non-zero exit code if any check fails. The "custom" test framework
+# (set in platformio.ini) means PlatformIO does NOT inject Unity's main/runner;
+# it just builds and runs our program and reports failure on a non-zero exit.
+# This minimal subclass is all that's needed to wire that up.
+#
+#     pio test -e native
+#
+# SPDX-License-Identifier: MIT
+
+from platformio.public import TestRunnerBase
+
+
+class CustomTestRunner(TestRunnerBase):
+    pass