# Meshtastic Python API Reference This page documents the key classes, methods, and patterns of the Meshtastic Python library. It covers the interface classes (the `MeshInterface` base class plus three concrete transports: Serial, TCP, and BLE), the event system, protobuf message types, and error handling. Refer to the library's source on GitHub and the API docs at python.meshtastic.org for the full, authoritative method signatures as the API evolves with each firmware release. ## Interface Class Hierarchy ``` MeshInterface (base class, meshtastic.mesh_interface) ├── SerialInterface (meshtastic.serial_interface) ├── TCPInterface (meshtastic.tcp_interface) └── BLEInterface (meshtastic.ble_interface) ``` The three concrete transports inherit the common message-sending, node-state, and configuration API from `MeshInterface`, but they are not identical: each subclass adds transport-specific constructor parameters (e.g. `SerialInterface``devPath`, `TCPInterface` `hostname`, `BLEInterface``address`) and some transport-specific helper methods. The shared send/read/config surface is inherited from the base class. ## MeshInterface (Base Class) ### Constructor Parameters The `MeshInterface` base constructor takes exactly three parameters: `__init__(self, debugOut=None, noProto=False, noNodes=False)`. There is no `configTimeout` parameter.
ParameterTypeDescription
`debugOut`file-likeStream for debug output. Default None.
`noProto`boolSkip protocol handshake (testing only). Default False.
`noNodes`boolSkip downloading node database on connect. Default False.
### Key Properties Note: configuration and channel data physically live on the local `Node` object, reachable via `iface.localNode` (e.g. `iface.localNode.localConfig`, `iface.localNode.moduleConfig`, `iface.localNode.channels`). The rows below describe those objects' shapes.
Property / PathTypeDescription
`nodes` `Optional[dict[str, dict]]` All known nodes keyed by `"!"` (None before connect). Each value is typically a dict with `num`, `user`, `position`, `snr`, `lastHeard`, `deviceMetrics` — though `position`/`deviceMetrics` are not guaranteed present on every node.
`myInfo` protobuf `MyNodeInfo` (Optional) Basic info about the local node. It is a protobuf object, not a plain dict; the node-number field is `my_node_num`.
`metadata` protobuf `DeviceMetadata` Firmware version, hardware model, capability flags (verify it is populated post-connect in your installed library version before relying on it).
`localNode.localConfig` protobuf `LocalConfig` Full device configuration: `.lora`, `.device`, `.position`, `.power`, `.network`, `.display`, `.bluetooth`, `.security`.
`localNode.moduleConfig` protobuf `LocalModuleConfig` Module configs: `.mqtt`, `.serial`, `.telemetry`, `.neighbor_info`, `.ambient_lighting`, etc.
`localNode.channels` `list[protobuf Channel]` List of channel objects (accessed via the local Node, not a public `localChannels` property on the interface). Each has `.index`, `.role`, `.settings` (name, PSK, etc.).
### Key Methods ``` # Send a text message iface.sendText( text: str, destinationId: Union[int, str] = BROADCAST_ADDR, # "^all" or "!aabbccdd" wantAck: bool = False, wantResponse: bool = False, onResponse: Optional[Callable] = None, channelIndex: int = 0, portNum: PortNum = portnums_pb2.PortNum.TEXT_MESSAGE_APP, ) # Send raw data (any port number) iface.sendData( data: bytes, destinationId: Union[int, str] = BROADCAST_ADDR, portNum: int = portnums_pb2.PortNum.PRIVATE_APP, wantAck: bool = False, wantResponse: bool = False, onResponse: Optional[Callable] = None, onResponseAckPermitted: bool = False, channelIndex: int = 0, hopLimit: Optional[int] = None, pkiEncrypted: bool = False, publicKey: Optional[bytes] = None, priority: MeshPacket.Priority = MeshPacket.Priority.RELIABLE, ) # Get my node info (None if not connected) iface.getMyNodeInfo() -> Optional[Dict] # The node number is read from getMyNodeInfo()["num"] or iface.myInfo.my_node_num # (there is no getMyNodeNum() method on MeshInterface). # Send a traceroute request (hopLimit is required, no default) iface.sendTraceRoute( dest: Union[int, str], hopLimit: int, channelIndex: int = 0, ) # Node-database and config writes are methods on the Node object, NOT on # the base MeshInterface. Obtain the local Node via iface.localNode (or # iface.getNode("^local")): # Remove a node from the local database iface.localNode.removeNode(nodeId: str) # nodeId: "!aabbccdd" # (or use the CLI: meshtastic --remove-node ...) # Write a config change to the device # (after modifying iface.localNode.localConfig protobuf object) iface.localNode.writeConfig(config_name: str) # config_name is one of: "device", "position", "power", "network", # "display", "lora", "bluetooth", "security" # Write module config iface.localNode.writeModuleConfig(config_name: str) # config_name is one of: "mqtt", "serial", "external_notification", # "store_forward", "range_test", "telemetry", # "canned_message", "audio", "remote_hardware", # "neighbor_info", "ambient_lighting", "detection_sensor" # Cleanly close the connection iface.close() -> None ``` ## SerialInterface ``` class meshtastic.serial_interface.SerialInterface( devPath: Optional[str] = None, # e.g. "/dev/ttyUSB0", "COM4"; None = auto-detect debugOut=None, noProto: bool = False, connectNow: bool = True, noNodes: bool = False, ) ``` Auto-detection scans `/dev/ttyUSB*`, `/dev/ttyACM*`, `/dev/cu.usbserial-*`, and Windows COM ports for a device that responds to the Meshtastic handshake. ## TCPInterface ``` class meshtastic.tcp_interface.TCPInterface( hostname: str, # IP address or mDNS hostname debugOut=None, noProto: bool = False, connectNow: bool = True, portNumber: int = 4403, # TCP port; default is 4403 noNodes: bool = False, ) ``` ## BLEInterface ``` class meshtastic.ble_interface.BLEInterface( address: str, # Device name or MAC address noProto: bool = False, debugOut=None, noNodes: bool = False, ) # Static method: scan for devices (synchronous, do NOT await it) BLEInterface.scan() -> list[BLEDevice] ``` ## Event System (pypubsub Topics) The library uses `pypubsub` for all asynchronous notifications. Subscribe before or after creating the interface; the subscription takes effect for all future events. ``` from pubsub import pub # All received packets pub.subscribe(callback, "meshtastic.receive") # Filtered by port (the trailing segment is the protocol name) pub.subscribe(callback, "meshtastic.receive.text") # TEXT_MESSAGE_APP pub.subscribe(callback, "meshtastic.receive.position") # POSITION_APP pub.subscribe(callback, "meshtastic.receive.user") # NODEINFO_APP pub.subscribe(callback, "meshtastic.receive.telemetry") # TELEMETRY_APP (derived from the # protocol registry name; verify against your library's dispatch path) pub.subscribe(callback, "meshtastic.receive.routing") # ROUTING_APP; note ACK/NAK delivery # to callbacks depends on the response (ackPermitted) handlers, not solely this topic pub.subscribe(callback, "meshtastic.receive.data.") # is the integer # port or PortNum enum name (e.g. meshtastic.receive.data.1); no "portnum_" prefix # Connection lifecycle pub.subscribe(callback, "meshtastic.connection.established") # on connect + data download pub.subscribe(callback, "meshtastic.connection.lost") # on disconnect pub.subscribe(callback, "meshtastic.node.updated") # when node DB entry changes ``` ### Callback Signatures ``` # For meshtastic.receive.* def on_receive(packet: dict, interface: MeshInterface) -> None: ... # For meshtastic.connection.established def on_connect(interface: MeshInterface, topic=pub.AUTO_TOPIC) -> None: ... # For meshtastic.connection.lost def on_lost(interface: MeshInterface, topic=pub.AUTO_TOPIC) -> None: ... ``` ### Packet Dictionary Structure ``` { "id": 4012345678, # uint32 packet ID "from": 2864434397, # sender node number (integer) "fromId": "!aabbccdd", # sender node ID (hex string) "to": 4294967295, # destination (4294967295 = broadcast) "toId": "^all", # destination as string "hopLimit": 3, # remaining hops "hopStart": 3, # original hop limit "rxSnr": 4.25, # SNR at receiver (dB) "rxRssi": -98, # RSSI at receiver (dBm) "rxTime": 1714010000, # Unix time packet was received "viaMqtt": False, # True if packet came via MQTT gateway "channel": 0, # channel index "decoded": { "portnum": "TEXT_MESSAGE_APP", "text": "Hello mesh!", # present for TEXT_MESSAGE_APP "position": { ... }, # present for POSITION_APP "telemetry": { ... }, # present for TELEMETRY_APP "user": { ... }, # present for NODEINFO_APP "routing": { ... }, # present for ROUTING_APP }, "raw": } ``` ## Protobuf Message Types The library exposes raw protobuf objects for advanced use. The most important generated modules in the package are:
ModuleKey Message Types
`meshtastic.mesh_pb2` `MeshPacket`, `NodeInfo`, `User`, `Position`, `Data`, `Routing`
`meshtastic.config_pb2` `Config`, `Config.DeviceConfig`, `Config.LoRaConfig`, `Config.PositionConfig`, `Config.NetworkConfig`
`meshtastic.module_config_pb2` `ModuleConfig`, `ModuleConfig.MQTTConfig`, `ModuleConfig.TelemetryConfig`
`meshtastic.telemetry_pb2` `Telemetry`, `DeviceMetrics`, `EnvironmentMetrics`, `PowerMetrics`
`meshtastic.portnums_pb2` `PortNum` enum (TEXT\_MESSAGE\_APP, POSITION\_APP, TELEMETRY\_APP, etc.)
`meshtastic.channel_pb2` `Channel`, `ChannelSettings`
### Example: Modifying a Config Setting ``` import meshtastic import meshtastic.serial_interface iface = meshtastic.serial_interface.SerialInterface() # Get the local Node object (config reads/writes happen on the Node) node = iface.getNode("^local") # Read current value print("Current hop limit:", node.localConfig.lora.hop_limit) # Modify the protobuf object directly node.localConfig.lora.hop_limit = 2 node.localConfig.lora.tx_power = 20 # dBm # Write back to the device (triggers a reboot if radio settings changed) node.writeConfig("lora") iface.close() ``` ## Error Handling Patterns ``` import meshtastic import meshtastic.serial_interface from meshtastic.mesh_interface import MeshInterface # Handle connection failures try: iface = meshtastic.serial_interface.SerialInterface() except Exception as exc: print(f"Failed to connect: {exc}") # Common causes: # - No Meshtastic device found on any serial port # - Permission denied (Linux: add user to dialout group) # - Device busy (app connected via BLE using same serial port implicitly) raise # Handle send timeout (device not responding) import meshtastic.mesh_interface as mi try: iface.sendText("test", destinationId="!aabbccdd", wantAck=True) except Exception as exc: print(f"Send failed: {exc}") # Handle TCP connection refused try: import meshtastic.tcp_interface iface = meshtastic.tcp_interface.TCPInterface("192.168.1.99") except ConnectionRefusedError: print("TCP connection refused. Is the node on Wi-Fi with TCP API enabled?") # Handle device disconnect mid-session from pubsub import pub def on_lost(interface, topic=pub.AUTO_TOPIC): print("Connection to device lost. Attempting reconnect in 5 seconds...") import time, threading def reconnect(): time.sleep(5) try: new_iface = meshtastic.serial_interface.SerialInterface() print("Reconnected successfully.") except Exception as e: print(f"Reconnect failed: {e}") threading.Thread(target=reconnect, daemon=True).start() pub.subscribe(on_lost, "meshtastic.connection.lost") ``` ## Thread Safety The Meshtastic Python library spawns a background reader thread on connection. All pubsub callbacks are invoked from this thread. If your callback modifies shared state, use a `threading.Lock` to prevent race conditions. Outbound publishing is handled by an internal deferred-execution thread; if you call send methods from multiple threads, guard your own shared state and consult the current `mesh_interface.py` source for the library's locking behavior rather than assuming a particular guarantee. ``` import threading lock = threading.Lock() message_log = [] def on_receive(packet, interface): decoded = packet.get("decoded", {}) if decoded.get("portnum") == "TEXT_MESSAGE_APP": with lock: message_log.append({ "time": packet.get("rxTime"), "from": packet.get("fromId"), "text": decoded.get("text"), }) ``` ## Version Compatibility
Library VersionFirmware CompatibilityNotes
2.3.x Firmware 2.3.x Refined traceroute and neighbor-info handling (neighbor-info was introduced in firmware 2.2.0; traceroute predates 2.3).
2.4.x Firmware 2.4.x BLE improvements and config refinements.
2.5.x Firmware 2.5.x Public Key Cryptography (X25519) for direct messages and admin session keys; detection sensor module; power telemetry; new config fields.
Always match the library version to your firmware major/minor version. Mismatches can cause silent config field drops or protobuf decode errors. Run `pip install --upgrade meshtastic` after each firmware update.