Add River 2 Bluetooth telemetry and diagnostics

Decode River 2 charge, temperature, power flow, and time estimates. Preserve precise charge readings across packet reordering and omit unavailable time estimates.

Require valid PD, EMS, and BMS core heartbeats for diagnostic completion. Report optional packets separately and support raw watch output with reliable disconnect cleanup. Use synthetic regression tests and keep captures, credentials, and external keydata private.

Device details come from command-line arguments or discovery. This commit retains Poetry; the separate packaging commit migrates to uv.

README.md

@@ -53,3 +53,65 @@ To push data for a single UPS only:
 	poetry run bmspy-influxdb --ups network --url ...
 
 InfluxDB connection details can also be supplied via environment variables (`INFLUXDB_V2_URL`, `INFLUXDB_V2_ORG`, `INFLUXDB_V2_TOKEN`) instead of command-line flags.
+
+## EcoFlow Bluetooth LE devices
+
+Install the Bluetooth dependencies:
+
+```bash
+poetry install -E ecoflow-bt
+```
+
+Close the EcoFlow app and stop other Bluetooth collectors before connecting.
+
+### Setup
+
+Get your EcoFlow account user ID:
+
+```bash
+poetry run bmspy-ecoflow-login you@example.com
+```
+
+The command prompts for your password. Add `--region EU` or `--region US` if needed.
+Use the diagnostic scan below to find device addresses and serial numbers.
+
+Type 7 authentication also needs an external lookup table from
+[ha-ef-ble](https://github.com/rabits/ha-ef-ble). From the bmspy repository root, download it:
+
+```bash
+curl --fail --location --output bmspy/ecoflow_keydata.py \
+  https://raw.githubusercontent.com/rabits/ha-ef-ble/main/custom_components/ef_ble/eflib/keydata.py
+```
+
+This file is ignored by Git and excluded from packages. Type 1 devices do not need it.
+
+### Diagnostics
+
+Scan and collect reports from nearby supported devices:
+
+```bash
+poetry run python -u tools/ecoflow-bt.py --user-id YOUR_USER_ID --scan --timeout 30
+```
+
+Add `--watch` to print every packet until Ctrl+C. Watch mode ignores the telemetry
+timeout, but stops on a lost connection. Its payloads are already decrypted.
+Keep diagnostic output private because it can contain device and account identifiers.
+
+The scan detects encryption automatically. To select one discovered device,
+add `--device ADDRESS`. Without scanning, replace `--scan` with
+`--device ADDRESS --serial-number SERIAL`. Direct connections default to Type 7.
+Session keys stay internal. The script has no encryption override or key-export option.
+
+River 2 collection waits for three valid core reports, not optional inverter or
+solar reports. A timeout reports incomplete collection. Use `--watch` to receive
+later reports.
+
+River 2 reports charge, temperature, power, and time estimates. Missing measurements
+stay absent. See the [River 2 measurement reference](docs/ecoflow-river2-fields.md)
+for units, decoding rules, and known limits.
+
+Client snapshots include all complete River 2 heartbeat fields under
+`ef_river2_*`, alongside the shared measurements and raw packets.
+Partial reports retain earlier field values. See the
+[River 2 field reference](docs/ecoflow-river2-fields.md#reported-fields-available-to-clients)
+for names, units, and limits.