Filters Meshtastic MQTT messages based on the "Ok to MQTT" flag, forwarding only authorized messages to an output topic. Supports automatic decryption of encrypted packets using the default LongFast key or custom channel keys.
- Filters messages based on the "Ok to MQTT" bitfield flag (firmware 2.5+)
- Automatic decryption of encrypted packets with default LongFast key
- Support for custom channel encryption keys
- Statistics tracking and periodic reporting
- Daemon mode for background operation
- Docker support for easy deployment
- Create a
.envfile to override default settings (optional):
# Copy the example file
cp .env.example .env
# Edit with your settings
MQTT_BROKER=mqtt.patinhas.da4.org
MQTT_PORT=1883
MQTT_USERNAME=meshdev
MQTT_PASSWORD=large4cats
INPUT_TOPIC=msh/US/NY/#
OUTPUT_TOPIC=filtered/msh/US/NY
# Optional: Enable debug mode
DEBUG=true
# Optional: Add custom channel keys (comma-separated, base64)
CHANNEL_KEYS=base64key1==,base64key2==- Start the service:
docker-compose up -d- View logs:
docker-compose logs -f- Stop the service:
docker-compose downpip install -r requirements.txtThe easiest way to run the filter is using Docker Compose. Create a .env file to configure all settings:
# Copy the example configuration
cp .env.example .env
# Edit .env with your settings
nano .env
# Start the service
docker-compose up -dAll configuration is done via environment variables in the .env file. See .env.example for available options.
python mqtt_filter.py \
--broker mqtt.example.com \
--port 1883 \
--username your_username \
--password your_password \
--input-topic "msh/US/NY/#" \
--output-topic "filtered/meshtastic" \
--show-statsRun the filter in the background as a daemon:
python mqtt_filter.py \
--broker mqtt.example.com \
--input-topic "msh/US/NY/#" \
--output-topic "filtered/meshtastic" \
--daemon--broker: MQTT broker hostname or IP (required)--port: MQTT broker port (default: 1883)--username: MQTT username (optional)--password: MQTT password (optional)--input-topic: Input topic to subscribe to, supports wildcards (required)--output-topic: Output topic for filtered messages (required)--client-id: MQTT client ID (default: meshtastic_filter)--debug: Enable debug logging--show-stats: Print statistics summary every 30 seconds--daemon: Run as daemon in background--no-decrypt-default: Disable decryption with default LongFast key--channel-key: Add custom channel encryption key (base64), can be specified multiple times
- Connects to the MQTT broker with provided credentials
- Subscribes to the input topic (supports wildcards like
msh/US/NY/#) - Receives Meshtastic ServiceEnvelope protobuf messages
- Attempts to decrypt encrypted packets using available keys:
- Default LongFast key:
1PG7OiApB1nwvP+rz05pAQ== - Custom channel keys (if provided)
- Default LongFast key:
- Checks if the message has the "Ok to MQTT" flag set:
- Bit 0 (0x01) of the bitfield in decoded data
- Requires Meshtastic firmware 2.5+
- If approved, forwards the message to the output topic
- If not approved, logs and discards the message
python mqtt_filter.py \
--broker mqtt.patinhas.da4.org \
--username meshdev \
--password large4cats \
--input-topic "msh/US/NY/#" \
--output-topic "filtered/msh/US/NY" \
--show-statspython mqtt_filter.py \
--broker mqtt.example.com \
--input-topic "msh/EU_868/#" \
--output-topic "filtered/mesh" \
--channel-key "your-base64-key-here=" \
--debugpython mqtt_filter.py \
--broker mqtt.example.com \
--input-topic "msh/#" \
--output-topic "filtered/mesh" \
--show-stats \
--daemonThe project includes a comprehensive test suite. See tests/README.md for details.
# Install test dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt
# Run all tests
pytest
# Run with coverage report
pytest --cov=mqtt_filter --cov-report=htmltests/test_mqtt_filter.py- Unit tests for core functionalitytests/test_message_processing.py- Integration tests for message pipelinetests/conftest.py- Shared test fixtures
MIT License - see LICENSE file for details.