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.

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.

• Companion (default) -- connects to MeshCore mobile apps via BLE
• Repeater -- forwards packets, configured via USB serial CLI. See the Repeater CLI Command Reference for all available commands.

Prerequisites: Zephyr SDK >=1.0.1 (!) and west installed.

Optional: adafruit-nrfutil to allow DFU zip generation for OTA updates on nRF52

# 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.

For exact west build -b board strings, flash methods, and special setup (MG24 pyocd, nRF54L15 --no-sysbuild), see the Board Porting Guide.

Heltec V3 note: console and shell are routed to uart0 in ZephCore. Use the UART serial port for logs/CLI.

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

All code paths are event-driven. The CPU sleeps in WFI between events.

• LoRa RX: Zephyr driver callback enqueues to a ring buffer and signals the mesh event loop
• LoRa TX: A dedicated thread blocks on k_poll(), restarts RX 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
• USB: CDC-ACM with V3 binary framing protocol, frame timeout recovery
• Main loop: k_event_wait() blocks until work arrives; housekeeping runs every 5s

Arduino MeshCore uses three static delay knobs (txdelay, rxdelay, direct.txdelay) that add the same retransmit jitter regardless of local conditions. In a linear chain of repeaters where each only hears its neighbor, this adds latency for zero benefit. In dense areas with 50+ neighbors, the same value may be too low to avoid collisions.

ZephCore replaces all three with a self-tuning system based on observed retransmit contention:

1. Dupe counting: When a node retransmits a flood packet, it counts how many times it hears that same packet retransmitted by neighbors within a 10-second window. This is a direct measurement of local contention -- 0 dupes means a quiet linear chain, 15+ means a dense cluster.

2. EMA-based delay sizing: Dupe counts feed into a rolling exponential moving average. This drives a sqrt-curve delay factor for future retransmits: near-zero delay in sparse areas, scaling up in dense ones. At ~15 dupes (moderate density), the factor matches the old Arduino default of 0.5.

3. Reactive per-packet backoff: When a node is waiting to retransmit and hears a neighbor retransmit the same packet, it pushes its own TX back by a random amount (up to backoff.multiplier x airtime). This is real-time CSMA -- you hear the channel being used for your packet, so you defer.

Direct packets (routed, single next-hop) use minimal fixed jitter (~0-45ms) instead of adaptive delay, since only the next hop retransmits them.

The old txdelay, rxdelay, and direct.txdelay commands are still accepted for binary compatibility with Arduino prefs but are ignored -- the system is fully adaptive.

CLI commands:

• get txdelay -- shows adaptive status: contention estimate and current flood delay factor
• get/set backoff.multiplier -- reactive backoff cap (default 0.5, range 0.0-2.0). Set to 0 to disable reactive backoff (EMA window still works). Higher values allow more per-packet deferral in dense areas.

Compatibility: Purely local behavior, no wire protocol changes. Works alongside Arduino MeshCore repeaters -- their retransmits are counted as dupes just the same.

• 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

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

zephcore/
  src/              Main entry points and core mesh protocol
  app/              Companion and repeater role implementations
  adapters/
    ble/            BLE NUS transport
    board/          GPIO, LED, power management
    clock/          Millisecond and RTC clocks
    datastore/      LittleFS filesystem wrapper
    gps/            GPS/GNSS drivers
    ota/            WiFi OTA firmware updates
    radio/          LoRa radio drivers (SX126x, LR1110)
    rng/            Random number generator
    sensors/        I2C sensor auto-detection
    usb/            USB serial transport (CDC-ACM, V3 framing)
  helpers/
    ui/             Display, buzzer, button input
  boards/
    nrf52840/       nRF52840 board overlays and configs
    esp32/          ESP32-C3/C6/S3 board overlays and configs
    nrf54l/         nRF54L15 board overlay and config
    mg24/           EFR32MG24 board overlay and config
    common/         Shared Kconfig fragments and devicetree includes
  lib/              ED25519 crypto library
  patches/          Auto-applied patches to the Zephyr tree

Same license as the upstream MeshCore project.