Run an observer

Put your bots on the air

An observer is the radio your bots speak through: a repeater you already run, with the txmesh plugin. When someone on your mesh sends one of your !commands, this is the radio that hears it and transmits the answer. It carries your scheduled announcements and weather alerts the same way, and everything it hears while doing that lands on the live map. Nothing to flash, no second radio. About twenty minutes if the repeater is already up.

Create an account Sign in → Bot setup

What an observer really is

Your end of a hosted bot service, not a listening post.

A gateway is an openHop repeater running the txmesh plugin. The plugin adds a companion identity to the radio, so the same board keeps repeating for everyone and also has a node of its own. That node is what your bots run through: it hears the trigger, txmesh renders the reply, and the same radio transmits it back over the route the request took.

Custom !commands

Built in the Commands tab from helpers like {seen}, {vitals} and {route}. Your bots fire only on traffic your gateways hear and reply only through your gateways.

Scheduled announcements

Anything you want on your mesh at a set time, transmitted from your radio.

Weather and flood alerts

Automated NWS watches and warnings and river-gauge flood stages for your area, on the air the moment they are issued.

Route traces

!path and !mpath answer with a link to the path a message actually took to reach your radio.

Everything the radio hears while doing that lands in the archive behind the live map, the node roster, the topology graph and the route traces. That is why we call it an observer, but the observing is the byproduct: the radio is there to run your bots, and the picture of the mesh is what falls out. The wire contract between the plugin and this site is documented in How it works, if you would rather build your own backend.

What you need

An openHop repeater

A LoRa board running openHop Repeater, on a host you can log in to. Version 1.1.4 or newer has a Plugins page in its web UI, which is the easy install. Older versions work with the manual install below.

A way out to the internet

The plugin connects outbound to the collector over TLS on port 443. No inbound ports, no port forwarding.

A txmesh account with observer access

Tick I'm going to run an observer when you sign up, or press Enable observer access on the Bot setup page later. Either way you get one broker login that every gateway you run shares.

A node name

What the mesh will see, so pick one unique to you. It has to match exactly in two places, which is the most common thing to get wrong.

Step by step

The Bot setup page renders both config files below with your login and node name filled in. This page explains what they are and where they go.

1 Get your broker login. Sign in and open Bot setup. It shows a username (obs-…), a password and the endpoint. This login is separate from the password you sign in with, and it can only publish under its own topic, so it is safe to keep in a config file on the repeater host. Don't press Rotate unless it has leaked: rotating breaks every gateway still using the old one.

2 Install the plugin. On the repeater's web UI open Plugins, choose Install, and upload the wheel from the latest release (the file named openhop_txmesh_plugin-<version>-py3-none-any.whl).

No Plugins page, or running it on a separate machine? Install it by hand on the repeater host:

python3 -m venv /opt/openhop_txmesh
/opt/openhop_txmesh/bin/pip install openhop-txmesh-plugin
/opt/openhop_txmesh/bin/openhop-txmesh --help

The manual setup guide also has a systemd unit so it starts with the repeater.

3 Give the radio its second identity. Generate a keypair on the repeater host and keep the identity_key it prints. That key is your node: lose it and the replacement is a different node with a different public key.

openhop-txmesh keygen

Then add a companion to the repeater's config.yaml (/etc/openhop_repeater/config.yaml for the systemd install; on Docker it is in the container's config volume), under identities: companions:. Indentation matters in YAML, and a misaligned block stops the repeater from starting.

identities:
  companions:
    - name: "YOUR-NODE-NAME"
      identity_key: "PASTE-IDENTITY-KEY-HERE"
      settings:
        node_name: "YOUR-NODE-NAME"
        tcp_port: 5001
        bind_address: "127.0.0.1"
        tcp_timeout: 0

Restart the repeater and check its log for the companion frame server coming up:

sudo systemctl restart openhop-repeater
sudo journalctl -u openhop-repeater -n 50 | grep -i "companion frame server"

4 Configure the plugin. The Plugins page has a form for these; the manual install reads them from /etc/openhop_txmesh/config.json. Bot setup prints the whole file ready to paste.

setting	value
node_name	Exactly the name in the companion block above. Same spelling, same case.
companion_host / companion_port	127.0.0.1 and 5001, matching the companion's bind_address and tcp_port.
host / port / transport	the collector host, 443, websockets. Use the endpoint Bot setup shows; a different broker address is the usual reason for "connected, but nothing arrives".
tls_enabled	true
username / password	The broker login from step 1, not your txmesh sign-in.
channels	Which channels the node joins, besides Public which is always on. [{"idx": 1, "name": "#bot"}] is the usual start. A #hashtag channel needs nothing else; a private channel also needs its secret as hex.

Every other setting has a sensible default; the configuration reference lists them all.

5 Enable it and watch it connect. Press Enable on the Plugins page (or start the service). Three lines in the plugin log mean it is working: Connected to companion, Observer MQTT connected and Send bridge subscribed. The repeater's own log shows Companion client connected (port=5001). Within a few minutes your node appears under Devices on the dashboard, and from then on the Commands tab lets you build bots that answer through it. That is what the radio is there for; the map entry came free.

If it doesn't show up

The node name doesn't match. It appears in the companion block and in the plugin config, and they must be identical. This is the first thing to check.

The repeater won't start after the edit. YAML indentation. Every line in the companion block is nested under companions: with consistent spaces, never tabs.

"Connected to companion" never appears. Only one client can hold a companion connection. A phone app attached to the same companion blocks the plugin; give the plugin its own.

Connected, but the site never sees it. The plugin is pointed at a different broker address than the one Bot setup shows. Use that endpoint exactly, TLS on.

It stopped after working for months. Someone pressed Rotate on Bot setup. Paste the current password into the plugin config and restart it.

It came back as a new node. The identity key was lost or regenerated. Restore the original key from your backup; there is no way to rebuild it.

What it shares along the way

The adverts, path hashes and channel messages it hears on the channels you joined, plus its own health: battery, uptime, packet counts. It cannot read direct messages or channels it doesn't hold a key for, so those never leave the radio. On the public site, companion positions are coarsened to about a kilometre and position history is held back; signed-in operators see the precise data their own gateways collected.

Create an account About txmesh