Jean-Pierre MartineauandClaude Opus 5.5
5d0bf52717
A new page, docs/connecting.md, collects every connection failure MeshTerm reports, with its cause and remedy: who pairs a Bluetooth companion on each system (MeshTerm on Windows and Linux, macOS's own dialog there, where --ble-pin does nothing), the terminal's Bluetooth permission on macOS and its refusal over SSH, reading a screenless companion's PIN over USB, forgetting a pairing on each system, and the dialout group and ModemManager for USB on Linux. The README, the docs index, hardware.md, and the CLI manual's failure section link to it, and --ble-pin says it has no effect on macOS. The CLI manual's no-radio example shows today's message. The changelog covers the Linux Bluetooth pairing and link fixes and the per-step failure messages. configuration.md shows db_path, and a few lists gain their Oxford comma, WiFi becomes Wi-Fi, and "never-before-seen" becomes "heard for the first time". Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
8.4 KiB
When a companion won't connect
MeshTerm talks to a MeshCore companion over USB, Bluetooth, or TCP, or runs the node itself on a radio on the SPI bus. When a connection fails, MeshTerm says which step failed and what to do about it, in the device picker and on the command line alike. This page collects those messages, so you can look one up before you meet it, or search for the one you have.
Every failure is also written to the log file, ~/.meshterm/meshterm.log (see
Where MeshTerm keeps its state). Attach it to a
bug report. For more detail, set the Log detail preference to DEBUG (meshterm preferences set log_level DEBUG) and run it again.
Bluetooth
A companion takes one Bluetooth connection at a time. If your phone's MeshCore app is connected to it, MeshTerm cannot connect until the phone lets go, and the companion stops advertising while it is connected, so MeshTerm cannot even see it. Disconnect the phone first, or turn its Bluetooth off.
Who does the pairing
A PIN-protected companion must be paired before it will talk: the computer and the companion exchange keys once, using the six-digit PIN, and remember them. Who runs that exchange depends on the system.
| System | Who pairs | What you do |
|---|---|---|
| Windows | MeshTerm | Give the PIN when MeshTerm asks for it (the picker's PIN dialog, or --ble-pin on the command line). You do not need to pair in Settings first. |
| Linux | MeshTerm | The same. MeshTerm answers the pairing itself, so it works over SSH and on machines with no desktop, and you do not need bluetoothctl or the desktop's Bluetooth settings. |
| macOS | macOS | macOS shows its own dialog asking for the code; type the PIN there. --ble-pin has no effect on macOS. |
Once paired, the system remembers it, and later connections need no PIN.
On macOS, the terminal needs Bluetooth permission. macOS grants Bluetooth to the app MeshTerm runs in (Terminal, iTerm2, Ghostty), not to MeshTerm itself. If no pairing dialog appears, or no Bluetooth devices are listed, check System Settings > Privacy & Security > Bluetooth. Over SSH, macOS denies Bluetooth outright and never asks, so run MeshTerm in a terminal on the Mac itself.
Finding the PIN
The PIN is shown on the companion's screen, or in the MeshCore app's settings for it. A companion with no screen (a T1000-E, for instance) can tell you over USB instead:
$ meshterm --port /dev/ttyACM0 config get device_pin
123456
meshterm config set device_pin <PIN> changes it, and so does the Device PIN row on
the menu's Device config page. A changed PIN makes every existing pairing with that
companion out of date. See a stale pairing below.
What each Bluetooth message means
In the device picker, a pairing problem opens the PIN dialog with a one-line reason under the question. On the command line, it is the error message. Both come from the same diagnosis.
| The message starts with… | What happened | What to do |
|---|---|---|
| couldn't open a Bluetooth link | The companion was never reached. | Move closer, check it is powered on, and make sure no phone or other computer is connected to it. |
| requires a Bluetooth pairing PIN | The companion is PIN-protected and not paired with this computer. | Give the PIN: the picker asks for it; on the command line, add --ble-pin <PIN>. |
| Windows has … paired / Linux has … paired, but the device refused that pairing | Your computer remembers a pairing that the companion no longer accepts. It was reflashed, reset, or given a new PIN, or it was paired without a PIN back when it did not have one. | Give the PIN, and MeshTerm removes the old pairing and pairs again. Or forget the pairing yourself and reconnect. |
| rejected the Bluetooth PIN | The PIN was wrong. | Check the code on the device or in the MeshCore app, and try again. |
| refused to pair | The companion turned the pairing down. It is usually connected to a phone, or still holds an old pairing for this computer. | Disconnect it from anything else, or restart it, and try again. |
| Windows couldn't pair / Linux couldn't pair | The pairing failed for another reason, named in brackets. | Restart the companion, forget the pairing, and try again. |
| Windows couldn't reach / Linux couldn't reach … to pair it | The system could not find the companion when it came to pair. | As for a link that never opened: range, power, or another connection. |
| paired with …, but the device still refuses the connection | Pairing succeeded, yet the companion still refuses. It is holding an old pairing for this computer. | Restart the companion, forget the pairing, and try again. |
| was not paired. macOS asks for the pairing code in its own dialog | macOS had not finished pairing. | Type the PIN into the macOS dialog when it appears. If none appears, check the terminal's Bluetooth permission (above). |
| connecting … took longer than | The link, the pairing, or the service discovery stalled. | Move closer, restart the companion, and try again. |
| connected …, but it didn't answer the identity query | The link came up and the companion went quiet. | It may be busy with another app. Restart it and try again. |
| connected …, but it never answered as a MeshCore companion | Something answered, but not as a companion. | It may be running repeater or room server firmware, which has no companion interface. |
Forgetting a pairing
MeshTerm fixes a stale pairing itself when you give it the PIN. To remove one by hand:
- Windows: Settings > Bluetooth & devices, open the companion, and choose Remove device.
- Linux:
bluetoothctl remove AA:BB:CC:DD:EE:FF, with your companion's address. - macOS: System Settings > Bluetooth, the companion's ⓘ button, then Forget This Device.
On Windows and Linux, MeshTerm's quit dialog also offers Unpair & quit while a paired Bluetooth companion is connected. It forgets the pairing on the way out, so the next connection asks for the PIN again.
USB
| The message starts with… | What happened | What to do |
|---|---|---|
| no permission to open | Your user may not open the port. On Linux, serial ports belong to a group, dialout on Ubuntu and Debian. |
sudo usermod -aG dialout $USER, then log out and back in. The new group applies only to a new login. |
| … is in use by another program | Something else has the port open: the MeshCore app, a firmware flasher, or a serial monitor. On Windows this is reported as Access is denied. | Close the other program. On Linux, ModemManager probes new USB serial devices and can hold one: sudo systemctl stop ModemManager, and try again. |
| … isn't there | The port does not exist. The device was unplugged, or came back under another name (/dev/ttyACM0 becoming /dev/ttyACM1, COM5 becoming COM6). |
meshterm devices lists what is attached now. |
| no response from a MeshCore companion on … | The port opened, but nothing answered as a companion. | It may not be a MeshCore companion (repeater firmware, or another device), or it is powered off or busy. On Linux, ModemManager may be probing it: sudo systemctl stop ModemManager, and try again. |
To stop ModemManager for good rather than for one boot, sudo systemctl disable --now ModemManager, if nothing else on the machine needs it. Nothing does unless you have a
cellular modem.
TCP
no response from a MeshCore companion at HOST:PORT means nothing answered there. Check
the host and the port (MeshTerm's default is 5000), that the companion is powered on and
reachable on your network, and that no other client is already connected to it. Like
Bluetooth, a network companion serves one client at a time.
A radio on the SPI bus
A radio MeshTerm drives itself (--spi) is not a companion. It has no pairing and no port,
and its failures are about the node MeshTerm starts. Its own guides cover them:
the uConsole and adding a radio on the SPI bus.