Features
Everything beebo adds to stock MeshCore v1.18.0 on the Heltec V4, grouped by what you
want to do. Each row says what the feature does and where to read more. For a quick
tour see the home page; to try it, start with the
Quick Start.
Features marked phone work from the MeshCore app alone. The rest need the
beebo command line, which is optional.
Phone and app control
| Feature |
What it does |
Read more |
| Node console phone |
The v1.18 app's CLI screen sends commands to the node you are connected to. Beebo answers them in either role, with the words of the beebo command line: settings <path> reads and settings <path> <value> writes (settings board.node.role, settings radio.txpower), and status, check, monitor, battery, advert, neighbors and region work as on the computer. The stock get, set and ver commands keep working. |
Phone feed |
| Status feed phone |
The channel beebo-status carries the node's own reports: boot (version, role, reset reason), an hourly monitor line (packets, health score), trial progress, and warnings such as a transmit power under 16 dBm. |
Phone feed |
| Command channel phone |
The channel beebo-cli runs any command typed into it and posts the reply, split into up to four numbered parts if it is long. Both channels are private and never transmitted over the air. |
Phone feed |
| Role switch phone |
settings board.node.role repeater or companion from the CLI screen: one reboot, no reflash. |
Roles |
| Trials from the app phone |
settings routing.tuning.trial.enabled on or monitor tuning trial start starts the trial sequence and sets up the monitor for it. Progress arrives as feed lines. |
Setting trials |
| App sync with a repeater phone |
A repeater answers the app's sync commands (contacts, messages, channels) with valid, mostly empty replies, so the app can stay connected to it. |
Phone feed |
| Remote CLI on companions |
A contact that has the remote-CLI permission can run commands on a companion over the mesh. |
Commands |
self admin command |
admin <contact> cmd self <command> runs a command on the companion you are connected to, for apps without a CLI screen. |
Commands |
| RSSI with every message |
A synced message carries its received RSSI beside the SNR, in bytes older apps ignore. |
Firmware internals |
| Extended statistics |
Heap, PSRAM and flash use, packet and duplicate counts, and a command-latency ring through the companion stats commands. |
Firmware internals |
Roles, identity and builds
| Feature |
What it does |
Read more |
| One image, either role |
The same firmware runs as companion or repeater, chosen by a setting. |
Roles |
| Separate identities |
Companion and repeater each have their own Ed25519 keypair, node name, contacts, access list and settings, all kept on the node while the other role is live. |
Firmware internals |
| Identity tools |
Export, save, import and generate identities, and swap a whole identity, name and role in one call (beebo config identity …, beebo config switch). |
Commands |
| First boot from stock |
A board that runs stock v1.18.0 keeps its settings: beebo reads the stock preferences once, works out whether the board was a companion or a repeater, and starts in that role. |
Firmware internals |
| Static role builds |
--companion or --repeater images compile the other role out. The repeater build does not link the contact, channel and connection tables at all: 138 KB of static RAM against 168 KB for the multi-role image. |
Firmware internals |
| Node names and aliases |
board.node.name is the node's name; the device id is the board's MAC address; a local alias maps either to a transport. |
Commands |
Connections
| Feature |
What it does |
Read more |
| Three transports in one image |
BLE, WiFi (TCP) and USB, each switched by a setting. Default: BLE and USB on, WiFi off. |
Connections |
| Link state machine |
BLE and WiFi share one radio and are one state variable, so "both up" cannot happen. Switches defer until a live session ends, so a switch never cuts its own reply. |
Connections |
| Session state machine |
One transport owns the app conversation. Stray connections are evicted after a short grace period, and USB cannot starve wireless. |
Connections |
| Stale-session takeover |
A reconnecting phone replaces its own stale TCP session at once. A different address is refused. A client that vanishes is dropped in about 25 s. |
Connections |
| Clean close |
A session waits for its last reply to drain before it releases, which ended a class of BLE "Unlikely Error" disconnects. |
Connections |
| BLE pairing |
A first pairing waits for link encryption so the app does not time out while you type the PIN. |
Connections |
| USB write pacing |
Frames are written only when they fit the transmit buffer, so bulk downloads are not silently truncated. |
Connections |
| Remote transport control |
Switch a deployed repeater's WiFi on or off through the mesh (beebo admin <node> transport), to service it and return it to its low-power state. |
Update and service |
Radio and RF
| Feature |
What it does |
Read more |
| Default transmit power 18 |
Measured at the antenna connector: 22.3 dBm at the stock setting of 10, 27.3 dBm at 17 and above, where the KCT8103L saturates. Beebo ships 18. Check your local limits. |
RF experiments |
| Antenna-referenced RSSI |
Per-path offsets (board.fem.rssi_offset.lna and .bypass) refer packet RSSI and the noise floor to the antenna connector, so the LNA-on and LNA-off paths agree to about 1 dB on the bench. |
RF experiments |
| LNA control |
The KCT8103L low-noise amplifier is a setting (fem.rxgain), off by default as in stock. It buys about 6 dB of sensitivity over the stock bypass setting (4.3 dB better than the bare SX1262) and costs about 17 dB of tolerance to out-of-band interference (the intermodulation threshold falls from −3 dBm to −20 dBm). |
Board analysis |
| In-field LNA comparison |
beebo rxlog --compare toggles the LNA against your real mesh traffic and compares the two with a statistical test, with the chassis closed and no bench equipment. |
Analysis |
| RX boosted gain |
The SX1262 boosted-gain mode is a per-role setting, on by default. |
Firmware internals |
| Per-role radio settings |
Receive delay, airtime budget, boosted RX gain, CAD, FEM gains, timezone and WiFi are separate for each role. The transmit delays, interference threshold and AGC interval belong to the repeater. |
Firmware internals |
| CW test carrier |
A continuous carrier with a safety auto-stop, for bench transmit-power measurement. |
Commands |
| Bench measurement |
beebo measure runs noise-floor, bandwidth-sweep and transmit-power-curve measurements, with plotting scripts. |
RF experiments |
| Board analysis |
A written analysis of the V4.3 transmit and receive chains: power amplifier, sensitivity, saturation, regulatory limits. |
Board analysis |
| Hardware detection |
The power amplifier type (KCT8103L or GC1109) is detected and logged at boot. |
Firmware internals |
Routing and self-tuning
| Feature |
What it does |
Read more |
| Setting trials |
A repeater compares two values of one setting in alternating A/B/B/A blocks on live traffic, scores each, and keeps the better. Twelve settings can be trialed; the main profile runs four. |
Setting trials |
| Automatic schedule |
Block length and count follow the traffic the node counts, so the confidence you ask for is reachable. A trial ends early when the evidence settles. |
Trial reference |
| Dead-side check |
A setting that deafens the radio is caught during the trial instead of winning by default. |
Trial reference |
| Objective function |
Trials and the tuner score what the node actually delivered: forwards confirmed by an echo or ACK. The weights are settings. |
Scoring |
| Adaptive tuner |
A bandit scores the forwarding-timing knobs and proposes changes. It starts observe-only, each knob is opted in separately, and a change that measurably hurts delivery is rolled back. |
Adaptive tuner |
| Route retry |
A repeater that hears no echo of a forward resends it, each retry at its own LoRa coding rate. |
How a repeater routes |
| Echo window from the send |
The echo timeout starts when the packet is sent, so it measures the neighbor's turnaround and not queue time. |
How a repeater routes |
| Hop-capped group sends |
--max-hops N sends a group message that only N repeaters can forward. |
Commands |
| Traffic injection |
beebo traffic send sends at a constant rate from the host, and beebo traffic sustain makes the firmware keep a node counting the traffic its trials need. |
Commands |
| Region management |
The repeater region map, with the stock region commands available from the CLI. |
Commands |
Observability and health
| Feature |
What it does |
Read more |
| Monitor ring |
A continuous ring of 65,536 records in PSRAM: every packet's RSSI, SNR, noise and disposition, radio and environment changes, tuning and trial records, setting changes and commands. |
Monitoring |
| Pull, decode, plot |
beebo monitor pull builds an incremental local dataset, decode filters it, plot draws live charts. A timer or cron job can keep it current. |
Monitoring |
| Analysis |
beebo analyze reads the dataset offline: packets, retries, timing, mesh paths, and trial results with noise and confidence. |
Analysis |
| Health check |
beebo check gives a verdict on delivery, battery and tuning, plus a settings check-up. |
Health Check |
| Service scores |
A confirm ratio (QoS) and a health score (SoH) computed on the node and shown in the hourly feed line. |
Scoring |
| Time accounting |
Where the loop's time goes (RX, TX, the host link, housekeeping, idle), loop headroom, and routing latency split into busy and waiting. |
Time accounting |
| Neighbors and paths |
neighbors, discover, trace, and single-peer poke and ping. |
Commands |
| Battery state |
Charging, discharging, charged or plugged, inferred from how the voltage moves over time. The ADC multiplier can be calibrated against a voltmeter. |
Battery |
| Clock |
An RTT-corrected, millisecond-precision sync on every connect, and a clock that survives a power cycle. |
Firmware internals |
| Live debug stream |
A continuous stream of the node's debug log over USB, and of its monitor records over USB or the session's own transport, with replay on enable. |
Commands |
| Transport debug ring |
Connect, disconnect and lock events across BLE, WiFi and USB, streamed by beebo monitor debug. |
Connections |
| JTAG debugging |
A debug build, gdb and OpenOCD launchers and VS Code configurations for the board's built-in JTAG. |
Firmware internals |
Fleet operation
| Feature |
What it does |
Read more |
| Over-the-air update |
Over BLE, WiFi or USB, streamed straight to flash. About 30 s over WiFi. The new image is validated on first boot and rolled back if it fails. |
Update and service |
| Named configurations |
beebo config pulls a node's whole settings tree into a file, diffs it against a node, pushes it back (writing only what differs, in one flash write), and keeps validation templates. Secrets are never stored. |
Commands |
| Guided setup |
beebo config onboard asks for name, role, LoRa preset, a new admin password and WiFi, defaulting each answer to the node's current value. |
Commands |
| Recovery bundles |
beebo config backup and recover save and restore a node's keys, names and passwords. |
Commands |
| Remote administration |
beebo admin <node> status, telemetry and commands over the mesh, rendered as tables with units and decoded fault flags. |
Commands |
| Aliases and sessions |
One symlink per node pre-fills its transport. beebo -i keeps one connection open, and beebo run runs curated or personal scripts. |
Commands |
| Python API |
beebo.api offers the same operations to your own scripts, with an async Node and a blocking SyncNode. |
Python API |
| Settings tree |
One dotted-path tree covers radio, board, transports, WiFi, monitoring and tuning, with help, ranges and choices on every leaf. |
Settings |
| Feature |
What it does |
Read more |
| ESP-IDF 5.5 platform |
Arduino-ESP32 3.3 on pioarduino, with IDF libraries rebuilt for beebo's configuration. Stock builds on IDF 4.4 with Arduino-ESP32 2.0.17. |
Firmware internals |
| USB transmit fix |
The Arduino-ESP32 fix for the native USB transmit hang came with the move. A five-minute load test passes, but it passed on IDF 4.4 as well, so it does not by itself prove the old hang is gone. |
Firmware internals |
| Lean BLE stack |
One connection, no central role, host memory in PSRAM: about 59 KB of internal RAM free after BLE starts, against about 20 KB with the stock IDF libraries. |
Connections |
| More free heap |
106 kB of free internal heap with WiFi up, against 82 kB before the move. The offline message queue lives in PSRAM. |
Firmware internals |
| Headless board |
GPS, display and button are compiled out. The node reports as "Heltec V4.3 Headless". Builds exist for the R2 and R8 PSRAM variants. |
Firmware internals |
| Tests |
Native firmware unit tests, thousands of command-line tests, and hardware-in-the-loop tests on real boards for every feature that crosses the protocol. |
Commands |
| Build tooling |
build.sh and release.sh version every image consistently, with a shared compiler cache. fw/ also builds standalone with plain pio run. |
Firmware internals |
Compatibility and upstream
Beebo is built to stay a drop-in replacement:
- Existing apps work unchanged. Beebo implements the standard companion protocol.
Its additions travel in one wrapper command, and anything that has no stock
counterpart is invisible to an app that does not know it.
- Stock commands remain. The rule is that every stock text command keeps a binary or
beebo command counterpart, even where beebo has a better way, so scripts written for
stock keep working. Beebo-only fields in shared code sit behind their own build flags, so other
boards build unchanged.
- Upstream is tracked.
fw/ shares no git history with MeshCore, so each release is
merged file by file. The v1.18.0 pass resolved 95% of 375 files mechanically and the
rest by hand, and every upstream fix is checked against beebo's own copy of the code:
the 1.17.1 pass found a path-length validation fix this way. A stock checkout must
still build its own targets. The v1.18.0 additions beebo adopted include the remote
companion CLI, the local CLI command, stricter input validation (ciphertext length,
region transport code, raw data lengths), and hidden-node discovery.
- Your settings carry over. A board that runs stock v1.18.0 keeps its settings when
you flash beebo on top.
For MeshCore itself see the MeshCore documentation.