As some of you are aware, the OAuth2 using just OH Rules and myopenhab.org came out of experiments trying to get integration between Dexcom and OH. Dexcom is a Continuous Glucose Monitor (CGM) used by diabetics, mostly Type 1/insulin dependent diabetics. For these users knowing their current blood sugar levels can be a matter of life and death. So having some sort of integration with one’s home automation can be useful where one can flash a light, send a message to an audio sync, or something like that in response to alarms.
This tutorial covers at a high level how to install and integrate a local instance of Nightscout, an open source alternative to Dexcom’s Clarity, with openHAB.
Nightscout
Nightscout is as much a community as it is a FOSS system. But the documentation and support is scattered and not always complete or easy to follow. The default set of instructions assumes you will be installing the Nightscout server and MongoDB database into the cloud. However, lots of folks like to run stuff like this locally. The following is what I did to set it up.
Out of scope of this tutorial is setting up and configuring the devices and apps that will publish the CGM readings into NightScout. We use xDrip+ on a new Google Pixel 3XL with a Dexcom G5. The G6 is on order. In both of these cases the CGM sensor can talk directly with the phone and the xDrip+ app will publish the readings to NightScout. Many other CGMs and apps are supported, including an app for iPhones and support for bridging from the sensor’s native source like Dexcom Clarity/Dexcom Share and NightScout.
NightScout itself consists of two main parts, the Mongo database and the Node.js based web app server. If one wants to access NightScout while not at home an nginx reverse proxy, ssh tunnel, or VPN connection from the phone reporting to NightScout and your LAN is required. This too is beyond the scope of this tutorial. If you don’t know how to do this securely I recommend using the default cloud based installation instructions. If you do so skip to the NightScout openHAB integration section.
The machine used to host this is an Ubuntu 18.04 Server running on a VM.
MongoDB
Install MongoDB Community Edition
I followed the official instructions for installing MongoDB documented here. It involves adding the repo and key for that repo and installing it using apt-get install mongodb-org. Then enabling and starting mongod using systemctl.
Create an admin user on MongoDB
Post installation the next thing I did was to create a user with the admin role in the admin database giving this new user the role userAdminAnyDatabase. I’ve done all of this in Ansible so I am not positive about these specific commands.
- First run
mongoto access the MongoDB shell.
mongo - Switch to the admin database.
use admin - Create a new user with the userAdminAnyDatabase role on the admin database.
db.createUser(
{
user: "foo",
pwd: "bar",
roles: [
{ role: "userAdminAnyDatabase", db: "admin" }
]
}
)
- logout of the mongo shell
Full session.
rich@fenrir:~ mongo
MongoDB shell version v4.0.3
connecting to: mongodb://127.0.0.1:27017
Implicit session: session { "id" : UUID("7b7b4d25-239f-4983-a7ba-57a2e3bab068") }
MongoDB server version: 4.0.3
> use admin
switched to db admin
> db.createUser(
... {
... user: "foo",
... pwd: "bar",
... roles: [
... { role: "userAdminAnyDatabase", db: "admin" }
... ]
... }
... )
Successfully added user: {
"user" : "foo",
"roles" : [
{
"role" : "userAdminAnyDatabase",
"db" : "admin"
}
]
}
> logout
Enable Authorization
Now that you have an admin user, enable authorization by adding the following to /etc/mongod.conf
security:
authorization: enabled
Restart MongoDB
Now restart mongod.
sudo systemctl restart mongod
Nightscout
Create User and Database for Nightscout
We will be doing the following steps:
- Log into mongo:
mongo -u foo -p bar --authenticationDatabase admin
- Create a
nightscoutdatabase
use nightscout
- Create the nightscout user replacing “foo” with “nightscout”, “bar” with nightscout’s db password, the role with “dbOwner”, and “admin” with “nightscout”.
db.createUser(
{
user: "nightscout",
pwd: "nightscoutpw",
roles: [
{ role: "dbOwner", db: "nightscout" }
]
}
)
TODO Create a nightscout User to Run Under
The rest of these steps will run nightscout under your login user or root.
Install Nightscout Prerequisites
Using apt, install nodejs. At least on Ubuntu 18.04, this will also install npm. If it doesn’t for your system you may need to install it separately.
Fork and Clone the Nightscout Repo
The built in update mechanism depends on comparing your fork to the main Nightscout repo on GitHub. So if you want the ability to determine when it is time to upgrade automatically you must create a GitHub account, if you don’t have one already. Plus, this will let you contribute to OH. 
Log into GitHub and navigate to the main nightscout repo.
Now fork the repo.
This should open you to a https://github.com/<your github username>/cgm-remote-monitor page which is a complete copy of everything in the “official” repo.
Now, back in your terminal and create /opt/cgm-remote-monitor.
sudo mkdir /opt/cgm-remote-monitor
sudo chown user:user /opt/cg,-remote-monitor
Where “user” is your login account.
Now change to /opt and clone your fork of the cgm-remote-monitor repo. Click on the green “Clone or download this repo” button. Make sure you have “Use https” selected if you haven’t set up ssh certs with GitHub and click the clipboard icon to copy the path to the repo to your clipboard.
cd /opt
git clone <ctrl>-v
Where -v is the paste from your clipboard the path to your github repo.
This will check out all the code that makes up Nightscout to the cgm-remote-monitor folder.
Install required libraries
NightScout requires the use of a lot of libraries. To automatically install them change to /opt/cgm-remote-monitor and run npm install.
cd /opt/cgm-remote-monitor
npm install
This may take a few minutes to complete.
Configuration
NightScout appears to be wholly configured through environment variables. To capture these environment variables and make them available only to the Nightscout process create a file my.env in the /opt/cgm-remote-monitor folder.
See the NightScout documentation and tutorials for the full list of supported variables. I used the following:
my.env
MONGO=mongodb://nightscout:nightscoutpw@localhost:27017/nightscout
API_SECRET=NIGHTSCOUTAPISECRET
ENABLE=careportal%20basal%20bwp%20iob%20cob%20cage%20sage%20iage
DISPLAY_UNITS=mg/dl
PORT=80
| Parameter | Purpose |
|---|---|
| MONGO | The first line provides the MongoDB URL where the data gets saved. Note we are passing the database username and password (not the admin user and password). If you installed MongoDB on a different host change localhost to the appropriate hostname or IP address. |
| API_SECRET | At least a 12 character (I think) secret that is required to enable access from new devices (kind of like that one time code you get when you have two-factor authentication enabled). |
| ENABLED | List of add-ons that are enabled by default. I don’t know what any of these do yet, they appear to be the default set from many of the tutorials I’ve seen. |
| DISPLAY_UNITS | I’m in the U.S. so … |
| PORT | By default Nightscout runs on a different port. I’m not running behind a reverse proxy and have no other servers to conflict on this machine so I’m running on port 80. |
Run NightScout
All of the very sparse tutorials I’ve found runs NightScout using pm2. I’m no Node.js developer so I can’t argue with any of the benefits or problems with this.
First we need to install pm2 and then run the server.
sudo npm install -g pm2
cd /opt/cgm-remote-monitor
sudo env $(cat my.env) pm2 start server.js
Congratulations, NightScout should be up and running. You can check on the status of the service using the command:
sudo pm2 status
TODO Configure
Configure the service to restart when the machine reboots.
Configure NightScout and Collector
This is outside the scope of this tutorial. Before NightScout will let you do anything with the tool it will require you to set up a profile. The profile will include all the stuff you are used to like carb conversion ratios and the like.
As I said previously, we are using the Android app xDrip+ as the collector. There is a setting in this app where the path to the MongoDB or the path to the NightScout REST API can be entered and it will start publishing CGM readings and other info like the battery level of the CGM sensor transmitter.
NightScout Integration with openHAB
Unlike all the pain I went through trying to get the Dexcom official API to work only to discover that the data is too old to do anything with, the NightScout API is refreshingly simple and easy to use. We only need simple HTTP get commands and the JSON transformation.
Prerequisites
- HTTP Binding
- JSON Transformation
- Running NightScout
The NightScout API is documented here. We will only be demonstrating the entries/current.json endpoint. Working with the rest is an exercise left to the student.
Binding Config
We will use the HTTP binding in cache mode. Open $OH_CONF/service/html.cfg and add a new ID with a URL and upodateInterval. We will use an interval of three minutes which is half of the average of 6 minutes that I’m seeing records reported. YMMV.
nightscout.url=http://<hostname or IP address of nightscout server>/api/v1/entries/current.json
nightscout.updateInterval=180000
Items
You can go to that URL yourself in the browser to see all the available fields. The following Items shows how to get a few of them:
DateTime NS_LastReading_Time "Last Reading Time [%1$tm/%1$td %1$tH:%1$tM]" { http="<[nightscout:180000:JSONPATH($[0].dateString)]", expire="7m" }
Number NS_LastReading "Last Reading [%d] mg/dl" { http="<[nightscout:180000:JSONPATH($[0].sgv)]", expire="7m" }
String NS_Trend "Trend [%s]" { http="<[nightscout:180000:JSONPATH($[0].direction)]", expire="7m" }
Sitemap
Frame label="NightScout" {
Text item=NS_LastReading_Time
Text item=NS_LastReading
Text item=NS_Trend
}
Good luck!
