diff --git a/components/libretiny.rst b/components/libretiny.rst new file mode 100644 index 000000000..4b531c54c --- /dev/null +++ b/components/libretiny.rst @@ -0,0 +1,221 @@ +LibreTiny Platform +================== + +.. seo:: + :description: Configuration for the LibreTiny platform for ESPHome. + :image: libretiny.svg + +This component contains platform-specific options for the `LibreTiny `__ platform. +It provides support for the following microcontrollers: + +- **BK72xx**: BK7231T, BK7231N +- **RTL87xx**: RTL8710BN, RTL8710BX + +Since different microcontrollers are supported, you need to include the appropriate ESPHome component, +depending on which processor your device has. + +Refer to `LibreTiny/Boards `__ to find your board type. + +.. code-block:: yaml + + # Example configuration entry for BK72xx + bk72xx: + board: generic-bk7231n-qfn32-tuya + + # Example configuration entry for RTL87xx + rtl87xx: + board: generic-rtl8710bn-2mb-788k + +Configuration variables: +------------------------ + +- **board** (**Required**, string): The PlatformIO board ID that should be used. Choose the appropriate board from + `this list `__ + (the icon next to the name can be used to copy the board ID). + + **This affects CPU selection and some internal settings** - make sure to choose the right CPU. + If unsure about the choice of a particular board, choose a generic board such as ``generic-bk7231n-qfn32-tuya``. + +- **framework** (*Optional*): Options for the underlying framework used by ESPHome. + + - **version** (*Optional*, string): The LibreTiny version number to use, from + `LibreTiny platform releases `__. Defaults to ``recommended``. Additional values + + - ``dev``: Use the latest commit from https://github.com/kuba2k2/libretiny, note this may break at any time + - ``latest``: Use the latest *release* from https://github.com/kuba2k2/libretiny/releases, even if it hasn't been recommended yet. + - ``recommended``: Use the recommended framework version. + + - **source** (*Optional*, string): The PlatformIO package or repository to use for the framework. This can be used to use a custom or patched version of the framework. + + - :ref:`Advanced options ` + +- **family** (*Optional*, boolean): The family of LibreTiny-supported microcontrollers that is used on this board. + One of ``bk7231n``, ``bk7231t``, ``rtl8710b``, ``rtl8720c``, ``bk7251``, ``bk7231q``. + Defaults to the variant that is detected from the board, if a board that's unknown to ESPHome is used, + this option is mandatory. **It's recommended not to include this option**. + +.. note:: + + Support for the LibreTiny platform is still in development and there could be issues or missing components. + + In particular, **MQTT is not supported yet**, because of reported stability issues. + + Please report any issues on `LibreTiny GitHub `__. + +Getting Started +--------------- + +Since BK72xx and RTL87xx chips are relatively new on the IoT Open Source development stage, +there aren't many resources on flashing and configuring them. + +Here are a few useful links: + +- `tuya-cloudcutter `__ - flashing ESPHome Over-the-Air + to some devices compatible with Tuya/SmartLife apps (BK72xx only!) + + - `Textual & video guide by digiblurDIY `__ + - `Video guide by LibreTiny `__ + - `ESPHome-Kickstart `__ - starter firmware to upload OTA with Cloudcutter + +- `Flashing BK72xx by UART `__ +- `Flashing RTL8710B by UART `__ +- `UPK2ESPHome `__ - generating ESPHome YAML automatically, from Cloudcutter profiles or Kickstart firmware (also BK72xx only) + +GPIO Pin Numbering +------------------ + +Chips supported by LibreTiny use the internal GPIO pin numbering of the boards, this means that +you don't have to worry about other kinds of pin numberings, yay! + +Additionally, you can use **pin function macros** to quickly access a GPIO tied to a particular peripheral, +such as UART1 TX/RX or PWM0. +See `LibreTiny/GPIO Access `__ to learn more. + +Most of the popular boards (often incorrectly called "chips"), that are usually shipped with Smart Home devices, +are *supported by LibreTiny*, which means that a pinout drawing is available, with all GPIOs described. +Visit `LibreTiny/Boards `__ to find all supported boards. + +The ``Pin functions`` table outlines all GPIOs available on the chosen board. +*You can use any of the visible names* to access a particular GPIO. + +Some notes about the pins on BK72xx: + +- ``TX2 (P0)`` and ``RX2 (P1)`` are used for the default :doc:`/components/logger` UART port. +- ``TX1 (P11)`` and ``RX1 (P10)`` are used for flashing firmware, as well as for :doc:`/components/tuya`. +- ``ADC3 (P23)`` is the only :doc:`/components/sensor/adc` available on BK7231. + +Some notes about the pins on RTL8710BN/BX: + +- ``TX2 (PA30)`` and ``RX2 (PA29)`` are used for flashing the firmware, + as well as the default :doc:`/components/logger` UART port. +- ``TX2 (PA30)`` is additionally used to determine the boot mode on startup (similar to ESP32). + Pulling it LOW on startup will enter "download mode". + +Example configuration entries using various naming styles: + +.. code-block:: yaml + + # GPIO switch on P26/GPIO26 (BK72xx example) + switch: + - platform: gpio + name: Relay 1 + pin: P26 + + # GPIO binary sensor on PA12 (RTL87xx example) + binary_sensor: + - platform: gpio + name: "Pin PA12" + pin: PA12 + + # ADC reading (BK72xx example) + sensor: + - platform: adc + pin: ADC3 + name: "Battery Level" + + # PWM component + output: + - platform: libretiny_pwm + pin: PWM2 + frequency: 1000 Hz + id: pwm_output + # using light with the PWM + light: + - platform: monochromatic + output: pwm_output + name: "Kitchen Light" + + # Tuya MCU on UART1 (BK72xx example) + uart: + rx_pin: RX1 + tx_pin: TX1 + baud_rate: 9600 + tuya: + +.. _advanced-options: + +Advanced options +---------------- + +These are some advanced configuration options of LibreTiny platform. + +.. code-block:: yaml + + # Example configuration entry + bk72xx: + board: cb2s + framework: + version: dev + loglevel: debug + debug: + - wifi + - ota + sdk_silent: auto + uart_port: 2 + gpio_recover: false + options: + LT_LOG_HEAP: 1 + LT_AUTO_DOWNLOAD_REBOOT: 1 + +- **loglevel** (*Optional*, string): Logging level for LibreTiny core. Controls the output of logging messages + from the core (doesn't affect ESPHome logger!). *These messages are only visible on the physical UART*. + One of ``verbose``, ``trace`` (same as ``verbose``), ``debug``, ``info``, + ``warn`` (default), ``error``, ``fatal``, ``none``. + +- **debug** (*Optional*, string or string list): Modules to enable LibreTiny debugging for. + Refer to `LibreTiny/Configuration `__ + for more information - some modules are enabled by default. + One or more of ``wifi``, ``client``, ``server``, ``ssl``, ``ota``, ``fdb``, + ``mdns``, ``lwip``, ``lwip_assert``. + Specifying ``none`` will disable all modules. You can also combine ``none`` with one or more of the modules. + +- **sdk_silent** (*Optional*, string): Define the SDK logging "silent mode". + This disables messages from vendor SDKs, which makes UART output more readable, but can hide some error messages. + *This affects the physical UART port only*. + Refer to `LibreTiny/Configuration `__ for more information. + + - ``all``: Disable all messages (default). + - ``auto``: Disable selectively, i.e. during Wi-Fi activation. + - ``none``: Keep all logging messages, don't disable anything. + +- **uart_port** (*Optional*, int): Choose the default UART port of the framework. + This affects LibreTiny logging messages, **as well as the default port for** + :doc:`ESPHome logger ` (e.g. if you don't specify any other). + One of 0, 1, 2. The default value is chip-specific and is chosen by LibreTiny appropriately. + +- **gpio_recover** (*Optional*, boolean): Disable JTAG/SWD debugging peripherals. This may be needed + to free GPIOs that should be used for other functions. Defaults to ``true``. + +- **options** (*Optional*, mapping): Custom options passed to LibreTiny platform. + Refer to `LibreTiny/Configuration `__ to see all options. + *This takes precedence (overrides) all options described above*. + +See Also +-------- + +- :doc:`esphome` +- :doc:`/components/output/libretiny_pwm` +- :doc:`/components/text_sensor/libretiny` +- `LibreTiny Documentation `__ (external) +- :doc:`/components/tuya` +- :ghedit:`Edit` diff --git a/components/output/libretiny_pwm.rst b/components/output/libretiny_pwm.rst new file mode 100644 index 000000000..da3086c08 --- /dev/null +++ b/components/output/libretiny_pwm.rst @@ -0,0 +1,66 @@ +LibreTiny PWM Output +==================== + +.. seo:: + :description: Instructions for setting up LibreTiny hardware PWMs. + :image: pwm.png + +The LibreTiny PWM platform allows you to use a hardware PWM on BK72xx and RTL87xx chips. +Refer to `LibreTiny/Boards `__ to find your board +and which PWM pins it supports. + +.. code-block:: yaml + + # Example configuration entry + output: + - platform: libretiny_pwm + pin: P8 + frequency: 1000 Hz + id: pwm_output + + # Example usage in a light + light: + - platform: monochromatic + output: pwm_output + name: "Kitchen Light" + +Configuration variables: +------------------------ + +- **pin** (**Required**, :ref:`Pin Schema `): The pin to use PWM on. +- **id** (**Required**, :ref:`config-id`): The id to use for this output component. +- **frequency** (*Optional*, frequency): The frequency to run the PWM with. Lower frequencies + have more visual artifacts, but can represent much more colors. Defaults to ``1000 Hz``. +- All other options from :ref:`Output `. + +.. _output-libretiny_pwm-set_frequency_action: + +``output.libretiny_pwm.set_frequency`` Action +--------------------------------------------- + +This :ref:`Action ` allows you to manually change the frequency of a LibreTiny PWM +channel at runtime. Use cases include controlling a passive buzzer (for pitch control). + +.. code-block:: yaml + + on_...: + - output.libretiny_pwm.set_frequency: + id: pwm_output + frequency: 100Hz + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the PWM output to change. +- **frequency** (**Required**, :ref:`templatable `, float): The frequency + to set in hertz. + +See Also +-------- + +- :doc:`/components/libretiny` +- :doc:`/components/output/index` +- :doc:`/components/light/monochromatic` +- :doc:`/components/fan/speed` +- :doc:`/components/power_supply` +- :apiref:`libretiny_pwm/libretiny_pwm.h` +- :ghedit:`Edit` diff --git a/components/text_sensor/libretiny.rst b/components/text_sensor/libretiny.rst new file mode 100644 index 000000000..c81693f3c --- /dev/null +++ b/components/text_sensor/libretiny.rst @@ -0,0 +1,31 @@ +LibreTiny Text Sensor +===================== + +.. seo:: + :description: Instructions for setting up LibreTiny text sensors. + :image: libretiny.svg + +The ``libretiny`` text sensor platform exposes various LibreTiny core +information via text sensors. + +.. code-block:: yaml + + # Example configuration entry + text_sensor: + - platform: libretiny + version: + name: LibreTiny Version + +Configuration variables: +------------------------ + +- **version** (*Optional*): Expose the version of LibreTiny core as a text sensor. All options from + :ref:`Text Sensor `. + + +See Also +-------- + +- :doc:`/components/libretiny` +- :apiref:`libretiny/lt_component.h` +- :ghedit:`Edit` diff --git a/images/bk72xx.svg b/images/bk72xx.svg new file mode 100644 index 000000000..f96e6b01f --- /dev/null +++ b/images/bk72xx.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/images/libretiny.svg b/images/libretiny.svg new file mode 100644 index 000000000..3e06e29e2 --- /dev/null +++ b/images/libretiny.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/images/rtl87xx.svg b/images/rtl87xx.svg new file mode 100644 index 000000000..03818bcdc --- /dev/null +++ b/images/rtl87xx.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + diff --git a/index.rst b/index.rst index 76b675a20..5feaf4036 100644 --- a/index.rst +++ b/index.rst @@ -5,14 +5,14 @@ .. seo:: :description: ESPHome Homepage - Reimagining DIY Home Automation. ESPHome is a framework that - tries to provide the best possible use experience for using ESP8266, ESP32 and RP2040 microcontrollers + tries to provide the best possible use experience for using IoT microcontrollers for Home Automation. Just write a simple YAML configuration file and get your own customized firmware. :image: logo.svg .. image:: /images/logo-text.svg :class: dark-invert -ESPHome is a system to control your ESP8266/ESP32 and RP2040 by simple yet powerful configuration files and control them remotely through Home Automation systems. +ESPHome is a system to control your microcontrollers by simple yet powerful configuration files and control them remotely through Home Automation systems. .. image:: /images/hero.png @@ -124,6 +124,8 @@ Platforms ESP8266, components/esp8266, esp8266.svg ESP32, components/esp32, esp32.svg RP2040, components/rp2040, rp2040.svg + BK72xx, components/libretiny, bk72xx.svg + RTL87xx, components/libretiny, rtl87xx.svg Core Components --------------- @@ -497,6 +499,7 @@ Output Components GPIO Output, components/output/gpio, pin.svg, dark-invert ESP32 DAC, components/output/esp32_dac, dac.svg ESP32 LEDC, components/output/ledc, pwm.png + LibreTiny PWM, components/output/libretiny_pwm, pwm.png AC Dimmer, components/output/ac_dimmer, ac_dimmer.svg, dark-invert PCA9685, components/output/pca9685, pca9685.jpg TLC59208F, components/output/tlc59208f, tlc59208f.jpg @@ -677,6 +680,7 @@ Text Sensor Components Nextion Text Sensor, components/text_sensor/nextion, nextion.jpg Tuya Text Sensor, components/text_sensor/tuya, tuya.png WL-134 Pet Tag Sensor , components/text_sensor/wl_134, fingerprint.svg, dark-invert + LibreTiny, components/text_sensor/libretiny, libretiny.svg Climate Components ------------------