diff --git a/README.md b/README.md index 5937b6f..caf8f58 100644 --- a/README.md +++ b/README.md @@ -173,7 +173,7 @@ rx_pin: 22 # to CAN board CRX (with 4.7K resistor except for SN65HVD230) ## Requirements -* [ESPHome 2026.7.0 or higher](https://github.com/esphome/esphome/releases) +* [ESPHome 2026.8.0 or higher](https://github.com/esphome/esphome/releases) * ESP32 MCU (buying a board with ≥8MB flash is advised if you intend to monitor multiple BMS) * CAN transceiver (only with TJA1050/TJA1051 => 4.7K resistor for 5V to 3V3 level shifing) * BMS JK, JBD, Seplos (other BMS brands already integrated with ESPhome can be added easily) @@ -184,22 +184,26 @@ rx_pin: 22 # to CAN board CRX (with 4.7K resistor except for SN65HVD230) ## Data collection > [!NOTE] -> For your information, in July 2026 there were `250` YamBMS users. +> For your information, in August 2026 there were `255` YamBMS active users. -If the ESP32 has an internet connection, the following data is sent to [this script](http://script.opentel.be/yambms.post.php) -for statistics collection. Only [@Sleeper85](https://github.com/Sleeper85) have access to this information for the production of statistics, the support and the update service. +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: -- ESP32 MAC address +- Node ID hash - YamBMS version - Board chip - Board name - BMS model +- BMS protocol - BMS count -- CAN bus name -- CAN bus protocol +- 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/dev/Design_decisions.md b/documents/README/dev/Design_decisions.md index 26bbcfd..90d2980 100644 --- a/documents/README/dev/Design_decisions.md +++ b/documents/README/dev/Design_decisions.md @@ -121,7 +121,7 @@ interval to make protocols "consistent" with each other. When adding a frame to a sequence, remember that the sequence length is tracked alongside the array. Keep the two in sync, or the new frame will silently never be emitted. -## The update service must never block the loop task +## The update and telemetry services must never block the loop task **File:** `packages/yambms/yambms_service.yaml` @@ -164,8 +164,93 @@ Nesting would stack one blocking request inside another on a loop task whose sta default — see [LOOP_TASK_STACK.md](../LOOP_TASK_STACK.md). It also avoids a second 7s freeze on a filtered network, halving the worst case. -Reaching 3 failures disables the service until reboot, or until the user toggles the -`Update service` switch off and on, which rearms the counter. +Reaching 3 failures disables both requests until reboot. + +### Two services, one counter + +The two requests are gated independently, by substitution and therefore at compile time: + +| Substitution | Request | What it does | +|---|---|---| +| `yambms_update_service` | GET | checks the latest published version | +| `yambms_telemetry_service` | POST | sends the node's configuration | + +They share **one** counter, and that is deliberate: the counter measures whether the network is +reachable, not whether a given endpoint answered. Both requests block the loop task the same way, +so either one is a valid source of that signal. + +This is why the POST carries its own `on_error` / `on_response`, which looks redundant next to +the GET's. It is not. With `yambms_update_service: 'false'` there is no GET, and without those +triggers nothing would ever increment the counter — the POST would freeze the loop for 7s every +6h forever, which is exactly the bug the counter exists to prevent. + +The one thing the two services share besides the counter is +`yambms${yambms_id}_var_service_round_failed`: cleared at the start of every round, raised by any +request that could not connect. The POST is skipped when it is set, so a round that has already +frozen the loop once does not freeze it a second time for nothing. + +Keep that flag separate from the counter. The counter is cumulative and spans rounds; the +question the POST needs answered is "did a request fail *in this round*", which is not the same +question. Expressing it as `failures == 0` happens to work while the GET runs immediately before +the POST and always writes the counter, but it silently breaks with `yambms_update_service: +'false'`: nothing resets the counter before the guard, so the POST would stop for good after its +first failed round, and the counter would sit at 1 without ever reaching the threshold that +disables the service. + +### The interval carries a `startup_delay` + +An `interval:` does **not** wait a full period before its first run. The scheduler sets the first +execution at `now + random(0, min(period / 2, 5s))`, capped by `MAX_INTERVAL_DELAY = 5000` — see +the `first execution happens immediately after a random smallish offset` comment in +`core/scheduler.cpp`. A 6h interval therefore fires within 5 seconds of `setup()`. + +Without `startup_delay`, that first request lands in the middle of boot: combiner init at +priority 600, the first CAN frames to the inverter, RS485 polling starting up. Whether it runs at +all comes down to a race with the WiFi association, since `is_connected()` is usually still false +that early. That race is also why the reported symptom was a reboot every 6h rather than a boot +loop — but it is a race, not a design, and a fast reconnect after OTA can win it. + +`startup_delay: 5min` puts the request outside the boot window and makes the sequence +deterministic on a network that filters outbound traffic: + +| t | What happens | `failures` | +|---|---|---| +| 5min | GET fails after 7s, POST skipped | 1 | +| 6h05 | same | 2 | +| 12h05 | same | 3 | +| 18h05 and later | condition is false, no request is made | 3 | + +So a device that will never reach the internet freezes for 7s three times over 12 hours, then +never again. The counter is `restore_value: no`, so a reboot replays that sequence — acceptable +for a node meant to run for months, and the reason the threshold is not lower: a single transient +outage must not disable version checking for good. + +A version check has no urgency, so the 5min delay costs nothing. + +## A derived sensor is published by its source, not polled + +**File:** `packages/base/device_base.yaml` + +`esp32_uptime` formats the value of `esp32_uptime_sec` for humans. It used to do so from its own +`update_interval: 10s` lambda, reading `id(esp32_uptime_sec).state`. + +Two independent pollers reading one another is a race. Each starts with its own random offset in +`[0, 5s)` — see the `startup_delay` note above — so on roughly half of boots the text sensor ran +first and formatted a state that had never been published. That state is `NaN`, and the +`float`→`int` conversion saturates to `INT32_MAX` on Xtensa, which the formatter prints as +`24855d 3h 14m 7s`. It reached the dashboard, the LVGL label, and the telemetry POST, where it +was stored server-side as a real record. + +The source's `on_value` now publishes the text sensor, and the lambda formats `x` — the value +that was just published. The failure mode is not guarded against, it cannot occur. + +Do not convert it back to a polled lambda with a `has_state()` guard. The guard would work, but +it leaves two pollers where one is enough, and it puts the ordering question back in front of +whoever edits the file next. + +`esp32_date_time_now` keeps its own poller, because it has no source sensor to hang a trigger on. +There the guard is `now().is_valid()`, and it is the right tool: the problem is an NTP sync that +may not have happened yet, not a scheduling order. ## Empirical constants diff --git a/packages/base/device_base.yaml b/packages/base/device_base.yaml index 1374fd7..af91c1b 100644 --- a/packages/base/device_base.yaml +++ b/packages/base/device_base.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.29 -# Version : 1.2.8 +# Updated : 2026.08.31 +# Version : 1.2.9 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -109,6 +109,25 @@ sensor: id: esp32_uptime_sec device_id: ${board_id} update_interval: 10s + # Drives the human-readable text sensor. Publishing from the source's own + # value makes it structurally impossible to format a state that has not + # been published yet — see Design_decisions.md. + on_value: + then: + - text_sensor.template.publish: + id: esp32_uptime + state: !lambda |- + int uptime_sec = x; + int days = uptime_sec / 86400; + int hours = (uptime_sec % 86400) / 3600; + int minutes = (uptime_sec % 3600) / 60; + int seconds = uptime_sec % 60; + return ( + (days ? std::to_string(days) +"d " : "") + + (hours ? std::to_string(hours) +"h " : "") + + (minutes ? std::to_string(minutes) +"m " : "") + + (std::to_string(seconds) +"s") + ); # https://esphome.io/components/sensor/internal_temperature - platform: internal_temperature @@ -124,23 +143,9 @@ text_sensor: name: Uptime id: esp32_uptime device_id: ${board_id} - update_interval: 10s + update_interval: never # published by esp32_uptime_sec's on_value icon: mdi:clock-start entity_category: diagnostic - lambda: |- - int uptime_sec = id(esp32_uptime_sec).state; - int days = uptime_sec / 86400; - int hours = (uptime_sec % 86400) / 3600; - int minutes = (uptime_sec % 3600) / 60; - int seconds = uptime_sec % 60; - return { - ( - (days ? std::to_string(days) +"d " : "") + - (hours ? std::to_string(hours) +"h " : "") + - (minutes ? std::to_string(minutes) +"m " : "") + - (std::to_string(seconds) +"s") - ).c_str() - }; # Now date and time - platform: template @@ -149,7 +154,10 @@ text_sensor: update_interval: 10s icon: mdi:clock-start entity_category: diagnostic - lambda: return id(my_time).now().strftime("%Y-%m-%d %H:%M:%S"); + lambda: |- + auto t = id(my_time).now(); + if (!t.is_valid()) return {}; + return t.strftime("%Y-%m-%d %H:%M:%S"); # https://esphome.io/components/text_sensor/version - platform: version diff --git a/packages/yambms/yambms_core.yaml b/packages/yambms/yambms_core.yaml index 2db7599..f05152e 100644 --- a/packages/yambms/yambms_core.yaml +++ b/packages/yambms/yambms_core.yaml @@ -1,4 +1,4 @@ -# Updated : 2026.08.29 +# Updated : 2026.08.31 # Version : 1.8.0 # GitHub : https://github.com/Sleeper85/esphome-yambms @@ -19,6 +19,9 @@ substitutions: yambms_version: "1.8.0" + # YamBMS services + yambms_update_service: 'true' # Set to false to disable update checks + yambms_telemetry_service: 'true' # Set to false to disable the sending of telemetry data # Cut-Off Charging Logic yambms_cutoff_crate: '0.05' # (C-Rate) matches the standard charge termination of most LFP, Li-ion and LTO datasheets and is the right value for the vast majority of installations. Check your cell datasheet before changing it. yambms_eoc_min_soc: '95' # (%) minimum SoC (Max 98%) required to allow Cut-Off/EOC @@ -208,15 +211,15 @@ globals: restore_value: no initial_value: '0.0' # YamBMS - - id: yambms${yambms_id}_var_service + - id: yambms${yambms_id}_var_initialized type: bool restore_value: no - initial_value: 'true' + initial_value: 'false' - id: yambms${yambms_id}_var_service_failures type: int restore_value: no initial_value: '0' - - id: yambms${yambms_id}_var_initialized + - id: yambms${yambms_id}_var_service_round_failed type: bool restore_value: no initial_value: 'false' diff --git a/packages/yambms/yambms_service.yaml b/packages/yambms/yambms_service.yaml index d6e012d..14e706a 100644 --- a/packages/yambms/yambms_service.yaml +++ b/packages/yambms/yambms_service.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.21 -# Version : 1.3.0 +# Updated : 2026.08.31 +# Version : 1.4.0 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -23,6 +23,19 @@ esphome: then: - lambda: id(yambms${yambms_id}_running_version).publish_state("${yambms_version}"); - lambda: id(yambms${yambms_id}_last_version).publish_state("${yambms_version}"); + # Derived node identifier sent to the telemetry service instead of the raw + # MAC address. get_mac_address() returns the canonical lowercase form with + # no separator, independent of whatever the board package exposes as its + # MAC sensor — a user-written board file must not be able to change it. + - lambda: |- + std::string in = "yambms_node_id:" + get_mac_address(); + sha256::SHA256 hasher; + hasher.init(); + hasher.add(in); + hasher.calculate(); + char hex[65]; + hasher.get_hex(hex); + id(yambms${yambms_id}_node_id_hash).publish_state(std::string(hex, 32)); text_sensor: # +--------------------------------------+ @@ -42,6 +55,18 @@ text_sensor: icon: mdi:new-box entity_category: diagnostic update_interval: never + # +--------------------------------------+ + # | Node identifier | + # +--------------------------------------+ + # Exposed so the user can quote it for support: it is the only handle left + # once the MAC address is no longer sent. Published by on_boot above. + - platform: template + name: "Node ID hash" + id: yambms${yambms_id}_node_id_hash + device_id: ${board_id} + icon: mdi:fingerprint + entity_category: diagnostic + update_interval: never # https://esphome.io/components/http_request.html http_request: @@ -57,47 +82,75 @@ http_request: interval: - interval: 6h # 60min + # The scheduler fires an interval within 5 s of setup, not after a full + # period. Without this delay the first request lands during boot, and + # whether it runs depends on a race with the WiFi association. + startup_delay: 5min then: if: condition: and: - - lambda : return id(yambms${yambms_id}_var_service) == true; - - lambda : return id(my_network).is_connected(); # only proves the device has an IP, not that the internet is reachable. + - lambda : return ${yambms_update_service} || ${yambms_telemetry_service}; + - lambda : return id(my_network).is_connected(); # only proves the device has an IP, not that the internet is reachable. - lambda : return id(yambms${yambms_id}_var_service_failures) < 3; then: - - http_request.get: - url: http://script.opentel.be/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 - # status still fires on_response, which rightly resets the counter. - on_error: - then: - - lambda: id(yambms${yambms_id}_var_service_failures) += 1; - on_response: - then: - - lambda: |- - id(yambms${yambms_id}_var_service_failures) = 0; - json::parse_json(body, [](JsonObject root) -> bool { - // Explicitly cast to std::string to resolve ambiguity - id(yambms${yambms_id}_last_version).publish_state(root["version"].as()); - return true; - }); - - # Guarded by an `if` rather than nested in on_response: nesting would - # stack a blocking request inside another one on the loop task, whose - # stack is 8192 B by default (see LOOP_TASK_STACK.md). On a filtered - # network it also avoids a second 7 s freeze for nothing. + - globals.set: + id: yambms${yambms_id}_var_service_round_failed + value: 'false' + # +--------------------------------------+ + # | Update service (GET) | + # +--------------------------------------+ - if: condition: - lambda: return id(yambms${yambms_id}_var_service_failures) == 0; + lambda: return ${yambms_update_service}; + then: + - http_request.get: + url: http://script.opentel.be/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 + # status still fires on_response, which rightly resets the counter. + on_error: + then: + - lambda: |- + id(yambms${yambms_id}_var_service_failures) += 1; + id(yambms${yambms_id}_var_service_round_failed) = true; + on_response: + then: + - lambda: |- + id(yambms${yambms_id}_var_service_failures) = 0; + json::parse_json(body, [](JsonObject root) -> bool { + // Explicitly cast to std::string to resolve ambiguity + id(yambms${yambms_id}_last_version).publish_state(root["version"].as()); + return true; + }); + + # +--------------------------------------+ + # | Telemetry service (POST) | + # +--------------------------------------+ + # Guarded by an `if` rather than nested in the GET's on_response: nesting + # would stack one blocking request inside another on a loop task whose + # stack is 8192 B by default (see LOOP_TASK_STACK.md). + # Skipped when a request already failed this round, to avoid a second 7s + # freeze for nothing. The two services are otherwise independent. + - if: + condition: + 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 request_headers: Content-Type: application/json + on_error: + then: + - lambda: |- + id(yambms${yambms_id}_var_service_failures) += 1; + id(yambms${yambms_id}_var_service_round_failed) = true; + on_response: + then: + - lambda: id(yambms${yambms_id}_var_service_failures) = 0; json: |- - root["mac"] = id(esp32_mac_address).state; + root["node_id_hash"] = id(yambms${yambms_id}_node_id_hash).state; root["version"] = "${yambms_version}"; root["board_chip"] = "${board_chip}"; root["board_name"] = "${board_name}"; @@ -106,5 +159,5 @@ interval: root["bms_count"] = id(yambms${yambms_id}_var_bms_counter); root["comm_bus"] = id(yambms${yambms_id}_var_communication_bus); root["comm_protocol"] = id(yambms${yambms_id}_var_communication_protocol); - root["uptime"] = id(esp32_uptime).state; + root["uptime"] = id(esp32_uptime_sec).state; root["date_time_now"] = id(esp32_date_time_now).state; diff --git a/yambms_custom.yaml b/yambms_custom.yaml index 1004f5d..0d5297b 100644 --- a/yambms_custom.yaml +++ b/yambms_custom.yaml @@ -1,5 +1,5 @@ -# Updated : 2026.08.21 -# Version : 1.1.7 +# Updated : 2026.08.31 +# Version : 1.1.8 # GitHub : https://github.com/Sleeper85/esphome-yambms # YamBMS ( Yet another multi-BMS Merging Solution ) @@ -38,25 +38,6 @@ switch: - globals.set: id: yambms${yambms_id}_var_force_float value: 'false' - # Update service switch - - platform: template - device_id: yambms_yambms${yambms_id} - name: "Update service" - restore_mode: RESTORE_DEFAULT_ON - optimistic: true - entity_category: config - turn_on_action: - - globals.set: - id: yambms${yambms_id}_var_service - value: 'true' - # Rearm the circuit breaker, so the user can retry after fixing the network - - globals.set: - id: yambms${yambms_id}_var_service_failures - value: '0' - turn_off_action: - - globals.set: - id: yambms${yambms_id}_var_service - value: 'false' esphome: on_boot: