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

RuuviTag 开源 BLE 传感器

ruuvitag 传感器平台允许您使用 Esp32 Ble Tracker 跟踪 RuuviTag 蓝牙低功耗设备的输出。每次传感器发送 BLE 广播时，该组件都会跟踪 RuuviTag 设备的温度、湿度、加速度和电池电压（基于 RAWv1 协议）。同样支持 RAWv2 协议，此外还会跟踪发射功率、运动计数和测量序列号。

通过 BLE 连接的 RuuviTagSensor。
# 示例配置条目
esp32_ble_tracker:


sensor:
- platform: ruuvitag
  mac_address: XX:XX:XX:XX:XX:XX
  humidity:
    name: "RuuviTag Humidity"
  temperature:
    name: "RuuviTag Temperature"
  pressure:
    name: "RuuviTag Pressure"
  acceleration:
    name: "RuuviTag Acceleration"
  acceleration_x:
    name: "RuuviTag Acceleration X"
  acceleration_y:
    name: "RuuviTag Acceleration Y"
  acceleration_z:
    name: "RuuviTag Acceleration Z"
  battery_voltage:
    name: "RuuviTag Battery Voltage"
  tx_power:
    name: "RuuviTag TX Power"
  movement_counter:
    name: "RuuviTag Movement Counter"
  measurement_sequence_number:
    name: "RuuviTag Measurement Sequence Number"

配置变量

Section titled “配置变量”

  • mac_address (必选, MAC Address): RuuviTag 设备的 MAC 地址。

  • humidity (可选): 湿度传感器的信息

  • temperature (可选): 温度传感器的信息。

  • pressure (可选): 压力传感器的信息。

  • acceleration (可选): 加速度传感器的信息。

  • acceleration_x (可选): 加速度 x 传感器的信息。

  • acceleration_y (可选): 加速度 y 传感器的信息。

  • acceleration_z (可选): 加速度 z 传感器的信息。

  • battery_voltage (可选): 电池电压传感器的信息。

  • tx_power (可选): 发射功率传感器的信息

    • Sensor 的所有选项。
    • 仅在使用 RAWv2 协议时可用。

  • movement_counter (可选): 运动计数传感器的信息

    • Sensor 的所有选项。
    • 仅在使用 RAWv2 协议时可用。

  • measurement_sequence_number (可选): 测量序列号传感器的信息

    • Sensor 的所有选项。
    • 仅在使用 RAWv2 协议时可用。

设置设备

Section titled “设置设备”

要设置 RuuviTag 设备，首先需要找到它们的 MAC 地址，以便 ESPHome 可以识别它们。因此，首先创建一个不包含任何 ruuvitag 条目但启用了 ruuvi_ble 的简单配置，如下所示：

esp32_ble_tracker:


ruuvi_ble:

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

Got ruuvi RuuviTag (XX:XX:XX:XX:XX:XX): Humidity: 67.5%, Temperature: 22.97°C,
Pressure: 977.09hPa, Acceleration X: 0.005G, Acceleration Y: 0.017G, Acceleration Z: 1.066G,
Battery Voltage: 3.223V

然后将地址（XX:XX:XX:XX:XX:XX）复制到新的 sensor.ruuvitag 平台条目中，就像上面配置示例中那样。

NOTE

ESPHome 的 Ruuvi BLE 组件被动监听 RuuviTag 设备自行发送的数据包。 因此，ESPHome 不会影响设备的电池寿命。

参见

Section titled “参见”