diff --git a/CHANGELOG.md b/CHANGELOG.md index dc80e6d..44501bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index 480e535..99c7e28 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/README.md b/docs/README.md index 4349037..f0673dd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 | | --- | --- | diff --git a/docs/cli.md b/docs/cli.md index 857364e..0f1bf80 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -52,8 +52,8 @@ With no command, MeshTerm launches the interactive menu instead. | `--version` | Print `meshterm ` 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. | diff --git a/docs/configuration.md b/docs/configuration.md index c28750c..78aae8d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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. diff --git a/docs/connecting.md b/docs/connecting.md new file mode 100644 index 0000000..90cc5ad --- /dev/null +++ b/docs/connecting.md @@ -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 ` 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 `. | +| **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). diff --git a/docs/features.md b/docs/features.md index 2d2319b..39ffd9b 100644 --- a/docs/features.md +++ b/docs/features.md @@ -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` | diff --git a/docs/hardware.md b/docs/hardware.md index ce06204..3492652 100644 --- a/docs/hardware.md +++ b/docs/hardware.md @@ -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 diff --git a/meshterm/assets/pages/about.md b/meshterm/assets/pages/about.md index b69bf76..1b2f96d 100644 --- a/meshterm/assets/pages/about.md +++ b/meshterm/assets/pages/about.md @@ -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