小米 Mijia BLE 传感器

xiaomi_ble 传感器平台让您可以使用 Esp32 Ble Tracker 跟踪小米蓝牙低功耗设备的输出。此组件将跟踪例如温度、湿度、水分、电导率、光照强度、甲醛、蚊香片和电池电量，每次传感器发送 BLE 广播时都会更新。与其他实现不同，xiaomi_ble 被动监听广播包，不与设备配对。因此 ESPHome 不会影响电池寿命。因此，如果您只使用此类传感器，可以安全地在 esp32_ble_tracker 配置中设置 scan_parameters.active: false，以避免用无用的扫描请求干扰您的射频环境。

NOTE

您也可以使用 ESPHome 的 蓝牙代理 组件将传感器数据转发到 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 温度"
    moisture:
      name: "Xiaomi HHCCJCY01 水分"
    illuminance:
      name: "Xiaomi HHCCJCY01 光照强度"
    conductivity:
      name: "Xiaomi HHCCJCY01 土壤电导率"
    battery_level:
      name: "Xiaomi HHCCJCY01 电池电量"

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 温度"
    moisture:
      name: "GCLS02 水分"
    conductivity:
      name: "GCLS02 土壤电导率"
    illuminance:
      name: "GCLS02 光照强度"

HHCCPOT002

花盆，花花草草，RoPot，广播水分和电导率

配置示例：

sensor:
  - platform: xiaomi_hhccpot002
    mac_address: "XX:XX:XX:XX:XX:XX"
    moisture:
      name: "HHCCPOT002 水分"
    conductivity:
      name: "HHCCPOT002 土壤电导率"

LYWSDCGQ

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

配置示例：

sensor:
  - platform: xiaomi_lywsdcgq
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "LYWSDCGQ 温度"
    humidity:
      name: "LYWSDCGQ 湿度"
    battery_level:
      name: "LYWSDCGQ 电池电量"

LYWSD02

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

• 电池电量，需要小米固件 1.1.2_0085

配置示例：

sensor:
  - platform: xiaomi_lywsd02
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "LYWSD02 温度"
    humidity:
      name: "LYWSD02 湿度"
    battery_level:
      name: "LYWSD02 电池电量"

LYWSD02MMC

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

配置示例：

sensor:
  - platform: xiaomi_lywsd02mmc
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "2529d8e0d23150a588675cc54ad48400"
    temperature:
      name: "LYWSD02MMC 温度"
    humidity:
      name: "LYWSD02MMC 湿度"
    battery_level:
      name: "LYWSD02MMC 电池电量"

CGG1

清平（Qingping）：温湿度计，圆形机身，电子墨水屏。

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

配置示例：

sensor:
  - platform: xiaomi_cgg1
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "CGG1 温度"
    humidity:
      name: "CGG1 湿度"
    battery_level:
      name: "CGG1 电池电量"
  - platform: xiaomi_cgg1
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "CGG1（新版）温度"
    humidity:
      name: "CGG1（新版）湿度"

LYWSD03MMC

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

此传感器有多种操作方式：

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

使用 PVVX 固件和 “BTHome v2” 广播时，支持使用 bindkey 加密，就像小米官方固件一样 （请参阅获取 Bindkey）。非加密通信仅在自定义固件中支持，但由于明显的安全原因，不建议使用。

NOTE

PVVX 固件从版本 6.0 开始弃用了除 “BTHome v2” 以外的任何其他广播格式。

小米官方固件或设置为 “Mi Like” 广播的 ATC MiThermometer 固件的配置示例：

sensor:
  - platform: xiaomi_lywsd03mmc
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "LYWSD03MMC 温度"
    humidity:
      name: "LYWSD03MMC 湿度"
    battery_level:
      name: "LYWSD03MMC 电池电量"

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

sensor:
  - platform: bthome_mithermometer
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "BTHome 温度"
    humidity:
      name: "BTHome 湿度"
    battery_level:
      name: "BTHome 电池电量"
    battery_voltage:
      name: "BTHome 电池电压"
    signal_strength:
      name: "BTHome 信号强度"

如果您在 PVVX 固件中启用”加密信标”，请使用您在 Telink Flasher 中按下 “Get BindKey” 按钮时看到的值指定 bindkey（请参阅获取 Bindkey）。

NOTE

一旦您设置了 bindkey，该组件将不再接受来自该 mac_address 的未加密信标。不匹配的情况将打印在日志中。

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

sensor:
  - platform: pvvx_mithermometer
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "PVVX 温度"
    humidity:
      name: "PVVX 湿度"
    battery_level:
      name: "PVVX 电池电量"
    battery_voltage:
      name: "PVVX 电池电压"
    signal_strength:
      name: "PVVX 信号强度"

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

sensor:
  - platform: atc_mithermometer
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "ATC 温度"
    humidity:
      name: "ATC 湿度"
    battery_level:
      name: "ATC 电池电量"
    battery_voltage:
      name: "ATC 电池电压"
    signal_strength:
      name: "ATC 信号强度"

XMWSDJ04MMC

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

配置示例：

sensor:
  - platform: xiaomi_xmwsdj04mmc
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "XMWSDJ04MMC 温度"
    humidity:
      name: "XMWSDJ04MMC 湿度"
    battery_level:
      name: "XMWSDJ04MMC 电池电量"

MHO-C303

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

类似于 LYWSD02，增加了时钟功能（闹钟、番茄计时器）。使用两节 AAA 电池供电。

配置示例：

sensor:
  - platform: xiaomi_mhoc303
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "MHO-C303 环境温度"
    humidity:
      name: "MHO-C303 环境湿度"
    battery_level:
      name: "MHO-C303 环境电池电量"

MHO-C401

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

（MHO-C201 没有 BT）

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

1. 小米官方固件（需要 bindkey 来解密接收到的数据，请参阅获取 Bindkey）
2. 刷入 PVVX MiThermometer 自定义固件的设备

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

小米官方固件的配置示例：

sensor:
  - platform: xiaomi_mhoc401
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "MHOC401 温度"
    humidity:
      name: "MHOC401 湿度"
    battery_level:
      name: "MHOC401 电池电量"

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

sensor:
  - platform: pvvx_mithermometer
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "PVVX 温度"
    humidity:
      name: "PVVX 湿度"
    battery_level:
      name: "PVVX 电池电量"
    battery_voltage:
      name: "PVVX 电池电压"

CGD1

清平（Qingping）闹钟，段码 LCD，加密，广播温度、湿度和电池状态。需要 bindkey 来解密接收到的数据（请参阅获取 Bindkey）。

配置示例：

sensor:
  - platform: xiaomi_cgd1
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "CGD1 温度"
    humidity:
      name: "CGD1 湿度"
    battery_level:
      name: "CGD1 电池电量"

CGDK2

清平（Qingping）温湿度计精简版，圆形机身，段码 LCD，加密，广播温度、湿度和电池状态。需要 bindkey 来解密接收到的数据（请参阅获取 Bindkey）。 测量值每 10-15 分钟广播一次。

配置示例：

sensor:
  - platform: xiaomi_cgdk2
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    temperature:
      name: "CGDK2 温度"
    humidity:
      name: "CGDK2 湿度"
    battery_level:
      name: "CGDK2 电池电量"

JQJCY01YM

小米（霍尼韦尔）甲醛传感器，OLED 显示屏，广播温度、湿度、甲醛浓度（mg/m³）和电池状态。

配置示例：

sensor:
  - platform: xiaomi_jqjcy01ym
    mac_address: "XX:XX:XX:XX:XX:XX"
    temperature:
      name: "JQJCY01YM 温度"
    humidity:
      name: "JQJCY01YM 湿度"
    formaldehyde:
      name: "JQJCY01YM 甲醛"
    battery_level:
      name: "JQJCY01YM 电池电量"

WX08ZM

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

配置示例：

sensor:

binary_sensor:
  - platform: xiaomi_wx08zm
    mac_address: "XX:XX:XX:XX:XX:XX"
    tablet:
      name: "WX08ZM 蚊香片"
    battery_level:
      name: "WX08ZM 电池电量"

MUE4094RT

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

配置示例：

sensor:

binary_sensor:
  - platform: xiaomi_mue4094rt
    name: "MUE4094RT 夜灯"
    mac_address: "XX:XX:XX:XX:XX:XX"
    timeout: "5s"

MJYD02YL-A

小米 Yeelight 夜灯，MJYD02YL 的 BLE 版本，广播灯光开关状态、运动检测、上次运动事件后的空闲时间和电池状态。需要 bindkey 来解密接收到的数据（请参阅获取 Bindkey）。实现为混合传感器，配置中需要同时有 sensor 和 binary_sensor。

配置示例：

sensor:

binary_sensor:
  - platform: xiaomi_mjyd02yla
    name: "MJYD02YL-A 夜灯"
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    idle_time:
      name: "MJYD02YL-A 空闲时间"
    light:
      name: "MJYD02YL-A 灯光状态"
    battery_level:
      name: "MJYD02YL-A 电池电量"
    illuminance:
      name: "MJYD02YL-A 光照强度"

CGPR1

清平运动与环境光传感器。广播运动检测、上次运动事件后的空闲时间、光照值和电池状态。需要 bindkey 来解密接收到的数据（请参阅获取 Bindkey）。

配置示例：

binary_sensor:
  - platform: xiaomi_cgpr1
    name: "CGPR1 运动检测器"
    mac_address: "XX:XX:XX:XX:XX:XX"
    bindkey: "00112233445566778899aabbccddeeff"
    idle_time:
      name: "CGPR1 空闲时间"
    battery_level:
      name: "CGPR1 电池电量"
    illuminance:
      name: "CGPR1 光照强度"

RTCGQ02LM - 米家运动传感器 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: "米家运动"
    light:
      name: "米家运动传感器灯光"
    button:
      name: "米家运动传感器按钮"

sensor:
  - platform: xiaomi_rtcgq02lm
    id: motion_one
    battery_level:
      name: "米家运动传感器电池电量"

设置设备

必填：

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

以下选项来自 传感器，支持：

• 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 复制到新的平台条目中，如示例配置所示。

获取 Bindkey

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

WARNING

如果您保留官方固件，新的绑定密钥将与 ESPHome 一起使用，但一旦设备被 TeLink flasher 应用程序激活，Mi Home 应用程序将不再识别该传感器。 要再次在小米 Mi Home 应用程序中使用该传感器，需要在 Mi Home 应用程序中删除然后重新添加该设备。

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

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

• 另一个选择是使用原始 Mi Home 应用程序添加一次传感器。在添加设备时，会生成一个新密钥并上传到小米云端 和设备本身。一旦生成，该密钥将不会再次更改，直到在小米应用程序中删除并重新添加设备。

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

  • 另一个选择是使用 SSL 数据包嗅探器。它可以在 Android 手机或 iPhone 上设置。有关如何使用 Android 获取密钥的说明可以在 GitHub 上的 此教程 中找到。 有关如何使用 iPhone 获取密钥的说明可以在 GitHub 上的 custom-components/sensor.mitemp_bt 中找到。一旦记录了 Mi Home 应用程序和小米服务器之间的流量，绑定密钥将以明文显示：

    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 传感器使用小米官方固件运行，您也可以使用 ATC 的 TeLink flasher 应用程序 轻松生成新的绑定密钥并将密钥上传到设备，而无需刷写新固件（见图）。为此，您使用 支持的浏览器 加载 flasher 网页 并通过按 “Connect” 连接设备。连接建立后， 您按下 “Do Activation” 按钮，新密钥将显示在 “Mi Bind Key” 字段中。该密钥可以直接复制到传感器 YAML 配置中。

Telink flasher 应用程序。

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

改善接收性能

使用具有以太网连接到网络的开发板，以减轻 ESP32 无线模块的 WiFi 流量负担，这可以提高蓝牙方面的性能。

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

安全考虑

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

另见

• ESP32 蓝牙低功耗跟踪器集线器

• 传感器组件

• PVVX MiThermometer 显示

• 以太网组件

• 蓝牙代理

• Home Assistant 的被动 BLE 监控集成（ble_monitor 自定义组件） 由 @Magalex2x14 和 @Ernst79 提供

• 小米温度计 LYWSD03MMC 的自定义固件 (PVVX)

• TeLink flasher 应用程序 (PVVX)

• 小米温度计 LYWSD03MMC 的自定义固件 (ATC)

• TeLink flasher 应用程序 (ATC)

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

• 小米 LYWSD03MMC 被动传感器读取 由 @ahpohl 提供

• Cloud Tokens Extractor

• API Reference: xiaomi_ble.h