vnode 0.1.4

Virtual Meshtastic node using mudp transport and meshdb storage.

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

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.

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/pip install -e .
.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")

The runtime also mirrors the common Meshtastic Python pubsub and method surface:

• topics: meshtastic.connection.established, meshtastic.connection.lost, meshtastic.receive, meshtastic.receive.text, meshtastic.receive.position, meshtastic.receive.user, meshtastic.receive.data.<PORTNUM>, meshtastic.node.updated, meshtastic.log.line
• methods: receive(), unreceive(), close(), sendText(), sendData(), sendPosition(), getMyNodeInfo(), getMyUser(), getLongName()

That means code shaped like the Meshtastic Python library can often run on VirtualNode with minimal changes.

Examples

Use these as small runnable references for common tasks:

• examples/autoresponder.py: DM-only reply bot for inbound direct text messages
• examples/listen_packets.py: packet logger using the mirrored meshtastic.receive callback shape
• examples/send_dm.py: minimal one-shot direct-message sender
• examples/library_embed.py: minimal application-style embedding example using both vnode and Meshtastic-style APIs
• examples/meshtastic_compat.py: minimal Meshtastic-style example using meshtastic.* topics and sendText()
• examples/serial_or_vnode.py: try a real serial node first, then fall back to vnode when no device is attached
• examples/watch_reliability.py: watcher for ACK, NAK, retry, and retransmit-failure events

.venv/bin/python examples/autoresponder.py
.venv/bin/python examples/listen_packets.py
.venv/bin/python examples/send_dm.py --to '!1234abcd' --message 'hello'
.venv/bin/python examples/library_embed.py
.venv/bin/python examples/meshtastic_compat.py
.venv/bin/python examples/serial_or_vnode.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.