esphome-docs/components/tm1651.rst
2024-08-01 22:38:39 +12:00

155 lines
3.8 KiB
ReStructuredText

TM1651 Battery Display
======================
.. seo::
:description: Instructions for setting up TM1651 Battery Display.
:image: tm1651_battery_display.jpg
.. _tm1651:
Battery Display
---------------
The ``tm1651`` display platform allows you to use battery display units based on the TM1651 chip such as
`this one <https://aliexpress.com/item/32811491559.html>`__ with ESPHome. This component supports the level
and brightness settings. All updates can be made via lambda expressions.
.. figure:: images/tm1651-battery-display.jpg
:align: center
:width: 70.0%
.. code-block:: yaml
tm1651:
id: tm1651_battery
clk_pin: GPIOXX
dio_pin: GPIOXX
Configuration variables:
************************
- **clk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): CLK pin
- **dio_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): DIO pin
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
.. _tm1651-set_level_percent_action:
``tm1651.set_level_percent`` Action
-----------------------------------
This :ref:`Action <config-action>` changes the level of the battery display at runtime.
Automatically calculates input level in percentages to actual level for the display.
.. code-block:: yaml
on_...:
- tm1651.set_level_percent:
id: tm1651_battery
level_percent: 50
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID of the TM1651.
- **level_percent** (**Required**, :ref:`templatable <config-templatable>`, int): Level from 0 to 100
.. _tm1651-set_level_action:
``tm1651.set_level`` Action
---------------------------
This :ref:`Action <config-action>` changes the level of the battery display at runtime.
.. code-block:: yaml
on_...:
- tm1651.set_level:
id: tm1651_battery
level: 5
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID of the TM1651.
- **level** (**Required**, :ref:`templatable <config-templatable>`, int): Level from 0 to 7
.. _tm1651-set_brightness_action:
``tm1651.set_brightness`` Action
--------------------------------
This :ref:`Action <config-action>` allows you to manually change the brightness of the battery display at runtime.
.. code-block:: yaml
on_...:
- tm1651.set_brightness:
id: tm1651_battery
brightness: 1
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID of the TM1651.
- **brightness** (**Required**, :ref:`templatable <config-templatable>`, int): There is three levels of brightness
(``1``, ``2`` or ``3``) from lowest to highest brightness.
.. _tm1651-turn_off:
``tm1651.turn_off`` Action
--------------------------
This :ref:`Action <config-action>` turns off all the LEDs.
.. code-block:: yaml
on_...:
- tm1651.turn_off:
id: tm1651_battery
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID of the TM1651.
.. _tm1651-turn_on:
``tm1651.turn_on`` Action
-------------------------
This :ref:`Action <config-action>` turns on the LEDs.
.. code-block:: yaml
on_...:
- tm1651.turn_on:
id: tm1651_battery
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID of the TM1651.
Advanced Configuration
----------------------
You also can control this component with lambda expressions
.. code-block:: yaml
api:
actions:
- action: battery_level
variables:
level: int
then:
- lambda: |-
id(tm1651_battery).set_level(level);
- action: battery_brightness
variables:
brightness: int
then:
- lambda: |-
id(tm1651_battery).set_brightness(brightness);
See Also
--------
- :doc:`index`
- :ghedit:`Edit`