Beebo

A MeshCore node that tunes its own radio, changes role without a reflash, and reports to your phone.

Beebo adds four things to stock MeshCore: a repeater that tests its own settings against real traffic and keeps what works; one firmware image that is a companion or a repeater at your command; a feed in your app where the node reports its health and progress; and a monitor ring that records the packets it handles for analysis. It is a drop-in replacement for stock MeshCore v1.18.0 on the Heltec WiFi LoRa 32 V4 (headless): you flash it with the Web Flasher and keep the app you already have.

Get started in ten minutes See every feature

What beebo adds

• A status feed in your channel list

  Two channels, beebo-status and beebo-cli, appear in your app. The node reports its boot, health, warnings and tuning progress in one, and answers commands in the other. The app's own CLI screen runs the same commands, with the words of the beebo command line. Switch role, fix the transmit power, check the node's health or start a trial without a computer.

  The phone feed

• One firmware for both roles and all three transports

  Stock MeshCore ships a separate image for each role and for each companion transport. Beebo is one image that runs as a companion or a repeater, switched with settings board.node.role, and offers BLE, WiFi and USB together. Each role keeps its own keys, name and settings, so switching back restores them. A node that will never switch can run a single-role build, which frees 29 KB of RAM on a repeater.

  Roles

• A repeater that tunes itself

  A trial runs your repeater's current setting against one alternative in alternating blocks on live traffic, scores both by what the node actually delivered, and keeps the better one. The default profile tests the front-end LNA, channel-activity detection, the retransmit delay and the route retry; the exhaustive profile tests twelve settings. Trials start with one command from the app. An older adaptive tuner, which proposes changes to the timing settings and can apply them live, is still available as an experimental feature, observe-only until you opt each setting in.

  Setting trials

• Forwards that know if they were heard, and retry if not

  After a repeater forwards a flood, it listens for a neighbor to repeat it, and counts the forward as confirmed or not. A forward nobody echoed can be resent at a more robust LoRa coding rate (4/5 up to 4/8), up to three times. The same confirmed delivery is what the trials score, and beebo analyze retries reports how many retries were heard, the rescue rate and the extra airtime. Retry is off by default: turn it on only once you have verified a gain in service rates: every retry costs airtime, and it can load the mesh unnecessarily if repeaters do not deduplicate correctly.

  How a repeater routes

• Stable connections, driven by state machines

  BLE and WiFi share one radio, so beebo models their link state explicitly, and runs a separate session state machine so that exactly one transport owns the app conversation. Both follow the connection and pairing handshakes of the protocols instead of working around them: a first BLE pairing waits for encryption so the app does not time out while you type the PIN, and a session waits for its last reply to leave the device before it closes. The failures that are left recover on their own: a reconnecting phone replaces its own stale TCP session, and a client that disappears is dropped within about 25 seconds.

  Connections

• Full power: 27.3 dBm at the antenna, measured

  On the V4.3's KCT8103L amplifier the stock default radio.txpower of 10 delivers 22.3 dBm at the antenna connector. Beebo ships 18: 27.3 dBm, where the amplifier saturates, measured on the bench with a spectrum analyzer. RSSI and the noise floor are referred to the antenna connector, so readings from the LNA-on and LNA-off paths agree to within about 1 dB on the bench. Local transmit limits still apply: check them before you raise the power.

  Board analysis and RF experiments

• Updates over the link you already have

  Over-the-air updates run over whichever transport you are connected on, stream straight to flash, take about 30 seconds over WiFi, and roll back automatically if the new image does not boot. A deployed repeater can have its WiFi switched on through the mesh for servicing and switched off again afterwards for low power operation.

  Firmware updates

• A flight recorder on every node

  An always-on monitor ring records every packet's RSSI, SNR, noise floor and what the node did with it, plus its own tuning and setting changes. A health check turns the data into a verdict on delivery, battery and tuning. The beebo command line pulls, decodes, plots and analyzes it: why a forward was or was not echoed, the routes to each repeater, a console map of the nodes you hear, and a statistical comparison of LNA on and off on your own mesh traffic. A live debug stream shows the node's log and monitor records as they happen.

  Commands

• RF engineering you can reproduce

  The V4.3's KCT8103L front end has no public datasheet, so beebo works the radio out from first principles and then measures it. The board analysis covers both signal chains: amplifier saturation, thermal noise floor, sensitivity, system noise figure, in-band saturation, out-of-band interference against the LNA, and the regulatory limits on radiated power. The RF experiments check it on the bench: the transmit power curve and compression point, and the system noise floor with and without an antenna and a bandpass filter. beebo measure repeats the noise-floor, bandwidth and transmit-power measurements on your own board, with a test carrier for your analyzer.

  Board analysis · RF experiments

• A tool chest for fleets

  Named configurations pull a node's whole settings tree into a file, diff it against another node, and push back only what differs in a single flash write. Guided setup walks a new node through its name, role, region preset, admin password and WiFi. Recovery bundles save a node's keys and names. One alias per node picks its transport, beebo -i keeps a connection open, beebo run runs scripts, and a Python API, async or blocking, gives your own code the same operations. beebo admin runs status, telemetry and commands on a distant node over the mesh. Every setting is in one dotted-path tree, with help, valid ranges and choices on each, and the node's own console in the app answers the same names.

  Commands · Settings

• Battery trend and millisecond time, built in

  The V4.3 has no charge-detect pin, so beebo infers the battery state (charging, discharging, charged, plugged) from how the voltage moves, and the ADC can be calibrated against a voltmeter. Every connection syncs the clock to the millisecond with a round-trip-corrected probe, and the clock survives a full power cycle.

  Battery and clock

• ESP-IDF 5 and built-in debugging

  Built on ESP-IDF 5.5 and Arduino-ESP32 3.3 through pioarduino, not the IDF 4.4 platform stock uses. The move brings the upstream fix for the native USB transmit hang, which was its reason, 106 kB of free internal heap with WiFi up (82 kB before), and a trimmed BLE stack that leaves about 59 KB of internal RAM free after it starts (about 20 KB with the stock IDF libraries). A continuous live debug stream and JTAG debugging are built in.

  Feature reference

• Tested on real hardware

  Features are built test-first: native firmware unit tests, thousands of command-line tests, and hardware-in-the-loop tests on real boards for everything that crosses the protocol, so a feature is not done until it works on a node and not only against a mock. Every image is versioned from a single source.

  Platform and quality

• A drop-in that follows upstream

  Beebo speaks the standard MeshCore companion protocol, so existing apps work unchanged. A board that already runs v1.18.0 keeps its settings and starts in the role it had. Upstream releases are merged file by file, and upstream fixes are reviewed against beebo's own code.

  How beebo follows upstream

Beebo and stock MeshCore, side by side

Differences confirmed in the code and in bench measurements. Stock means MeshCore v1.18.0 built for the Heltec V4.

	Stock MeshCore	Beebo
Firmware images	One per role, and three companion images (BLE, WiFi, USB)	One image: companion or repeater at runtime, all three transports
Changing role	Flash a different image	settings board.node.role repeater: one reboot
Identity	One identity per image	Separate keys per role, kept across switches
Over-the-air update	Repeater start ota opens a MeshCore-OTA access point and a web upload page	Over the connection you already have, streamed to flash, with rollback
Default transmit power	radio.txpower 10 (22.3 dBm measured)	18 (27.3 dBm measured)
Radio tuning	Fixed settings	Trials and an adaptive tuner score the changes against live traffic
Observability	Packet log	Monitor ring with per-packet RSSI, SNR and disposition, health scores, live debug stream
App CLI screen	Stock commands	Stock commands plus the beebo command language: settings, status, check, monitor, battery, ...
ESP-IDF	4.4 (Arduino-ESP32 2.0.17)	5.5 (Arduino-ESP32 3.3)

Start here

1. Quick Start: flash, connect, read the feed, switch a role, run a trial. About ten minutes, phone only.
2. Using beebo: roles, the phone feed, connections, troubleshooting.
3. Tuning: setting trials and the performance tuning guide behind them.
4. Command line: the beebo command line for scripting, fleets and analysis, and updating a node.
5. Under the hood: firmware internals, the board analysis and the RF experiments. The complete feature catalog is its own page.

For MeshCore itself (protocol, apps, packet formats) see the MeshCore documentation. For a mistake, a missing piece, a bug or an idea, see Support and Feature Requests.