I am going to see about updating codersaurs documentation and will post it here if i can get the minor stuff updated to be valid.
HubitatData Visualization using InfluxDB and Grafana
POSTED ON 2016-04-11 BY CODERSAUR updated Doc for Hubitat by mavrrick
Original Doc at codersaur.com
Overview
There are three key components to the solution:
- Hubitat Hub: Hubitats home automation controller. Since youāre reading this article Iāll to assume youāre already reasonably familiar with this platform. To get data out of Hubitat weāre going to use a custom SmartApp, more on that later.
- InfluxDB: A free open-source distributed database for managing IoT time-series data. Itās super-easy to install and natively supports compression, retention policies, and down-sampling.
- Grafana: A free open-source platform for visualizing time series data. Grafana makes it easy to create dashboards and charts. As well as InfluxDB, it works with several other data sources such as Graphite, Elasticsearch, and OpenTSDB.
Installation
For this solution Iāmusing Ubuntu Server 22.04 running in a virtual machine,however you could substitute this with a Raspberry Pi running Raspbian, or any other Linux distribution of your choice. If youāre not using Ubuntu or another Debian-based distribution you will need to use different commands to those shown below, follow the links to the official installation instructions for more information.
Installing InfluxDB
At the time of writing, the latest version of InfluxDB is v1.8.10, and the official installation instructions can be found here. If you use a different platform please confirm with that link the correct install directions for your platform.
Submit the below commands.
wget https://dl.influxdata.com/influxdb/releases/influxdb_1.8.10_amd64.deb
sudo dpkg -i influxdb_1.8.10_amd64.deb
Start the InfluxDB service:
~$ sudo service influxdb start
To verify InfluxDB is up and running we can run the influx CLI:
~$ influx
Connected to http://localhost:8086 version 1.8.10
InfluxDB shell 1.8.10
We can also browse InfluxDBās web interface on port 8083, *http://localhost:8083/*:
InfluxDB Web UI
Next, we need to create a database for Hubitat and a user account for Grafana. From the InfluxDB CLI, issue the following commands (obviously, replace password with something a little more secure):
CREATE DATABASE "Hubitat"
CREATE USER "grafana" WITH PASSWORD 'password'
Installing Grafana
At the time of writing, the latest version of Grafana is v9.0.0, and the official installation instructions can be found here.
To install the latest OSS release:
sudo apt-get install -y apt-transport-https
sudo apt-get install -y software-properties-common wget
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
Add this repository for stable releases:
echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list
After you add the repository:
sudo apt-get update
sudo apt-get install grafana
Start the Grafana service:
Start the Grafana server with systemd
To start the service and verify that the service has started:
sudo systemctl daemon-reload
sudo systemctl start grafana-server
sudo systemctl status grafana-server
Configure the Grafana server to start at boot:
sudo systemctl enable grafana-server.service
We can verify Grafana is running by browsing to the web interface on port 3000, *http://localhost:3000/*:
Grafana: Log In Page
At this point, Irecommend Logging into Grafana and changing the default admin password.
So far, so good. We now have InfluxDb and Grafana running, but before we can start constructing some charts and dashboards, we need some dataā¦
Installing the InfluxDB Logger SmartApp
To get data from Hubitat into our InfluxDB database, Iāve written a custom Hubitat SmartApp. Once installed, we can use this SmartApp to subscribe to the devices we want to monitor and it will send data to InfluxDB using its HTTP API. The SmartApp uses the hubAction command,which means it will support the InfluxDB server being on the same privateLAN as our Hubitat Hub, so there is no need to make the logging server accessible from the internet.
Follow the standard procedures to install the InfluxDB Logger SmartApp in the Hubitat Hub. The raw link to the latest code is below
InfluxDB logger on Hubitat Community Github
InfluxDB LoggerSettings
Once weāve added the InfluxDB Logger to the user app section of Hubitat, we must configure it. Enter the host name and port of the InfluxDB server(note that the InfluxDB HTTP API uses port 8086 by default, whereas the web interface uses 8083). Additionally we must specify the database name we created above.
The InfluxDBLogger also allows us to configure a Soft-polling interval. If enabled, this will cause the attributes of all devices to be sent to the InfluxDB database on a periodic basis. I implemented this feature because Hubitat will only generate an event when a device attribute actually changes in value.For attributes that donāt change very often, this can lead to big gaps in the data series, which in turn can lead to gaps in our Grafana charts. For now,I recommend setting the soft-polling interval to 5-10 minutes.
Finally, we must configure the devices we want to monitor. When finished, press Done.
Verifying Data Logging
The InfluxDB Logger SmartApp should now be sending events to InfluxDB via HTTP, we can verify this by checking the Hubitat logs and by running a query from the InfluxDB CLI.
From the Hubitat ,navigate to the Logging tab. After a few minutes, we should see some info events from the SmartApp, corresponding to changes of device attributes:
Hubitat: Logging
From the InfluxDB CLI we can query data in the database directly using the InfluxQL querylanguage. Remember to set the database first using the
use
command first.For example, to query switch measurements:
use Hubitat
SELECT * FROM switch
name: switch
time deviceId deviceName groupName unit value valueBinary
1460400903900824163 xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxxEn-suite Towel Rail Bedroom switch off 0
1460401204143438152 xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx AVPower Lounge switch off 0
1460401204169860754xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx Computer Power Office switch on 1
We can see above that the InfluxDB Logger maps device attribute names (e.g. switch or power)to a measurement name in InfluxDB. Additionally, deviceId, deviceName and groupName (i.e.room name) are added as tags. Device attribute values are mapped to the value field. In cases where an attribute value can also logically be represented as a binary value, thenan additional field called valueBinary is also included. E.g.for a switch; off = 0 and on = 1. We will see later how these additional tags and fields are useful when building charts and dashboards in Grafana.
If you want to learn more about querying data using the InfluxQL query language,you can find a guide here.
Now we have data in our database we can begin building charts using Grafana. Happy days!
Configuring Grafana
To configure datasources, dashboards, and charts we must use the Grafana web interface on port 3000, http://localhost:3000/.
We will first need to login using the admin password that we configured earlier. Once logged in as admin you may wish to create additional users from the Grafana admin menu.
Data Sources
Next we need to define a data source that corresponds to our InfluxDB database. Click on the gear in the lower left corner of the browser and select Data Sources. Now click on the Add Data source button in the window that came up.
Grafana: Add Data Source
Select InfluxDB from the presented screen and you should be put on the page to configure the Data Source. Provide a valid name for the data source like Hubitat, Update the URL to point to our InfluxDB instance on http://localhost:8086. Scroll down to the bottom of the setup screen and set the database name to "Hubitat" and the username and password to what we set earlier. Save and test the connection.
We can now begin using the Dashboards sectionā¦
Dashboards
Grafana supports the creation of multiple dashboards. Each dashboard can contain any number of graphs, tables, stats, and text panels.
Create a new dashboard from the top menu, give it a name, then click +Add Row to add a row to the dashboard.
Letās start by adding a graph to our dashboard. From the row menu select Add Panel and then Graph:
Grafana: Add Graph Panel
Graph Panel
We are first presented with the Metrics tab of our new graph. In the bottom-right corner, ensure the data source for the graph is set to Hubitat.We should find a drop-down menu of available measurements when we click on Select measurement. In this example Iāve selected temperature:
Grafana: Graph Query
If we have multiple devices with temperature attributes, we can add the tag deviceName into the GROUP BY clause, which will create an individual data series for each device. Additionally, Iāve specified the deviceName tag in the ALIAS BY clause above so that each series name matches the device name. We end up with a chart looking something like this (obviously we have to wait a while for multiple data points to be logged):
Grafana: Basic Temperature Graph
Grafana supports a wealth of graph settings, most of which should be self-explanatory. We can customise the graphās title, axes, legend, generate aggregate values, and overlay data series from multiple devices and measurement types. For the time being Iāll leave you to experiment.
In future posts Iāll share some of the more-advanced charts and dashboards Iāve created, including use of the templating and annotation features. Weāll also look at configuring data retention policies and down-sampling data in InfluxDB.