RP2 平台

此组件包含 RP2 平台的平台特定选项，该平台涵盖 Raspberry Pi RP 系列的 RP2040 和 RP2350 芯片。

NOTE

平台键在 ESPHome 2026.7.0 中从 rp2040 改名为 rp2，以便系列名称反映工具链同时涵盖 RP2040 和 RP2350 芯片。旧的 rp2040: 键作为弃用的别名继续工作，将在 2027.7.0 中移除。

NOTE

Raspberry Pi Pico W 和其他带有提供无线连接的 Cypress CYW43439 芯片的 RP2040 开发板受支持并经过测试。

RP2350 开发板（如 Pico 2 和 Pico 2 W）受支持。

使用 ESP-AT WiFi 模块（如 ESP8285）的开发板不受支持。这包括标有 RP2040 Pico W-2023 或类似名称的 Pico W 克隆板，它们使用 ESP 无线电芯片而不是 CYW43439。

如果你遇到未知问题，请搜索或创建 issue。

# 示例配置条目
rp2:
  board: rpipicow

NOTE

自 ESPHome 2024.9.2 起，由于 ESPHome 内部处理方式的变化，下面的 platform_version 不再是必需的。按原样使用下面的 platform_version 已知会因版本不匹配而导致编译问题。

建议从配置中移除 platform_version。

# 示例配置条目
rp2:
  board: rpipicow
  framework:
    platform_version: https://github.com/maxgerhardt/platform-raspberrypi.git

首次刷写（BOOTSEL 模式）

要通过 USB 首次刷写 RP2040 开发板，你需要将其置于 BOOTSEL 模式：

将设备从 USB 拔下。
按住开发板上的 BOOT/BOOTSEL 按钮。
按住按钮的同时插入 USB 电缆。
松开按钮——设备应该作为一个 USB 驱动器出现（通常名为 RPI-RP2）。

进入 BOOTSEL 模式后，运行 esphome run your_config.yaml。ESPHome 将自动检测挂载的 RPI-RP2 卷，并将其作为上传目标提供。UF2 固件将被复制到设备并显示进度条，然后设备将自动重启进入新固件。

首次刷写后，后续更新可以空中（OTA）或通过串口完成，无需按住 BOOTSEL 按钮——picotool 上传协议将自动将设备重置为 BOOTSEL 模式。

配置变量

variant (可选, string): 要针对的 RP2 系列芯片。为 rp2040 或 rp2350 之一。这必须与所使用的硬件匹配，否则将无法刷写。
board (可选, string): PlatformIO 开发板标识符。常见开发板包括 rpipicow （Raspberry Pi Pico W）、rpipico（Raspberry Pi Pico）、rpipico2w（Raspberry Pi Pico 2 W）和 rpipico2（Raspberry Pi Pico 2）。由 arduino-pico 框架支持的 140 多种开发板受支持。该框架支持的任何开发板都可以在这里使用。

NOTE

必须至少指定 board 或 variant 之一。如果只指定了 variant，则开发板配置将自动使用该变体的 Raspberry Pi 基金会规范参考板填充： rp2040 使用 rpipicow（Pico W），rp2350 使用 rpipico2w（Pico 2 W）。两者都可以指定，但必须定义相同的变体。如果 ESPHome 无法识别开发板，则必须显式指定 variant。

WARNING

某些组件仅限于特定的开发板，而不是整个变体。例如，WiFi 组件需要一个带有 Cypress CYW43439 无线芯片的开发板（如 rpipicow 或 rpipico2w）；选择一个没有该芯片的开发板（如 rpipico 或 rpipico2）将无法通过验证，即使该变体本身是有能力的。

watchdog_timeout (可选, Time): 应用于 RP2040 看门狗的超时时间。当设备挂起该时间长度时，它将会重启。默认为 8388ms（最大值）。设为 0s 可完全禁用看门狗。
enable_full_printf (可选, boolean): 启用完整的基于 FILE* 的 printf 支持。默认情况下，ESPHome 用使用 vsnprintf() + fwrite() 的轻量级存根包装 printf()、vprintf() 和 fprintf()，节省约 9.2 KB 的闪存。ESPHome 日志使用 snprintf/vsnprintf，而不是 libc printf，因此除非外部组件调用这些函数，否则它们通常不被使用。仅当外部组件需要完整的基于 FILE* 的 printf 时才设为 true。默认为 false。

GPIO 引脚名称

ESPHome 支持为具有已知引脚映射的开发板提供命名的 GPIO 引脚。这些名称会自动解析为你开发板的正确 GPIO 编号：

引脚名称	描述	示例（Pico W）
`LED`	板载 LED	GPIO 64 (CYW43)
`SDA`	默认 I²C 数据	GPIO 4
`SCL`	默认 I²C 时钟	GPIO 5
`SDA1`	次要 I²C 数据	GPIO 26
`SCL1`	次要 I²C 时钟	GPIO 27
`MISO`	默认 SPI MISO	GPIO 16
`MOSI`	默认 SPI MOSI	GPIO 19
`SCK`	默认 SPI 时钟	GPIO 18
`SS`	默认 SPI 片选	GPIO 17
`TX`	默认 UART TX	GPIO 0
`RX`	默认 UART RX	GPIO 1

NOTE

在带有 CYW43439 无线芯片的开发板（Pico W、Pico 2 W）上，板载 LED 连接到无线芯片而不是标准的 GPIO。它可以作为引脚 64（或 LED 引脚名称）访问，并且只支持输出模式。

板载 LED 示例

rp2:
  board: rpipicow

output:
  - platform: gpio
    pin: LED
    id: led_output

light:
  - platform: binary
    name: "Onboard LED"
    output: led_output

串行调试

默认情况下，ESPHome 通过 USB CDC（用于刷写的同一 USB 连接）记录日志。如果设备无法启动或 USB CDC 未启动，你可以使用硬件 UART 通过 USB 转串行适配器获取日志。

在你的配置中添加以下内容：

logger:
  hardware_uart: UART0
  baud_rate: 115200

然后将 USB 转串行适配器连接到你的开发板的 UART0 引脚：

信号	Pico W 引脚	连接到适配器
TX	GPIO 0	RX
RX	GPIO 1	TX
GND	Any GND	GND

TIP

TX 和 RX 引脚名称解析为你开发板的默认 UART0 引脚。如果你的开发板与上面的 Pico W 默认值不同，请在 boards.py 中搜索你的开发板名称（例如 seeed_xiao_rp2040），并在其引脚映射中查找 TX 和 RX 条目。请注意，GPIO 编号可能与开发板上的丝印标签不匹配。例如，在 Seeed XIAO RP2040 上，TX（GPIO 0）和 RX（GPIO 1）在开发板上标注为 D6 和 D7——请检查你的开发板的引脚定义图以找到正确的引脚。

以 115200 波特率打开串行终端查看日志。这对于诊断启动失败、WiFi 问题或阻止 USB 初始化的崩溃尤其有用。

RP2 平台

首次刷写（BOOTSEL 模式）

配置变量

GPIO 引脚名称

板载 LED 示例

串行调试

另请参阅