ZephCore — MeshCore for Zephyr RTOS

A port of MeshCore LoRa mesh firmware from Arduino to Zephyr RTOS. Aiming for full protocol compatibility with the original Arduino firmware and the MeshCore mobile apps.

DISCLAIMER: I did this to be a PoC for my Wio Tracker and nRF repeater. The porting flow was this:

• Copy the meshcore companion source and hit it with a hammer named Claude until the FW works on the node
• if the FW is stable, hit it until it works with the official app
• if both goal is reached, hit the repeater fw and make it work exactly like the arduino counterpart
• Add T1000 and make LR1110 work
• try to fix a thousand bugs that the hammering did
• Add new boards that doesn't even work on arduino (that was not a choice....)
• Try to make it universal so new boards/radios/whatever can be plugged in
• Try to clean up the code and hunt down anything that I've missed <-- YOU ARE HERE NOW
• Revise everything once again, try to understand more than just a quarter of it
• Cleanup-debug--port upstream changes-anything that pops in my mind
• ???
• Profit

Wio Tracker L1 companion and Ikoka Nano 30dB repeater is working according to my tests, I can't vouch for anything else yet. It's compatible with the current bootloaders I use, so I can roll back to arduino version easily and I have DFU. Repeater's "touch 1200" and other methods to enter DFU aren't tested yet.

And now, the sacred AI texts:

Why Zephyr?

The Arduino version uses a loop(). This port replaces that with Zephyr's event-driven primitives (k_event_wait, k_poll, k_msgq), so the CPU sleeps in WFI (Wait For Interrupt) between events.

Other benefits:

• Proper driver model -- LoRa, GNSS, display, sensors, and BLE all use Zephyr subsystem drivers rather than Arduino libraries
• Hierarchical build configuration -- board-specific settings compose cleanly via Kconfig and devicetree overlays
• DFU support -- generates Arduino compatible zip packages for OTA updates and UF2 binaries for drag-and-drop flashing
• Back and forth compatible -- Adapted to softdevice and adafruit's bootloader, so no bootloader re-flashing required.

Supported Boards

Board	MCU	Radio	Extras
Wio Tracker L1	nRF52840	SX1262	GPS (L76K), OLED display, joystick, buzzer, QSPI flash
Seeed T1000-E	nRF52840	LR1110	GPS (Mediatek AG3335), LEDs, button
Ikoka Nano 30dBm	XIAO nRF52840	SX1262 (E22-900M30S, 30dBm PA)	RGB LEDs

Device Roles

Companion (default)

Repeater

Building

Prerequisites: Zephyr SDK and west installed.

# Initialize workspace (first time only)
cd %cloned folder%
west init -l zephcore
west update

# Companion (with logging)
west build -b wio_tracker_l1 zephcore --pristine

# Companion (production, no logging)
west build -b wio_tracker_l1 zephcore --pristine -- \
 -DEXTRA_CONF_FILE="boards/common/prod.conf"

# Repeater (with logging)
west build -b rak4631/nrf52840 zephcore --pristine -- \
  -DEXTRA_CONF_FILE="boards/common/repeater.conf"

# Repeater (production)
west build -b rak4631/nrf52840 zephcore --pristine -- \
  -DEXTRA_CONF_FILE="boards/common/repeater.conf;boards/common/prod.conf"

# Repeater with packet logging (clean RAW/RX/TX lines only, no debug spam)
west build -b rak4631/nrf52840 zephcore --pristine -- \
  -DEXTRA_CONF_FILE="boards/common/repeater.conf;boards/common/packet_logging.conf"

# Formatter (with serial logging)
west build -b wio_tracker_l1 zephcore/tools/formatter --pristine

# Companion (BLE debug logging)
west build -b rak4631/nrf52840 zephcore --pristine -- -DCONFIG_ZEPHCORE_BLE_LOG_LEVEL_DBG=y

Output binaries are in build/zephyr/ -- .hex, .uf2, and DFU .zip as applicable.

Architecture Overview

Mobile App  <--BLE (NUS)--> [ Companion ]  <--LoRa-->  Mesh Network
                                  |
                            k_event_wait()
                           /      |       \
                    LORA_RX   LORA_TX_DONE  BLE_RX

All code paths are event-driven. No polling loops, no busy waits.

• LoRa RX: Zephyr driver callback signals the mesh event loop
• LoRa TX: A dedicated 512-byte thread blocks on k_poll(), restarts RX immediately on completion, then notifies the mesh loop
• BLE: NUS write handler enqueues to k_msgq and signals the mesh loop; TX uses bt_gatt_notify_cb() chaining
• Main loop: k_event_wait() blocks until work arrives

Key Differences from Arduino

	Arduino	Zephyr
Main loop	50ms polling	k_event_wait() (blocks until event)
LoRa TX	Blocking transmit()	Async thread with k_poll()
BLE queues	Ring buffer + mutex	k_msgq (lock-free, ISR-safe)
Drivers	Arduino libraries	Zephyr subsystem drivers
Configuration	#define constants	Kconfig + devicetree
Threading	Single-threaded loop()	Multi-threaded with explicit sync
Power	Always-on loop	WFI sleep between events

Power Saving

• LoRa RX duty cycle: CAD-based receive windowing reduces LoRa RX current from ~10-15mA to ~3-5mA (configurable via CONFIG_ZEPHCORE_LORA_RX_DUTY_CYCLE)
• USB disabled in production: Saves ~2-5mA and 62KB flash when logging is off
• GPIO-gated GPS: Powered on only during fix acquisition

Configuration

Key Kconfig options (set in board configs or via -D flags):

Option	Default	Description
CONFIG_ZEPHCORE_ROLE_COMPANION	y	BLE companion mode
CONFIG_ZEPHCORE_ROLE_REPEATER	n	USB CLI repeater mode
CONFIG_ZEPHCORE_RADIO_NATIVE	y	SX1261/62/68/(7x?) radio
CONFIG_ZEPHCORE_RADIO_LR1110	n	LR1110/LR1120 radio
CONFIG_ZEPHCORE_LORA_RX_DUTY_CYCLE	y	RX power saving
CONFIG_ZEPHCORE_MAX_CONTACTS	350	Contact storage slots
CONFIG_ZEPHCORE_MAX_CHANNELS	40	Channel slots
CONFIG_ZEPHCORE_BLE_PASSKEY	123456	BLE pairing PIN
CONFIG_ZEPHCORE_GPS_POLL_INTERVAL_SEC	300	GPS fix interval

Project Structure

zephcore/
  src/              Main entry points and core mesh protocol
  app/              Companion and repeater role implementations
  adapters/
    radio/          LoRa radio drivers (SX126x, LR1110)
    board/          GPIO, LED, power management
    datastore/      LittleFS filesystem wrapper
    sensors/        I2C sensor auto-detection
    clock/          Millisecond and RTC clocks
  helpers/
    ui/             Display, buzzer, button input
  boards/
    nrf52840/       Per-board devicetree overlays and configs
    common/         Shared Kconfig fragments and devicetree includes
  lib/              ED25519 crypto library
  patches/          Auto-applied patches to the Zephyr tree

License

Same license as the upstream MeshCore project.