Meshtastic Visualizer

Python PyQt graphical desktop app to interface with a Meshtastic node using a TCP, Bluetooth or serial connection. Possibility to subscribe to MQTT servers and retrieve nodes, messages,... Objective is to use an already configured Meshtastic device, and be able to inspect messages, packets, metrics,...

Initial work based on original repository of "Meshtastic Chat Desktop"

Main framework used is PyQt6. Linux compatible, debian based tested (should work on Windows, compatibility not ensured).

Features

Connection	Serial	TCP	Bluetooth
Availability	✅	✅	✅

Feature	Using local device	Using MQTT
Display nodes configuration (PK, hopsaway,...)	✅	✅
Display map of nodes	✅	✅
Display messages	✅	✅
Display packets	✅	✅
Send messages with acknowledgment	✅	❌
Perform traceroute (with SNR)	✅	❌
Export nodes (json)	✅	✅
Export messages and packets (json)	✅	✅
Export telemetry metrics (json)	✅	✅
Export mqtt logs	-	✅
Export radio serial console	✅	-
Nodes telemetry metrics plotting (CHutil, power,...)	✅	✅
Packets RF metrics plotting (RSSI, SNR,...)	✅	✅
Custom tiles server	✅	✅

Packets investigations

For path analysis and RF experimentation, the Packets tab provides filters to inspect precisely the following categories:

• Radio vs MQTT packets
• Source node
• Detected PORT_NUM
• Relay node (one byte) that requires 2.6.X firmware on relayers. This is particularly helpful when debugging RF links. The average value is updated accordingly.

How to download

$ git clone https://github.com/antlas0/meshtastic_visualizer.git
$ git checkout v1.8

How to install and run

uv is used to manage dependencies, venv and packaging. To install dependencies and run on your computer:

$ uv run meshtastic_visualizer

Note: If you rely on Wayland, you may experience Qt event not properly managed. To fall back on a X11 session, provide the following environment variable when launching the application: XDG_SESSION_TYPE=x11. Otherwise, you can try QT_QPA_PLATFORM=xcb, by having previously installed libxcb-cursor0 package.

How to run with Docker

Based on X11, build the dockerfile and run the docker container. This example assumes your node is accessible at /dev/ttyACM0.

$ export DISPLAY=:0.0
$ xhost +local:docker
$ docker build . -t meshtastic_visualizer:latest
$ docker run -it \
    --env="DISPLAY=$DISPLAY" \
    --privileged \
    --volume="/var/run/dbus/:/var/run/dbus/" \
    --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
    --device=/dev/ttyACM0 \
    meshtastic_visualizer:latest

How to use a local tiles server

To setup a local tiles server, one solution is to use Docker to run a server and point to it from the application.

To import and setup the server, we can rely on openstreetmap-tile-server. Globally we will:

• Download the needed tiles in .pbf format along with the polylines in .poly format, from https://download.geofabrik.de. Here is an example for all France.
• Import them in a Docker volume

$ docker volume create osm-data
$ docker run \
    -v /absolute/path/to/france.osm.pbf:/data/region.osm.pbf \
    -v /absolute/path/to/france.poly:/data/region.poly \
    -v osm-data:/data/database/ \
    overv/openstreetmap-tile-server \
    import

• Run the tiles server with this volume, in this case it will be bound to 0.0.0.0:8080

$ docker run \
    -p 8080:80 \
    -v osm-data:/data/database/ \
    -d overv/openstreetmap-tile-server \
    run

• Give to the application the tiles request http://127.0.0.1:8080/tile/{z}/{x}/{y}.png.

Considerations for an offline map

I would appreciate providing this, but this is currently off the roadmap as folium package does not provide this feature.

Worth to mention that the offline_folium package is intented to overcome this, but only partially at the moment (not all map widgets are supported). Based on that, next steps would be to iterate over all map widgets used in the application, submit a PR to offline_folium to support them (other choice would be to insource this package).

Then implement the dedicated procedure to download locally JS and CSS files. Adding this feature in the application in this context would imply rethinking a bit the distribution due to the offline_folium pre-run steps.

This is not a technical issue, as even with more complexity the feature could become available, but rather an energy / time spent issue. This may change in the future.

Todo

A lot ! Please fill an issue to add ideas or raise bugs.

Here is a list of things it could be intetesting to work on:

App features

• Code factorisation
• Decode environment metrics
• Custom tile server
• Offline map
• Theming
• Quick node actions (shutdown,... TBD)
• Traceroute results: review graphical display as not optimal
• Map: add layer for only "online" nodes
• Map: review "relay node" layer as not easily scalable

Packaging

• Automate non-regression build
• Add backend unitary testing
• Make Docker image available without having to build it

Contributing

Please open a Pull Request.

Overview