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

串行代理

IMPORTANT

此组件为实验性。API（包括 Python 配置和 C++ 接口） 可能随时更改，且不遵循常规的破坏性更改政策。使用风险自负。 一旦 API 被视为稳定，此警告将被移除。

serial_proxy 组件通过原生 API 将你的 ESPHome 设备上的物理 UART 串行端口暴露给 API 客户端 （如 Home Assistant）。这允许 API 客户端直接向连接到 ESP 的串行设备发送数据和 接收来自它的数据，实际上创建了一个 网络附加的串行端口。

此组件需要 Native API 和 UART 组件。

单个设备上可以配置多个 serial_proxy 实例，每个附加到不同的 UART。

# 示例配置条目
serial_proxy:
  - id: serial_proxy_1
    uart_id: serial_1
    name: My Serial Device
    port_type: TTL

配置变量

Section titled “配置变量”
  • id (可选, ID): 手动指定用于代码生成的 ID。
  • name (必选, string): 此串行端口的人类可读名称，用于向 API 客户端标识它。
  • uart_id (必选, ID): 此代理所附加的 UART 组件的 ID。
  • port_type (必选, string): 串行端口的电气类型。为以下之一：
    • TTL: 标准 TTL 逻辑电平 UART（3.3V 或 5V）。通常用于与大多数微控制器的直接连接。
    • RS232: RS-232 标准串行端口（通常通过适当的线路驱动器 IC 提供 ±12V 电平）。通常用于 PC 风格的串行连接，常带有 DB9 型连接器。
    • RS485: RS-485 差分串行总线。通常用于工业/多点分支串行网络。
  • rts_pin (可选, Pin): 用作 RTS（请求发送） 调制解调器控制输出的 GPIO 引脚。此引脚的状态可由 API 客户端在运行时控制。
  • dtr_pin (可选, Pin): 用作 DTR（数据终端就绪） 调制解调器控制输出的 GPIO 引脚。此引脚的状态可由 API 客户端在运行时控制。

工作原理

Section titled “工作原理”

当 API 客户端连接时，它可以：

  • 向串行设备发送数据，通过 API 写入字节。
  • 从串行设备接收数据 — 到达 UART 的数据会在每个循环迭代时自动转发给已连接的 API 客户端（每次最多 256 字节）。
  • 在运行时重新配置 UART — API 客户端可以在不重新刷写固件的情况下更改波特率、数据位、停止位和校验位。
  • 控制调制解调器引脚 — 如果配置了 rts_pin 或 dtr_pin，API 客户端可以在运行时设置它们的状态。

完整示例

Section titled “完整示例”
# 两个不同 UART 上的串行代理
uart:
  - id: device_uart
    tx_pin: GPIO4
    rx_pin: GPIO5
    baud_rate: 9600


  - id: rs485_uart
    tx_pin: GPIO16
    rx_pin: GPIO17
    baud_rate: 19200


api:


serial_proxy:
  - id: device_serial
    uart_id: device_uart
    name: TTL Device
    port_type: TTL


  - id: rs485_serial
    uart_id: rs485_uart
    name: RS-485 Bus
    port_type: RS485
    rts_pin: GPIO18

另请参阅

Section titled “另请参阅”