Docs: Add the 1.8.1 upgrade guide and complete the changelog
New Changelog_upgrade_to_YamBMS_1.8.1.md: a short step-by-step guide to move a 1.7.0 or 1.8.0 YAML to 1.8.1, starting from the example YAML. It covers the biggest changes (inverter brand, UART and CAN declared by the packages, RS485 entry point, C-Rate defaults, CCL/DCL divided by the number of declared links), CAN and RS485 examples with the valid UART ids, the inverter brand selection, the 1.8.1 dashboard, the common validation errors and the PVbrain2 board files. Changelog.md: link the new documentation pages and the 1.8.1 dashboards, and list the remaining 1.8.1 changes (services and telemetry, Auto CCL, 0 A limits, fixes and merged PRs).
This commit is contained in:
1 parent
faad9e60ce
commit
1cf367f333
2 files changed
+165
-5
No files matched your search
@@ -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.
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
# Upgrade to YamBMS 1.8.1
|
||||
|
||||
[](https://www.gnu.org/licenses/gpl-3.0)
|
||||
[](https://github.com/Sleeper85/esphome-yambms/releases/latest)
|
||||

|
||||

|
||||

|
||||
|
||||
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).
|
||||
Reference in new issue
Block a user