Docs: Add the Telemetry page and change the services URL

Replace the README Data collection section with Telemetry.md and point
the update and telemetry requests to script.yambms.org.
This commit is contained in:
Sleeper85 committed 2026-11-08 23:08:34 +01:00
1 parent a4844fc947
commit 00e04df04b
3 files changed
+165 -27

No files matched your search

+1 -23
View File
@@ -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.).
+160
View File
@@ -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.
+4 -4
View File
@@ -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: