跳转到内容
ESPHome - 让智能家居更简单2026.7.0

LibreTiny 平台

此组件包含 LibreTiny 平台的平台特定选项。 它提供对以下微控制器的支持，这些微控制器常用于 Tuya 设备等：

  • BK72xx: BK7231T、BK7231N、BK7238
  • RTL87xx: RTL8710BN、RTL8710BX
  • LN882x: LN882H

由于支持不同的微控制器，你需要根据设备所使用的处理器，包含相应的 ESPHome 组件。

请参阅 LibreTiny/开发板 来找到你的开发板类型。

# 示例配置条目（适用于 BK72xx）
bk72xx:
  board: generic-bk7231n-qfn32-tuya


# 示例配置条目（适用于 RTL87xx）
rtl87xx:
  board: generic-rtl8710bn-2mb-788k


# 示例配置条目（适用于 LN882x）
ln882x:
  board: generic-ln882h

配置变量

Section titled “配置变量”

  • board (必选, string): 应当使用的 PlatformIO 开发板 ID。请从 此列表 中选择适当的开发板（名称旁的图标可用于复制开发板 ID）。

    这会影响 CPU 的选择和一些内部设置 - 请确保选择正确的 CPU。 如果对特定开发板的选择不确定，请选择通用开发板，如 generic-bk7231n-qfn32-tuya。

  • framework (可选): ESPHome 所使用的底层框架的选项。

  • family (可选, string): 此开发板上使用的 LibreTiny 支持的微控制器系列。 为 bk7231n、bk7231q、bk7231t、bk7238、bk7251、ln882h、rtl8710b、rtl8720c 之一。 默认为从开发板检测到的变体；如果使用了 ESPHome 未识别的开发板， 则此选项为必填。建议不要包含此选项。

NOTE

对 LibreTiny 平台的支持仍在开发中，可能存在一些问题或缺少组件。

请在 LibreTiny GitHub 上报告任何问题。

入门指南

Section titled “入门指南”

由于 BK72xx 和 RTL87xx 芯片在 IoT 开源开发舞台上相对较新， 关于刷写和配置它们的资源不多。

以下是一些有用的链接：

GPIO 引脚编号

Section titled “GPIO 引脚编号”

LibreTiny 支持的芯片使用开发板内部的 GPIO 引脚编号，这意味着 你不必担心其他类型的引脚编号，太好了！

此外，你可以使用引脚功能宏快速访问与特定外设绑定的 GPIO， 例如 UART1 TX/RX 或 PWM0。 参阅 LibreTiny/GPIO 访问 了解更多。

大多数常见的开发板（通常被错误地称为”芯片”），即通常随智能家居设备附带的那种， 都受 LibreTiny 支持，这意味着存在描述所有 GPIO 的引脚定义图可供查阅。 访问 LibreTiny/开发板 查找所有受支持的开发板。

Pin functions（引脚功能）表概述了所选开发板上所有可用的 GPIO。 你可以使用任何可见的名称 来访问特定的 GPIO。

关于 BK72xx 引脚的一些说明：

  • TX2 (P0) 和 RX2 (P1) 用于默认的 Logger UART 端口。
  • TX1 (P11) 和 RX1 (P10) 用于刷写固件，以及用于 Tuya。
  • ADC3 (P23) 是 BK7231 上唯一可用的 Adc。

关于 RTL8710BN/BX 引脚的一些说明：

  • TX2 (PA30) 和 RX2 (PA29) 用于刷写固件， 以及作为默认的 Logger UART 端口。

  • TX2 (PA30) 还用于在启动时确定引导模式（类似于 ESP32）。 在启动时将其拉低将进入”下载模式”。

关于 LN882H 引脚的一些说明：

  • TX0 (PA2) 和 RX0 (PA3) 用于刷写固件， 以及作为默认的 Logger UART 端口。

  • BOOT1 (PA9) 还用于在启动时确定引导模式（类似于 ESP32）。 在启动时将其拉低将进入”下载模式”。

使用各种命名风格的示例配置条目：

# 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: 1kHz
    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:

高级选项

Section titled “高级选项”

以下是一些 LibreTiny 平台的高级配置选项。

# 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 (可选, string): LibreTiny 内核的日志级别。控制来自内核的 日志消息的输出（不影响 ESPHome 的记录器！）。这些消息仅在物理 UART 上可见。 为 verbose、trace（与 verbose 相同）、debug、info、 warn（默认）、error、fatal、none 之一。

  • debug (可选, string 或 string 列表): 要为其启用 LibreTiny 调试的模块。 参阅 LibreTiny/配置 了解更多信息 - 某些模块默认启用。 为 wifi、client、server、ssl、ota、fdb、 mdns、lwip、lwip_assert 之一或多个。 指定 none 将禁用所有模块。你也可以将 none 与一个或多个模块组合使用。

  • sdk_silent (可选, string): 定义 SDK 日志的”静默模式”。 这会禁用来自厂商 SDK 的消息，使 UART 输出更易读，但也可能隐藏一些错误消息。 这仅影响物理 UART 端口。 参阅 LibreTiny/配置 了解更多信息。

    • all : 禁用所有消息（默认）。
    • auto : 选择性禁用，例如在 Wi-Fi 激活期间。
    • none : 保留所有日志消息，不禁用任何内容。

  • uart_port (可选, int): 选择框架的默认 UART 端口。 这会影响 LibreTiny 日志消息，以及 ESPHome 记录器 的默认端口（例如，如果你没有指定其他端口）。 为 0、1、2 之一。默认值取决于芯片，由 LibreTiny 恰当选择。

  • gpio_recover (可选, boolean): 禁用 JTAG/SWD 调试外设。这可能 需要释放那些本应用于其他功能的 GPIO。默认为 true。

  • options (可选, mapping): 传递给 LibreTiny 平台的自定义选项。 参阅 LibreTiny/配置 查看所有选项。 这将优先于（覆盖）以上描述的所有选项。

另请参阅

Section titled “另请参阅”