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 three 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 repeat off

set flood.advert.interval 168

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

reboot

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¶

The companion bridge does not currently support preset-based configuration. Enter the following connection details manually when prompted, or in the bridge configuration:

For more details, see the meshcore-packet-capture README. For help, reach out on the ChiMesh Discord or the MeshCore 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 soon!