search

geoffwhittington / meshtastic-bridge

MIT License
30 stars 6 forks source link

readme

Meshtastic Bridge

Connect Meshtastic radio networks using MQTT and HTTP.

WARNING: Work in progress

Requirements

Refer to https://meshtastic.org/docs/settings/config/wifi#wifi-client for details on how to configure a Meshtastic device to use wifi and expose a TCP address.

Command-line installation

Download the code and install it onto a system:

$ git clone https://github.com/geoffwhittington/meshtastic-bridge.git

Create a Python virtual environment

$ python3 -m venv meshtastic-bridge

Install the bridge dependencies

$ cd meshtastic-bridge
$ source bin/activate
$ pip install -r requirements.txt

Docker installation

There is nothing to install with Docker, the bridge is downloaded at the time it is run

Configuration

The bridge is configured using a YAML file config.yaml. It is composed of three sections, devices, mqtt_servers and pipelines.

An example config.yaml is provided below:

devices:
   - name: remote
     tcp: 192.168.86.39
     active: true
mqtt_servers:
   - name: external
     server: broker.hivemq.com
     port: 1883
     topic: meshtastic/radio-network1
     pipelines:
       mqtt-to-radio:
         - decrypt_filter:
            key: '/home/user/keys/key.pem'
         - radio_message_plugin:
            device: remote
pipelines:
 radio-to-mqtt:
   - encrypt_filter:
       key: '/home/user/keys/cert.pem'
   - mqtt_plugin:
       name: external
       topic: mesh/tastic

devices is a list of radios the bridge listens for packets or to where it can send packets.

NOTE: If tcp or serial are not given the bridge will attempt to detect a radio attached to the serial port. Additional configuration may be needed to use the serial port with the Docker option.

mqtt_servers is a list of MQTT servers the bridge listens for shared network traffic.

pipelines is a list of ordered plugins (filters/actions) that run when a packet is detected by any connected radio. Each set is given a name; such as radio-to-mqtt (as in the example above). Pipelines can run in any order, however plugins run in the order they are defined.

Plugins

The following plugins can be used in the pipelines section of config.yaml:

Plugin Description
debugger Log the packet to the system console
message_filter Filters out packets from the bridge that match a specific criteria
location_filter Filters out packets that originate too far from a specified device
webhook Send HTTP requests with custom payloads using packet information
mqtt_plugin Send packets to a MQTT server
encrypt_filter Encrypt a packet for a desired MQTT recipient
decrypt_filter Decrypt a packet originating from MQTT
radio_message_plugin Send a packet to a specified device
nostr_plugin Send a NoStr event to a relay
owntracks_plugin Send location data to MQTT server for Owntracks

debugger - Output the contents of a packet

For example:

debugger:
  log_level: debug

Useful for troubleshooting.

message_filter - Allow or block packets based on criteria

For example:

message_filter:
  from:
     allow:
        - !bd5ba0ec
        - !f85bc0bc
     disallow:
        - !c15ba2ec
  message:
     disallow:
        - Good night

location_filter - Filter packets by location from current node (default) or specific location

For example

location_filter:
  max_distance_km: 1000

webhook - Send a HTTP request

Placeholders can be used with the body value:

For example:

webhook:
  active: true
  body: '{"lat": "{LAT}", "lng": "{LNG}", "text_message": "{MSG}"}'
  url: 'https://localhost:8000/message'
  headers:
     Authorization: Token {AUTH_TOKEN}
     Content-type: application/json

mqtt_plugin - Send a packet to a MQTT server

For example:

mqtt_plugin:
  name: external
  topic: meshtastic/topic

Placeholders can be used with the message value:

encrypt_filter - Encrypt a packet before sending it to a MQTT server

For example:

encrypt_filter:
  key: '/home/user/keys/cert.pem'

decrypt_filter - Decrypt message from a MQTT server

For example:

decrypt_filter:
  key: '/home/user/keys/key.pem'

nostr_plugin - Send a NoStr event

For example:

nostr_plugin:
  private_key: "{NOSTR_PRIVATE_KEY}"
  public_key: "npub1d0ja5d.......xw7jys4eqnk0"
  relays:
    - "wss://nostr-pub.wellorder.net"

Placeholders can be used with the message value:

owntracks_plugin - Send location data to MQTT server for Owntracks

For example:

owntracks_plugin:
  server_name: external
  tid_table:
    "1234": ["Van", "GV"]
    "-5678": ["Home", "HR"]

Placeholders can be used with the message value:

radio_message_plugin - Send a packet to a radio

For example:

Broadcasts all packets to the "remote" radio network that are destined to the node 12354345.

radio_message_plugin:
  device: remote
  node_mapping:
    12354345: ^all

Run the bridge

Command-line

Create a config.yaml in the meshtastic-bridge directory. Run:

$ source bin/activate

And:

python main.py

Docker

Create a config.yaml with the desired settings and run the following Docker command:

Linux

docker run --rm --network host -v $(pwd)/config.yaml:/code/config.yaml gwhittington/meshtastic-bridge:latest

Resources