Zephyrtastic

A Zephyr RTOS port of the Meshtastic mesh networking stack, with a focus on getting Heltec V4 boards working.

Disclaimer: This project is not affiliated with or endorsed by Meshtastic LLC. Meshtastic® is a registered trademark of Meshtastic LLC.

Goals

• Bring up Heltec WiFi LoRa 32 boards (ESP32-S3 + Semtech SX1262) as first-class targets.
• Experiment with different ways to configure individual nodes and groups of nodes.
• Experiment with different ways to perform firmware updates.

The target is the Heltec V4 rev 4.2. Other Heltec V4 variants share the same architecture and should work, but are currently untested. See docs/heltec-boards.md for per-board specs (MCU, PSRAM, flash layout, FEM, and pin mapping).

This is early-stage, actively-developed work. Expect gaps and breaking changes.

It is also, candidly, a learning project — a way to get hands-on with Zephyr RTOS internals and the Meshtastic protocol stack. It is not affiliated with the Meshtastic project and comes with no guarantees of correctness, completeness, or regulatory compliance. Caveat emptor: understand your local RF regulations and verify behavior before relying on it.

Building

Provision a standalone workspace using this repository as the west manifest:

west init -m https://github.com/roperscrossroads/zephyrtastic --mr main <workspace>
cd <workspace>
west update

Build the sample for a supported board. Board targets need their full qualifier — the bare board name is rejected:

west build -b heltec_wifi_lora32_v4/esp32s3/procpu samples/meshtastic

Note this repository is a Zephyr module, not an application: its top-level CMakeLists.txt is included by the build rather than being an entry point. Build samples/meshtastic, not the repository root.

See samples/meshtastic/README.rst for build options and optional features (BLE, GNSS, shell, MQTT, telemetry).

For the detailed feature matrix and shell command reference, see README.rst.

Testing

The native_sim ztest suites are the pre-hardware proof tier — tests/protocol (wire format, routing, MQTT downlink), tests/admin_pki (the real X25519 + AES-CCM remote-admin path) and tests/shell (the console write surface and its is_managed gate). Run them all from the workspace:

west twister -T tests -p native_sim/native/64 --inline-logs

CI runs exactly this on every push and pull request (.github/workflows/sim.yml).

Sim-green is necessary but not sufficient — the radio PHY is mocked, and several subsystems are gated out of the suites entirely. Anything touching modulation, timing, regional frequencies, flash durability, or power draw needs real hardware before it can be called proven.

Wire compatibility

tests/vectors/meshtastic_vectors.h holds known-answer vectors harvested by compiling and running upstream firmware's own functions, so that a symmetric error — one where our encoder and decoder are wrong in the same way, and every self-loopback test still passes — is caught. The wire_vectors suite asserts against them and needs no upstream tree.

A scheduled job re-checks those vectors against upstream at HEAD and reports when an algorithm we depend on has changed. It is intentionally not a merge gate. See tools/vectors/README.md for the trust model and how to re-harvest.

Credit

Zephyrtastic builds directly on the excellent meshtastic-zephyr project by Benjamin Cabé (@kartben), which established a clean, Zephyr-native Meshtastic stack from scratch. That work is the foundation for everything here, and I'm grateful that he shared it.

I am learning about Zephyr OS and the inner workings of Meshtastic, and I expect this to heavily diverge. Zephyrtastic starts from upstream commit 1365e7c. All original attribution and the GPL-3.0 license are preserved.

License

GPL-3.0, matching both the upstream Meshtastic firmware and the original meshtastic-zephyr project. See LICENSE.