RuuviTag Open Source BLE Sensor

The ruuvitag sensor platform lets you track the output of RuuviTag Bluetooth Low Energy devices using the ESP32 Bluetooth Low Energy Tracker Hub. This component will track the temperature, humidity, acceleration and battery voltage of a RuuviTag device with RAWv1 protocol every time the sensor sends out a BLE broadcast. RAWv2 protocol is supported too. Then tx power, movement count and measurement sequence number are also tracked.

../../_images/ruuvitag-full.jpg

RuuviTagSensor over BLE.

../../_images/ruuvitag-ui.jpg
# Example configuration entry
esp32_ble_tracker:

sensor:
- platform: ruuvitag
  mac_address: FF:56:D3:2F:7D:E8
  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"

Configuration variables:

  • mac_address (Required, MAC Address): The MAC address of the RuuviTag device.

  • humidity (Optional): The information for the humidity sensor

    • name (Required, string): The name for the humidity sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • temperature (Optional): The information for the temperature sensor.

    • name (Required, string): The name for the temperature sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • pressure (Optional): The information for the pressure sensor.

    • name (Required, string): The name for the pressure sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • acceleration (Optional): The information for the acceleration sensor.

    • name (Required, string): The name for the acceleration sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • acceleration_x (Optional): The information for the acceleration x sensor.

    • name (Required, string): The name for the acceleration x sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • acceleration_y (Optional): The information for the acceleration y sensor.

    • name (Required, string): The name for the acceleration y sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • acceleration_z (Optional): The information for the acceleration z sensor.

    • name (Required, string): The name for the acceleration z sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • battery_voltage (Optional): The information for the battery voltage sensor.

    • name (Required, string): The name for the battery voltage sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

  • tx_power (Optional): The information for the transmit power sensor

    • name (Required, string): The name for the transmit power sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

    • Only available if RAWv2 protocol is used.

  • movement_count (Optional): The information for the movement count sensor

    • name (Required, string): The name for the movement count sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

    • Only available if RAWv2 protocol is used.

  • measurement_sequence_number (Optional): The information for the measurment sequence number sensor

    • name (Required, string): The name for the measurment sequence number sensor.

    • id (Optional, ID): Set the ID of this sensor for use in lambdas.

    • All other options from Sensor.

    • Only available if RAWv2 protocol is used.

Setting Up Devices

To set up RuuviTag devices you first need to find their MAC Address so that ESPHome can identify them. So first, create a simple configuration without any ruuvitag entries like so:

esp32_ble_tracker:

After uploading the ESP32 will immediately try to scan for BLE devices. When it detects these sensors, it will automatically parse the BLE message print a message like this one:

Got ruuvi RuuviTag (FF:56:D3:2F:7D:E8): 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

Then just copy the address (FF:56:D3:2F:7D:E8) into a new sensor.ruuvitag platform entry like in the configuration example at the top.

Note

The ESPHome Ruuvi BLE integration listens passively to packets the RuuviTag device sends by itself. ESPHome therefore has no impact on the battery life of the device.