mushtastic

mushtastic installs the mush command: a Meshtastic live packet logger with an interactive prompt. It connects to a radio over serial, TCP, or BLE; stores received and locally sent packets in SQLite; and provides tools to inspect nodes and packets, send messages, configure the radio, and manage channels.

Requirements

• Python 3.10 or newer
• A Meshtastic-capable radio reachable over USB/serial, TCP, or BLE

Install

pip install mushtastic

Run either entry point after installation:

mush --help
python -m mushtastic --help

Start a live session

mush live                         # auto-detect a serial radio
mush live --dev /dev/ttyUSB0
mush live --tcp 192.168.1.50:4403
mush live --ble AA:BB:CC:DD:EE:FF

Choose at most one of --dev, --tcp, and --ble. A TCP address without a port uses port 4403. Serial connections automatically try to reconnect after a radio restart.

Use Ctrl+D to leave the prompt. BLE shutdown is limited to five seconds, so mush may print a warning and exit if the underlying Bluetooth library stalls.

The prompt shows the radio's default hop limit, local node identity, and the current message target, for example:

🐰3 !deadbeef MUSH @ primary>

Global options

Place global options before the command:

Without --database, mush uses mush.db in the current directory.

Messaging in the prompt

Commands begin with /. Any other nonempty line sends a text message to the current target, which starts as the primary channel. Set the target with /target:

/target !deadbeef       # a node ID
/target NORTH           # a unique node short name, or a channel name
/target #1              # channel 1
Hello from the field!   # sent to the selected target

Channel names take precedence when a channel name and node short name match. !xxxxxxxx, ^local, and ^all identify nodes. #0 through #7 identify enabled channels.

Send one message to another target without changing the selection by prefixing it with @ENTITY:

@LongFast hello everyone
@!deadbeef are you there?
@#1 need assistance

Use a #N prefix to override the hop limit for one message, where N is 0 through 7. For a one-off target, it may appear before @ENTITY or immediately after it:

#3 hello there
@admin #2 need help
#2 @admin need help

Use /hops to view the default hop limit, or /hops N to change it. A literal message cannot begin with /.

Prompt commands

Type / then press Tab for completion, or use /COMMAND --help for full syntax.

Radio and configuration

Configuration option names accept snake_case and camelCase. Repeated values must be JSON arrays, such as [1, 2].

Nodes

/node (/n, /nodes) without a subcommand shows the local node's saved record.

Channels

/channel (/c, /chan) lists channels. Channel management is available only inside a live session.

Channel indexes are 0 through 7. Channel names are limited to 10 characters. The primary channel (0) cannot be deleted or moved. A supplied PSK can use the base64: prefix; --random-psk creates and displays a 32-byte key.

Packets and filters

/filter limits displayed live packets and /packet results. /filter-out hides matching packets. Neither prevents packets from being saved.

/filter from NORTH SOUTH
/filter channel LongFast
/filter portnum POSITION_APP
/filter-out portnum TELEMETRY_APP
/filter clear

Each filter provides clear, from [NODE ...], to [NODE ...], channel [CHANNEL ...], and portnum [PORTNUM ...]. Values within one field are alternatives; active inclusion fields are combined. An exclusion applies only when all of its configured fields match.

/packet (/p, /pkt, /packets) operates on the active filtered set:

One-shot shell commands

These commands query the local database without connecting to a radio:

mush ble-scan
mush node ls [COUNT]
mush node show NAME
mush node rm ID
mush node count
mush packet [FILTERS] list [COUNT]
mush packet [FILTERS] show [ID] [--raw]
mush packet [FILTERS] process
mush packet [FILTERS] import [--merge=append|overwrite|skip]
mush packet [FILTERS] portnums
mush packet [FILTERS] count

mush packet supports --id, --msg-id, --limit, --portnum, --from-id, --to-id, --id-start, --id-end, --rx-time-start, and --rx-time-end. For example:

mush packet --portnum POSITION_APP list 20

Use mush COMMAND --help for command-specific options and aliases.

Data and privacy

The SQLite database contains the node, packet, and replhistory tables. It can contain node identities, messages, telemetry, and locations. Treat it as sensitive data. To back it up or move it, copy the database while mush is not running.