diff --git a/.gitignore b/.gitignore index c10e2d0..3115484 100644 --- a/.gitignore +++ b/.gitignore @@ -73,8 +73,10 @@ rtt_*.txt # JLink scripts and outputs *.jlink -# Documentation that was moved/deleted -/docs/ +# Internal working docs: per-topic audit indexes, handovers, handoffs, and +# other local-only scratch notes (see the HANDOVER_*/​*_AUDIT_INDEX rules below, +# kept for pre-2026-08-24 history/muscle memory even though this covers them). +/devdocs/ # Temporary/scratch files *.tmp diff --git a/zephcore/LICENSE b/LICENSE similarity index 86% rename from zephcore/LICENSE rename to LICENSE index 3e0321d..2d4b701 100644 --- a/zephcore/LICENSE +++ b/LICENSE @@ -31,6 +31,7 @@ compatible licenses: patches are applied to, and remain part of, the separately-licensed Zephyr source tree fetched via `west update`; they are not distributed as standalone files under this project's MIT license. -- `img/kite-network-logo-*.svg` (at the repository root, one level above this - file) — ZephCore logo, by recrof (https://github.com/recrof). Licensed under - the WTFPL. +- `img/kite-network-logo-bright.svg`, `img/kite-network-logo-dark.svg`, + `img/kite-network-logo-thick-bright.svg`, `img/kite-network-logo-thick-dark.svg` + — ZephCore logo, by recrof (https://github.com/recrof). Licensed under the + WTFPL. diff --git a/README.md b/README.md index ecaf1e2..fd6c429 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

ZephCore — MeshCore for Zephyr RTOS ZephCore logo

+

ZephCore — MeshCore for Zephyr RTOS ZephCore logo

A port of [MeshCore](https://github.com/meshcore-dev/MeshCore/) LoRa mesh firmware from Arduino to [Zephyr RTOS](https://zephyrproject.org/). Aiming for full protocol compatibility with the original Arduino firmware and the MeshCore mobile apps. @@ -15,63 +15,20 @@ Other benefits: ## Supported Boards -### nRF52840 +nRF52840, ESP32, nRF54L15, MG24, and STM32WL boards, covering SX126x, LR1110, +LR2021, and SX127x radios. ZephCore also runs as a **native Linux process** on +SBCs (Femtofox / Luckfox Pico Mini, Raspberry Pi + RAK6421 HAT) with a real +SX1262 on SPI/GPIO and the companion app connecting over TCP — see +[LINUX_NATIVE.md](docs/LINUX_NATIVE.md). -| Board | Radio | Extras | -|-------|-------|--------| -| **Wio Tracker L1** | SX1262 | GPS (L76KB), OLED (SH1106), joystick, buzzer, QSPI flash | -| **Seeed T1000-E** | LR1110 | GPS (AG3335), LEDs, button | -| **RAK4631** / **RAK WisMesh Pocket** | SX1262 | Same `rak4631` build. GPS (u-blox MAX-7Q), optional WisBlock OLED (SSD1306), I2C sensors (SHTC3, LPS22HB, BME680) | -| **RAK3401 1W** | SX1262 + SKY66122 (30 dBm) | GPS (u-blox MAX-7Q, optional), I2C sensors | -| **RAK WisMesh Tag** | SX1262 | GPS (AT6558R), accelerometer, buzzer | -| **ThinkNode M1** | SX1262 | GPS, e-paper display (SSD1681), QSPI flash, buzzer, RGB LEDs | -| **ThinkNode M3** | LR1110 | GPS, buzzer, two buttons, RGB LEDs | -| **ThinkNode M6** | SX1262 | GPS (L76K), QSPI flash, RGB LEDs | -| **LilyGo T-Echo** | SX1262 (TCXO 1.8V) | GPS (L76K), 1.54" e-paper (SSD1681), BME280, QSPI flash, touch-button backlight | -| **Heltec T114** | SX1262 | 1.14" TFT (ST7789V); screenless build via `no_display.conf` | -| **Heltec Mesh Node T096** | SX1262 + KCT8103L PA/FEM | UC6580 GNSS, ST7735S 160×80 TFT, button, LED, battery ADC | -| **Ikoka Nano 30dBm** | SX1262 (E22-900M30S, 30 dBm PA) | RGB LEDs | -| **GAT562 30S Mesh Kit** | SX1262 (30 dBm / 1 W PA) | RAK4631 core module. OLED (SSD1306), 5-way joystick, buzzer, GPS, BME280 pad, 2×18650 + solar | -| **SenseCAP Solar** | SX1262 | GPS (L76K), QSPI flash, battery monitor | -| **XIAO nRF52840 + Wio-SX1262** | SX1262 | Bare XIAO + Wio-SX1262 expansion | -| **ProMicro SX1262** | SX1262 (E22-900M30S) | GPS, battery ADC, button, LED | -| **muzi works R1 Neo** | SX1262 | GPS, RTC, buzzer, button, LEDs, soft power-off | - -### ESP32 - -| Board | MCU | Radio | Extras | -|-------|-----|-------|--------| -| **XIAO ESP32-C3** | ESP32-C3 | SX1262 | BLE 5.0 | -| **XIAO ESP32-C6** | ESP32-C6 | SX1262 | BLE 5.0, Wi-Fi 6 | -| **XIAO ESP32-S3** | ESP32-S3 | SX1262 | BLE 5.0, 8MB flash, 8MB PSRAM | -| **Station G2** | ESP32-S3 | SX1262 + PA (~20 dB gain) | OLED (SH1106), GPS, 16MB flash, 8MB PSRAM | -| **LilyGo TLoRa C6** | ESP32-C6 | SX1262 | BLE 5.0, Wi-Fi 6 | -| **LilyGo T3S3** | ESP32-S3 | SX1262 | OLED (SSD1306), button, TX LED, battery ADC, 4MB flash, 2MB PSRAM. **SX1262 variant only** — the SX1276/SX1280/LR1121 versions of this board are not supported | -| **Heltec V3** | ESP32-S3 | SX1262 | OLED (SSD1306), 8MB flash | -| **Heltec V4.2** | ESP32-S3 | SX1262 + GC1109 PA | OLED (SSD1306), 16MB flash, 2MB PSRAM | -| **Heltec V4.3** | ESP32-S3 | SX1262 + KCT8103L PA | OLED (SSD1306), 16MB flash, 2MB PSRAM | -| **Heltec Wireless Tracker V1.1** | ESP32-S3 | SX1262 | ST7735R 160×80 TFT, UC6580 GPS | -| **Heltec Wireless Tracker V2** | ESP32-S3FN8 | SX1262 + KCT8103L PA/FEM | ST7735R 160x80 TFT, UC6580 GNSS, battery ADC | -| **ThinkNode M9** | ESP32-S3 | LR1110 | ST7789 320x240 TFT, CC1167Q GPS, PCF8563 RTC, buzzer, 16MB flash, 8MB PSRAM | -| **LilyGo T-Beam v1.2** | ESP32 (PICO-D4) | SX1262 | AXP2101 PMU, GNSS, USB-UART CLI | -| **TTGO LoRa32** | ESP32 (PICO-D4) | **SX1276** (loramac-node backend) | SX127x reference board — **source-only, no published firmware** | - -### Other - -| Board | MCU | Radio | Extras | -|-------|-----|-------|--------| -| **XIAO nRF54L15 + Wio-SX1262** | nRF54L15 | SX1262 | FLPR multicore, RRAM storage | -| **XIAO MG24 + Wio-SX1262** | EFR32MG24 | SX1262 | BLE (SiLabs blob) | -| **Seeed LoRa-E5 mini** | STM32WL (STM32WLE5JC) | Integrated sub-GHz (SX1262-class) | No BLE/USB — companion + CLI over USART1 | - -ZephCore also runs as a **native Linux process** on SBCs (Femtofox / Luckfox Pico Mini, Raspberry Pi + RAK6421 HAT) with a real SX1262 on SPI/GPIO and the companion app connecting over TCP — see [LINUX_NATIVE.md](zephcore/LINUX_NATIVE.md). - -For exact `west build -b` board strings, flash methods, and special setup, see the [supported boards list](zephcore/boards/supported_boards.md) and the [Board Porting Guide](zephcore/boards/example_board/README.md). +For the full board list with exact `west build -b` strings, radios, and +hardware notes, see the [supported boards list](docs/supported_boards.md) and +the [Board Porting Guide](zephcore/boards/example_board/README.md). ## Device Roles -- **Companion** (default) -- connects to MeshCore mobile apps via BLE. Contacts, channels, offline message queue. -- **Repeater** -- forwards packets, configured via USB serial CLI. See the [Repeater CLI Command Reference](zephcore/Repeater_CLI_commands.md) for all available commands. +- **Companion** (default) -- connects to MeshCore mobile apps via BLE/USB. Contacts, channels, offline message queue. +- **Repeater** -- forwards packets, configured via USB serial CLI. See the [Repeater CLI Command Reference](docs/Repeater_CLI_commands.md) for all available commands. - **Room Server** -- store-and-forward shared message room (a "BBS"). Clients log in with an admin or guest password and post messages; the server pushes each new post to every other logged-in client. No BLE; configured via the same USB serial CLI as the repeater. - **Observer** (ESP32 only) -- listen-only node that publishes received LoRa packets to MQTT over WiFi STA. Configured at runtime via serial CLI. @@ -193,7 +150,6 @@ The old `txdelay`, `rxdelay`, and `direct.txdelay` commands are still accepted f ## Power Saving - **LoRa RX duty cycle**: chip-autonomous receive windowing (sniff mode) reduces LoRa RX current from ~10-15mA to ~3-5mA. Off by default; toggle at runtime with `set rxduty on/off` (SX126x only — unsupported on LR1110 due to a mid-preamble lock issue, and on SX127x). Window timing is auto-sized per SF/BW/preamble from the SX126x datasheet constraints. -- **Adaptive Power Control (APC)**: compiled in by default but disabled at runtime. Enable per-node with `set tx apc` -- automatically reduces TX power when echo SNR shows excess margin, ramping back up if echoes drop. See [apc.md](zephcore/apc.md). - **Production by default**: No logging, no asserts, reboot-on-fatal. Add `debug.conf` to enable logging. - **GPIO-gated GPS**: Powered on only during fix acquisition @@ -263,7 +219,7 @@ zephcore/ ## License -MIT License — see [`zephcore/LICENSE`](zephcore/LICENSE). Same license as the +MIT License — see [`LICENSE`](LICENSE). Same license as the upstream MeshCore project, which this work relies heavily on (see the [official meshcore repo](https://github.com/meshcore-dev/MeshCore/)). diff --git a/zephcore/ADAPTIVE_CAD.md b/docs/ADAPTIVE_CAD.md similarity index 100% rename from zephcore/ADAPTIVE_CAD.md rename to docs/ADAPTIVE_CAD.md diff --git a/zephcore/ARCHITECTURE.md b/docs/ARCHITECTURE.md similarity index 100% rename from zephcore/ARCHITECTURE.md rename to docs/ARCHITECTURE.md diff --git a/zephcore/LINUX_NATIVE.md b/docs/LINUX_NATIVE.md similarity index 100% rename from zephcore/LINUX_NATIVE.md rename to docs/LINUX_NATIVE.md diff --git a/MESHTIMESYNC.md b/docs/MESHTIMESYNC.md similarity index 97% rename from MESHTIMESYNC.md rename to docs/MESHTIMESYNC.md index 137dc75..d30223c 100644 --- a/MESHTIMESYNC.md +++ b/docs/MESHTIMESYNC.md @@ -84,4 +84,4 @@ adverts take tens of minutes to accumulate after a reboot, so an operator syncing right after login always wins. For the design details (consensus algorithm, security model, why the limits -are what they are), see [ARCHITECTURE.md](zephcore/ARCHITECTURE.md) section 4.9. +are what they are), see [ARCHITECTURE.md](ARCHITECTURE.md) section 4.9. diff --git a/PROVIDER_CATALOG.md b/docs/PROVIDER_CATALOG.md similarity index 100% rename from PROVIDER_CATALOG.md rename to docs/PROVIDER_CATALOG.md diff --git a/zephcore/Repeater_CLI_commands.md b/docs/Repeater_CLI_commands.md similarity index 100% rename from zephcore/Repeater_CLI_commands.md rename to docs/Repeater_CLI_commands.md diff --git a/zephcore/boards/supported_boards.md b/docs/supported_boards.md similarity index 83% rename from zephcore/boards/supported_boards.md rename to docs/supported_boards.md index 5b75236..3b41f1a 100644 --- a/zephcore/boards/supported_boards.md +++ b/docs/supported_boards.md @@ -19,10 +19,12 @@ sensecap_solar xiao_nrf52840 lilygo_techo promicro_sx1262 +promicro_lr2021 heltec_t114 heltec_t096 gat562_30s muziworks_r1neo +lilygo_timpulse_plus ``` > **RAK WisMesh Pocket** (WisBlock pocket): use `-b rak4631` — same board string and firmware as **RAK4631**. @@ -32,6 +34,10 @@ muziworks_r1neo > **SenseCAP MeshTracker X1** (`meshtracker_x1`): nRF52840 + LR2021, AG3335M dual-band L1+L5 GNSS, SPA06 barometer, DRV2605L vibration, YSN8900 RTC, 8 MB QSPI flash (`/ext`), RGB LED, buzzer. Untested on hardware — first ZephCore board to use a real LR2021. The RTC is treated as an RX8900 second-source; boot-time discovery validates that before trusting it. > > **Heltec Mesh Node T096** (`heltec_t096`): nRF52840 with SX1262 + KCT8103L PA/FEM, UC6580 GNSS, and ST7735S 160x80 TFT companion display. The external SPI flash footprint is documented in the board notes but left disabled until the device parameters are confirmed. +> +> **LilyGo T-Impulse Plus** (`lilygo_timpulse_plus`): nRF52840 wristband/tracker with SX1262 (GPIO antenna switch, not DIO2), SSD1315 64x32 OLED, u-blox MIA-M10Q GPS, 4 MB QSPI flash (`/ext`), touch button, haptic motor. Builds and ships in releases, but several parameters are inferred from vendor sources and not bench-verified (TCXO voltage, battery divider ratio, OLED offsets) — see the board README. Early hardware testing also showed occasional spontaneous reboots, untriaged. +> +> **ProMicro LR2021** (`promicro_lr2021`): nRF52840 SuperMini + Semtech LR2021, the first ZephCore board bring-up for that radio. Source-only — **not in `build.sh`, the release workflow, or the Mesh America catalog**, so no release carries a binary for it. The bring-up module was destroyed by an accidental 5V feed (LR2021 VBAT max ~3.7V); build it yourself if you want to continue testing on a fresh module. ## ESP32 @@ -129,4 +135,4 @@ me25ls02/nrf54l15/cpuapp Not `west build -b` boards — `EXTRA_CONF_FILE` presets on top of `native_sim` for SBCs (Femtofox / Luckfox Pico Mini, Raspberry Pi + RAK6421 HAT). See -[LINUX_NATIVE.md](../LINUX_NATIVE.md) for build commands and wiring. +[LINUX_NATIVE.md](LINUX_NATIVE.md) for build commands and wiring. diff --git a/img/kite-network-logo-thick-bright.svg b/img/kite-network-logo-thick-bright.svg new file mode 100644 index 0000000..9889cd8 --- /dev/null +++ b/img/kite-network-logo-thick-bright.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/img/kite-network-logo-thick-dark.svg b/img/kite-network-logo-thick-dark.svg new file mode 100644 index 0000000..9fb295a --- /dev/null +++ b/img/kite-network-logo-thick-dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/releasenotes/RELEASE_NOTES_1.16.5-zephcore.md b/releasenotes/RELEASE_NOTES_1.16.5-zephcore.md index 18d1ea1..6e877fb 100644 --- a/releasenotes/RELEASE_NOTES_1.16.5-zephcore.md +++ b/releasenotes/RELEASE_NOTES_1.16.5-zephcore.md @@ -59,7 +59,7 @@ Quiet sites end up *more* sensitive than the old fixed default (fewer stomped pa off until the false alarms stop. CAD also now uses 4 detection symbols everywhere, which improves detection of an in-progress packet's payload (not just its preamble). Full guide, including the honest limitation that the "missed detection" side isn't locally observable, is in -**[ADAPTIVE_CAD.md](https://github.com/liquidraver/ZephCore/blob/master/zephcore/ADAPTIVE_CAD.md)**. +**[ADAPTIVE_CAD.md](https://github.com/liquidraver/ZephCore/blob/master/docs/ADAPTIVE_CAD.md)**. (SX127x boards have no hardware CAD and keep their RSSI-based gate.) ### New: V-Contact — admin your companion from the chat app, no cable diff --git a/releasenotes/RELEASE_NOTES_1.17.2-zephcore.md b/releasenotes/RELEASE_NOTES_1.17.2-zephcore.md index 41127ef..55fb311 100644 --- a/releasenotes/RELEASE_NOTES_1.17.2-zephcore.md +++ b/releasenotes/RELEASE_NOTES_1.17.2-zephcore.md @@ -161,7 +161,7 @@ that empty slot. Unused slots are now skipped, so those messages are simply igno If your node keeps finding the channel busy and can never transmit, it now says so after four seconds and flags it as an error. Before, a node that could hear everyone but never got heard back looked completely -idle, with nothing in the log to explain it. +idle, with nothing in the log to explain it. (in debug logs) All roles, all boards. @@ -232,12 +232,6 @@ instead of once. Now it does it once, halving the time it spends unable to hear LR2021 boards only. -## An LR1110 too old to reach the mesh now says so - -An LR1110 running firmware older than 0x0303 cannot be moved off the public LoRa channel. It transmits -and receives perfectly well, but nobody on your mesh can see it. That now appears in the log instead of -looking like a broken radio. - ## New setting: switch the antenna amplifier's receive gain off Some boards carry an extra amplifier chip between the radio and the antenna. It boosts what the node @@ -249,13 +243,6 @@ amplifier draws. Transmitting is untouched: every packet the node sends still go amplifier at full strength. `set radio.fem.rxgain 1` puts it back, and `get radio.fem.rxgain` shows where it stands. The node keeps the setting across reboots. -> [!WARNING] -> **This costs range, and a lot of it.** With the receive side off the node goes substantially deafer — -> on a Wireless Tracker V2 the measured noise floor moves by about 23 dB between the two settings. Distant -> and weak neighbours simply stop being heard, while the node's own transmissions carry exactly as far as -> before, so from the outside it still looks perfectly healthy. Only worth doing on a battery-powered node -> where you already know every neighbour is close and strong. - Supported on the **Heltec T096**, **Wireless Tracker V2**, **WiFi LoRa 32 V4** and **WiFi LoRa 32 V4.3**. Everything else replies `Error: unsupported` — either the board has no such amplifier, or its amplifier is switched on by a line the radio driver cannot reach. The **RAK3401 1 W** is in that second group. @@ -280,7 +267,7 @@ LR1110 it never could, so the adaptive channel-busy detection had nothing to wor calibrated. And the check that stops a node transmitting over a packet it is already receiving was answering "not receiving" almost always, which quietly disabled it. -**LR1110 boards** (T1000-E, ThinkNode M9, Wio-SX1262 variants and others). If you switched `rxduty` off +**LR1110 boards** (T1000-E, ThinkNode M9, Wio variants and others). If you switched `rxduty` off because the node seemed unreliable, it is worth switching back on. ## Contacts survive a power cut, and the flash lasts longer diff --git a/zephcore/docs/AN1200.85-Introduction-to-Channel-Activity-Detection.pdf b/zephcore/docs/AN1200.85-Introduction-to-Channel-Activity-Detection.pdf deleted file mode 100644 index a64f9e1..0000000 Binary files a/zephcore/docs/AN1200.85-Introduction-to-Channel-Activity-Detection.pdf and /dev/null differ