MeshCore Python API

The MeshCore Python library provides an async interface for building applications and scripts that communicate with MeshCore nodes. It is the primary programmatic access method for automation, network monitoring, and custom integrations.

Requirements

• Python 3.10 or newer (required — uses structural pattern matching)
• A MeshCore node connected via USB serial or TCP

Installation

pip install meshcore

Source: github.com/MeshCore-dev/MeshCore_py

Connecting to a node

import asyncio
from meshcore import MeshCore

async def main():
    # Connect via USB serial (most common)
    mc = await MeshCore.connect_serial("/dev/ttyUSB0", baudrate=115200)

    # Or via TCP (for nodes with WiFi/TCP bridge)
    # mc = await MeshCore.connect_tcp("192.168.1.100", port=5000)

    print(f"Connected to: {mc.self_info.name}")
    await mc.disconnect()

asyncio.run(main())

Listing nodes and contacts

async def main():
    mc = await MeshCore.connect_serial("/dev/ttyUSB0")

    # Get all known contacts (nodes heard by this device)
    contacts = await mc.get_contacts()
    for contact in contacts:
        print(f"{contact.name} | RSSI: {contact.last_rssi} dBm | SNR: {contact.last_snr} dB")

    await mc.disconnect()

Sending a message

async def main():
    mc = await MeshCore.connect_serial("/dev/ttyUSB0")

    # Send to a channel (broadcast)
    await mc.send_channel_message("Hello mesh!", channel=0)

    # Send direct message to a contact by node ID
    contacts = await mc.get_contacts()
    target = next(c for c in contacts if c.name == "Base Station")
    await mc.send_direct_message(target.node_id, "Hello from Python!")

    await mc.disconnect()

Monitoring incoming messages

import asyncio
from meshcore import MeshCore, MessageEvent

async def main():
    mc = await MeshCore.connect_serial("/dev/ttyUSB0")

    async def on_message(event: MessageEvent):
        print(f"[{event.sender_name}] {event.text}")

    mc.on_message(on_message)

    # Keep running and receiving events
    print("Monitoring... press Ctrl+C to stop")
    try:
        await asyncio.sleep(float('inf'))
    except KeyboardInterrupt:
        pass
    finally:
        await mc.disconnect()

asyncio.run(main())

Getting node telemetry

async def main():
    mc = await MeshCore.connect_serial("/dev/ttyUSB0")

    info = mc.self_info
    print(f"Node: {info.name}")
    print(f"Battery: {info.battery_mv} mV")
    print(f"Uptime: {info.uptime_s} seconds")
    print(f"TX power: {info.tx_power_dbm} dBm")

    await mc.disconnect()

Use cases

• Network monitoring dashboards — log all messages and node activity to a database
• Gateway integrations — bridge MeshCore messages to Discord, MQTT, or other platforms
• Automated alerts — notify via SMS or email when specific keywords are detected
• Repeater health monitoring — check uptime, battery level, and contact count on a schedule
• Coverage mapping — record signal reports from automated messages during a walking survey

Error handling notes

MeshCore over serial can occasionally miss bytes or timeout. The library includes automatic reconnect logic, but long-running scripts should wrap operations in try/except blocks and handle MeshCoreConnectionError gracefully.