From 6a6b9dd567379f0c83a11aa6cae7862516be1103 Mon Sep 17 00:00:00 2001
From: Scott Penrose <scooter.me@gmail.com>
Date: Mon, 8 Jun 2026 02:38:50 +1000
Subject: [PATCH] native runner

---
 .gitignore                 |  1 +
 README.md                  | 13 +++++++++++++
 platformio.ini             | 18 ++++++++++++++++++
 test/test_custom_runner.py | 17 +++++++++++++++++
 4 files changed, 49 insertions(+)
 create mode 100644 platformio.ini
 create mode 100644 test/test_custom_runner.py

diff --git a/.gitignore b/.gitignore
index 943861c..72d1bf3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,7 @@
 
 # PlatformIO
 .pio/
+__pycache__/
 
 # Local design scratch (chat transcript, not a repo artifact)
 /STRUCTURE.md
diff --git a/README.md b/README.md
index b0fc377..38bf334 100644
--- a/README.md
+++ b/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
diff --git a/platformio.ini b/platformio.ini
new file mode 100644
index 0000000..b0545ee
--- /dev/null
+++ b/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
diff --git a/test/test_custom_runner.py b/test/test_custom_runner.py
new file mode 100644
index 0000000..955a0d9
--- /dev/null
+++ b/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