LibreTiny Platform
This component contains platform-specific options for the LibreTiny platform. It provides support for the following microcontrollers, commonly used in Tuya devices, amongst others:
- BK72xx: BK7231T, BK7231N, BK7238
- RTL87xx: RTL8710BN, RTL8710BX, RTL8720CF, RTL8720CM
- LN882x: LN882H
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.
# Example configuration entry for BK72xxbk72xx: board: generic-bk7231n-qfn32-tuya
# Example configuration entry for RTL87xxrtl87xx: board: generic-rtl8710bn-2mb-788k
# Example configuration entry for LN882xln882x: board: generic-ln882hConfiguration variables
Section titled “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 valuesdev: Use the latest commit from https://github.com/libretiny-eu/libretiny, note this may break at any timelatest: Use the latest release from https://github.com/libretiny-eu/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.
-
-
family (Optional, string): The family of LibreTiny-supported microcontrollers that is used on this board. One of
bk7231n,bk7231q,bk7231t,bk7238,bk7251,ln882h,rtl8710b,rtl8720c. 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.
Please report any issues on LibreTiny GitHub.
Getting Started
Section titled “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
-
UPK2ESPHome - generating ESPHome YAML automatically, from Cloudcutter profiles or Kickstart firmware (also BK72xx only)
GPIO Pin Numbering
Section titled “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)andRX2 (P1)are used for the default Logger UART port.TX1 (P11)andRX1 (P10)are used for flashing firmware, as well as for Tuya.ADC3 (P23)is the only Adc available on BK7231.
Some notes about the pins on RTL8710BN/BX:
-
TX2 (PA30)andRX2 (PA29)are used for flashing the firmware, as well as the default 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”.
Some notes about the pins on LN882H:
-
TX0 (PA2)andRX0 (PA3)are used for flashing the firmware, as well as the default Logger UART port. -
BOOT1 (PA9)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:
# 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 componentoutput: - platform: libretiny_pwm pin: PWM2 frequency: 1kHz id: pwm_output# using light with the PWMlight: - platform: monochromatic output: pwm_output name: "Kitchen Light"
# Tuya MCU on UART1 (BK72xx example)uart: rx_pin: RX1 tx_pin: TX1 baud_rate: 9600tuya:Advanced options
Section titled “Advanced options”These are some advanced configuration options of LibreTiny platform.
# Example configuration entrybk72xx: 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 asverbose),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. Specifyingnonewill disable all modules. You can also combinenonewith 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 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.
Crash Handler
Section titled “Crash Handler”On BK7238, BK7231N, RTL8710B, RTL8720C and LN882H, ESPHome captures crash data from the previous boot and logs
it on startup, the same way it does on ESP32, ESP8266 and RP2040. On BK7238 and BK7231N it covers the chip’s
three fault traps: undefined instruction, prefetch abort and data abort. On RTL8720C and LN882H it covers the
hard fault, bus fault, usage fault and memory management fault (and the secure fault on RTL8720C). RTL8710B
reports every fault as a hard fault. On all three the report also shows the fault status register (CFSR),
which gives the cause, and, when the chip recorded one, the address that faulted.
When a crash occurs, the fault PC, the return address and up to 8 stack-scanned return addresses are
preserved across the reboot and logged at the ERROR level. The report is also replayed to the next log
client that connects over the API or MQTT, and the ESPHome CLI decodes the addresses to function names
(see Getting a Stack Trace from Crashes).
[E][libretiny.crash]: *** CRASH DETECTED ON PREVIOUS BOOT ***[E][libretiny.crash]: Reason: Undefined instruction[E][libretiny.crash]: PC: 0x0001D6DC (fault location)[E][libretiny.crash]: LR: 0x0001D6DD (return address)[E][libretiny.crash]: SP: 0x0040DDB8[E][libretiny.crash]: BT0: 0x0001D735 (stack backtrace)[E][libretiny.crash]: BT1: 0x0001D305 (stack backtrace)On RTL8710B, RTL8720C and LN882H the report adds the fault status register and the faulting address. Address
is only recorded for bus and memory management faults and reads 0x00000000 otherwise, as in this usage fault:
[E][libretiny.crash]: *** CRASH DETECTED ON PREVIOUS BOOT ***[E][libretiny.crash]: Reason: Usage fault[E][libretiny.crash]: CFSR: 0x00010000 Address: 0x00000000[E][libretiny.crash]: PC: 0x9B0073A4 (fault location)[E][libretiny.crash]: LR: 0x9B0073A5 (return address)[E][libretiny.crash]: BT0: 0x9B007301 (stack backtrace)The crash handler also makes the device restart after a crash and report it: within a second on BK72xx and RTL8720C, within about 1.5 seconds on RTL8710B, and within a few seconds on LN882H. Without it, a BK72xx device with Wi-Fi connected hangs until its power is cycled, an RTL8710B or RTL8720C device waits for the 10 second watchdog, and an LN882H device locks up until the watchdog resets it.
No configuration is needed — the crash handler is always enabled on BK7238, BK7231N, RTL8710B, RTL8720C and LN882H. Other BK72xx chips do not have it yet, and a crash with Wi-Fi connected can still leave them hung until they are power-cycled.