One of the main things that Meshtastic is missing is a proactive way to monitor the network. Has a vital infrastructure node gone offline? Has your channel utilization reached unsafe levels for more than x amount of time? Is your node full of water? Unless you know what you're looking for and consistently check in on this data, you'll never know if something is amiss.
The goal of this repo is to solve that problem. This code will listen to your Meshtastic radio and perform healthchecks on your network on a schedule. If the mesh is in an unhealthy state and triggers a notification, it will send a text message to all admin nodes subscribed to the alert. Think of it like AWS CloudWatch, but for Meshtastic and without relying on any internet backbone.
The listener does accept some basic commands for interfacing with the notification configuration.
-
!t- Replies to the sender with transmission details -
!w- Adds a list of waypoints from the server to your local map with a ttl of 7 days. -
!c- Get the node's healthcheck -
!l- Lists all connected listener nodes -
!i- Get service information (GitHub link and version) -
!h- Prints the list of commands
- Add support for syncing databases between 2 nodes both running the software.
- Notify Admins if version of local node is out of sync with another (like behind verison)
- Metrics Alerting Features:
- Define new subscription tables and allow users to sub / unsub from them
- Give admins the ability to add / remove admin accounts
- Paths through the network with their forward and back SNR, and RX/TX times.
- Gather and analyze error rates for messages (what we see on the notification card on phones)
- Battery level trend over time? ie: downward trend of battery level over n days.
- Monitor CPU core temperatures
Yes, this repo does use a Postgres database on the backend. Yes, it's overkill. Why? Because I needed to learn how to interact with Postgres for a work project. This is how I learned it. Can SQLite3 also get the job done? Absolutely. In fact, that's what the project started with. See versions 1.5.0 if you want to use that. However, I need to learn a new DB and Postgres is the name of the game.
One of the main reasons for switching to Postgres was to allow for a full API frontend and database browser that was independent from the Meshtastic Listener code. The docker-compose file currently includes a conatainer for Adminer. This allows you to view the DB quickly without any additional software. This may change in the future, but it works for now.
git clone https://github.com/migillett/Meshtastic-Listener.git
cd ./Meshtastic-Listener
python3 pip3 install uv
uv sync| Variable | Description | Default |
|---|---|---|
DEVICE_IP |
The IP address or hostname with your radio using TCP/IP. | serial auto-detect |
CMD_PREFIX |
Prefix to use when triggering cmd_handler.py. |
! |
UPDATE_INTERVAL |
How often the service should poll for status updates. Relates to programmatic traceroutes and node database updates. | 15 |
ADMIN_NODE_IDS |
Admin node IDs with elevated permissions and service notifications. List of comma-separated node IDs as integers. | None |
ENABLE_DEBUG |
Sets the logger to debug mode if set to True. |
False |
POSTGRES_DB |
The name of the Postgres database. | listener_db |
POSTGRES_PASSWORD |
The password of the user to connect to the database | No default defined |
ENABLE_DEBUG |
Sets the default logging level to debug if set to true |
false |
This repo has a Docker Compose file to faster deploys. You'll also want to modify the environment secrets for your specific use as well. For examples on various docker deployments, see the Docker Compose Readme
All test scripts can be found in the tests directory. To run tests, you will need to startup the test database using:
docker compose -f ./tests/docker-compose.yml up
alembic upgrade headThen run the test scripts using:
uv run --env-file .env pytest -s ./testsCreate new revision:
alembic revision --autogenerate -m "message"
Upgrade db to current:
alembic upgrade head