+
+**How it works:** since aranet 0.3.0, the first time aranet connects to a sensor that isn't paired yet, it pairs the sensor and logs `Paired with
`. aranet can't enter a PIN, though: a sensor that wants its PIN has to be paired by hand once (solution 2), and aranet then uses that pairing. aranet doesn't register a system-wide Bluetooth agent: its agent exists only while it pairs that sensor and approves nothing else, so the desktop's Bluetooth settings keep working while aranet runs. (aranet 0.2.1 and earlier register BlueZ's default agent for as long as they run instead.) Sensors that are already paired are used as they are. `aranet` logs pairing failures by default and `Paired with` only with `--verbose`; for `aranet-service` or `aranet server`, set `RUST_LOG=aranet_core=info` to see pairing messages, including failures.
+
+**Symptoms:** aranet logs a warning that pairing failed or timed out, then connects anyway. This usually happens after the sensor was reset or paired with a phone. If the sensor refuses to pair (it may want its PIN), aranet doesn't try again for 10 minutes; after other failures it tries again at the next connection. Until the sensor is paired, its reads can time out on a server without a desktop Bluetooth agent: stop `aranet-service` or `aranet server` and any other aranet command that uses the sensor, then pair it by hand in an interactive `bluetoothctl` session (solution 2), entering its PIN if asked (a connect during the pairing cancels it). The one-line `bluetoothctl pair ` registers no agent, so on a server it can't ask for the PIN.
+
+A sensor that wants its PIN can also seem to pair: an Aranet2 with BlueZ 5.82, for example, completes aranet's pairing without the PIN (aranet logs `Paired with `) and then rejects that pairing, so every later connection to it fails. Removing the pairing and letting aranet pair again (solution 1) only repeats this: pair such a sensor by hand, with its PIN (solution 2).
+
+**Solutions:**
+
+1. **Remove the old pairing and connect again** (for a sensor that wants its PIN, use solution 2 instead):
+```bash
+bluetoothctl remove
+aranet read --device
+```
+While `aranet-service` or `aranet server` runs, skip the `aranet read`: the service pairs the sensor again at its next poll, and a connect from a second aranet process during that pairing cancels it. If the sensor refused to pair, the service waits until the 10 minutes are up, or tries at once if you restart it.
+
+2. **Or pair by hand in `bluetoothctl`**, then connect again. A sensor that wants its PIN has to be paired by hand: this way, or in your desktop's Bluetooth settings. First stop `aranet-service` or `aranet server` and any other aranet command that uses the sensor: a connect during the pairing cancels it. Remove the old pairing if there is one, start a scan, wait until the sensor's MAC address is listed (after `remove`, BlueZ has to find the sensor again before it can pair it), stop the scan, and pair. The sensor may show a PIN on its screen: type it when `bluetoothctl` asks for it.
+```bash
+bluetoothctl
+# then, at the [bluetooth]# prompt:
+remove
+# (if this computer has no record of the sensor, remove says so: go on)
+scan on
+# wait until a line with the sensor's MAC address appears, then:
+scan off
+pair
+quit
+```
+
+
+