Setting up a MeshCore Observer¶

What is a MeshCore Observer?¶

A MeshCore Observer is a MeshCore node (repeater, room server, or companion device) that listens to nearby mesh traffic and reports what it hears to an MQTT broker over the internet. ChiMesh uses observer data to power network analysis, coverage mapping, and reliability reporting across the Chicagoland area via CoreScope, Chicagoland MeshCore Live Map, and the ChiMesh Discord MeshCore MQTT Feed. Observers can be configured to share only advertisement packets, enough to appear on the node map, without exposing the contents of other traffic. You can stop sharing data at any time.

Choose Your Setup Method¶

There are four ways to run an Observer:

Method 1: Native Observer Firmware¶

Step 1: Download and Flash the Firmware¶

Fresh Install¶

Use the MeshCore MQTT Observer Flasher to find, download, and flash the correct firmware for your device. This is an online flasher, select your device variant and follow the prompts to flash directly from your browser.

Updating via OTA¶

If you already have MeshCore running, you can update wirelessly using the companion app and a web browser instead of the web flasher and USB:

1. Download the App Firmware
   • Before starting the OTA process, visit the MeshCore Observer Flasher
   • Select your device, and use the Download button to download the app firmware option

   Do not use a merged file

   This variant does not erase your flash and is safe for updating an existing install. Do not use a merged file, it will wipe all your settings.

2. Open Remote Management
   • Open the MeshCore companion app
   • Select your node from the contacts list or map
   • Scroll down and tap Remote Management
   • Enter the admin password when prompted
3. Launch the Command Line
   • Tap Command Line in the middle of the bottom footer
   • Enter start ota
   • Click Enter on your keyboard
4. Navigate to the OTA Upload Page
   • If your node is not connected to Wi-Fi, it will broadcast a MeshCore-OTA hotspot instead, connect to that and go to http://192.168.4.1/update
   • If your node is already connected to Wi-Fi, it will stay on your existing network:
     • Check your node's display for the IP address or if your node does not have a screen, check your router's DHCP table to find the IP address assigned to your node
     • Open a browser and go to http://<node-ip>/update (e.g. http://192.168.1.42/update)
5. Upload the Firmware
   • Select and upload your downloaded .bin file
   • Wait for the update to complete
6. Verify the Update
   • Reopen the companion app
   • Confirm the firmware version under Remote Management

Step 2: Apply ChiMesh Observer Settings¶

Once your firmware is installed, open the Command Line under Remote Management and enter the following commands:

set timezone America/Chicago

set path.hash.mode 2

set advert.interval 240

set mqtt.iata ORD

set mqtt1.preset analyzer-us

set mqtt2.preset chimesh

set mqtt2.server wss://mqtt.chimesh.org

set mqtt2.port 443

set mqtt2.audience mqtt.chimesh.org

set mqtt2.preset custom

set mqtt.rx on

set mqtt.tx advert

set wifi.ssid your-wifi-network

set wifi.pwd your-wifi-password

set bridge.enabled on

set flood.advert.interval 72

set radio.watchdog 60

set repeat off

set flood.advert.interval 168

set mqtt.owner your-primary-companion-device-pub-key

reboot

Step 3: Configure Observer Alerts (Optional)¶

The ESP32-native MQTT observer firmware can alert you over the LoRa network if it encounters Wi-Fi or broker connectivity issues. Alerts are sent as flooded channel messages to either a hashtag channel or a private channel of your choosing.

Choose an Alert Channel¶

If you choose to use the shared hashtag channel #chimesh-observer-alert, no setup required on the channel itself. Set your companion to receive messages on #chimesh-observer-alert.

If you prefer to use your own private channel, create a private channel via the mobile app, then use the share option on the channel to copy the secret hex key to your clipboard. Save the secret somewhere safe (e.g. a password manager) in case you need to restore it later or add it to a new companion device.

Configure Alerts¶

From the Command Line, run the commands for whichever channel option you chose:

If using the ChiMesh hashtag channel (recommended):

set alert.hashtag #chimesh-observer-alert

If using your own private channel:

set alert.psk <secretkey>

Then, regardless of which option you chose:

set alert.wifi 10

set alert.mqtt 30

set alert on

Once configured, use the alert test command to immediately send a test message and confirm your companion can receive alerts from the firmware:

alert test

Method 2: Computer Bridge (USB + Raspberry Pi)¶

Requirements¶

• Any supported MeshCore repeater or room server node with existing firmware
• A Linux device (Raspberry Pi or similar) with internet access
• USB connection between the node and the Linux device

Step 1: Get Compatible Firmware¶

Your node needs firmware that includes packet logging support. Use the MeshCore Observer Flasher to find and flash the appropriate firmware for your device variant.

Step 2: Connect and Run the Install Script¶

With your node connected to your Linux device via USB, run the following from your terminal:

curl -fsSL https://raw.githubusercontent.com/Cisien/meshcoretomqtt/main/install.sh | bash

When prompted by the install script, select the LetsMesh and ChiMesh presets.

Method 3: Companion Bridge¶

Unlike repeater or room server nodes, companion observers don't require special firmware. Your standard MeshCore companion build supports packet logging. This method uses different bridge software than mctomqtt and runs on a macOS or Linux device connected to your companion via USB, BLE, or Wi-Fi.

Requirements¶

• A macOS or Linux device (e.g., Raspberry Pi) with internet connectivity
• A MeshCore companion device accessible via USB, BLE, or Wi-Fi

Step 1: Install Node.js LTS¶

First, install NVM (Node Version Manager):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Close and reopen your terminal, or run the following to activate it immediately:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Then install Node.js LTS:

nvm install --lts

Step 2: Run the Install Script¶

From your macOS or Linux machine, run:

bash <(curl -fsSL https://raw.githubusercontent.com/agessaman/meshcore-packet-capture/main/install.sh)

The installer will set up packet capture support for BLE, TCP, and Wi-Fi connections to your companion device.

Step 3: Configure ChiMesh MQTT¶

When prompted during setup, select chimesh from the available presets. The installer will configure the connection details automatically.

For more details, see the meshcore-packet-capture README. For help, reach out on the ChiMesh Discord or the MeshCore Discord.

Method 4: openHop Repeater (Advanced)¶

openHop Repeater is a Python-based MeshCore repeater daemon that runs on Linux and publishes to MQTT natively through its config.yaml. It supports direct SPI LoRa HATs, USB modem boards (ESP32/nRF52 running openHop Modem firmware), and TCP-connected modems, and can operate as a dedicated observer that uploads packet activity and mesh health to MQTT without needing the standard MeshCore firmware or any bridge script.

Requirements¶

• A Raspberry Pi or other Linux SBC with internet access
• A supported LoRa radio
  • SPI HAT (e.g., Waveshare SX1262 HAT, meshadv, meshadv-mini) connected directly to the Pi
  • ESP32 or nRF52 board flashed with openHop Modem firmware connected over USB-CDC or TCP
  • CH341 USB-to-SPI adapter wired to an SX1262 module (e.g., for Proxmox LXC deployments)

Step 1: Install openHop Repeater¶

git clone https://github.com/openhop-dev/openhop_repeater.git
cd openhop_repeater
sudo bash ./manage.sh install

The installer will create the config directory at /etc/openhop_repeater/, install the application to /opt/openhop_repeater/, launch an interactive setup wizard for radio hardware selection, and install and enable the openhop-repeater systemd service.

Follow the wizard prompts to select your hardware type and radio preset. For USB modem boards, select the pymc_usb modem (USB-CDC) option. For Wi-Fi or Ethernet modems, select pymc_tcp modem. For a direct SPI HAT, select sx1262.

Step 2: Configure ChiMesh MQTT¶

Open /etc/openhop_repeater/config.yaml and update the mqtt_brokers section:

mqtt_brokers:
  iata_code: "ORD"
  status_interval: 300
  owner: ""
  brokers:
    - preset: letsmesh

    - name: chimesh
      enabled: true
      host: mqtt.chimesh.org
      port: 443
      transport: websockets
      audience: mqtt.chimesh.org
      use_jwt_auth: true
      tls:
        enabled: true

mqtt_brokers:
  owner: "your-primary-companion-device-pub-key"

Step 3: Apply ChiMesh Mesh Settings¶

In the same config.yaml, set the following under the mesh section:

mesh:
  unscoped_flood_allow: true
  path_hash_mode: 2
  loop_detect: minimal

And under repeater, set a reasonable advert interval:

repeater:
  send_advert_interval_hours: 4

Step 4: Restart and Verify¶

sudo systemctl restart openhop-repeater
sudo journalctl -u openhop-repeater -f

The web dashboard is available at http://<repeater-ip>:8000 and shows connection status, packet history, and MQTT broker state.

For full configuration options, see the openHop Repeater Configuration Reference. For help, reach out on the Discord.

Additional Notes¶

• These settings are required to appear on ChiMesh(Core) services
• set mqtt2.preset chimesh is what connects your observer to the ChiMesh network specifically while set mqtt1.preset analyzer-us is what connects your observer to the global LetsMesh analyzer and the official MeshCore map
• The mqtt.owner field is optional but highly encouraged, it links your observer to your primary companion device

Thank you for supporting ChiMesh.org, we hope to see you on MeshCore MQTT!