Meshtastic MQTT Parser

A lightweight Python library for parsing Meshtastic MQTT messages into JSON format. This tool makes it easy to build applications that interact with Meshtastic mesh networks via MQTT.

Overview

This library connects to a Meshtastic MQTT broker and decodes various message types into JSON format, making it simple to process Meshtastic mesh network data in your Python applications.

Features

• Connects to any Meshtastic MQTT broker
• Decrypts encrypted messages
• Parses all standard Meshtastic message types
• Outputs clean JSON format
• Message type filtering support
• Simple command-line interface

Installation

Install from PyPI:

pip install meshtastic-mqtt-json

usage

meshtastic_mqtt_json [options]

from meshtastic_mqtt_json import MeshtasticMQTT

# Create client instance
client = MeshtasticMQTT()

# Register callbacks for specific message types
def on_text_message(json_data):
    print(f'Received text message: {json_data["decoded"]["payload"]}')

def on_position(json_data):
    print(f'Received position update: {json_data["decoded"]["payload"]}')

client.register_callback('TEXT_MESSAGE_APP', on_text_message)
client.register_callback('POSITION_APP', on_position)

# Connect to MQTT broker
client.connect(
    broker='mqtt.meshtastic.org',
    port=1883,
    root='msh/US/2/e/',
    channel='LongFast',
    username='meshdev',
    password='large4cats',
    key='AQ=='
)

Callback System

The library provides a callback system that allows you to register handlers for specific message types. Each callback function receives a JSON object containing the parsed message data.

# Register a callback
client.register_callback('MESSAGE_TYPE', callback_function)

# Unregister a callback
client.unregister_callback('MESSAGE_TYPE')

The callback function should accept a single parameter that will receive the JSON data:

def my_callback(json_data):
    # json_data contains the parsed message
    print(json_data)

If no callback is registered for a message type, the message will be printed to the console by default.

Command Line Options

Filter Example

python meshtastic_mqtt_json.py --filter "NODEINFO,POSITION,TEXT_MESSAGE"

Supported Message Types

The library supports parsing of the following Meshtastic message types: | Message Type | Description | | ------------------------------- | ----------------------------- | | ADMIN_APP | Administrative messages | | ATAK_FORWARDER | ATAK forwarding messages | | ATAK_PLUGIN | ATAK plugin messages | | AUDIO_APP | Audio messages | | DETECTION_SENSOR_APP | Sensor detection data | | IP_TUNNEL_APP | IP tunneling messages | | NEIGHBORINFO_APP | Neighbor information | | NODEINFO_APP | Node information and details | | PAXCOUNTER_APP | People counter data | | POSITION_APP | GPS position updates | | PRIVATE_APP | Private messages | | RANGE_TEST_APP | Range testing data | | REMOTE_HARDWARE_APP | Remote hardware control | | REPLY_APP | Reply messages | | ROUTING_APP | Routing information | | SERIAL_APP | Serial communication | | SIMULATOR_APP | Simulator messages | | STORE_FORWARD_APP | Store and forward messages | | TELEMETRY_APP | Device telemetry data | | TEXT_MESSAGE_APP | Plain text messages | | TEXT_MESSAGE_COMPRESSED_APP | Compressed text messages | | TRACEROUTE_APP | Network route tracing | | WAYPOINT_APP | Waypoint information | | ZPS_APP | Zone/Position System messages |

Roadmap

• Add support for custom node ID & names for the client
• Add support for custom MQTT servers besides the official Meshtastic server
• Create a PyPi package for easy import into other projects
• Create an examples folder with use cases for the library, such as an IRC relay, cli chat, logging, etc.

Mirrors for this repository: acid.vegas • SuperNETs • GitHub • GitLab • Codeberg