vnode

Virtual Meshtastic node runtime built around:

• mudp for multicast UDP send/receive
• meshdb for packet and node persistence
• Meshtastic-style PKI DM encryption using X25519 + SHA-256 + AES-CCM

Install

Install from PyPI:

pip install vnode

If you are working from this repository instead:

.venv/bin/pip install -e .

Config

Edit node.json.

If node.json does not exist yet, the runtime will create it automatically from example-node.json.

If the template leaves node_id blank, the runtime will generate and persist a random Meshtastic-style node ID when it creates or first loads node.json. If long_name or short_name are blank, the runtime will also generate them from the last 4 hex characters of the node ID, for example Meshtastic 691c and 691c.

The runtime will generate and persist a PKI private key into node.json on first run if the private key is blank.

The derived public key is written automatically to node.public.key next to node.json. That file is generated by the runtime and should not need manual edits.

The position section in node.json controls periodic position broadcasts. Set position.enabled to true, then set position.latitude and position.longitude, and adjust position.position_interval_seconds to control how often the node sends POSITION_APP packets. You can also set position.altitude if you want altitude included in the payload. Leave position.enabled false or leave latitude/longitude as null to disable position broadcasts.

Run

.venv/bin/python -m vnode --vnode-file node.json run

Send a DM

.venv/bin/python -m vnode --vnode-file node.json send-text --to '!1234abcd' --message 'hello'

send-text uses PKI automatically for direct messages when the destination node has a stored public key in meshdb. Otherwise it falls back to channel encryption. --config is still accepted as a compatibility alias for --vnode-file.

Library

The installable package lives under vnode/vnode, and the public library surface is exported from vnode directly:

from vnode import NodeConfig, VirtualNode, generate_keypair

node = VirtualNode("node.json")
packet_id = node.send_text("!1234abcd", "hello")

Supported VirtualNode calls:

• Lifecycle: start(), stop(), close(), run_forever()
• Subscription: receive(callback), unreceive(callback)
• Node identity: getLongName(), getShortName(), getPublicKey(), getMyUser(), getMyNodeInfo()
• Native vnode sends: send_text(), send_reply(), send_nodeinfo(), send_position()
• MeshInterface-compatible sends: sendText(), sendAlert(), sendData(), sendPosition()
• Packet helpers: is_direct_message_for_me(), is_text_message(), get_text_message(), reply_to_packet()

receive(callback) is deduplicated. Repeated multicast copies stay on mudp's wire-level topics, while vnode publishes meshtastic.receive from mesh.rx.unique_packet so application callbacks run once per logical packet.

Examples

Use these as small runnable references for common tasks:

• examples/autoresponder.py: DM-only reply bot for inbound direct text messages
• examples/basic_subscriptions.py: minimal node.receive() subscription example
• examples/listen_packets.py: packet logger for multicast traffic and decoded text
• examples/mesh_interface_compat.py: examples of MeshInterface-style compatibility calls on VirtualNode
• examples/serial_or_vnode.py: try a serial Meshtastic node first, then fall back to VirtualNode
• examples/send_dm.py: minimal one-shot direct-message sender
• examples/library_embed.py: minimal application-style embedding example using VirtualNode directly
• examples/watch_reliability.py: watcher for unique ACK, NAK, retry, and retransmit-failure events

.venv/bin/python examples/autoresponder.py
.venv/bin/python examples/basic_subscriptions.py
.venv/bin/python examples/listen_packets.py
.venv/bin/python examples/mesh_interface_compat.py
.venv/bin/python examples/serial_or_vnode.py
.venv/bin/python examples/send_dm.py --to '!1234abcd' --message 'hello'
.venv/bin/python examples/library_embed.py
.venv/bin/python examples/watch_reliability.py --to '!1234abcd' --message 'hello'

See examples/README.md for the full list.

License

GPL-3.0-only. See LICENSE.

Meshtastic® is a registered trademark of Meshtastic LLC. Meshtastic software components are released under various licenses, see GitHub for details. No warranty is provided - use at your own risk.