SY6970 Battery Management IC
The sy6970 component allows you to use the SY6970 battery management and charging ICs SY6970 Datasheet with ESPHome.
The SY6970 is a highly integrated battery charger and system power path management device for single-cell lithium-ion and lithium-polymer batteries. It features a wide input voltage range, programmable charge current and voltage, and comprehensive safety features.
This component is found in the LilyGo T-Display S3 Pro.
The I²C Bus is required in your configuration for this sensor to work.
This implementation was inspired by lewisxhe/XPowersLib Arduino Library.
Component/Hub
Section titled “Component/Hub”The SY6970 component must be defined in your configuration to set up the device. All other platforms below refer to this component.
# Example configuration entryi2c: - id: bus_a sda: GPIO5 scl: GPIO6
sy6970: id: pmu address: 0x6A enable_status_led: true input_current_limit: 1000 charge_voltage: 4200 charge_current: 500 precharge_current: 128 charge_enabled: true enable_adc: true i2c_watchdog_timeout: 40S update_interval: 1sConfiguration variables
Section titled “Configuration variables”- id (Optional, ID): Manually specify the ID used for code generation.
- address (Optional, int): The I²C address of the device. Defaults to
0x6A. - enable_status_led (Optional, boolean): Enable or disable the status LED on the IC. Defaults to
true. - input_current_limit (Optional, int): Input current in milliamps. Accepts values between 100 and 3200. Defaults to
500. - charge_voltage (Optional, int): Charge voltage in millivolts. Accepts values between 3840 and 4608. Defaults to
4208. - charge_current (Optional, int): Charge current in milliamps. Accepts values between 0 and 5056. Defaults to
2048. - precharge_current (Optional, int): Pre-charge current in milliamps. Accepts values between 64 and 1024. Defaults to
128. - charge_enabled (Optional, boolean): Enable or disable charging. Defaults to
true. - enable_adc (Optional, boolean): Enable or disable the ADC. Defaults to
true. - i2c_watchdog_timeout (Optional, enum): The timeout of the IC’s I²C watchdog. One of
DISABLED,40S,80Sor160S. Defaults to40S. See Watchdog. - All other options from I²C Device.
- update_interval (Optional, Time): The interval to check the sensor. Defaults to
5s.
Watchdog
Section titled “Watchdog”The SY6970 has an I²C watchdog. If the host does not reset it within the timeout, the IC reverts several
registers to their power-on defaults, including charge_enabled and enable_status_led. Charging and the status
LED then switch back on by themselves.
While i2c_watchdog_timeout is not DISABLED, ESPHome resets the watchdog every 10 seconds, whatever the
timeout and independent of update_interval, so any update_interval - including never - is valid and a single
missed reset does not let the watchdog expire. If the IC cannot be reached over I²C, the watchdog is not reset and
the IC returns to its defaults after the timeout. Once the IC has reverted, your configured settings are not
re-applied until the next reboot.
Set i2c_watchdog_timeout: DISABLED to turn the watchdog off.
Deep Sleep
Section titled “Deep Sleep”Nothing runs on the ESP while it is in deep sleep, including the watchdog reset. If
the ESP sleeps for about as long as i2c_watchdog_timeout or longer, the IC’s watchdog fires mid-sleep and
reverts charge_enabled and enable_status_led before the device wakes up to reconfigure it.
Disable the watchdog before sleeping with an on_shutdown automation,
which runs both for the deep_sleep.enter action and for sleep
entered automatically after run_duration. setup() re-arms the configured i2c_watchdog_timeout on wake, since
waking from deep sleep restarts the ESP:
esphome: on_shutdown: - lambda: 'id(pmu).set_i2c_watchdog_timeout(sy6970::I2C_WATCHDOG_DISABLED);'Without that, keep sleep_duration at least 10 seconds plus the boot time below the timeout, since the last reset
can be up to 10 seconds old when the ESP goes to sleep, or set i2c_watchdog_timeout: DISABLED for the whole
configuration.
Sensor
Section titled “Sensor”The sy6970 sensor platform exposes voltage and current measurements from the SY6970 IC.
# Example configuration entrysensor: - platform: sy6970 sy6970_id: pmu vbus_voltage: name: "VBUS Voltage" battery_voltage: name: "Battery Voltage" system_voltage: name: "System Voltage" charge_current: name: "Charge Current" precharge_current: name: "Precharge Current"Sensor Configuration variables
Section titled “Sensor Configuration variables”- sy6970_id (Optional, ID): The ID of the SY6970 component. Defaults to the only SY6970 component in your configuration.
- vbus_voltage (Optional): The voltage on the VBUS (USB) input in volts.
- All options from Sensor.
- battery_voltage (Optional): The battery voltage in volts.
- All options from Sensor.
- system_voltage (Optional): The system voltage in volts.
- All options from Sensor.
- charge_current (Optional): The charging current in milliamps.
- All options from Sensor.
- precharge_current (Optional): The precharge current in milliamps.
- All options from Sensor.
- All other options from Sensor.
Binary Sensor
Section titled “Binary Sensor”The sy6970 binary sensor platform exposes charging state information from the SY6970 IC.
# Example configuration entrybinary_sensor: - platform: sy6970 sy6970_id: pmu vbus_connected: name: "VBUS Connected" charging: name: "Battery Charging" charge_done: name: "Charge Done"Binary Sensor Configuration variables
Section titled “Binary Sensor Configuration variables”- sy6970_id (Optional, ID): The ID of the SY6970 component. Defaults to the only SY6970 component in your configuration.
- vbus_connected (Optional): Indicates whether VBUS (USB power) is connected.
- All options from Binary Sensor.
- charging (Optional): Indicates whether the battery is currently charging.
- All options from Binary Sensor.
- charge_done (Optional): Indicates whether charging is complete.
- All options from Binary Sensor.
- All other options from Binary Sensor.
Text Sensor
Section titled “Text Sensor”The sy6970 text sensor platform exposes status information from the SY6970 IC as text.
# Example configuration entrytext_sensor: - platform: sy6970 sy6970_id: pmu bus_status: name: "Power Source Type" charge_status: name: "Charging Status" ntc_status: name: "Battery Temperature"Text Sensor Configuration variables
Section titled “Text Sensor Configuration variables”- sy6970_id (Optional, ID): The ID of the SY6970 component. Defaults to the only SY6970 component in your configuration.
- bus_status (Optional): The type of power source connected. Possible values are:
No Input- No power source connectedUSB SDP- USB Standard Downstream PortUSB CDP- USB Charging Downstream PortUSB DCP- USB Dedicated Charging PortHVDCP- High Voltage Dedicated Charging PortAdapter- Dedicated adapterNon-Standard Adapter- Non-standard adapterOTG- OTG mode- All options from Text Sensor.
- charge_status (Optional): The current charging status. Possible values are:
Not Charging- Battery is not chargingPre-charge- Battery is in pre-charge phaseFast Charge- Battery is in fast charge phaseCharge Done- Charging is complete- All options from Text Sensor.
- ntc_status (Optional): The battery temperature status based on NTC thermistor. Possible values are:
Normal- Temperature is in normal rangeWarm- Battery is warmCool- Battery is coolCold- Battery is coldHot- Battery is hot- All options from Text Sensor.
- All other options from Text Sensor.
Complete Example
Section titled “Complete Example”Below is a complete example configuration for the LilyGo T-Display S3 Pro v1:
# Complete configuration example for LilyGo T-Display S3 Proi2c: - id: bus_a scan: true sda: GPIO5 scl: GPIO6
sy6970: id: pmu address: 0x6A update_interval: 1s enable_status_led: true input_current_limit: 1000 charge_voltage: 4200 charge_current: 500 precharge_current: 128 charge_enabled: true enable_adc: true
sensor: - platform: sy6970 sy6970_id: pmu vbus_voltage: name: "VBUS Voltage" battery_voltage: name: "Battery Voltage" system_voltage: name: "System Voltage" charge_current: name: "Charge Current" precharge_current: name: "Precharge Current"
text_sensor: - platform: sy6970 sy6970_id: pmu bus_status: name: "Power Source Type" charge_status: name: "Charging Status" ntc_status: name: "Battery Temperature"
binary_sensor: - platform: sy6970 sy6970_id: pmu charging: name: "Battery Charging" vbus_connected: name: "VBUS Connected" charge_done: name: "Charge Done"Advanced Configuration
Section titled “Advanced Configuration”The SY6970 provides several configuration methods that can be called from automations or scripts:
# Example automation to adjust charging parametersautomation: - trigger: - platform: homeassistant event: start then: - lambda: |- // Set input current limit to 1500mA id(pmu).set_input_current_limit(1500); // Set charge target voltage to 4200mV id(pmu).set_charge_target_voltage(4200); // Set charge current to 1000mA id(pmu).set_charge_current(1000); // Enable charging id(pmu).set_charge_enabled(true);Available Methods
Section titled “Available Methods”set_input_current_limit(uint16_t milliamps)- Set the input current limit (100-3200mA in 50mA steps)set_charge_target_voltage(uint16_t millivolts)- Set the target charging voltage (3840-4608mV in 16mV steps)set_charge_current(uint16_t milliamps)- Set the fast charge current (0-5056mA in 64mA steps)set_precharge_current(uint16_t milliamps)- Set the precharge current (64-1024mA in 64mA steps)set_charge_enabled(bool enabled)- Set battery charging enabled/disabledset_led_enabled(bool enabled)- Set status LED to enabled/disabledset_enable_adc_measure(bool enabled)- Enable ADC measurementsset_i2c_watchdog_timeout(I2CWatchdogTimeout timeout)- Change the I²C watchdog timeout at runtime (sy6970::I2C_WATCHDOG_DISABLED,I2C_WATCHDOG_40S,I2C_WATCHDOG_80SorI2C_WATCHDOG_160S). Starts or stops the automatic watchdog reset to match.reset_i2c_watchdog()- Reset the I²C watchdog timer. Called automatically every 10 seconds while the watchdog is enabled, independent ofupdate_interval. Returnstrueif the reset was written,falseotherwise.
Technical Details
Section titled “Technical Details”The SY6970 is an I²C controlled battery management IC with the following features:
- Single-cell Li-Ion/Li-Polymer battery charger
- Wide input voltage range: 4.5V to 14V
- Programmable charge current up to 5A
- Programmable charge voltage up to 4.608V
- Battery over-temperature protection via NTC thermistor
- Automatic power path management
- Built-in ADC for voltage and current monitoring
- Status LED output
Register Implementation
Section titled “Register Implementation”The component directly implements the SY6970 register protocol:
- REG_0B: Bus and charge status (bits 7:5 for bus type, bits 4:3 for charge state)
- REG_0E: Battery voltage (base 2304mV, 20mV steps)
- REG_11: VBUS voltage (base 2600mV, 100mV steps)
- REG_12: Charge current (50mA steps)
- REG_00-07: Configuration registers for current limits, charge parameters, and safety timers