Getting Started

When you first launch Meshy, you'll see the connection screen. You need a MeshCore companion device (e.g., a Heltec V3, T-Beam, WisBlock, or similar LoRa board running MeshCore firmware) to use the app.

The Companions list

Companions are listed together. Each row has a button for every connection method (Bluetooth, WiFi, USB) between the name and the Connect button.

  • A bright icon means the method is set up. Click it to select that method, then click Connect.
  • A greyed-out icon means the method is not set up yet. Click it to configure it (pair over Bluetooth, or enter the WiFi address).
  • A USB companion shows only its USB button, because USB cannot be combined with the other methods.

Use the Add New Companion button below the list to add a new companion:

  • Bluetooth — pick an already-paired companion or pair a new one.
  • WiFi — enter the IP address/hostname and port.
  • USB — pick a connected serial device.

Right-click (or long-press) a row to Change Address (WiFi) or Remove Companion (with an option to delete its stored data).

Connecting via Bluetooth

  1. Make sure Bluetooth is enabled on your computer.
  2. Click Add New Companion → Bluetooth and pick your companion, or choose Pair a New Companion to scan for a new one. Meshy scans for devices advertising the Nordic UART Service (NUS), which is how MeshCore companions identify themselves over Bluetooth.
  3. Select your device from the scan results. If the device requires a PIN, a dialog will appear. Enter the PIN shown on your device's screen. If you enter a wrong PIN, an error message is shown and the PIN dialog reappears automatically.
  4. Once paired, Meshy connects automatically and begins syncing contacts, channels, and messages.

Connection Retry: If the connection fails, Meshy automatically retries up to 3 times with increasing delays between attempts.

Connecting via USB

  1. Connect your MeshCore device via USB cable.
  2. Click Add New Companion → USB and pick the detected serial device (ttyACM/ttyUSB).
  3. The connection uses 115200 baud by default.
  4. If you see a permission error, Meshy will offer to install a udev rule. This requires administrator privileges and sets the correct permissions for the serial device. After installation, unplug and replug the device.

Connecting via WiFi / TCP

For network-connected companion devices or remote access:

  1. Click Add New Companion → WiFi.
  2. Enter the IP address or hostname (e.g., 192.168.40.10).
  3. Enter the port (default is 5000).
  4. Click Connect.

The connection is saved with its companion and can be reconnected later. To change the address, right-click (or long-press) the companion and select Change Address.

Multiple connection methods

A single companion can be reached several ways. For a board that runs Bluetooth and WiFi at the same time (MeshCore firmware 1.18 and newer) that is already added over Bluetooth, click the greyed-out WiFi icon on its row and enter the IP address. Both icons then appear on the row — click the one you want to use, then Connect. The device's IP can be read on its screen or, once connected over Bluetooth, with the get wifi.ip command in the Device CLI.

Meshy also detects this automatically: whenever it connects to a companion over Bluetooth or USB and that companion reports it is reachable over WiFi, Meshy remembers the WiFi address (and network name) and adds the WiFi option to the row, so you do not have to type the IP yourself. A manually entered WiFi address is never overwritten.

Auto-Reconnect

Meshy remembers the last connected device and transport method. On subsequent launches, it attempts to reconnect automatically. If the device is unavailable or the connection fails after retries, the connection screen is shown.

While Meshy is connecting or reconnecting, the connecting screen and the sidebar banner offer a Cancel button. It stops the current attempt or the retry loop, so a companion that is out of range does not keep Meshy retrying in the background.

Meshy is also suspend-aware: when your computer goes to sleep, it cleanly disconnects from the device and reconnects automatically after wake-up. Any messages received by the device while disconnected are synced on reconnect, and a notification shows the count of missed direct and channel messages.