diff --git a/README.md b/README.md index 17b005c..42810d0 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,7 @@ Come and discuss it on the [DIY Solar Forum dedicated topic](https://diysolarfor 6) [Installation procedure](documents/README/Installation_procedure.md) 7) [Troubleshooting](documents/README/Troubleshooting.md) 8) [Changelog](documents/README/changelog/Changelog.md) +9) [Telemetry](documents/README/Telemetry.md) ## YamBMS ( Yet another multi-BMS Merging Solution ) @@ -181,29 +182,6 @@ rx_pin: 22 # to CAN board CRX (with 4.7K resistor except for SN65HVD230) * Optional: 48V to 5V DC-DC converter to power the ESP32 from the JK-BMS VBAT pin (URB4805YMD-10WR3 or VRB4805S-6WR3) * Optional: JK RS485 adaptor and RS485 to TTL 3V3 adaptor (see schematic section) -## Data collection - -> [!NOTE] -> For your information, in August 2026 there were `255` YamBMS active users. - -If the ESP32 has an internet connection, the following is sent every 6 hours to -[this script](http://script.opentel.be/yambms.post.php) for statistics collection: - -- Node ID hash -- YamBMS version -- Board chip -- Board name -- BMS model -- BMS protocol -- BMS count -- Communication bus -- Communication protocol -- Uptime -- Current date and time - -Only [@Sleeper85](https://github.com/Sleeper85) has access to the collected data, which is used -for statistics, support and the update service. - ## References * Thanks to [@syssi](https://github.com/syssi/) for help and developing many BMS components (JK, JBD, Seplos, Pace, etc.). diff --git a/documents/README/Telemetry.md b/documents/README/Telemetry.md new file mode 100644 index 0000000..e6387f8 --- /dev/null +++ b/documents/README/Telemetry.md @@ -0,0 +1,160 @@ +# Telemetry + +[![Badge License: GPLv3](https://img.shields.io/badge/License-GPLv3-brightgreen.svg)](https://www.gnu.org/licenses/gpl-3.0) +[![Badge Version](https://img.shields.io/github/v/release/Sleeper85/esphome-yambms?include_prereleases&color=yellow&logo=DocuSign&logoColor=white)](https://github.com/Sleeper85/esphome-yambms/releases/latest) +![GitHub stars](https://img.shields.io/github/stars/Sleeper85/esphome-yambms) +![GitHub forks](https://img.shields.io/github/forks/Sleeper85/esphome-yambms) +![GitHub watchers](https://img.shields.io/github/watchers/Sleeper85/esphome-yambms) + +This page describes YamBMS 1.8.1. + +## Summary + +Telemetry is **on by default**. Every 6 hours, each ESP32 sends its YamBMS setup : +versions, board, BMS and inverter types, uptime, date, and an identifier derived from its MAC +address. This shows which hardware to support first. +The server also sees your public IP address and sends a reduced form of it to ip-api.com to +find your country. Data has no expiry date. To stop all requests, see [How to disable](#how-to-disable). + +## Why + +These reports show how YamBMS is really used. They help to: + +- decide which BMS, boards and inverters to support first; +- find bad default protocols: if many users of one inverter brand force another protocol, the + default for that brand needs review; +- follow how fast new YamBMS and ESPHome versions are adopted. + +## What is sent + +The ESP32 sends one HTTP POST to `http://script.yambms.org/yambms.post.php`. This is the complete +list, from [yambms_service.yaml](../../packages/yambms/yambms_service.yaml): + +| Field | Example | Meaning | +|---|---|---| +| `node_id_hash` | `0123456789abcdef0123456789abcdef` | Identifier derived from the MAC address, see [Identity](#identity) | +| `version` | `1.8.1` | YamBMS version | +| `board_chip` | `ESP32` | Chip of the board | +| `board_name` | `DevKit V1` | Name of the board | +| `bms_model` | `JK,JK,` | Model of each BMS | +| `bms_protocol` | `UART,UART,` | Protocol of each BMS | +| `bms_count` | `2` | Number of BMS | +| `inverter_brand` | `Deye,SRNE,` | Inverter brand of each link, `Not defined` if not set | +| `inverter_bus` | `CAN,RS485,` | Bus of each link | +| `inverter_protocol` | `PYLON V1,PYLON,` | Protocol of each link, also `None` (not configured) or `Disabled` | +| `inverter_protocol_source` | `auto,manual,` | `auto` if the protocol is set to `Automatic`, `manual` if you forced it | +| `uptime` | `93784` | Seconds since the last boot | +| `date_time_now` | `2026-09-02 12:37:37` | Date and local time of the ESP32 | +| `User-Agent` (HTTP header) | `ESPHome/2026.10.2 (https://esphome.io)` | ESPHome version. The server stores the version only | + +`board_name`, `bms_model` and `bms_protocol` come from your YAML, so a value you edited there is +sent as you wrote it. The firmware does not send battery values (voltage, current, SoC), the WiFi +name or password, API or OTA keys, or the device name. + +**When:** a first report 5 minutes after each boot, then every 6 hours. Nothing is sent without a +network connection. + +**No internet access:** the update and telemetry services turn themselves off. After 3 failed +attempts in a row, about 12 hours after boot, the ESP32 stops trying. It tries again only after +the next reboot. + +**Version check:** a separate request, sent at the same times, reads the latest version from +`http://script.yambms.org/yambms.get.php`. It has no data fields, but the server sees your IP +address and `User-Agent`, as with any web request. It writes nothing to the database. + +**Plain HTTP:** the reports are not encrypted. Anyone on the network path, such as your internet +provider, can read them. HTTPS is not used because a TLS handshake needs 30 to 40 KB of internal +RAM, which does not fit next to BLE on boards without PSRAM. + +## How it is processed + +### Identity + +- The ESP32 computes a SHA-256 hash of a public salt and its MAC address, and keeps the first 32 + characters. This is the **Node ID hash**. A reflash does not change it. +- The server hashes that value again with a secret key, and stores only the result. +- The MAC address and the Node ID hash are not stored in the database. +- The Node ID hash is **not anonymous**. The salt is public, so someone who captures your traffic + can find your MAC address by trying candidates. A database leak alone does not reveal it, + because the secret key is not in the database. +- **Firmware before 1.8.0 sends the MAC address itself**, in clear. The server derives the same + identifier and does not store the MAC. + +### IP address + +The server reads your public IP address on each report. It does not store it in the database or +in its application logs. It derives two values: + +- **Location ID:** a hash of the IP address made with a second secret key (the full IPv4 address, + or the first 64 bits of an IPv6 address). It is stored and replaced at each report. It estimates + how many installations exist when several nodes share one address. It changes when your address + changes, and it does not prove that nodes are in the same home (CGNAT). Someone who has the + secret key could find an address by trying candidates. +- **Country:** a two-letter code, or `XX` if unknown. The server cuts the address down to a network + prefix (/24 for IPv4, /48 for IPv6) and holds it in the database, normally for up to 15 minutes. + It then sends the prefix to [ip-api.com](https://ip-api.com), **a third party, over plain HTTP** + (the free service has no HTTPS). The prefix is sent without any node identifier, and is deleted + from the database once resolved. This happens for a new node, when the address changes, or + while the country is unknown. YamBMS has no control over what ip-api.com does with the prefix. + +### Retention + +- The server keeps **one row per node**, overwritten at each report. There is no history of + past reports. The row also keeps the date the node was first seen. +- **There is no expiry date.** A row stays forever, even if the node is off or telemetry is + disabled. It is removed only [on request](#access-or-delete-your-data). +- The server also keeps the number of active nodes, once per week, with no per-node data. + +Only [@Sleeper85](https://github.com/Sleeper85) can view the per-node data, on a password-protected +page. The hosting provider runs the server that holds it. + +### Active nodes + +A node is one ESP32 running YamBMS. It is **active** if its last report is less than 3 days old. +This count has limits: + +- It counts ESP32 boards, not users. One user can have several nodes. +- A replaced ESP32 is a new node. The old row stays in the table. +- The date comes from the clock of the ESP32, not from the server. A node with a wrong clock can + be counted wrongly. + +## What is published + +Public statistics are at [stats.yambms.org](https://stats.yambms.org). The page shows aggregated +counts of active nodes only, per version, board, BMS, inverter and country. Any value used by fewer +than 5 nodes is grouped into `Other`, except the number of BMS per node. + +The page also shows the best and the average uptime of active nodes, in whole days. The best uptime +comes from a single node, with nothing else attached to it. No other per-node data is published. + +## How to disable + +Both services are set at compile time. Add this to the `substitutions:` block of your main YAML, +then compile and flash again: + +```yaml +substitutions: + yambms_update_service: 'false' # Set to false to disable update checks + yambms_telemetry_service: 'false' # Set to false to disable the sending of telemetry data +``` + +| `yambms_telemetry_service` | `yambms_update_service` | Result | +|---|---|---| +| `'false'` | `'false'` | **No request is sent at all** | +| `'false'` | `'true'` | No report. The version check still runs | +| `'true'` | `'false'` | Reports are sent. The `Last version` entity no longer updates | + +Disabling stops new reports. It does not delete your existing row. The precompiled demo firmware +cannot be changed: build your own firmware to disable telemetry. + +## Access or delete your data + +Use the form on the [Contact page](https://stats.yambms.org/contact/) of **stats.yambms.org** to ask a question, +get a copy of your data, or have it deleted. For configuration or hardware help, use +[GitHub](https://github.com/Sleeper85/esphome-yambms). + +Access and deletion need your Node ID hash: 32 characters, digits and letters `a` to `f`. Find it +in the `Diagnostic` page of the YamBMS dashboard, card `YamBMS - Network`, line `Node ID hash`, or +in the `Node ID hash` diagnostic entity in Home Assistant. Each ESP32 has its own value. + +Disable telemetry before asking for deletion. Otherwise, the next report creates a new row. diff --git a/packages/yambms/yambms_service.yaml b/packages/yambms/yambms_service.yaml index 69b0203..3912d03 100644 --- a/packages/yambms/yambms_service.yaml +++ b/packages/yambms/yambms_service.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.09.02 -# Version : 1.5.0 +# Updated : 2026.11.07 +# Version : 1.5.1 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -105,7 +105,7 @@ interval: lambda: return ${yambms_update_service}; then: - http_request.get: - url: http://script.opentel.be/yambms.get.php + url: http://script.yambms.org/yambms.get.php capture_response: true # on_error fires only when no connection could be made (DNS or # connect failure) — the cases that freeze the loop. An HTTP error @@ -138,7 +138,7 @@ interval: lambda: return ${yambms_telemetry_service} && !id(yambms${yambms_id}_var_service_round_failed); then: - http_request.post: - url: http://script.opentel.be/yambms.post.php + url: http://script.yambms.org/yambms.post.php request_headers: Content-Type: application/json on_error: