CLI client for the officialmesh Meshtastic firmware fork (a.k.a. the Official Mesh Firmware). Talks to ports 350–368 on a connected node, exposing features that aren't part of upstream Meshtastic:
Project home: officialmesh.org · github.com/official-mesh/python
Maintainer: The Official Mesh Admin <officialmeshadmin@proton.me>
License: GNU Affero General Public License v3.0-only — see LICENSE
This CLI is compatible with the Official Mesh firmware fork of Meshtastic. "Meshtastic" is referenced nominatively. This project is not affiliated with, endorsed by, licensed from, or authorized by Meshtastic LLC or its maintainers.
| Port | Module | Subcommand |
|---|---|---|
| 350 | Capabilities | officialmesh capabilities ... |
| 351 | Privacy mode | officialmesh privacy ... |
| 352 | Raw send | officialmesh rawsend ... |
| 353 | Hop obfuscation | officialmesh hop ... |
| 354 | Rebroadcast jitter | officialmesh jitter ... |
| 355 | Cover traffic | officialmesh cover ... |
| 356 | Multi-WiFi fallback | officialmesh wifi ... |
| 358 | Raw recv (observer) | officialmesh rawrecv ... |
| 359 | WireGuard | officialmesh wireguard ... |
| 360 | Blackout (TX mute) | officialmesh blackout ... |
| 361 | Hardware inventory | officialmesh hwid ... |
| 362 | FSK side-channel | officialmesh fsk ... |
| 363 | Radio diagnostics | officialmesh diag ... |
| 364 | Priority TX | officialmesh ptx ... |
| 365 | RFFI countermeasures | (library: codec.rffi_countermeasures) |
| 366 | Originator jitter | (library: codec.originator_jitter) |
| 367 | Panic button | (library: codec.panic_button) |
| 368 | Dualboot net-OTA control | (library: codec.dualboot_control) |
Wire-format spec: see firmware/PRIVATE_PORTS.md in the officialmesh firmware fork.
Ports 365–368 currently expose codec-only bindings (build/parse helpers under
officialmesh.codec.<port>); CLI subcommands will follow. Capability bit
DUALBOOT_NET_OTA (CapBit.DUALBOOT_NET_OTA, bit 5) advertises port-368
support on builds that ship dualboot net-OTA.
This CLI ships alongside five companion repos under the official-mesh org:
| Repo | Purpose |
|---|---|
official-mesh/firmware |
Meshtastic firmware fork |
official-mesh/android |
Android client for the fork |
official-mesh/python |
This CLI |
official-mesh/meshbot |
Meshbot — automated node operator; also hosts the org-wide CLA and Code of Conduct |
official-mesh/remote |
Meshbot Remote — remote-control surface for Meshbot |
official-mesh/dualboot |
Mesh Dualboot — switch a device between upstream Meshtastic and the officialmesh fork |
Either tool installs the officialmesh console script onto your PATH:
# pip
pip install -e .
# poetry
poetry installAfter install, officialmesh --help works from anywhere — no python -m needed.
Same flags as upstream meshtastic:
officialmesh --port /dev/ttyUSB0 capabilities query
officialmesh --host 192.168.1.42 wireguard status
officialmesh --ble Heltec_abcd wifi list# verify the firmware build supports WireGuard (bit 9 set)
officialmesh --port /dev/ttyUSB0 capabilities query
# push a wg-quick config and bring the tunnel up
officialmesh --port /dev/ttyUSB0 wireguard set-config --conf wg0.conf
officialmesh --port /dev/ttyUSB0 wireguard enable
officialmesh --port /dev/ttyUSB0 wireguard statusofficialmesh --port /dev/ttyUSB0 wifi add --ssid Home --psk hunter2
officialmesh --port /dev/ttyUSB0 wifi add --ssid Cafe
officialmesh --port /dev/ttyUSB0 wifi list
officialmesh --port /dev/ttyUSB0 wifi statusThe transport and codec layers behind the CLI are importable. Build a Client
around a meshtastic interface and talk to private ports directly:
import meshtastic.tcp_interface
from officialmesh.transport import Client
from officialmesh.ports import PrivatePortnums, CapBit
from officialmesh.capabilities import require, CapabilityMissing
from officialmesh.codec import wireguard as wg, rawrecv as rr
iface = meshtastic.tcp_interface.TCPInterface(hostname="192.168.1.42")
client = Client(iface)
# Optional: gate on a build-conditional feature before sending.
try:
require(client, CapBit.WIREGUARD_CONTROL)
except CapabilityMissing as e:
raise SystemExit(e)
# Build a request with the codec helpers and round-trip it.
reply = client.send(
PrivatePortnums.WIREGUARD_CONTROL,
wg.build_status(),
timeout=5.0,
)
print(wg.parse_status_reply(reply))
# Subscribe to streams (RawRecv observer, FSK side-channel listen).
# The firmware only emits these once the module is enabled.
client.send(PrivatePortnums.RAW_RECV, rr.build_enable(), want_response=False)
def on_frame(payload: bytes) -> None:
print(f"got {len(payload)} bytes on raw recv")
unsub = client.subscribe(PrivatePortnums.RAW_RECV, on_frame)
# When done: unsub(); client.close()The CLI subcommand modules under officialmesh.commands.<port> are argparse
glue, not a library API — for programmatic use, build requests with
officialmesh.codec.<port> (e.g. wg.build_status() /
wg.parse_status_reply() for port 359) and round-trip them via
Client.send() / Client.subscribe(). Stable surface for library users:
| Symbol | Purpose |
|---|---|
officialmesh.transport.Client |
Wrap a meshtastic.MeshInterface; send() / subscribe(). |
officialmesh.ports.PrivatePortnums |
Port-number constants (mirrors firmware/src/mesh/PrivatePortnums.h). |
officialmesh.ports.CapBit |
Capability bitmap bits; pair with capabilities.require(). |
officialmesh.capabilities.require |
Raises CapabilityMissing for un-compiled features. |
officialmesh.codec.<port> |
Pure encode/decode helpers — build_*, parse_*, and dataclasses. Underscore-prefixed names are not stable. |
Everything else is internal — argparse glue, CLI formatting, etc.
Before opening a PR, please review:
Both are maintained centrally in official-mesh/meshbot and apply to every repo under the official-mesh org, including this one.
Signed git tags and release artifacts are signed by:
The Official Mesh Admin <officialmeshadmin@proton.me>
GPG fingerprint: 9A18 814D 74A6 3138 9F95 6EA0 5F8D 7A5E ED20 3343
The public key is in KEYS at the repo root, or fetch it from a
keyserver:
gpg --keyserver hkps://keys.openpgp.org --recv-keys 9A18814D74A631389F956EA05F8D7A5EED203343Always verify the fingerprint matches the value above before importing.
gpg --verify officialmesh-<ver>.tar.gz.asc officialmesh-<ver>.tar.gz # release artifact
git verify-tag v<ver> # signed git tagCopyright (C) 2026 The Official Mesh Admin
This program is free software: you can redistribute it and/or modify it under the terms of version 3 of the GNU Affero General Public License as published by the Free Software Foundation. See LICENSE for the full text.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.