diff --git a/documents/README/changelog/Changelog.md b/documents/README/changelog/Changelog.md index 47995ba..2fdee17 100644 --- a/documents/README/changelog/Changelog.md +++ b/documents/README/changelog/Changelog.md @@ -8,6 +8,14 @@ * YamBMS 1.8.1 : * Set esphome `min_version` to `2026.10.0` + * New documentation : + * [Upgrade to YamBMS 1.8.1](documents/README/changelog/Changelog_upgrade_to_YamBMS_1.8.1.md) + * [Telemetry.md](documents/README/Telemetry.md) + * New documentation for contributors : + * [Project_structure.md](documents/README/dev/Project_structure.md) + * [Coding_conventions.md](documents/README/dev/Coding_conventions.md) + * [Design_decisions.md](documents/README/dev/Design_decisions.md) + * Updated HA dashboards `1.8.1` with a markdown card for the new inverter link diagnostics (`Inverter link protocol`, `Inverter battery mode`, `Note`) and a system fault card * **Breaking change** - New `Inverter brand` select and reworked `Protocol` select : selecting your inverter brand is enough, the protocol follows ; a protocol chosen explicitly still takes priority over the brand. Both selects are renamed, so their stored value is reset : **the inverter link stays inactive until you select your inverter brand**, see [release note](documents/README/changelog/Changelog_Inverter_brand_and_protocol.md) * Removed the `YamBMS name` select : the manufacturer name sent on CAN frame `0x35E` is now derived from the protocol in use, which is what the `Automatic` mode already did ; the `GOODWE`, `SHEnergy` and `BYD` names are no longer selectable @@ -32,8 +40,36 @@ * Auto EOC : new `Auto EOC Start Hour` / `Auto EOC Start Minute` define the charging window, which may cross midnight, and the target hour can be set from `0` to `23` (night charging from the grid) ; outside the window the status is `Wait: Starts at hh:mm` instead of `Stop: Target time passed`, the default start `0:00` keeps the daylight behaviour * `Daily Charging Energy` / `Daily Discharging Energy` (YamBMS and BMS) rounded to 10 Wh (`0.01 kWh`) instead of 1 Wh, to reduce the number of state changes recorded by Home Assistant + * The `Update service` switch is removed : the version check and the telemetry are now enabled separately with the `yambms_update_service` and `yambms_telemetry_service` substitutions (both `'true'` by default), see [Telemetry](documents/README/Telemetry.md) + * Telemetry no longer sends the MAC address but a salted SHA-256 hash of it, shown in the new `Node ID hash` diagnostic entity so that you can quote it for support ; the uptime is now sent in seconds + * The update and telemetry requests now go to `script.yambms.org` + * Fixed `Uptime` sometimes showing `24855d 3h 14m 7s` after boot, on the dashboard, the LVGL display and in the telemetry : the text sensor could format the uptime before it had a value, it is now published by its source + * Fixed `charging cycles` and `total charging cycle capacity` published as `0` after a reboot until the first BMS frame, which also landed in the Home Assistant long-term statistics : both are now unavailable during that time + + * Auto CCL : the max cell voltage used by the curve is now smoothed with a time-based moving average (`auto_ccl_max_cell_v_tau`, default `30`s, `0` disables), which stops the requested CCL swinging between about 8 A and 45 A near the top of charge ; a reading more than `auto_ccl_max_cell_v_guard` (default `5` mV) above the average still cuts the current at once + * Auto CCL : new `auto_ccl_min_current` (default `1` A), Auto CCL never requests less, including above the end of its curve ; other limits can still request 0 A + * A BMS reporting a charge (CCL) or discharge (DCL) limit of `0 A` now stays combined : a full battery at 0 A CCL, or an empty one at 0 A DCL, no longer drops out of the capacity, SoC and totals ; this applies to all BMS models, a limit not received yet still keeps the BMS uncombined + * Deye CAN : the battery power sensors now follow `bms_update_interval` instead of updating every 60s + * Fixed sensors `device_class` / `state_class` that Home Assistant reported or handled wrongly : power sensors in W declared as `current` (BASEN RS485, DEYE CAN module), Ah sensors carrying a class that does not accept Ah (BASEN RS485, DEYE CAN, JK RS485 Display, Modbus client), DEYE battery capacity moved from `total_increasing` to `measurement` + * Fixed PACE BMS compilation with ESPHome 2026.9 / 2026.10 + * Fixed the Waveshare ESP32-S3 Touch-LCD 4.3, 4.3B and 7 boards failing validation on ESPHome 2026.10 with `Pin 2 is used in multiple places` ; the backlight stays under control of the LVGL designs + * New board `board_ESP32-P4_Elecrow-CrowPanel-Advanced-7-10.yaml` (CrowPanel Advanced ESP32-P4) and new Blue Navy 1024x600 HA display design + * Fixed [issue 332](https://github.com/Sleeper85/esphome-yambms/issues/332) YamBMS_RP_BMS_PACE_RS485_Modbus.yaml no longer compiles under esphome 2026-9-1 + * Fixed [issue 335](https://github.com/Sleeper85/esphome-yambms/issues/335) PACE / DEYE packages: compile errors on ESPHome 2026.9–2026.10 + Deye power updated only every 60 s + full Deye excluded from combine + * Merged [PR 322](https://github.com/Sleeper85/esphome-yambms/pull/322) Add CrowPanel Advanced (ESP32-P4) board and Blue Navy 1024x600 HA display + * Merged [PR 329](https://github.com/Sleeper85/esphome-yambms/pull/329) Auto CCL smooths max cell voltage + * Merged [PR 331](https://github.com/Sleeper85/esphome-yambms/pull/331) Fix sensor device_class and state_class + * Merged [PR 337](https://github.com/Sleeper85/esphome-yambms/pull/337) Improve Deye support + * Merged [PR 338](https://github.com/Sleeper85/esphome-yambms/pull/338) Auto EOC 24h charging window + * Merged [PR 339](https://github.com/Sleeper85/esphome-yambms/pull/339) Round daily energy sensors to 10 Wh + * YamBMS 1.8.0 : * Set esphome `min_version` to `2026.8.0` + * New documentation : + * [Charging_a_battery_with_CVL_and_CCL.md](documents/README/Charging_a_battery_with_CVL_and_CCL.md) + * [Understanding_ESPHome_Modbus.md](documents/README/Understanding_ESPHome_Modbus.md) + * [How_to_perform_a_PR_to_the_dev_branch.md](documents/README/How_to_perform_a_PR_to_the_dev_branch.md) + * [HA_entities_cleanup.md](documents/README/HA_entities_cleanup.md) * Updated HA dashboards `1.8.0` for the new Cut-Off Cell Voltage, Charger Offset V., C-Rate and Auto CCL Current Taper entities * Rewritten Cut-Off / EOC charging logic : adds a current deadband (rejects sensor noise / low-solar current limiting) and a minimum SoC gate before Cut-Off can be declared, extends the cut-off confirmation delay from 60s to 180s to reject transient voltage readings, see [release note](documents/README/changelog/Changelog_YamBMS_1.8.0_Cut-Off_charging_logic.md) * New select `Cut-Off Cell Voltage` : choose between `Max Cell Voltage` (default, conservative) and `Average Cell Voltage` (consistent charge termination voltage for packs with a runner cell, requires Auto CVL and/or Auto CCL for cell protection) @@ -60,14 +96,15 @@ * Updated default PSRAM options for ESP-IDF 5.5+, see [documentation](documents/README/PSRAM_options.md) * Fixed incorrect Max/Min Cell Voltage scaling (×100 instead of ×1000) sent on the CAN bus for the Deye PCS protocol * `secrets.yaml` template renamed to `secrets_example.yaml` (copy it to your own gitignored `secrets.yaml`, as documented in Installation_procedure.md) + * Fixed a reboot every 6h on networks that filter the ESP32 outbound traffic (port 80 or DNS blocked) : the update and telemetry requests blocked the device long enough to trigger the watchdog ; requests now time out after 3s, the first one waits 5min after boot, and the services stop until the next reboot after 3 failed attempts + * Added `KS BMS` BLE support, fixed [issue 151](https://github.com/Sleeper85/esphome-yambms/issues/151) [ADD] Requesting KS BMS support + * JK BLE : BMS alarms are now taken into account through the new `errors_bitmask_hex` of the JK BLE component, instead of always reporting no alarm + * Web server authentication switched to `digest` + * Fixed the `brightness not supported` warning logged on every status LED change on boards with a single-colour LED ; `rgb_order` replaced by `channel_colors` in the board files (deprecated by ESPHome, removed in 2027.3.0), to report in your own board file if you have one + * CAN frame logs moved from `INFO` to `DEBUG` level * Merged [PR 308](https://github.com/Sleeper85/esphome-yambms/pull/308) Check if Auto SoC Limit has reached its target * Merged [PR 303](https://github.com/Sleeper85/esphome-yambms/pull/303) Auto CCL Current Taper * Merged [PR 290](https://github.com/Sleeper85/esphome-yambms/pull/290) Add grace period to Auto EOC - * New documentation : - * [Charging_a_battery_with_CVL_and_CCL.md](documents/README/Charging_a_battery_with_CVL_and_CCL.md) - * [Understanding_ESPHome_Modbus.md](documents/README/Understanding_ESPHome_Modbus.md) - * [How_to_perform_a_PR_to_the_dev_branch.md](documents/README/How_to_perform_a_PR_to_the_dev_branch.md) - * [HA_entities_cleanup.md](documents/README/HA_entities_cleanup.md) * YamBMS 1.7.0 : * Partial rewrite of `yambms_core` and merging of C++ code into a single lambda in several stages with increased datas control. diff --git a/documents/README/changelog/Changelog_upgrade_to_YamBMS_1.8.1.md b/documents/README/changelog/Changelog_upgrade_to_YamBMS_1.8.1.md new file mode 100644 index 0000000..a1bf6a9 --- /dev/null +++ b/documents/README/changelog/Changelog_upgrade_to_YamBMS_1.8.1.md @@ -0,0 +1,123 @@ +# Upgrade to YamBMS 1.8.1 + +[![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) + +YamBMS 1.8.1 changes the way the inverter, UART and CAN are configured, so a 1.7.0 or 1.8.0 YAML +no longer validates as it is. If you use Remote Packages, your next compile will fail until you +have made the changes below. + +## Biggest changes + +- **Inverter brand:** a new `Inverter brand` select sets the protocol for you, and you can still + force one with `Protocol`. Your old protocol selection is not kept: **the CAN or RS485 link does + not work until you select your inverter brand, or `Other` for a manual setup**. Your choice is + then remembered. +- **UART:** each package now declares its own UART from its `*_uart_id` var. Two packages can no + longer share a UART. +- **CAN:** each package now declares its own CAN node, which needs the new `canbus_platform` var. +- **RS485:** you now include `yambms_rs485.yaml` and choose the protocol with `rs485_protocol`. +- **Current limits:** the `Max charge C-Rate` and `Max discharge C-Rate` + sliders added in 1.8.0 default to 0.5C. A 280 Ah bank is limited to 140 A in both directions + until you raise them (1C maximum). +- **Several inverter links:** CCL and DCL are divided by the number of CAN and RS485 links declared + in your YAML, including a link set to `Disabled`. Only declare the links that are actually wired. + CAN and RS485 links can run at the same time: keep both blocks, each link with its own + `canbus_id` or `rs485_id`. The dashboard shows up to 3 CAN links and 3 RS485 links. If you only + use RS485, comment out the CAN block. + +## How to update from 1.7.0 or 1.8.0 + +> [!IMPORTANT] +> Off-grid users: plan this for a moment when you can reach Home Assistant or the web server. +> Your inverter will report a BMS fault and stop using the battery until step 9 is done. + +1. Save a copy of your current YAML and update ESPHome to **2026.10.0 or later**. +2. Start from the new [Remote Packages example](../../../YamBMS_Remote_Packages_example.yaml) + ([Local Packages example](../../../YamBMS_Local_Packages_example.yaml) if you use local + packages). +3. Report your own values one by one, without pasting your old `substitutions:` block: + `hostname`, `friendly_name`, `yambms_name`, then **all your battery settings** (chemistry, cell + count, voltages, currents) and your static IP if you have one. These are not checked by + validation. Keep the new `yambms_cutoff_timer: '180'`. +4. Select your board and its options (PSRAM, display, web server). Do not copy your old UART and + CAN includes, packages now declare them. +5. Paste your BMS, Shunt and Balancer blocks as they are ([you will find the updated examples in the examples folder](../../../examples/)). + * Deye BMS on CAN: add `canbus_platform` to the `top` package. + * If your board requires flow control, add `uart_flow_control_pin: ${talk_pin}` to the `vars:` of the package that uses that UART. +6. CAN inverter: keep the CAN block of the example and set `canbus_platform` (`esp32_can` or + `mcp2515`, `external` with the espBerry board). With the web server, include `yambms_canbus_web_server.yaml` instead. + + ```yaml + - path: 'packages/yambms/yambms_canbus.yaml' + vars: + canbus_id: '1' # Must be a number + canbus_name: 'CANBUS 1' + canbus_status_led_id: 'esp_light' + canbus_link_timer_enabled: 'true' + canbus_link_timer: '10s' # min 6s with Deye + # CAN setup + canbus_platform: 'esp32_can' # esp32_can / mcp2515 + canbus_node_id: 'canbus_inverter_1' # CAN bus node to which your inverter is connected + canbus_bitrate: '500kbps' # Default : 500kbps + ``` + +7. RS485 inverter: uncomment the RS485 block of the example, then set `rs485_protocol` and + `rs485_uart_id`. With the web server, include `yambms_rs485_web_server.yaml` instead. + + ```yaml + - path: 'packages/yambms/yambms_rs485.yaml' + vars: + rs485_id: '1' # Must be a number + rs485_name: 'RS485 1' + rs485_protocol: 'pylon' # pylon / voltronic + rs485_update_timeout: '10s' + rs485_status_led_id: 'esp_light' + # UART setup + rs485_uart_id: 'uart_esp_3' # UART interface to which your inverter is connected + # ESP32 : uart_esp_1 to uart_esp_3 + # WK2168 : uart_spi_0 to uart_spi_7 / uart_i2c_0 to uart_i2c_7 + rs485_uart_baud_rate: '9600' # Default : 9600 / Epever : 115200 + ``` + +8. Run `esphome config your_file.yaml`, then flash. +9. Select your `Inverter brand` in Home Assistant or the web server, for each link. If it is not + listed, select `Other` and set `Protocol` yourself. The link starts once this is done, and you + only have to do it once. Read [Inverter Brand and Protocol](../YamBMS_functions.md#inverter-brand-and-protocol) + before you start: it explains each setting and the battery mode to set on your inverter. +10. Replace your Home Assistant dashboard with its 1.8.1 version, from the + [HomeAssistant_Dashboards](../../../HomeAssistant_Dashboards/) folder: open your dashboard, + then *Edit dashboard* → *Raw configuration editor*, and paste the file that matches your + setup. If you had customised it, carry your changes over to the new version. +11. Update any automations that use the old protocol entities. Coming from 1.7.0, also check the + two C-Rate sliders and `Charger Offset V.` (formerly `Inverter Offset V.`). + +## If validation fails + +| Error | Cause | +| --- | --- | +| `Expected integer, but cannot parse ${uart_baud_rate}` | A UART include is still in your YAML. | +| `Bit rate ${CANBUS_BIT_RATE} is not supported` | A CAN include is still in your YAML. | +| `Cannot load include with unresolved substitutions` | `canbus_platform` or `rs485_protocol` is missing. | +| `Source for extension of ID 'rs4851_protocol' was not found` | You are still including `yambms_rs485_pylon.yaml`. | +| `ID uart_esp_1 redefined` | Two packages use the same UART. | + +## PVbrain2 + +PVbrain2 users have a few more changes (board and expander files, `uart_spi_N` ids). Start from +the updated [PVbrain2 YAML](../../../YamBMS_RP_PVbrain2.yaml). + +Coming from 1.7.0, the PVbrain2 board file is now split in two, depending on the revision of your +DevKitC-1: + +- `board_ESP32-S3_DevKitC-1_PVbrain2_LED-48.yaml` for V1.0 (LED on GPIO 48, CAN TX on 38) +- `board_ESP32-S3_DevKitC-1_PVbrain2_LED-38.yaml` for V1.1 (LED on GPIO 38, CAN TX on 48) + +## More information + +Everything else is in the [changelog](Changelog.md) and the [inverter brand release note](Changelog_Inverter_brand_and_protocol.md). + +If you encounter any difficulties, open an issue on [GitHub](https://github.com/Sleeper85/esphome-yambms).