meshtastic-mqtt-json

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

Option	Description	Default
--broker	MQTT broker address	mqtt.meshtastic.org
--port	MQTT broker port	1883
--root	Root topic	msh/US/2/e/
--channel	Channel name	LongFast
--username	MQTT username	meshdev
--password	MQTT password	large4cats
--key	Encryption key	AQ==
--filter	Filter specific message types

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