This library provides UDP-based broadcasting of Meshtastic-compatible packets.

Installation

pip install mudp

Command Line

To view all Meshtastic udp activity on your LAN:

mudp

mudp accepts the Meshtastic 1-byte PSK aliases AQ==, Ag==, Aw==, BA==, BQ==, Bg==, and Bw== anywhere a channel key is used and normalizes them internally.

If multicast binding needs tuning, set MUDP_BIND_MODE to auto, group, or any. auto prefers binding to the multicast group first on Linux, then falls back to 0.0.0.0.

PubSub RX Topics

When using this library as a listener, it can publish received packets to the Python pubsub system. The following topics are available:

• mesh.rx.raw – publishes (data, addr) with the raw UDP packet bytes and source address tuple.
• mesh.rx.decode_error – publishes (addr) when a packet fails to decode.
• mesh.rx.packet – publishes (packet, addr) for all successfully parsed MeshPacket objects, including duplicates.
• mesh.rx.unique_packet – publishes (packet, addr) only for the first copy of a packet seen by the listener.
• mesh.rx.duplicate – publishes (packet, addr) when the listener sees the same (from, id) again.
• mesh.rx.decoded – publishes (packet, portnum, addr) when the decoded portion is available for a unique packet.
• mesh.rx.port.<portnum> – publishes (packet, addr) for filtering unique packets by port number.
• mesh.rx.text – publishes (packet, addr) for unique decoded TEXT_MESSAGE_APP packets.
• mesh.rx.routing – publishes (packet, routing, addr) for unique decoded ROUTING_APP packets.
• mesh.rx.ack – publishes (packet, routing, addr, pending) for unique routing ACKs and clears any matching pending outbound ACK state.
• mesh.rx.nak – publishes (packet, routing, addr, pending) for unique routing NAKs and clears any matching pending outbound ACK state.

Use mesh.rx.packet when you need every wire observation. Use mesh.rx.unique_packet and the decoded/per-port/text/routing topics for application logic that should run once per logical message.

UDPPacketStream also accepts dedupe_ttl_sec and dedupe_max_entries to tune how long (from, id) observations stay in the duplicate-suppression cache and how large that cache can grow.

Reliability Topics

When sending direct packets with want_ack=True, mudp tracks pending ACK state and retransmits the original serialized packet if no ACK or NAK is received.

• mesh.tx.retry – publishes (pending) when a tracked outbound packet is retransmitted.
• mesh.tx.retry_error – publishes (pending, error) if a retransmit send attempt fails locally.
• mesh.tx.max_retransmit – publishes (pending, error_reason) when retry attempts are exhausted.

Current behavior:

• direct want_ack packets are retried
• broadcast packets are not retried
• ACK and NAK handling uses ROUTING_APP packets
• duplicate classification happens at the listener level using a TTL-backed (from, id) cache

Meshtastic 2.8 examples

The low-level send helpers below create unsigned channel-encrypted packets; they do not derive a key-based node ID, sign broadcasts, or perform PKI DM encryption. The hello-world and ISS scripts are unsigned transport demos and may be rejected by Strict receivers. Setting pki_encrypted=True is only a packet flag; it does not perform PKI encryption.

For an authenticated 2.8 identity, install the optional vnode>=0.1.11 runtime:

from vnode import VirtualNode

node = VirtualNode("node.json")  # Persists a key; derives the node ID from it.
node.send_nodeinfo()            # Signed nodeinfo, including the fixed MAC field.

examples/reply-bot-example.py uses vnode to listen for direct text messages and reply to their sender with automatic PKI selection. Configure node.json with the desired channel and multicast address. vnode remains an optional example dependency, not a mudp runtime dependency.

Low-level unsigned send functions

from mudp import (
    conn,
    node,
    send_nodeinfo,
    send_reply,
    send_text_message,
    send_device_telemetry,
    send_position,
    send_environment_metrics,
    send_power_metrics,
    send_health_metrics,
    send_waypoint,
    send_data,
)

MCAST_GRP = "239.0.0.69"
MCAST_PORT = 4403

node.node_id = "!deadbeef"
node.long_name = "UDP Test"
node.short_name = "UDP"
node.channel = "LongFast"
node.key = "1PG7OiApB1nwvP+rz05pAQ=="
conn.setup_multicast(MCAST_GRP, MCAST_PORT)

send_text_message("text", keys=values...)
send_reply("text", packet.id, keys=values...)
send_reply("👍", packet.id, emoji=True, keys=values...)
send_nodeinfo(keys=values...)
send_device_telemetry(keys=values...)
send_position(latitude, longitude, keys=values...)
send_environment_metrics(keys=values...)
send_power_metrics(keys=values...)
send_health_metrics(keys=values...)
send_waypoint(latitude, longitude, keys=values...)
send_data(destination_id, payload, portnum=256, want_ack=False)

Optional Arguments for all message types:

- to=INT
- hop_limit=INT
- hop_start=INT
- want_ack=BOOL
- want_response=BOOL

Example:
```python
send_text_message("Happy New Year", to=12345678, hop_limit=5)
send_reply("👍", reply_id=packet.id, emoji=True)
send_reply("message received", reply_id=packet.id)
send_data("!deadbeef", b"raw bytes here", portnum=256, want_ack=True)

Use emoji=True when the reply payload is an emoji reaction. Plain-text replies only need reply_id.

Supported keyword arguments for nodeinfo:

• node_id
• long_name
• short_name
• hw_model
• is_licensed
• role
• public_key

Supported keyword arguments for device metrics:

• battery_level
• voltage
• channel_utilization
• air_util_tx
• uptime_seconds

Supported keyword arguments for position metrics:

• latitude (required)
• longitude (required)
• latitude_i
• longitude_i
• altitude
• precision_bits
• HDOP
• PDOP
• VDOP
• altitude_geoidal_separation
• altitude_hae
• altitude_source
• fix_quality
• fix_type
• gps_accuracy
• ground_speed
• ground_track
• next_update
• sats_in_view
• sensor_id
• seq_number
• timestamp
• timestamp_millis_adjust

Supported keyword arguments for environment metrics:

• temperature
• relative_humidity
• barometric_pressure
• gas_resistance
• voltage
• current
• iaq
• distance
• ir_lux
• lux
• radiation
• rainfall_1h
• rainfall_24h
• soil_moisture
• soil_temperature
• uv_lux
• weight
• white_lux
• wind_direction
• wind_gust
• wind_lull
• wind_speed

Supported keyword arguments for power metrics:

• ch1_voltage
• ch1_current
• ch2_voltage
• ch2_current
• ch3_voltage
• ch3_current

Supported keyword arguments for health metrics:

• heart_bpm
• spO2
• temperature

Supported keyword arguments for waypoints:

• id
• latitude
• longitude
• expire
• locked_to
• name
• description
• icon

Install in development (editable) mode:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Signed packets

UDPPacketStream preserves binary protobuf payloads by default. Use parse_payload=True only for legacy display formatting of unsigned payloads; signed payloads remain unchanged even in that mode. Neither parsing nor receipt of a signature verifies it. UDP-supplied xeddsa_signed flags are cleared.