Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

added docs for ruuvitag (#383) 

* added docs for ruuvitag

* updated for RAWv2 protocol

* typo

* punctuation

Co-Authored-By: Otto Winter <otto@otto-winter.com>

* added acceleration

* typo

Co-Authored-By: Otto Winter <otto@otto-winter.com>
This commit is contained in:
Alexander Leisentritt 2019-11-07 22:10:13 +01:00 committed by Otto Winter
parent e05e0a5865
commit 5a83a0dcef
5 changed files with 188 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
components/sensor/images/ruuvitag-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
components/sensor/images/ruuvitag-ui.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

187
components/sensor/ruuvitag.rst Normal file
View File

@ -0,0 +1,187 @@
RuuviTag Open Source BLE Sensor
===============================
.. seo::
:description: Instructions for setting up RuuviTag bluetooth-based sensors in ESPHome.
:image: ruuvitag.jpg
:keywords: Ruuvi, RuuviTag, BLE, Bluetooth
The ``ruuvitag`` sensor platform lets you track the output of RuuviTag
Bluetooth Low Energy devices using the :doc:`/components/esp32_ble_tracker`.
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.
.. figure:: images/ruuvitag-full.jpg
:align: center
:width: 80.0%
RuuviTagSensor over BLE.
.. figure:: images/ruuvitag-ui.jpg
:align: center
:width: 80.0%
.. code-block:: yaml
# 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*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **temperature** (*Optional*): The information for the temperature sensor.
- **name** (**Required**, string): The name for the temperature sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **pressure** (*Optional*): The information for the pressure sensor.
- **name** (**Required**, string): The name for the pressure sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **acceleration** (*Optional*): The information for the acceleration
sensor.
- **name** (**Required**, string): The name for the acceleration sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **acceleration_x** (*Optional*): The information for the acceleration x
sensor.
- **name** (**Required**, string): The name for the acceleration x sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **acceleration_y** (*Optional*): The information for the acceleration y
sensor.
- **name** (**Required**, string): The name for the acceleration y sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **acceleration_z** (*Optional*): The information for the acceleration z
sensor.
- **name** (**Required**, string): The name for the acceleration z sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **battery_voltage** (*Optional*): The information for the battery voltage
sensor.
- **name** (**Required**, string): The name for the battery voltage sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **tx_power** (*Optional*): The information for the transmit power
sensor
- **name** (**Required**, string): The name for the transmit power sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-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*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-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*, :ref:`config-id`): Set the ID of this sensor for use
in lambdas.
- All other options from :ref:`Sensor <config-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:
.. code-block:: yaml
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:
.. code::
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.
See Also
--------
- :doc:`/components/esp32_ble_tracker`
- :doc:`/components/sensor/index`
- :apiref:`ruuvitag/ruuvitag.h`
- `Ruuvi <https://ruuvi.com>`__
- :ghedit:`Edit`

BIN
images/ruuvitag.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.4 KiB

1
index.rst
View File

@ -136,6 +136,7 @@ Sensor Components
PZEM DC, components/sensor/pzemdc, pzemdc.svg
Resistance, components/sensor/resistance, omega.svg
Rotary Encoder, components/sensor/rotary_encoder, rotary_encoder.jpg
RuuviTag, components/sensor/ruuvitag, ruuvitag.jpg
SenseAir, components/sensor/senseair, senseair_s8.jpg
SDS011 Sensor, components/sensor/sds011, sds011.jpg
SCD30, components/sensor/scd30, scd30.jpg