The docs say what to do when a companion won't connect

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>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5.5 committed 2026-09-25 20:52:08 -04:00
1 parent 79137598cf
commit 5d0bf52717
9 files changed
+173 -15

No files matched your search

+17 -1
View File
@@ -56,11 +56,27 @@ one caveat SemVer makes for a leading zero: while the major version is still `0`
device rejected the request as malformed". MeshTerm now reads the radio's clock first: a
few seconds ahead is in sync and left alone, and further ahead says by how much and that
rebooting the radio resets it.
- **Bluetooth on Linux works with a PIN-protected companion.** MeshTerm never got the PIN to
the radio there: pairing fell back to "Just Works", which the firmware refuses, so a
correct PIN was reported as rejected, again and again. MeshTerm now does the pairing
itself, answering with the PIN, so it works over SSH and without a desktop, and a
companion paired before it had a PIN is paired again properly. An unpaired companion
with no PIN given is reported in seconds, where it used to take 30. **Unpair & quit** now
works on Linux too.
- **A Bluetooth connect on Linux no longer loses its own link.** When the radio needed a few
tries to open the link, which is routine on a Raspberry Pi, MeshTerm lost track of the
link that finally opened. The companion, still connected, stopped advertising, so the
retry could not find it and MeshTerm reported it out of range.
- **A connection that fails says which step failed.** Bluetooth now tells a link that never
opened from a stale saved pairing, a wrong PIN, a companion that refused to pair, and
a connect that timed out; the PIN dialog shows the reason instead of calling every
refusal a wrong PIN. A USB port says whether it is missing, in use by another program
(ModemManager, on Linux), or not yours to open (the `dialout` group). All of them are
listed, with what to do, in [When a companion won't connect](https://github.com/jpmartineau/MeshTerm/blob/main/docs/connecting.md).
- **The default flood scope is stored the way the firmware and the MeshCore app store it.**
MeshTerm saved it as `#name` where they save `name`, refused a 30-character name the
firmware accepts, and mis-framed a name with an accent. Device config also now refuses
a name no repeater could list back (spaces, commas, a private `$` region).
- **The SPI bridge remembers its channels across restarts.** It kept them only in memory,
so after every reboot the Channels page came up empty while mute settings, which
MeshTerm keeps itself, survived. Update the service (menu option 2) to get the fix.
+11 -4
View File
@@ -58,10 +58,12 @@ https://github.com/user-attachments/assets/f91a6695-14d5-4ae0-8fdc-e65492d0955d
sweep, and a walkable graph of how the mesh actually hangs together.
- **It talks.** Live channel and direct messaging, store-and-forward courier delivery for
contacts that aren't there yet, and shareable channels as QR codes and `meshcore://` links.
- **It connects however your companion does.** Serial (USB), Bluetooth LE, or TCP (a WiFi
- **It connects however your companion does.** Serial (USB), Bluetooth LE, or TCP (a Wi-Fi
board or a network proxy) — the discoverable transports are auto-found and picked
interactively, a network device is named by hand, and every kind reconnects live when a link
drops. No radio? A built-in simulator covers development.
drops. It pairs a PIN-protected Bluetooth companion itself on Windows and Linux, and when a
connection fails it says which step failed and what to do. No radio? A built-in simulator
covers development.
- **It works offline.** The street map caches OpenStreetMap tiles to disk and falls back to
a blank grid when there's no network — it never needs the internet to run.
@@ -199,6 +201,7 @@ surveys kept as a historical record. The short version:
| **[What MeshTerm does](docs/features.md)** | Every screen the menu offers, and the command that does the same job without it. |
| [The CLI cookbook](docs/cookbook.md) | Common one-liners, by the thing you're trying to do. |
| [Configuring MeshTerm](docs/configuration.md) | Preferences, device profiles, and everything kept under `~/.meshterm`. |
| [When a companion won't connect](docs/connecting.md) | Bluetooth pairing on each system, finding the PIN, USB permissions, and every connection error, with what to do about it. |
| [MeshTerm on hardware](docs/hardware.md) | Which handheld manual is yours — the [PicoCalc](docs/picocalc.md) build, or the [uConsole](docs/uconsole.md), whose LoRa chip MeshTerm can drive directly. |
| [How the code is laid out](docs/architecture.md) | The layering, and where a new feature goes. |
| [CONTRIBUTING.md](CONTRIBUTING.md) | The development setup and the house rules. |
@@ -210,8 +213,8 @@ surveys kept as a historical record. The short version:
# Interactive full-screen menu (auto-discovers serial + Bluetooth companions)
meshterm
# Connect over Bluetooth (address from `meshterm devices`)
meshterm --ble AA:BB:CC:DD:EE:FF info
# Connect over Bluetooth (address from `meshterm devices`); add --ble-pin if it has a PIN
meshterm --ble AA:BB:CC:DD:EE:FF --ble-pin 123456 info
# Connect over the network to a TCP companion (host[:port], port defaults to 5000)
meshterm --tcp 192.168.1.50 info
@@ -237,6 +240,10 @@ want the node on the mesh all the time. The device-side scripts both manuals run
[`scripts/`](scripts/); not sure which manual is yours?
[`docs/hardware.md`](docs/hardware.md) says.
A companion that won't connect? **[When a companion won't
connect](docs/connecting.md)** covers Bluetooth pairing on Windows, Linux, and macOS, the
`dialout` group and ModemManager for USB on Linux, and every error message MeshTerm gives.
## What it does
The menu asks one question — *what would you like to do?* — and answers it in two halves.
+2 -1
View File
@@ -12,12 +12,13 @@ This folder is the rest.
| **[The command line](cli.md)** | The manual. Every subcommand and option, what each prints on the plain and JSON faces, the exit statuses, and recipes built on `jq`. |
| [The CLI cookbook](cookbook.md) | Common one-liners by task, for when you want the shape of a command rather than its specification. |
| [Configuring MeshTerm](configuration.md) | Preferences versus config, device profiles, and everything kept under `~/.meshterm`. |
| [When a companion won't connect](connecting.md) | Bluetooth pairing on each system, finding the PIN, and every connection error MeshTerm reports, with what to do about it. |
| [Terminals, icons, and the Windows console](terminals.md) | Why the icons and charts draw on some terminals and not others, and what MeshTerm does about it on Windows. |
## Putting it on hardware
Only if you want MeshTerm running on a handheld's own screen. A MeshCore companion on
USB, Bluetooth or Wi-Fi needs none of this.
USB, Bluetooth, or Wi-Fi needs none of this.
| Read | For |
| --- | --- |
+9 -4
View File
@@ -52,8 +52,8 @@ With no command, MeshTerm launches the interactive menu instead.
| `--version` | Print `meshterm <version>` and exit `0`, before anything else is opened. |
| `-p`, `--profile NAME` | Use a named device profile from `config.toml`. |
| `--port PORT` | Serial port to connect to (`COM5`, `/dev/ttyACM0`), overriding the profile. |
| `--ble ADDRESS` | Bluetooth address of a companion; selects the BLE transport. |
| `--ble-pin PIN` | Pairing PIN, if the Bluetooth companion asks for one. |
| `--ble ADDRESS` | Bluetooth address of a companion; selects the Bluetooth transport. |
| `--ble-pin PIN` | Pairing PIN, if the Bluetooth companion asks for one. MeshTerm pairs with it itself on Windows and Linux; on macOS the system asks for the code in its own dialog, and this option has no effect. See [When a companion won't connect](connecting.md#bluetooth). |
| `--tcp HOST[:PORT]` | Network address of a TCP companion; selects the TCP transport. Default port 5000. |
| `--spi` | The LoRa radio on this machine's own SPI bus; selects the SPI transport. MeshTerm runs the node for the length of the command. With one radio attached, that's the one, profile or not; with none attached, the one SPI profile, else the uConsole AIO's wiring. With two, it refuses (exit `3`) and lists them — pick one with `-p`. See [Adding a radio on the SPI bus](configuration.md#adding-a-radio-on-the-spi-bus). Linux only. |
| `--mock` | Use the built-in simulator instead of real hardware. Nothing transmits, and the run records to `meshterm-mock.db` rather than your real history. |
@@ -482,11 +482,16 @@ consumer that cannot would have to tell an error document from a result.
```console
$ meshterm --port NOSUCHPORT99 info
meshterm: could not open serial port NOSUCHPORT99: could not open port 'NOSUCHPORT99': FileNotFoundError(2, 'The system cannot find the file specified.', None, 2)
meshterm: could not open serial port NOSUCHPORT99: NOSUCHPORT99 isn't there — the device was unplugged, or came back under another name.
$ echo $?
3
```
The sentence names the cause and the remedy: a port that is missing, in use by another
program, or not yours to open, and for Bluetooth a link that never opened, a pairing that is
out of date, or a PIN that was wrong. [When a companion won't connect](connecting.md) lists
every one of them.
With nothing named and more than one candidate attached, the same `3` arrives as a list
and the way out of it:
@@ -626,7 +631,7 @@ table has no room for.
| `target` | string | What `--port` / `--ble` take, verbatim. |
| `transport` | string | `"serial"` \| `"ble"` \| `"tcp"`, or `"mock"` under `--mock`. |
| `port` | string \| null | The serial port, for a serial device. `""` on the `--mock` row. |
| `address` | string \| null | The Bluetooth address, for a BLE device. |
| `address` | string \| null | The Bluetooth address, for a Bluetooth device. |
| `label` | string | The OS's name for the device, or the confirmed node name where we have one. |
| `hardware` | string \| null | The confirmed hardware model, else the USB vendor label. `""` on the `--mock` row. |
| `meshcore` | string | `"yes"` \| `"maybe"` \| `"no"`. Not a boolean — rounding a hint up to `true` would be a lie. |
+3 -2
View File
@@ -32,6 +32,7 @@ Copy [`config.example.toml`](../config.example.toml) to `~/.meshterm/config.toml
```toml
# default_profile = "s3" # uncomment and name your own profile to make it the default
connect_on_start = true # false opens the radio link lazily instead of at launch
# db_path = "C:/Users/you/meshterm/meshterm.db" # the history lives elsewhere
[profiles.s3]
port = "COM5"
@@ -41,13 +42,13 @@ description = "XIAO ESP32-S3 + Wio SX1262 serial companion"
# A Bluetooth LE companion: give it an `address` instead of a `port`.
[profiles.handheld]
address = "AA:BB:CC:DD:EE:FF"
# ble_pin = "123456" # only if your device requires a pairing PIN
# ble_pin = "123456" # only if your device requires a pairing PIN (not used on macOS)
description = "Pocket handheld over Bluetooth"
# A network (TCP) companion: give it a `host` (and optional `tcp_port`, default 5000).
[profiles.wifi]
host = "192.168.1.50"
description = "Basestation over WiFi"
description = "Basestation over Wi-Fi"
# A radio on this machine's own SPI bus (the uConsole AIO): MeshTerm runs its node.
# The pins default to the AIO v1's; a `spi` table states only what differs.
+128
View File
@@ -0,0 +1,128 @@
# 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](cli.md#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](#bluetooth)
- [Who does the pairing](#who-does-the-pairing)
- [Finding the PIN](#finding-the-pin)
- [What each message means](#what-each-bluetooth-message-means)
- [Forgetting a pairing](#forgetting-a-pairing)
- [USB](#usb)
- [TCP](#tcp)
- [A radio on the SPI bus](#a-radio-on-the-spi-bus)
---
## 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:
```console
$ 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](#what-each-bluetooth-message-means) 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](#forgetting-a-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](#forgetting-a-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](#forgetting-a-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](uconsole.md) and [adding a radio on the SPI bus](configuration.md#adding-a-radio-on-the-spi-bus).
+1 -1
View File
@@ -25,7 +25,7 @@ Every interactive screen is listed here with its scripted equivalent, where one
| --- | --- | --- |
| **📊 Dashboard** | The live mesh overview: a two-hour all-packet activity chart with a pulse line, session traffic tallies by packet class, and window RF health beside the radio's own live numbers. Repaints every second. | — |
| **📰 Live feed** | Every packet as it arrives, newest first: time, what the frame *is* (its parsed payload class), and what it is *about* — the node for an advert, the channel for a channel text, sender → recipient for a direct message or a request, the tag for a trace — with reception quality beside it, and the region a scoped flood was sent into. Enter opens any row in the packet viewer, route graph and all. | — |
| **🚨 Watchtower** | A passive sentinel over the nodes you star: silence alarms when a watched node goes quiet, SNR-sag warnings when reception degrades, recovery notes when it returns, and a heads-up when a never-before-seen node appears. Runs in the background all session; unacked alerts show as a header badge. | — |
| **🚨 Watchtower** | A passive sentinel over the nodes you star: silence alarms when a watched node goes quiet, SNR-sag warnings when reception degrades, recovery notes when it returns, and a heads-up when a node is heard for the first time. Runs in the background all session; unacked alerts show as a header badge. | — |
| **⏳ Time machine** | Everything the recorder ever heard, as braille charts: reception volume, the median-SNR band, hour-of-day rhythm, packets and nodes per day, and first-ever arrivals — over a switchable 24h / 7d / 30d / all-time window (on the PicoCalc the windows stop at 30d), per node or mesh-wide. | — |
| **🎧 Monitor** | Passive recording is always on in the app. On the CLI, capture a bounded foreground window, tailing each overheard packet and summarising when it ends. It transmits nothing — it only listens. | `meshterm monitor --seconds 60` |
+1 -1
View File
@@ -15,7 +15,7 @@ its own step-by-step manual, and this page only tells you which one is yours.
| a ClockworkPi **PicoCalc**, stock or already running Calculinux on a Luckfox Lyra, and I want MeshTerm on its own screen | **[MeshTerm on the PicoCalc](picocalc.md)** — from the shopping list to a working machine |
| …and I want a **radio** inside it | the same manual, [Phase 3](picocalc.md#phase-3--add-the-radio) — a XIAO nRF52840 + Wio-SX1262 soldered to the Lyra's UART |
| a ClockworkPi **uConsole** with the hackergadgets AIO board — an SX1262 on the host's own SPI bus | **[MeshTerm on the uConsole](uconsole.md)** — MeshTerm drives it directly with `--spi`, or a bridge service fronts it as a companion if you want it always on |
| a MeshCore companion on USB, BLE or Wi-Fi | nothing here — the [README](../README.md) |
| a MeshCore companion on USB, Bluetooth, or Wi-Fi | nothing here — the [README](../README.md), and [When a companion won't connect](connecting.md) if it doesn't |
The two targets have nothing in common but MeshTerm itself. The device-side scripts each
manual runs live in [`scripts/`](../scripts/), one folder per handheld; the
+1 -1
View File
@@ -59,7 +59,7 @@ itself, isn't affiliated with MeshTerm.
Built on **MeshCore** *https://meshcore.io/* — its firmware and companion
library — with Rich, prompt_toolkit, Typer, bleak, pyserial, pycryptodome,
markdown-it-py, tomli/tomli-w and Segno, each under its own terms.
markdown-it-py, tomli/tomli-w, and Segno, each under its own terms.
Map data **© OpenStreetMap contributors**, served as vector tiles by
**OpenFreeMap** *https://openfreemap.org/* on the **© OpenMapTiles** schema