小米米家 BLE 传感器

xiaomi_ble 传感器平台允许您使用 Esp32 Ble Tracker 追踪小米蓝牙低功耗设备的输出。每次传感器发送 BLE 广播时，该组件会追踪例如温度、湿度、湿度、电导率、照度、甲醛、蚊香片及设备的电池电量。与其他实现方式不同，xiaomi_ble 被动监听广播包，不与设备配对。因此 ESPHome 对电池寿命没有任何影响。因此，如果您只使用这类传感器，可以安全地在 esp32_ble_tracker 配置中设置 scan_parameters.active: false，以避免用无用的扫描请求刷屏 RF 环境。

NOTE

或者，您也可以使用 ESPHome 的 Bluetooth Proxy 组件将传感器数据转发给 Home Assistant，并使用其自身的 Mija BLE 组件配置 Mija 设备。这适用于刷了 PVVX MiThermometer 自定义固件的设备，以及常规的原厂固件。

支持的设备

HHCCJCY01

MiFlora、花花草草，可测量土壤中的温度、湿度、环境光与养分水平。

配置示例：

sensor:
  - platform: xiaomi_hhccjcy01
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "Xiaomi HHCCJCY01 Temperature"
    moisture:
      name: "Xiaomi HHCCJCY01 Moisture"
    illuminance:
      name: "Xiaomi HHCCJCY01 Illuminance"
    conductivity:
      name: "Xiaomi HHCCJCY01 Soil Conductivity"
    battery_level:
      name: "Xiaomi HHCCJCY01 Battery Level"

NOTE

新版本的 HHCCJCY01 附带 3.2.1 固件，并且它们 不再发送电池电量数据。

GCLS002

VegTrug Grow Care Garden、Takasho，适用于户外，类似于 MiFlora。

配置示例：

sensor:
  - platform: xiaomi_gcls002
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "GCLS02 Temperature"
    moisture:
      name: "GCLS02 Moisture"
    conductivity:
      name: "GCLS02 Soil Conductivity"
    illuminance:
      name: "GCLS02 Illuminance"

HHCCPOT002

FlowerPot、花花草草、RoPot，广播湿度与电导率

配置示例：

sensor:
  - platform: xiaomi_hhccpot002
    mac_address: "XX:XX:XX:XX:XX:XX"
    moisture:
      name: "HHCCPOT002 Moisture"
    conductivity:
      name: "HHCCPOT002 Soil Conductivity"

LYWSDCGQ

湿度计温度计，圆形机身，段式 LCD，广播温度、湿度和电池电量。该设备也被称为 MJ_HT_V1。在 HA 的原生 Xiaomi BLE 集成中，设备信息页面显示为 “MJ_HT_V1 (LYWSDCGQ by Xiaomi)”。

配置示例：

sensor:
  - platform: xiaomi_lywsdcgq
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "LYWSDCGQ Temperature"
    humidity:
      name: "LYWSDCGQ Humidity"
    battery_level:
      name: "LYWSDCGQ Battery Level"

LYWSD02

湿度计温度计，矩形机身，电子墨水显示屏，广播温度、湿度和电池电量。

• 电池电量，需要 xiaomi 固件 1.1.2_0085

配置示例：

sensor:
  - platform: xiaomi_lywsd02
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "LYWSD02 Temperature"
    humidity:
      name: "LYWSD02 Humidity"
    battery_level:
      name: "LYWSD02 Battery Level"

LYWSD02MMC

湿度计温度计，矩形机身，电子墨水显示屏，广播温度、湿度和电池电量。加密。

配置示例：

sensor:
  - platform: xiaomi_lywsd02mmc
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "2529d8e0d23150a588675cc54ad48400"
    temperature:
      name: "LYWSD02MMC Temperature"
    humidity:
      name: "LYWSD02MMC Humidity"
    battery_level:
      name: "LYWSD02MMC Battery Level"

CGG1

Cleargrass（青萍）：湿度计温度计，圆形机身，电子墨水显示屏。

新固件需要 bindkey 才能解密接收到的数据（参见获取 Bindkey），并且不再广播电池电量。

配置示例：

sensor:
  - platform: xiaomi_cgg1
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "CGG1 Temperature"
    humidity:
      name: "CGG1 Humidity"
    battery_level:
      name: "CGG1 Battery Level"
  - platform: xiaomi_cgg1
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "CGG1 (New) Temperature"
    humidity:
      name: "CGG1 (New) Humidity"

LYWSD03MMC

湿度计温度计，方形小机身，段式 LCD，加密，广播温度、湿度和电池状态。

有几种方式可以操作该传感器：

1. Xiaomi 原厂固件（需要 bindkey）
2. 刷有 PVVX MiThermometer 自定义固件的设备，支持 “BTHome v2”、“ATC1441”、“PVVX (Custom)”、“MIJIA (MiHome)” 广播
3. 刷有 ATC MiThermometer 自定义固件的设备，支持 “Mi Like”、“Custom” 广播

使用 PVVX 固件和 “BTHome v2” 广播，支持使用 bindkey 加密，就像 Xiaomi 原厂固件一样（参见获取 Bindkey）。仅在自定义固件中支持未加密通信，但出于明显的安全原因，不建议这样做。

NOTE

自 6.0 版本起，PVVX 固件弃用了除 “BTHome v2” 之外的任何广播格式。

Xiaomi 原厂固件或设置为 “Mi Like” 广播的 ATC MiThermometer 固件的配置示例：

sensor:
  - platform: xiaomi_lywsd03mmc
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "LYWSD03MMC Temperature"
    humidity:
      name: "LYWSD03MMC Humidity"
    battery_level:
      name: "LYWSD03MMC Battery Level"

设置为 “BTHome v2” 广播的 PVVX MiThermometer 固件的配置示例：

sensor:
  - platform: bthome_mithermometer
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "BTHome Temperature"
    humidity:
      name: "BTHome Humidity"
    battery_level:
      name: "BTHome Battery Level"
    battery_voltage:
      name: "BTHome Battery Voltage"
    signal_strength:
      name: "BTHome Signal"

如果您在 PVVX 固件中启用了 “Encrypted beacon”，请指定 bindkey，其值为您在 Telink Flasher 中按下 “Get BindKey” 按钮时所看到的值（参见获取 Bindkey）。

NOTE

设置 bindkey 后，组件将不接受来自该 mac_address 的未加密 beacon。不匹配会在日志中打印。

设置为 “pvvx” 广播的 PVVX MiThermometer 固件的配置示例（已弃用）：

sensor:
  - platform: pvvx_mithermometer
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "PVVX Temperature"
    humidity:
      name: "PVVX Humidity"
    battery_level:
      name: "PVVX Battery Level"
    battery_voltage:
      name: "PVVX Battery Voltage"
    signal_strength:
      name: "PVVX Signal"

设置为 “Custom” 广播的 ATC MiThermometer 固件的配置示例（已弃用）：

sensor:
  - platform: atc_mithermometer
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "ATC Temperature"
    humidity:
      name: "ATC Humidity"
    battery_level:
      name: "ATC Battery Level"
    battery_voltage:
      name: "ATC Battery Voltage"
    signal_strength:
      name: "ATC Signal"

XMWSDJ04MMC

湿度计温度计，方形小机身，电子墨水显示屏，加密，广播温度、湿度和电池状态。需要 bindkey 才能解密接收到的数据（参见获取 Bindkey）。

配置示例：

sensor:
  - platform: xiaomi_xmwsdj04mmc
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "XMWSDJ04MMC Temperature"
    humidity:
      name: "XMWSDJ04MMC Humidity"
    battery_level:
      name: "XMWSDJ04MMC Battery Level"

MHO-C303

带闹钟的湿度计温度计，矩形机身，电子墨水显示屏，广播温度、湿度和电池状态。未加密。

类似于 LYWSD02，此外还有时钟功能（闹钟、番茄钟定时器）。使用两节 AAA 电池供电。

配置示例：

sensor:
  - platform: xiaomi_mhoc303
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "MHO-C303 Climate Temperature"
    humidity:
      name: "MHO-C303 Climate Humidity"
    battery_level:
      name: "MHO-C303 Climate Battery Level"

MHO-C401

湿度计温度计，方形机身，电子墨水显示屏，加密，广播温度、湿度和电池状态。需要 bindkey 才能解密接收到的数据（参见获取 Bindkey）。

（MHO-C201 没有 BT）

与 LYWSD03MMC 类似，该设备也有自定义固件可用，因此操作该传感器有以下几种方式：

1. Xiaomi 原厂固件（需要 bindkey 才能解密接收到的数据，参见获取 Bindkey）
2. 刷有 PVVX MiThermometer 自定义固件的设备

• “Mi Like” 广播（需要虚拟 bindkey）
• “pvvx” 自定义广播（不需要 bindkey，仅限 PVVX 固件）

Xiaomi 原厂固件的配置示例：

sensor:
  - platform: xiaomi_mhoc401
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "MHOC401 Temperature"
    humidity:
      name: "MHOC401 Humidity"
    battery_level:
      name: "MHOC401 Battery Level"

设置为 “Custom” 广播的 PVVX MiThermometer 固件的配置示例：

sensor:
  - platform: pvvx_mithermometer
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "PVVX Temperature"
    humidity:
      name: "PVVX Humidity"
    battery_level:
      name: "PVVX Battery-Level"
    battery_voltage:
      name: "PVVX Battery-Voltage"

CGD1

Cleargrass（青萍）闹钟，段式 LCD，加密，广播温度、湿度和电池状态。需要 bindkey 才能解密接收到的数据（参见获取 Bindkey）。

配置示例：

sensor:
  - platform: xiaomi_cgd1
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "CGD1 Temperature"
    humidity:
      name: "CGD1 Humidity"
    battery_level:
      name: "CGD1 Battery Level"

CGDK2

Cleargrass（青萍）温湿度 Lite，圆形机身，段式 LCD，加密，广播温度、湿度和电池状态。需要 bindkey 才能解密接收到的数据（参见获取 Bindkey）。 测量数据每 10-15 分钟广播一次。

配置示例：

sensor:
  - platform: xiaomi_cgdk2
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "CGDK2 Temperature"
    humidity:
      name: "CGDK2 Humidity"
    battery_level:
      name: "CGDK2 Battery Level"

JQJCY01YM

Xiaomi（Honeywell）甲醛传感器，OLED 显示屏，广播温度、湿度、甲醛浓度（mg/m³）和电池状态。

配置示例：

sensor:
  - platform: xiaomi_jqjcy01ym
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "JQJCY01YM Temperature"
    humidity:
      name: "JQJCY01YM Humidity"
    formaldehyde:
      name: "JQJCY01YM Formaldehyde"
    battery_level:
      name: "JQJCY01YM Battery Level"

WX08ZM

驱蚊器智能版，广播蚊香片余量、开关状态和电池电量，实现为混合传感器，配置中同时需要 sensor 和 binary_sensor。

配置示例：

sensor:

binary_sensor:
  - platform: xiaomi_wx08zm
    mac_address: "XX:XX:XX:XX:XX:XX"
    tablet:
      name: "WX08ZM Mosquito Tablet"
    battery_level:
      name: "WX08ZM Battery Level"

MUE4094RT

Xiaomi Philips BLE 夜灯，广播运动检测（检测到/清除、开/关），默认超时为 5s，实现为混合传感器，配置中同时需要 sensor 和 binary_sensor。

配置示例：

sensor:

binary_sensor:
  - platform: xiaomi_mue4094rt
    name: "MUE4094RT Night Light"
    mac_address: "XX:XX:XX:XX:XX:XX"
    timeout: "5s"

MJYD02YL-A

Xiaomi Yeelight 夜灯，以 BLE 形式取代 MJYD02YL，广播灯光开关状态、运动检测、上次运动事件后的空闲时间及电池状态。需要 bindkey 才能解密接收到的数据（参见获取 Bindkey）。实现为混合传感器，配置中同时需要 sensor 和 binary_sensor。

配置示例：

sensor:

binary_sensor:
  - platform: xiaomi_mjyd02yla
    name: "MJYD02YL-A Night Light"
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    idle_time:
      name: "MJYD02YL-A Idle Time"
    light:
      name: "MJYD02YL-A Light Status"
    battery_level:
      name: "MJYD02YL-A Battery Level"
    illuminance:
      name: "MJYD02YL-A Illuminance"

CGPR1

青萍运动与环境光传感器。广播运动检测、上次运动事件后的空闲时间、lux 值和电池状态。需要 bindkey 才能解密接收到的数据（参见获取 Bindkey）。

配置示例：

binary_sensor:
  - platform: xiaomi_cgpr1
    name: "CGPR1 Motion detector"
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    idle_time:
      name: "CGPR1 Idle Time"
    battery_level:
      name: "CGPR1 Battery Level"
    illuminance:
      name: "CGPR1 Illuminance"

RTCGQ02LM - Mi Motion Sensor 2

运动与环境光传感器。广播运动检测、亮/暗和电池状态。还有一个按钮，按下时广播。 需要 bindkey 才能解密接收到的数据（参见获取 Bindkey）。

配置示例：

xiaomi_rtcgq02lm:
  - id: motion_one
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: 00112233445566778899aabbccddeeff

binary_sensor:
  - platform: xiaomi_rtcgq02lm
    id: motion_one
    motion:
      name: "Mi Motion"
    light:
      name: "Mi Motion Sensor Light"
    button:
      name: "Mi Motion Sensor Button"

sensor:
  - platform: xiaomi_rtcgq02lm
    id: motion_one
    battery_level:
      name: "Mi Motion Sensor Battery Level"

设置设备

需要：

• mac_address（MAC 地址）：设备的 MAC 地址。
• bindkey（string，32 个字符，不区分大小写）：用于解密加密传感器类型的 BLE 广播的密钥

Sensor 的所有选项均支持以下项：

• temperature
• humidity
• moisture
• illuminance
• conductivity
• tablet
• formaldehyde
• battery_level

获取 MAC 地址

要查找 MAC 地址以便 ESPHome 识别设备，您可以创建一个不含任何传感器条目的简单配置：

esp32_ble_tracker:

xiaomi_ble:

上传后，ESP32 将立即尝试扫描 BLE 设备。当它检测到新传感器时，会自动解析 BLE 消息并打印如下消息：

Found device XX:XX:XX:XX:XX:XX RSSI=-78
  Address Type: PUBLIC
  Name: 'LYWSD03MMC'

有时第一次收到 BLE 广播需要一段时间。一旦找到设备，将地址 XX:XX:XX:XX:XX:XX 复制到一个新的 platform 条目中，如示例配置所示。

获取 Bindkey

要设置加密设备，您需要获取 bindkey。xiaomi_ble 传感器组件无法自动生成 bindkey，因此需要其他方法。

WARNING

如果您保留原厂固件，新的 bind key 将在 ESPHome 中生效，但一旦设备被 TeLink flasher 应用程序激活，米家 App 将不再识别该传感器。 若要再次在 Xiaomi Mi Home App 中使用该传感器，需要在米家 App 中移除该设备，然后重新添加。

LYWSD03MMC、CGD1 以及大多数其他加密设备

• 最简单的方法是使用 PVVX 的 Telink flasher 方法。配套的 视频 展示了如何无线刷写 LYWSD03MMC，或如何获取原厂固件的 bind key （观看至约 13:10）。自定义固件允许您更改设备的几个设置，包括笑脸和广播间隔。 按照网站上的说明使用 Telink Flasher——使用带蓝牙的安卓手机效果最佳。请注意，默认情况下没有设置加密， 因此这种情况下不需要 bind_key，您可以直接将传感器添加到 ESPHome 配置中，如上所述。但是，如果您确实启用了 “Encrypted beacon” 复选框，请滚动到页面底部，按下 “Get BindKey” 按钮即可查看密钥。

• 另一个选项是使用原始的米家 App 添加一次传感器。在添加设备时，会生成一个新密钥并上传到小米云和设备本身。一旦生成，该密钥在设备从小米 App 中移除并重新添加之前不会再次更改。

  • 要从云端检索 bindkey，您可以使用 Cloud Tokens Extractor，由一位 Home Assistant 用户编写。 如果您不想使用可执行文件，请阅读Home Assistant 文档。

  • 另一个选项是使用 SSL 数据包嗅探器。它可以设置在安卓手机或 iPhone 上。在本教程中可在 GitHub 上找到使用 Android 获取密钥的说明。 使用 iPhone 获取密钥的说明可在 custom-components/sensor.mitemp_bt 的 GitHub 上找到。一旦记录了米家 App 与小米服务器之间的流量，bind key 将以明文形式显示：

    packet: POST /app/device/bltbind
    
    "data" = "{"did":"blt.3.129q4nasgeg00","token":"20c665a7ff82a5bfb5eefc36","props":[{"type":"prop","key":"bind_key","value":"cfc7cc892f4e32f7a733086cf3443cb0"},   {"type":"prop","key":"smac","value":XX:XX:XX:XX:XX:XX}]}"

    bind_key 就是上述输出中 32 位的 “value” 项，需要插入配置文件中。

• 如果 LYWSD03MMC 或 MHO-C401 传感器使用 Xiaomi 原厂固件运行，您也可以使用 ATC 的 TeLink flasher 应用程序 轻松生成新的 bind key 并将密钥上传到设备，无需刷写新固件（见图）。为此，您需要使用受支持的浏览器加载 flasher 网页，并按下 “Connect” 连接设备。建立连接后，按下 “Do Activation” 按钮，新密钥将显示在 “Mi Bind Key” 字段中。密钥可以直接复制到传感器 YAML 配置中。

Telink flasher 应用程序。

• 对于 CGDK2，还可以使用受支持的浏览器加载 Zaluthar 的应用程序 并按下 “Connect” 连接设备。建立连接后，按下 “Do Activation” 按钮，新密钥将显示在 “Mi Bind Key” 字段中。密钥可以直接复制到传感器 YAML 配置中。

改善接收性能

使用带以太网网络连接的板卡，将 ESP32 的无线电模块从 Wi-Fi 流量中卸载，这可以在蓝牙方面获得性能提升。

避免将 ESP 节点放置在机架内、靠近路由器/交换机或其他网络设备，因为电磁干扰会削弱蓝牙信号接收。为获得最佳效果，请将其尽可能远离任何其他此类设备，至少保持 3 米的距离。

安全注意事项

您至少应使用自定义配对 PIN 码保护您的传感器。选择一种使用 bindkey 的方法，以通过空中实现加密通信，并防止接受伪造的消息。

参见

• ESP32 蓝牙低功耗追踪器中心

• 传感器组件

• PVVX MiThermometer 显示屏

• 以太网组件

• 蓝牙代理

• Home Assistant 的被动 BLE 监视器集成（ble_monitor 自定义组件） 作者为 @Magalex2x14 和 @Ernst79

• Xiaomi 温度计 LYWSD03MMC 的自定义固件（PVVX）

• TeLink flasher 应用程序（PVVX）

• Xiaomi 温度计 LYWSD03MMC 的自定义固件（ATC）

• TeLink flasher 应用程序（ATC）

• 为 CGDK2 修改的 TeLink flasher 应用程序

• Xiaomi LYWSD03MMC 被动传感器读取，作者为 @ahpohl

• Cloud Tokens Extractor

• API 参考：xiaomi_ble.h