Set up a MeshCore source β
This page covers adding a MeshCore radio as a source: what you need, the USB and TCP links, first-boot env vars for headless installs, and fixes for common connection problems. For the short version, see Start here.
Source Types β
MeshCore sources are added through the UI. The Sources sidebar lets you pick a device type of Companion (native JS backend via meshcore.js) or Repeater (direct serial), and a transport of USB / Serial or TCP.
Room Server
Room Server devices use the same Companion path β when present they're auto-detected on connection. There's no Room Server option in the device-type selector; pick Companion and the device will be identified correctly.
Requirements β
- A MeshCore device β A LoRa device flashed with MeshCore firmware (Companion, Repeater, or Room Server)
- Serial port access β If connecting via USB serial, the device must be mapped into the container with
devices:. MeshMonitor opens it as the unprivilegednodeuser; the entrypoint grants that user the device's group automatically. See USB serial devices and the non-root user if you run the container withuser:.
Adding a MeshCore Source β
Add MeshCore sources from the UI β they hot-connect immediately without a restart.
- Open the Sources sidebar on the dashboard (admin only)
- Click + Add next to the Sources header
- Pick MeshCore as the source type
- Choose the transport β USB / Serial (enter the serial port, e.g.
/dev/ttyACM0) or TCP (enter the host and port; see TCP Transport below) - Pick the device type β Companion for full-featured devices, Repeater for direct-serial repeaters (USB only)
- (Optional) Set a Heartbeat interval in seconds (0 = off; new Companion sources start at 60). When set, MeshMonitor periodically probes the node and automatically reconnects with exponential backoff if the link drops β the same setting Meshtastic sources have. It works for Companion and Repeater devices. On a Repeater the probe is a
clockcommand on the serial console: it uses no airtime, and three missed replies in a row reopen the port. A Repeater whose serial port closes (USB unplug, device reset) reconnects on its own even with the heartbeat off. - Save β the source connects immediately if Auto-connect is on
Sources you create from the UI are wired into the per-source MeshCore manager registry the same way Meshtastic TCP sources are, so create / update / delete / connect / disconnect all work without a process restart.
TCP Transport β
Added in 4.5.1. MeshCore Companions can now be reached over TCP directly from the UI β no env-var bootstrap, no container restart. Pick TCP in the transport selector when adding or editing a MeshCore source.
| Field | Default | Notes |
|---|---|---|
| Host | (none) | Hostname or IP of the device or proxy reachable from the MeshMonitor container |
| Port | 5000 | Where the companion listens. WiFi and Ethernet builds use 5000. Change it for a native-TCP build (4403) or a ser2net/esp-link proxy. |
Common ways to put a MeshCore Companion on TCP:
- WiFi / Ethernet firmware β the common case, and what the port field expects. These builds listen on
5000. Put the device on your network and point MeshMonitor at it. - Native TCP firmware β a different Companion build that speaks the binary protocol straight over TCP. It listens on
4403, so change the port when you add the source. ser2netβ Bridge a serial-attached MeshCore device on another host to a TCP port. Useful when the companion is plugged into a Pi or workstation that isn't running MeshMonitor.esp-linkβ ESP8266/ESP32-based serial-to-WiFi adapter wired to the companion's UART. The same binary protocol flows transparently over the link.
Container networking
TCP sources connect from inside the MeshMonitor container, so the host must be reachable from there β use the device's LAN IP (or your gateway hostname), not localhost or 127.0.0.1. If the companion is on the same host as MeshMonitor, use host.docker.internal (already configured in docker-compose.dev.yml) or the host's LAN IP.
Companion only
TCP is a Companion-class feature. Repeater devices are still USB-only β pick the USB / Serial transport when adding a Repeater source.
Tuning Environment Variables β
A couple of background-scheduler tuning knobs are still environment-driven:
| Variable | Default | Description |
|---|---|---|
MESHCORE_TELEMETRY_INTERVAL_MS | 300000 | How often (ms) to poll the local companion for telemetry. Default 5 minutes. |
MESHCORE_REMOTE_TELEMETRY_TICK_MS | 30000 | How often (ms) the remote-telemetry scheduler walks each source and picks an eligible node. |
Headless installs: first-boot env vars β
To get a MeshCore source with no clicks in the UI, set these before the first start. They create a source named Default MeshCore, with the same config the Add Source form would save:
services:
meshmonitor:
environment:
# TCP Companion (WiFi/Ethernet build)...
- MESHCORE_TCP_HOST=192.168.1.60
- MESHCORE_TCP_PORT=5000 # optional, defaults to 5000
# ...or a USB device instead:
# - MESHCORE_SERIAL_PORT=/dev/ttyACM0
# - MESHCORE_BAUD_RATE=115200 # optional
# - MESHCORE_DEVICE_TYPE=repeater # optional: companion (default) or repeater
- MESHCORE_ENABLE_VIRTUAL_NODE=true # optional, Companion only
# devices: # needed for MESHCORE_SERIAL_PORT
# - /dev/ttyACM0:/dev/ttyACM0- First boot only. The vars apply when MeshMonitor first creates its sources. An install that already has sources never grows a MeshCore source because you added them later, and later restarts never change the source.
- Independent of Meshtastic.
MESHTASTIC_NODE_IPstill creates the Meshtastic "Default" source. Set either, both, or neither. With only the MeshCore vars, the disabled Meshtastic placeholder is skipped. - TCP or serial. Set
MESHCORE_TCP_HOSTorMESHCORE_SERIAL_PORT. Both set: MeshMonitor warns and uses TCP. A Repeater needs serial;MESHCORE_DEVICE_TYPE=repeaterwith a TCP host warns and creates no source. - Serial in Docker needs the device mapped into the container with
devices:(see Requirements). - Virtual Node (
MESHCORE_ENABLE_VIRTUAL_NODE,MESHCORE_VIRTUAL_NODE_PORT, default port5000): Companion only, with admin commands and PKI export/import off. See Virtual Node β MeshCore Virtual Node. - The full list is in Environment Variables β MeshCore Default Source.
3.x env vars
3.x had a MeshCore env-var bootstrap that 4.6 removed. These vars reuse most of its names, but only seed a source on first boot. MESHCORE_ENABLED is gone, and MESHCORE_FIRMWARE_TYPE is now MESHCORE_DEVICE_TYPE (the old name logs a warning and is ignored).
TIP
ENABLE_VIRTUAL_NODE is the Meshtastic Virtual Node var. It has no effect on MeshCore sources; use MESHCORE_ENABLE_VIRTUAL_NODE for the MeshCore one.
Device Types β
MeshMonitor automatically detects the device type on connection:
| Device Type | Description | Connection Method |
|---|---|---|
| Companion | Full-featured device with binary protocol support | Native JS backend (meshcore.js, serial or TCP) |
| Repeater | Lightweight relay with text CLI interface | Direct serial |
| Room Server | Chat room server for group messaging | Native JS backend (meshcore.js) |
Virtual Node β
A Companion source can share its radio with the MeshCore phone app. Tick Expose this node to the MeshCore app over WiFi in the source form and pick a port (default 5000), then point the app at the MeshMonitor host and that port. Allow admin commands, Allow PKI export and Allow PKI import stay off unless you trust every client that can reach the port: it has no login. See Virtual Node β MeshCore Virtual Node.
Troubleshooting β
MeshCore source can't be added or connection fails β
- For USB sources: Verify the serial port is accessible inside the container (check
devices:mapping in docker-compose). The entrypoint auto-grants thenodeuser access to mapped tty groups (look forGranted node user access to /dev/...in the container log); if you mounted a device after the container started, restart it. APermission deniedopening the port means the grant did not happen: see USB serial devices and the non-root user. - For TCP sources: Verify the host is reachable from inside the container (the MeshMonitor process resolves it, not your browser). Use a LAN IP rather than
localhost/127.0.0.1, orhost.docker.internalwhen the device shares a host with MeshMonitor. Check the port first β a wrong port is the usual reason a MeshCore TCP source never connects. Use5000for a WiFi/Ethernet build,4403for a native-TCP build, or whatever port yourser2net/esp-linkproxy uses. - Check MeshMonitor logs for
[MeshCore]entries for detailed error messages.
No nodes appearing β
- Verify your MeshCore device is properly flashed and operating.
- Check that the radio frequency and parameters match other nodes in your mesh.
- Try sending an advert to announce your presence on the network. A zero-hop advert reaches nodes in direct range; use a flood advert only if distant nodes need to find you.
Can't log in to or poll a node MeshMonitor shows β
The node is probably missing from the radio's own contact table, often because auto-add contacts is off on the radio. See Radio contact table vs MeshMonitor.
Reporting Issues β
If you hit a problem, please open an issue with:
- Your MeshCore device type and firmware version
- MeshMonitor version
- Relevant log output (look for
[MeshCore]prefixed messages) - Steps to reproduce the issue
