diff --git a/README_uart_ble.md b/README_uart_ble.md new file mode 100644 index 00000000..94854d84 --- /dev/null +++ b/README_uart_ble.md @@ -0,0 +1,245 @@ +# esphome-jk-bms + +![GitHub actions](https://github.com/syssi/esphome-jk-bms/actions/workflows/ci.yaml/badge.svg) +![GitHub stars](https://img.shields.io/github/stars/syssi/esphome-jk-bms) +![GitHub forks](https://img.shields.io/github/forks/syssi/esphome-jk-bms) +![GitHub watchers](https://img.shields.io/github/watchers/syssi/esphome-jk-bms) +[!["Buy Me A Coffee"](https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg)](https://www.buymeacoffee.com/syssi) + +ESPHome component to monitor a Jikong Battery Management System (JK-BMS) via UART-TTL or BLE + +![Lovelace entities card](lovelace-entities-card.png "Lovelace entities card") + +## Supported devices + +All JK-BMS models with software version `>=6.0` are using the implemented protocol and should be supported. + +* JK-BD4A8S4P, hw 11.xw, sw 11.24, using `JK02_32S` (reported by [@austin202220](https://github.com/syssi/esphome-jk-bms/issues/297)) +* JK-BD6A17S6P, hw 7.2, sw 7.1.0H +* JK-BD6A17S8P, hw 9.x, sw 9.01G (reported by [@jonadis](https://github.com/syssi/esphome-jk-bms/issues/35#issuecomment-1035312712)) +* JK-BD6A20S10P, hw 10.XW, sw 10.07 (reported by [@adadrag](https://github.com/syssi/esphome-jk-bms/issues/123)) +* JK-BD6A20S12P, hw 11.XW, sw 11.281, using UART-TTL (reported by [@asiridissa](https://github.com/syssi/esphome-jk-bms/discussions/339)) +* JK-BD6A24S6P, hw 6.x, sw 6.10S (reported by [@ziporah](https://github.com/syssi/esphome-jk-bms/issues/41)) +* JK-BD6A24S10P, hw 8.x, sw 8.0.6G (reported by [@spoonwzd](https://github.com/syssi/esphome-jk-bms/issues/67#issuecomment-1093844076)) +* JK-BD6A24S10P, hw 10.xw, sw 10.09 (reported by [@PMPoulsen](https://github.com/syssi/esphome-jk-bms/discussions/261#discussioncomment-5091812)) +* JK-BD4A17S4P, hw 11.xw, sw 11.01 (reported by [@Condor-XYZ](https://github.com/syssi/esphome-jk-bms/issues/221)) +* JK-BD4A17S4P, hw 11.xw, sw 11.27, using `JK02_32S` and/or UART-TTL (reported by [@hemskgren](https://github.com/syssi/esphome-jk-bms/issues/359)) +* JK-B1A8S10P, hw 11.XW, sw 11.261, using `JK02_32S` (reported by [@Chickenbreast0](https://github.com/syssi/esphome-jk-bms/issues/346)) +* JK-B1A24S15P, hw 8.x, sw 8.1.0H (reported by [@killee](https://github.com/syssi/esphome-jk-bms/discussions/4)) +* JK-B1A20S15P, hw 8.x, sw 8.14U (reported by [@trippfam07](https://github.com/syssi/esphome-jk-bms/issues/31)) +* JK-B1A20S15P, hw 10.xw, sw 10.07 (reported by [@romeox44](https://github.com/syssi/esphome-jk-bms/discussions/125)) +* JK-B1A20S15P, hw 10.xw, sw 10.10, using `JK02_24S` (reported by [@austin202220](https://github.com/syssi/esphome-jk-bms/issues/297#issuecomment-1510685683)) +* JK-B1A20S15P, hw 11.xw, sw 11.26, using UART-TTL (reported by [@Tesla72PL](https://github.com/syssi/esphome-jk-bms/issues/309)) +* JK-B2A24S15P, hw 6.x, sw 6.1.3S (reported by [@miguel300477](https://github.com/syssi/esphome-jk-bms/issues/57)) +* JK-B2A24S15P, hw 8.x, sw 8.21W (reported by [@mariusvaida](https://github.com/syssi/esphome-jk-bms/issues/120)) +* JK-B2A24S15P, hw 10.xw, sw 10.07 +* JK-B2A24S15P, hw 10.xw, sw 10.08 (reported by [@meccip](https://github.com/syssi/esphome-jk-bms/discussions/175#discussioncomment-3687287)) +* JK-B2A24S150P, hw 10.xw, sw 10.10 (reported by [@nayias](https://github.com/syssi/esphome-jk-bms/discussions/257#discussioncomment-5062807)) +* JK-B2A24S20P, hw 8.x, sw 8.1.2H (reported by [@KlausLi](https://github.com/syssi/esphome-jk-bms/issues/15#issuecomment-961447064)) +* JK-B2A24S20P, hw 8.x, sw 8.20G (reported by [@rob-oravec](https://github.com/syssi/esphome-jk-bms/discussions/46)) +* JK-B2A24S20P, hw 10.X-W, sw 10.02 (reported by [@SeByDocKy](https://github.com/syssi/esphome-jk-bms/issues/37#issuecomment-1040569576)) +* JK-B2A24S20P, hw 10.XG, sw 10.07D30 (reported by [@TheSmartGerman](https://github.com/syssi/esphome-jk-bms/discussions/122)) +* JK-B2A24S20P, hw 10.XW, sw 10.07 (reported by [@amagr0](https://github.com/syssi/esphome-jk-bms/issues/124#issuecomment-1166366196)) +* JK-B2A8S20P, hw 9.x, sw 9.01M3, using `JK02_24S` (reported by [@EasilyBoredEngineer](https://github.com/syssi/esphome-jk-bms/discussions/110)) +* JK-B2A8S20P, hw 9.x, sw 9.08W (reported by [@vrabi-cv](https://github.com/syssi/esphome-jk-bms/discussions/144#discussioncomment-3285901)) +* JK-B2A8S20P, hw 11.XW, sw 11.17, using `JK02_32S` (reported by [@senfkorn](https://github.com/syssi/esphome-jk-bms/issues/147)) +* JK-B2A8S20P, hw 11.XW, sw 11.26, using `JK02_32S` (reported by [@riker65](https://github.com/syssi/esphome-jk-bms/issues/276)) +* JK-B2A20S20P, hw 10.XW, sw 10.09 (reported by [@markusgg84](https://github.com/syssi/esphome-jk-bms/discussions/173)) +* JK-B2A20S20P, hw 10.XW, sw 11.21h, using `JK02_32S` (reported by [@Salve87](https://github.com/syssi/esphome-jk-bms/issues/308#issuecomment-1505614325)) +* JK-B2A20S20P, hw 11.XW, sw 11.24H, using `JK02_32S` (reported by [@austin202220](https://github.com/syssi/esphome-jk-bms/discussions/232)) +* JK-B2A20S20P, hw 11.XW, sw 11.25H, using `JK02_32S` (reported by [@iovcharyk](https://github.com/syssi/esphome-jk-bms/issues/249)) +* JK-B5A24S, hw 8.x, sw 8.0.3M, using `JK04` (reported by [@JSladen](https://github.com/syssi/esphome-jk-bms/issues/213)) +* JK-B2A16S, hw 3.0, sw 3.3.0, using `JK04` (reported by [@magnetus26](https://github.com/syssi/esphome-jk-bms/discussions/48)) +* GW-24S4EB (NEEY/Heltec 4A Smart Active Balancer), hw HW-2.8.0, sw ZH-1.2.3 (reported by [@cristi2005](https://github.com/syssi/esphome-jk-bms/issues/109)) +* GW-24S4EB (NEEY 4A Smart Active Balancer 4th generation), hw HW-3.2.0, sw ZH-1.2.4 (reported by [@fabhund](https://github.com/syssi/esphome-jk-bms/issues/310)) + +## Untested devices + +* JK-BD6A20S6P + +## Requirements + +* [ESPHome 2022.11.0 or higher](https://github.com/esphome/esphome/releases). +* Generic ESP32 or ESP8266 board + +## Schematics + + + + + + +``` + UART-TTL +┌──────────┐ ┌─────────┐ +│ │<----- RX ----->│ │ +│ JK-BMS │<----- TX ----->│ ESP32/ │ +│ │<----- GND ---->│ ESP8266 │<-- 3.3V +│ │ │ │<-- GND +└──────────┘ └─────────┘ + +# UART-TTL socket (4 Pin, JST 1.25mm pitch) +┌─── ─────── ────┐ +│ │ +│ O O O O │ +│GND RX TX VBAT│ +└────────────────┘ + │ │ │ + │ │ └─── GPIO17 (`rx_pin`) + │ └─────── GPIO16 (`tx_pin`) + └─────────── GND +``` + + +The UART-TTL (labeled as `RS485`) socket of the BMS can be attached to any UART pins of the ESP. A hardware UART should be preferred because of the high baudrate (115200 baud). The connector is called 4 Pin JST with 1.25mm pitch. + +## Installation + +You can install this component with [ESPHome external components feature](https://esphome.io/components/external_components.html) like this: +```yaml +external_components: + - source: github://syssi/esphome-jk-bms@main +``` + +or just use the `esp32-example.yaml` as proof of concept: + +```bash +# Install esphome +pip3 install esphome + +# Clone this external component +git clone https://github.com/syssi/esphome-jk-bms.git +cd esphome-jk-bms + +# Create a secrets.yaml containing some setup specific secrets +cat > secrets.yaml <= 6.0 and < 11.0) + # Please use "JK02_32S" if you own a new JK-BMS >= hardware version 11.0 (f.e. JK-B2A8S20P hw 11.XW, sw 11.26) + # Please use "JK04" if you have some old JK-BMS <= hardware version 3.0 (f.e. JK-B2A16S hw 3.0, sw. 3.3.0) + protocol_version: JK02_32S + +esphome: + name: ${name} + comment: ${device_description} + project: + name: "syssi.esphome-jk-bms" + version: 1.5.0 + +esp32: + board: wemos_d1_mini32 + framework: + type: esp-idf + +external_components: + - source: ${external_components_source} + refresh: 0s + +wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + +ota: + +logger: + level: DEBUG + +# If you don't use Home Assistant please remove this `api` section and uncomment the `mqtt` component! +api: + +#mqtt: +# broker: !secret mqtt_host +# username: !secret mqtt_username +# password: !secret mqtt_password +# id: mqtt_client + +esp32_ble_tracker: + on_ble_advertise: + then: + - lambda: |- + if (x.get_name().rfind("JK-", 0) == 0) { + ESP_LOGI("ble_adv", "New JK-BMS found"); + ESP_LOGI("ble_adv", " Name: %s", x.get_name().c_str()); + ESP_LOGI("ble_adv", " MAC address: %s", x.address_str().c_str()); + ESP_LOGD("ble_adv", " Advertised service UUIDs:"); + for (auto uuid : x.get_service_uuids()) { + ESP_LOGD("ble_adv", " - %s", uuid.to_string().c_str()); + } + } + +ble_client: + - mac_address: ${mac_address} + id: client0 + +jk_bms_ble: + - ble_client_id: client0 + protocol_version: ${protocol_version} + throttle: 5s + id: bms0 + +binary_sensor: + - platform: jk_bms_ble + balancing: + name: "${name} balancing" + charging: + name: "${name} charging" + discharging: + name: "${name} discharging" + online_status: + name: "${name} online status" + +button: + - platform: jk_bms_ble + retrieve_settings: + name: "${name} retrieve settings" + retrieve_device_info: + name: "${name} retrieve device info" + +number: + - platform: jk_bms_ble + jk_bms_ble_id: bms0 + balance_trigger_voltage: + name: "${name} balance trigger voltage" + cell_count: + name: "${name} cell count" + total_battery_capacity: + name: "${name} total battery capacity" + cell_voltage_overvoltage_protection: + name: "${name} cell voltage overvoltage protection" + cell_voltage_overvoltage_recovery: + name: "${name} cell voltage overvoltage recovery" + cell_voltage_undervoltage_protection: + name: "${name} cell voltage undervoltage protection" + cell_voltage_undervoltage_recovery: + name: "${name} cell voltage undervoltage recovery" + balance_starting_voltage: + name: "${name} balance starting voltage" + voltage_calibration: + name: "${name} voltage calibration" + current_calibration: + name: "${name} current calibration" + power_off_voltage: + name: "${name} power off voltage" + max_balance_current: + name: "${name} max balance current" + max_charge_current: + name: "${name} max charge current" + max_discharge_current: + name: "${name} max discharge current" + +sensor: + - platform: jk_bms_ble + jk_bms_ble_id: bms0 + min_cell_voltage: + name: "${name} min cell voltage" + max_cell_voltage: + name: "${name} max cell voltage" + min_voltage_cell: + name: "${name} min voltage cell" + max_voltage_cell: + name: "${name} max voltage cell" + delta_cell_voltage: + name: "${name} delta cell voltage" + average_cell_voltage: + name: "${name} average cell voltage" + cell_voltage_1: + name: "${name} cell voltage 1" + cell_voltage_2: + name: "${name} cell voltage 2" + cell_voltage_3: + name: "${name} cell voltage 3" + cell_voltage_4: + name: "${name} cell voltage 4" + cell_voltage_5: + name: "${name} cell voltage 5" + cell_voltage_6: + name: "${name} cell voltage 6" + cell_voltage_7: + name: "${name} cell voltage 7" + cell_voltage_8: + name: "${name} cell voltage 8" + cell_voltage_9: + name: "${name} cell voltage 9" + cell_voltage_10: + name: "${name} cell voltage 10" + cell_voltage_11: + name: "${name} cell voltage 11" + cell_voltage_12: + name: "${name} cell voltage 12" + cell_voltage_13: + name: "${name} cell voltage 13" + cell_voltage_14: + name: "${name} cell voltage 14" + cell_voltage_15: + name: "${name} cell voltage 15" + cell_voltage_16: + name: "${name} cell voltage 16" + cell_voltage_17: + name: "${name} cell voltage 17" + cell_voltage_18: + name: "${name} cell voltage 18" + cell_voltage_19: + name: "${name} cell voltage 19" + cell_voltage_20: + name: "${name} cell voltage 20" + cell_voltage_21: + name: "${name} cell voltage 21" + cell_voltage_22: + name: "${name} cell voltage 22" + cell_voltage_23: + name: "${name} cell voltage 23" + cell_voltage_24: + name: "${name} cell voltage 24" + cell_resistance_1: + name: "${name} cell resistance 1" + cell_resistance_2: + name: "${name} cell resistance 2" + cell_resistance_3: + name: "${name} cell resistance 3" + cell_resistance_4: + name: "${name} cell resistance 4" + cell_resistance_5: + name: "${name} cell resistance 5" + cell_resistance_6: + name: "${name} cell resistance 6" + cell_resistance_7: + name: "${name} cell resistance 7" + cell_resistance_8: + name: "${name} cell resistance 8" + cell_resistance_9: + name: "${name} cell resistance 9" + cell_resistance_10: + name: "${name} cell resistance 10" + cell_resistance_11: + name: "${name} cell resistance 11" + cell_resistance_12: + name: "${name} cell resistance 12" + cell_resistance_13: + name: "${name} cell resistance 13" + cell_resistance_14: + name: "${name} cell resistance 14" + cell_resistance_15: + name: "${name} cell resistance 15" + cell_resistance_16: + name: "${name} cell resistance 16" + cell_resistance_17: + name: "${name} cell resistance 17" + cell_resistance_18: + name: "${name} cell resistance 18" + cell_resistance_19: + name: "${name} cell resistance 19" + cell_resistance_20: + name: "${name} cell resistance 20" + cell_resistance_21: + name: "${name} cell resistance 21" + cell_resistance_22: + name: "${name} cell resistance 22" + cell_resistance_23: + name: "${name} cell resistance 23" + cell_resistance_24: + name: "${name} cell resistance 24" + total_voltage: + name: "${name} total voltage" + current: + name: "${name} current" + power: + name: "${name} power" + charging_power: + name: "${name} charging power" + discharging_power: + name: "${name} discharging power" + temperature_sensor_1: + name: "${name} temperature sensor 1" + temperature_sensor_2: + name: "${name} temperature sensor 2" + power_tube_temperature: + name: "${name} power tube temperature" + state_of_charge: + name: "${name} state of charge" + capacity_remaining: + name: "${name} capacity remaining" + total_battery_capacity_setting: + name: "${name} total battery capacity setting" + charging_cycles: + name: "${name} charging cycles" + total_charging_cycle_capacity: + name: "${name} total charging cycle capacity" + total_runtime: + name: "${name} total runtime" + balancing_current: + name: "${name} balancing current" + errors_bitmask: + name: "${name} errors bitmask" + +switch: + - platform: jk_bms_ble + charging: + name: "${name} charging" + discharging: + name: "${name} discharging" + balancer: + name: "${name} balancer" + + - platform: ble_client + ble_client_id: client0 + name: "${name} enable bluetooth connection" + +text_sensor: + - platform: jk_bms_ble + errors: + name: "${name} errors" + total_runtime_formatted: + name: "${name} total runtime formatted"