Meshtastic Bot

Although this is based on https://github.com/pskillen/meshtastic-bot I have personalised it a lot to my own setup for commands, auto replies and automations etc

I am now working on Node-totals which I hope to be able to report the number of nodes my remote nodes can see.

Meshtastic Bot is a Python-based bot for interacting with Meshtastic devices. It listens for messages, processes commands, and responds with appropriate actions. This guide is focused on helping you run the bot as-is, with minimal setup.

Quick Start: Run with Docker

The easiest way to run Meshtastic Bot is using Docker. This method requires minimal setup and keeps your environment clean.

1. Prepare Your Environment

• Ensure you have Docker and Docker Compose installed.
• Create a .env file in your project directory with the required environment variables:

MESHTASTIC_IP=your_meshtastic_node_ip
ADMIN_NODES=comma_separated_admin_node_ids
STORAGE_API_ROOT=https://meshflow.pskillen.xyz
STORAGE_API_TOKEN=your_storage_api_token from above site
# Optionally, you can upload to a second API as well
STORAGE_API_2_ROOT=your_storage_api_2_url
STORAGE_API_2_TOKEN=your_storage_api_2_token

# Feature Toggles
ENABLE_TCP_PROXY=true

# Command Toggles (set to false to disable)
ENABLE_COMMAND_PING=true
ENABLE_COMMAND_TR=true
ENABLE_COMMAND_HELLO=true
ENABLE_COMMAND_HELP=true
ENABLE_COMMAND_NODES=true
ENABLE_COMMAND_WHOAMI=true
ENABLE_COMMAND_PREFS=true
ENABLE_COMMAND_ADMIN=true
ENABLE_COMMAND_STATUS=true

2. Use This docker-compose.yaml

services:
  bot:
    image: ghcr.io/pskillen/meshtastic-bot:latest
    container_name: meshtastic-bot
    restart: unless-stopped
    env_file:
      - meshtastic-bot.env
    volumes:
      - mesh_bot_data:/app/data

volumes:
  mesh_bot_data:

3. Start the Bot

docker compose up -d

The bot will now run in the background. Data will be persisted locally in the mesh_bot_data Docker volume.

---

Customization

You can enable or disable specific features and commands using environment variables in your .env or meshtastic-bot.env file. All options default to true if not specified.

Feature Toggles

• ENABLE_TCP_PROXY: Set to false to disable the internal TCP proxy. The bot will connect directly to MESHTASTIC_IP.
• PROXY_HANDSHAKE_CACHE_SIZE: Number of initial packets to cache for connecting proxy clients (default 100).
• PROXY_ROLLING_CACHE_SIZE: Number of recent packets to cache in a rolling queue for connecting proxy clients (default 100).

Command Toggles

Set any of the following to false to disable the command and hide it from the !help menu:

• ENABLE_COMMAND_PING
• ENABLE_COMMAND_TR
• ENABLE_COMMAND_HELLO
• ENABLE_COMMAND_HELP
• ENABLE_COMMAND_NODES
• ENABLE_COMMAND_WHOAMI
• ENABLE_COMMAND_PREFS
• ENABLE_COMMAND_ADMIN
• ENABLE_COMMAND_STATUS

---

Docker Compose Options

There are two primary ways to run the bot using Docker:

1. Standard (docker-compose.yaml) - Recommended for local builds

• Purpose: Stable use with local source control.
• How it works: It builds the bot locally from the source files in the repository.
• Includes: Integrated Watchtower service which automatically checks for and applies updates to the meshtastic-bot container every hour.
• Environment: Configuration is pulled from your .env file.

2. Remote/Pre-built (docker-compose-remote.yaml)

• Purpose: Quick deployment using the official container.
• How it works: Pulls the pre-built image from the GitHub Container Registry (ghcr.io).
• Configuration: Uses meshtastic-bot.env for environment variables and a named Docker volume (mesh_bot_data) for persistence.

---

Native Installation (Advanced/Development)

If you prefer to run the bot natively (e.g., for development or customization):

1. Clone the repository:

   git clone https://github.com/yourusername/meshtastic-bot.git
   cd meshtastic-bot

2. Install dependencies:

   pip install -r requirements.txt

3. (Optional) On Raspberry Pi:

   sudo apt-get install libopenblas-dev

4. Configure environment:
   • Copy .env.example to .env and fill in the required values.
5. Run the bot:

   python main.py

---

Usage

The bot listens for messages and responds to commands as a direct message. You can interact with it via supported Meshtastic channels.

Supported Commands

Command	Description
!help	Displays a list of available commands
!hello	Displays information about the bot
!ping	Responds with "Pong!"
!nodes	Displays a list of connected nodes, stats, etc
!nodes totals	Manually triggers a node count report
!whoami	Displays information about the sender
!tr	Performs a traceroute to the sender (outbound & inbound)
!status	Displays bot status and radio connection details

Features

Node Count Reporting

The bot monitors mesh visibility and provides automated reporting:

• Scheduled Reports: Every 3 hours, a status update is sent to Channel 2 (GregPrivate) with the current online node count.
• Immediate Alerts: If the visible node count drops to zero, the bot sends an immediate warning.
• Manual Check: Use !nodes totals to get an instant report via DM.

Enhanced Connectivity (TCP Proxy)

The bot now includes a built-in TCP proxy to manage the connection to the Meshtastic node. This improves stability and allows for automatic reconnection if the radio connection is lost.

Improved Logging

Messages received on named Group Channels (e.g., 'LongRange', 'PrivateChat') are now logged with their specific channel name, making it easier to track conversations across different mesh networks.

Advanced Traceroute

The !tr command has been upgraded to show the full path:

• Outbound: The route from the bot to your node.
• Inbound: The route back from your node to the bot (if available).

---

Extending the Bot (Development)

If you want to add new commands or responders, see the src/commands/ and src/responders/ directories. The codebase is structured for easy extension, but most users will not need to modify the code to run the bot.

• Commands: Add new command classes and register them in the command factory.
• Responders: Inherit from AbstractResponder to handle public channel messages.

---

Contributing

Contributions are welcome! Please fork the repository and submit a pull request.

License

This project is licensed under the MIT License.