Radio Connection

MeshDash supports three physical connection modes. The connection.py module manages the full lifecycle: initial connect, packet streaming, reconnection on loss, and graceful shutdown.

Serial (USB) — Recommended

The most reliable and lowest-latency method. Plug your radio directly into the device running MeshDash over USB.

Finding Your Port

# List all serial devices
ls /dev/tty*

# More targeted — show only ACM and USB serial
ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null

# Watch for the device appearing when you plug in
dmesg | tail -20

Permissions

# Add your user to the dialout group (logout/login required after)
sudo usermod -aG dialout $USER

# Verify membership
groups | grep dialout

WSL2 USB Passthrough (usbipd)

WSL2 does not automatically share USB devices. Install usbipd on Windows then attach your radio:

# In Windows PowerShell (as Administrator)
winget install usbipd

# List all USB devices
usbipd list

# Bind and attach the radio (replace 1-3 with your BUSID)
usbipd bind --busid 1-3
usbipd attach --wsl --busid 1-3

# In WSL, verify
ls /dev/ttyACM*

Config

MESHTASTIC_CONNECTION_TYPE=SERIAL
MESHTASTIC_SERIAL_PORT=/dev/ttyACM0

TCP (WiFi / LAN)

Connects over the local network to a radio with WiFi enabled (e.g. T-Beam in AP or STA mode).

Finding the Radio's IP

• Check your router's DHCP client table
• Use the Meshtastic mobile app — it shows the IP in device settings
• Scan: nmap -sn 192.168.1.0/24

Config

MESHTASTIC_CONNECTION_TYPE=TCP
MESHTASTIC_HOST=192.168.1.50
MESHTASTIC_PORT=4403

Bluetooth (BLE)

Uses the Meshtastic Python SDK's BLE interface. Requires compatible Bluetooth hardware on the MeshDash host.

Finding the MAC Address

sudo bluetoothctl
scan on
# Wait ~10 seconds
devices
# Note the MAC: e.g. AA:BB:CC:DD:EE:FF
quit

Config

MESHTASTIC_CONNECTION_TYPE=BLE
MESHTASTIC_BLE_MAC=AA:BB:CC:DD:EE:FF

Web Serial (Browser-Direct USB)

A fourth connection mode — WEBSERIAL — lets the browser hold the serial port directly, bypassing the server's serial connection entirely. This is useful when MeshDash runs on a remote server but you want to connect a radio physically attached to your local PC.

Set MESHTASTIC_CONNECTION_TYPE=WEBSERIAL in the config (or select it in Settings). After restart, the server will not open any serial port. A WEB SERIAL button appears in the topbar — click it to connect the browser to the radio via the Web Serial API.

See the full Web Serial Connection guide for the complete setup walkthrough, baud rate selection, wakeup frame, and disconnect procedure.

Connection Status

The /api/status endpoint always reflects the current connection state:

GET /api/status

{
  "api_status": "online",
  "connection_status": "Connected",
  "is_system_ready": true,
  "local_node_info": { ... },
  "last_error": null,
  "public_mode": false
}

is_system_ready is true only when the radio connection is fully established and the background sync is complete. Always check this before sending messages.

Connection History

Every connection state change (Connected, Disconnected, Reconnecting, etc.) is logged to the connection_log table and exposed via:

GET /api/system/connection_history?limit=60

Returns timestamped entries with a numeric value field (0.9 = connected, 0.5 = transitioning, 0.1 = disconnected) suitable for time-series charting.

Troubleshooting