search

balda / ruuvitag-discovery

Web interface to Discover RuuviTag Environmental Sensors and save measures to MQTT, InfluxDB, Graphite and Home Assistant
MIT License
31 stars 5 forks source link

readme

RuuviTag Discovery

Discover RuuviTag Environmental Sensors using a web interface (all measures in one page, in real time).

Save measures to multiple targets:

Other Features:

discover page

Install

From source

Install Node.js

You can download pre-built installer for your platform or see instructions for your favorite package manager (developpers should install Node.js with a Node version manager).

Get the projet code

Download and unzip the code or use git (prefered method)

git clone https://github.com/balda/ruuvitag-discovery
Install / upgrade dependencies
cd ruuvitag-discovery/
npm install
Run

To start the application, run the command

npm start

In a browser, go to http://localhost:8099/ url to see the web interface.

By default, server port is 8099. It can be changed using SERVER_PORT environment variable

SERVER_PORT=8100 npm start

Default HCI device used can be changed, using NOBLE_HCI_DEVICE_ID environment variable (leave it empty to use the default). See noble documentation for more information.

NOBLE_HCI_DEVICE_ID=1 npm start
Stop

To stop the application, use ^c.

Configuration file

Configuration is saved in /data/ directory (created on first run).

Install Home Assistant add-on

See Home Assistant Documentation

Configuration

All the configuration is done in the web interface and saved in /data/config.json file.

Global configuration

History

Default configuration retain 100 measures max per RuuviTag (history config). History is used to calculate frequency (number of measures read per minute) and period (time in seconds between measures read). samples additional measure count measures in tag history.

Sampling

Default sampling is every 10 seconds (interval config). Setting interval = O disable sampling (last measures are always sent).

If sampling is enable, median measures are sent to non live targets (see targets below)

Battery level

Battery level is between 1% and 100%, for respectivly 2500mV (min config) and 3000mV (max config).

_See battery FAQ in RuuviTag firmware repository._

Server logs

Log options can be enable or disable in real time.

Measures

Available measures

RuuviTag environmental sensors

See Ruuvi sensor protocols to view available measures. Data format 3 and 5 are supported. Data format 1, 2 and 4 are not tested.

Additional measures

Calculated using default measures

Custom measures

New measure can be created, using a math expression like (temperature * 9/5) + 32 for Fahrenheit.

Each custom measure has a label, a field name (must be uniq in all the measures), an optional unit, an accuracy (number of decimals displayed and sent to targets) and a math expression.

Custom measures can be used to:

There are some examples on the "New Custom Measure" panel.

See mathjs.org for more documentation about math expressions syntax.

Targets

Measures can be sent in live to a target by setting interval = 0. Otherwise, every interval seconds, median measures are sent (or last measures if sampling is disabled).

All targets have a name and can be enabled or disabled.

Some targets have a measurement option:

Target have also specific configuration:

MQTT

For now, only mqtt: protocol is supported.

MQTT target use measurement option:

{
    "id": "RuuviTag.id",
    "name": "RuuviTag.name",
    "field": "RuuviTag.field",
    "measures": [
        {
            "label": "measure.label",
            "field": "measure.field",
            "value": "measure.value"
        },
        {...}
    ]
}

InfluxDB

For now, only http: protocol is supported.

InfluxDB target use measurement option:

Graphite

For now, only http: protocol is supported.

Measures are written in [prefix].[ruuvitag.field].[measure.field] series.

Home Assistant (MQTT discovery)

For now, only mqtt: protocol is supported.

MQTT discovery must be enable on Home Assistant and component discovery_prefix must match with target topic config.

Enabled RuuviTags will be present in the Devices list and their measures in Entities (one sensor per measure). All measures will be listed in the MQTT Integration. So RuuviTags can be placed in an Area.

Device name is the one defined in the web interface.

Entity is defined with some attributes:

Remove entity (sensor measure)

Entities are automatically removed. They can always appear in Home Assistant. After a reboot (or maybe after they disappearing from history), you can "remove" them using Home Assistant interface.

Remove device

Home Assistant does not provide an easy way to remove devices. For now, there's only two "solutions":

Home Assistant (API)

For now, Home Assistant (API) target only works as an Home Assistant addon (no remote: API Token is auto discovered by the addon).

The measure label will be used as the Entity name (with some attributes: RuuviTag name, RuuviTag ID, Measure and Unit).

Entity ID is built with the fields of RuuviTags and measures: sensor.[ruuvitag.field]_[measure.field].

API integration is limited compared to MQTT discovery integration:

Configuration file format

{
    "sampling": {
        "history": "100",
        "interval": "10000"
    },
    "battery": {
        "min": "2500",
        "max": "3000"
    },
    "ruuvitags": {},
    "targets": [
        {
            "type": "[mqtt|influxdb|graphite]",
            "id": "[ID]",
            "enable": "[1|0]",
            "name": "[TARGET_NAME]",
            "interval": "[broadcast interval (seconds)]",
            "tags": {
                "[TAGID]": {
                    "id": "[TAGID]",
                    "measures": {
                        "[MEASURE]": {
                            "label": "[MEASURE_LABEL]",
                            "field": "[MEASURE_FIELD]"
                        }
                    },
                    "name": "[RUUVITAG_NAME]",
                    "field": "[RUUVITAG_FIELD]"
                },
                "...": {
                    ...
                }
            }
        },
        ...
    ],
    "columns": {
        "name": true,
        "dataFormat": true,
        "rssi": true,
        "temperature": true,
        "humidity": true,
        "pressure": true,
        "battery": true,
        "battery_level": true,
        "txPower": true,
        "movementCounter": true,
        "measurementSequenceNumber": true,
        "samples": true,
        "frequency": true,
        "period": true,
        "ts": true
    }
}