mesh-test-bot

A bot for automatic range tests on a Meshtastic network. It sends a few short messages on a channel, listens for other bots' messages on the same channel, and at the end writes a report of who was heard, over how many hops, with what SNR and RSSI, and how many of each station's messages arrived. Runs in Docker (or with Python), connected to your radio, and repeats itself every week.

New to this, or don't know what Docker is? Follow Start here (also in Portuguese). It covers WiFi radios on Windows, Mac, Linux and Raspberry Pi, and Bluetooth radios on Windows, Linux and Raspberry Pi. The rest of this page is the full reference.

Unofficial project. Not affiliated with or endorsed by the Meshtastic project. "Meshtastic" is a trademark of Meshtastic LLC, used here only to indicate which technology this bot is compatible with.

The message and the report

The bot sends short messages such as MTBOT | ABCD | City | 2/3, listens for the same format from other stations, and writes a readable report and a JSON line per session. The field-by-field format, the report layout, how messages are read and the random timing are in The message, the report and how messages are read.

The report also records the radio's own LoRa mode for each session (Mode: in report.txt's header, radio.mode in report.jsonl), so you can compare sessions run in different modes on the same channel. It's read from the radio's own configuration, never typed by hand: the preset's name (LONG_FAST, NARROW_FAST…) or, for manual settings, BW<kHz>-SF<n>-CR<n> (e.g. BW62-SF7-CR6), which mode_aliases can rename. Only set mode yourself to force a label instead.

Prerequisites

• A Meshtastic radio with WiFi, reachable by IP, with the test channel already configured. The bot does not configure the radio. (A radio with only USB or Bluetooth, such as the RAK4631, works through a bridge: see Radios without WiFi.)
• A test channel, ideally: whatever the bot transmits is heard by everyone on that channel, in the same LoRa mode.
• The radio accepts only one TCP client at a time: close the app and any other program connected to the radio (including other bots) during the session, at the brief startup check --schedule does (below), and on each retry of it.

Quick install (Docker, no git)

You only need Docker with Compose v2: Docker Desktop on Windows and macOS, and on Linux or a Raspberry Pi curl -fsSL https://get.docker.com | sh. No need for git or the source code.

With the installer (Linux, macOS, Raspberry Pi)

curl -fsSL https://raw.githubusercontent.com/cunhaax/mesh-test-bot/master/install/install.sh | sh

Asks a few questions — how the bot should reach the radio (directly, through an existing MeshMonitor, or by setting up a new MeshMonitor right here; see With MeshMonitor below), the test channel's index and name, your city, the message/report prefixes, the session length, number of messages and report window, and whether to run on a recurring weekly schedule or on demand — press Enter to accept the default shown in brackets for any of them. Creates a mesh-test-bot/ folder with the configuration, and prints the exact docker compose commands that start it (the installer never starts anything itself: you run it, and know what it does). If you'd rather read the script before running it, download it and open it.

By hand (also on Windows)

mkdir mesh-test-bot && cd mesh-test-bot
curl -fsSLO https://raw.githubusercontent.com/cunhaax/mesh-test-bot/master/install/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/cunhaax/mesh-test-bot/master/install/env.example -o .env

On PowerShell use curl.exe instead of curl. Edit .env (the first 4 settings: the radio's IP, the channel, the channel's name and your city) and start it:

mkdir data
docker compose up -d

After installing

docker compose logs -f --no-log-prefix      # what it's doing (the 1st line says when the next session is)
docker compose pull && docker compose up -d # update
docker compose down                         # stop

• Reports (report.txt, report.jsonl) and rx.log are in the data/ folder.
• To change the configuration, edit .env and run docker compose up -d (Compose recreates the container when its settings change).
• At startup (scheduled mode), the bot briefly connects to the radio to check it's reachable and on the right channel: Startup check OK in the log means it's set up correctly. If it can't connect, it retries for a few minutes, then exits and the container restarts (each cycle takes a few minutes, so docker ps usually shows Up with a low uptime rather than Restarting; docker inspect -f '{{.RestartCount}}' mesh-test-bot climbing is a clearer sign) until the setup is fixed, instead of waiting quietly for the first scheduled session. docker compose logs says what's wrong (usually the host/port in .env, or the radio being unreachable). On-demand runs have no startup check: they connect when the session starts, and a failed connection shows in the log.
• Every option can go in .env too, as MTBOT_<NAME>: see defaults.ini for the full list and what each one does.

Installing with Docker, from source

git clone <this repository> && cd mesh-test-bot
mkdir data && printf '[bot]\nhost = 192.168.1.50\nchannel = 1\nplace = City\n' > data/bot.ini
# edit data/bot.ini; every other option and its default is in defaults.ini
docker compose up -d
docker compose logs -f --no-log-prefix

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗