ble on is saved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
About this fork (meshcore-tth)
A fork of meshcore-dev/MeshCore
that runs the repeaters, sensors and bench boards of a small Czech network on
the CZ mesh (869.432 MHz). Upstream main and dev are merged automatically
twice a day; everything below is on top of that. Our code is marked
CUSTOM (TeTeHacko) in the source. Nothing here changes the wire protocol.
Repeater: antispam (all of it off-switchable, none of it upstream)
- FairnessLimiter -- token buckets on forwarded floods, keyed on the 1-byte
ids already in the clear (channel hash, sender hash, advert origin). Port of
Beanow's proposal #1502,
limits re-sized from 30 days of real CZ traffic.
fairness [on|off|grid|cap|refill]; direct-routed traffic is never limited. - Per-origin advert window -- each node's flood advert forwarded at most
once per N hours (
fairness advert <h>|clear), ported from DutchMeshCore's AdvertLimiter. Aimed at nodes that re-advertise every minute. - Dry-run --
fairness dryrun oncounts every verdict but forwards anyway;fairness airreports the airtime shed (or that would be) per reason. - Channel filter -- on channels whose key the repeater knows (Public and
#hashtagchannels), stop forwarding messages of listed sender names (filter add|del|list). Names are spoofable: it contains a runaway bot, it is not security. - Channel-hash deny-forward --
filter hash add <hex> [secs]: keyless, works on private channels too; reception is unaffected, only forwarding. Withsecsthe channel is throttled (one packet persecs) instead of cut. - Message age limit --
filter age <min>|off(opt-in, 1-10080 min): do not forward group texts on the decrypted channels whose sender timestamp is older; inactive while the repeater clock is unset. It judges the sender's clock, so companions without a time sync are dropped too -- keep it in days. filter dryrun oncounts everyfilterverdict but forwards anyway.
Repeater: diagnostics and operations
- Passive analyzer in the console:
nodes(heard repeaters/rooms, multi-path join key),rxlog(every frame heard, type/path/SNR/RSSI),pktlog(raw frames for an observer feed), big paged replies. - Channel bot for the analyzer build (
!link, path questions, per-sender cooldown, ignore list) -- answers without repeating. dfu [uf2|serial|ota](deterministic reboot into the bootloader),blink,txpwrwith RadioLib's verdict,i2cbus scan, TX-failure counters in the status reply, reset reason printed at boot.- Text console over BLE next to USB ("dock-quiet": BLE stays dark while USB
holds DTR), persisted connection TX power (
blepwr),bleconn, a non-blocking BLE TX pump and connection parameters that hold on a weak link. RADIO_DIAGbuild flag:radiostat/radiokickfor an SX1262 receiver that stops receiving.- DIO1-less operation (
LORA_POLL_IRQ) for a board with a dead IRQ line.
Core fixes
- TRACE no longer appends its path past the end of the payload; TRACE/PATH
parsing and
Packet::readFromare bounds-checked. markSeenis idempotent again (the send path was eating the dedup window).calcMaxPacketMillisfallback no longer underflows (a node went deaf on it).- Path-hash width comes from the node's prefs on every TX path, including
sendZeroHop; 2-byte path hashes are the default (PATH_HASH_MODE_DEFAULT). - Failed transmits are re-queued with backoff instead of dropped.
- Per-packet RSSI captured at RX;
ContactInfozeroed before a partial fill.
Power, clock, GPS
- GPS duty cycle (
gps duty), also on the T1000-E, which had none; a position request warms the duty-cycled receiver for next time. - A node without GPS starts at its build epoch, not in 2024; the clock and a
hardfault record survive a warm reset (
.noinit);clkreboot. - No blinking LED and slower BLE advertising on solar nodes; battery level as an icon at the end of the advertised name (opt-in).
Sensors and companions
simple_sensor: telemetry from an external station over UART (BudkaLinkSensorManager, one LPP channel per meter),sensor read.- Companion:
gps dutypersists, key export / PIN gated on an unauthenticated USB link, bounded build-date copy. KISS modem: off-by-one in the name clamp.
Public builds: Czech mesh defaults
Releases built from this repository (pub-release) come preset for the
Czech mesh, following the meshcore.cz wiki, so a
freshly flashed node does not need the usual round of settings:
- radio 869.432 MHz / 62.5 kHz / SF7 / CR5 (all builds);
- repeater and room server: zero-hop advert off, flood advert every 25 h,
af 9(10 % duty cycle); - repeater: regions
czandcsnext to*-- add your owncz-<kraj>withregion put cz-xxx cz+region save; - 2-byte path hashes (this fork's default);
- repeater: the channel filter (
filter add <name>) is built in for Public,#meshcoreand#test, with an empty list -- it does nothing until you add a name.
They apply only to a node with no saved settings (new, or after an erase): a reflash keeps whatever the node already has, and regions you removed and saved stay removed. Set a name, an admin password and the BLE PIN yourself.
Build
- Version stamping in every nRF52 env (
v1.18.0-tth<sha>,+= dirty tree), base version from the upstream tag (tools/build_version.py). hardware/cavity-box: parametric enclosure for a cavity filter on a mast.
About MeshCore
MeshCore is a lightweight, portable C++ library that enables multi-hop packet routing for embedded projects using LoRa and other packet radios. It is designed for developers who want to create resilient, decentralized communication networks that work without the internet.
🔍 What is MeshCore?
MeshCore now supports a range of LoRa devices, allowing for easy flashing without the need to compile firmware manually. Users can flash a pre-built binary using tools like Adafruit ESPTool and interact with the network through a serial console. MeshCore provides the ability to create wireless mesh networks, similar to Meshtastic and Reticulum but with a focus on lightweight multi-hop packet routing for embedded projects. Unlike Meshtastic, which is tailored for casual LoRa communication, or Reticulum, which offers advanced networking, MeshCore balances simplicity with scalability, making it ideal for custom embedded solutions, where devices (nodes) can communicate over long distances by relaying messages through intermediate nodes. This is especially useful in off-grid, emergency, or tactical situations where traditional communication infrastructure is unavailable.
⚡ Key Features
- Multi-Hop Packet Routing
- Devices can forward messages across multiple nodes, extending range beyond a single radio's reach.
- Supports up to a configurable number of hops to balance network efficiency and prevent excessive traffic.
- Nodes use fixed roles where "Companion" nodes are not repeating messages at all to prevent adverse routing paths from being used.
- Supports LoRa Radios – Works with Heltec, RAK Wireless, and other LoRa-based hardware.
- Decentralized & Resilient – No central server or internet required; the network is self-healing.
- Low Power Consumption – Ideal for battery-powered or solar-powered devices.
- Simple to Deploy – Pre-built example applications make it easy to get started.
🎯 What Can You Use MeshCore For?
- Off-Grid Communication: Stay connected even in remote areas.
- Emergency Response & Disaster Recovery: Set up instant networks where infrastructure is down.
- Outdoor Activities: Hiking, camping, and adventure racing communication.
- Tactical & Security Applications: Military, law enforcement, and private security use cases.
- IoT & Sensor Networks: Collect data from remote sensors and relay it back to a central location.
🚀 How to Get Started
- Watch the MeshCore QuickStart Playlist by The Comms Channel
- Watch the MeshCore Technical Presentation by Liam Cottle.
- Read through our Frequently Asked Questions and Documentation.
- Flash the MeshCore firmware on a supported device.
- Connect with a supported client.
For developers:
- Install PlatformIO in Visual Studio Code.
- Clone and open the MeshCore repository in Visual Studio Code.
- See the example applications you can modify and run:
- Companion Radio - For use with an external chat app, over BLE, USB or Wi-Fi.
- KISS Modem - Serial KISS protocol bridge for host applications. (protocol docs)
- Simple Repeater - Extends network coverage by relaying messages.
- Simple Room Server - A simple BBS server for shared Posts.
- Simple Secure Chat - Secure terminal based text communication between devices.
- Simple Sensor - Remote sensor node with telemetry and alerting.
The Simple Secure Chat example can be interacted with through the Serial Monitor in Visual Studio Code, or with a Serial USB Terminal on Android.
⚡️ MeshCore Flasher
We have prebuilt firmware ready to flash on supported devices.
- Launch https://meshcore.io/flasher
- Select a supported device
- Flash one of the firmware types:
- Companion, Repeater or Room Server
- Once flashing is complete, you can connect with one of the MeshCore clients below.
📱 MeshCore Clients
Companion Firmware
The companion firmware can be connected to via BLE, USB or Wi-Fi depending on the firmware type you flashed.
- Web: https://app.meshcore.nz
- Android: https://play.google.com/store/apps/details?id=com.liamcottle.meshcore.android
- iOS: https://apps.apple.com/us/app/meshcore/id6742354151?platform=iphone
- NodeJS: https://github.com/liamcottle/meshcore.js
- Python: https://github.com/fdlamotte/meshcore-cli
Repeater and Room Server Firmware
The repeater and room server firmware can be set up via USB in the web config tool.
They can also be managed via LoRa in the mobile app by using the Remote Management feature.
🛠 Hardware Compatibility
MeshCore is designed for devices listed in the MeshCore Flasher
📜 License
MeshCore is open-source software released under the MIT License. You are free to use, modify, and distribute it for personal and commercial projects.
Contributing
Please submit PR's using 'dev' as the base branch! For minor changes just submit your PR and we'll try to review it, but for anything more 'impactful' please open an Issue first and start a discussion. It is better to sound out what it is you want to achieve first, and try to come to a consensus on what the best approach is, especially when it impacts the structure or architecture of this codebase.
Here are some general principles you should try to adhere to:
- Keep it simple. Please, don't think like a high-level lang programmer. Think embedded, and keep code concise, without any unnecessary layers.
- No dynamic memory allocation, except during setup/begin functions.
- Use the same brace and indenting style that's in the core source modules. (A .clang-format is probably going to be added soon, but please do NOT retroactively re-format existing code. This just creates unnecessary diffs that make finding problems harder)
Help us prioritize! Please react with thumbs-up to issues/PRs you care about most. We look at reaction counts when planning work.
Running unit tests
To run unit tests, run the following command:
pio test --environment native --verbose
Road-Map / To-Do
There are a number of fairly major features in the pipeline, with no particular time-frames attached yet. In very rough chronological order:
- Companion radio: UI redesign
- Repeater + Room Server: add ACL's (like Sensor Node has)
- Standardise Bridge mode for repeaters
- Repeater/Bridge: Standardise the Transport Codes for zoning/filtering
- Core + Repeater: enhanced zero-hop neighbour discovery
- Core: round-trip manual path support
- Companion + Apps: support for multiple sub-meshes (and 'off-grid' client repeat mode)
- Core + Apps: support for LZW message compression
- Core: dynamic CR (Coding Rate) for weak vs strong hops
- Core: new framework for hosting multiple virtual nodes on one physical device
- V2 protocol spec: discussion and consensus around V2 packet protocol, including path hashes, new encryption specs, etc
📞 Get Support
- Report bugs and request features on the GitHub Issues page.
- Find additional guides and components on my site.
- Join MeshCore Discord to chat with the developers and get help from the community.