Nightscout is educational source code for monitoring estimated glucose values from a Dexcom G4 Receiver. The following steps describe how one might use Nightscout.
Nightscout Quickstart Guide, Draft
All information, thought, and code described here is intended for informational and educational purposes only. Use of code from github.com/rnpenguin is without warranty or support of any kind. Please review the LICENSE found within each repository for further details. Do not use the information or code to make medical decisions.
Most likely, you will find yourself with a broken Dexcom receiver. The reciever's USB port was not intended to be used often. Even careful users report broken USB ports.
So you are thinking about a Nightscout rig?
What is the Nightscout project?
Nightscout is an open source,
DIY project. There is no support or
any warranty of any kind. The quality and performance of the project
is with you.
Is this project for me?
No programming experience is required, but there are several caveats to be aware of:
- data may go missing without warning
- data may be absent
- data may be wrong
- data may be delayed
- you may void your warranty
- you may break something
For all these reasons and more, it is important everyone carefully consider whether or not this project is right for them.
Right now, the best way to prepare yourself for a project of this nature is to follow the guidelines, to feel comfortable configuring and installing your own rig. Having this experience will prepare you to get help from the entire community quickly.
There is a community on Facebook that with people from all experience levels who will help you get up to speed on understanding and installing. Some may even help you experiment with new features, or different deployment techniques. While we love to see the diversity and Nightscout ecosystem grow, it is important that when asking for help, people who might provide you help need have an understanding of how things have been set up for you. If you departed from the community guides, it will be harder for people to help, potentially leaving you with less help if something breaks or needs to be upgraded.
What is required?
A Dexcom receiver, and a smartphone supporting USB OTG support. A special USB OTG cable allows the smartphone to read and report Dexcom readings to the cloud. The Dexcom USB port is fragile and will break if you are not very very careful. If you want the uploading to work everywhere, the smartphone will need a cell data plan. The smartphone must support USB OTG.
The combination of the smartphone + Dexcom allows data to go to a website, which you (or a friend?) will set up and manage. It will be your responsibility to make sure it continues to run. Several details need to be synchronized, using configuration menus in the UI in several different applications, in order for the system to work. The website will display the data from the cloud using a this website, many devices will be able to access this website.
There is no privacy or security provided by these tools, all data you upload will be publically available for anyone on the internet to read.
So the minimum requirements for a Nightscout rig are: a website managed by you, a smartphone, and a Dexcom. With these components, the CGM levels can be monitored from anywhere in the world. The website works on many other mobile devices, tablets, laptops; the sole purpose is to display the data. Due to the caveats mentioned and for many other reasons, it is important to not rely on this for therapy . .
Following the step by step guides should help prepare you for putting everything together and learning how to use the system.
What do we need?
Nightscout is a project composed of several parts.
From a place of caution, the first place to start is that you acquire 2 Dexcom receivers. The use of a CGM brings significant diabetes management advantage and it would be our first priority not to lose any data. The CGM in the Cloud system is a very useful extension of that data but the assembly has the disadvantage of potentially breaking the receiver charging port if not protected well or handled roughly. Better to have a second receiver, so there is never a time where you are without the CGM if one should break.
Next is the choice of android phone or tablet and cell data service provider and plan. Consider what your main goals are and select equipment and service to minimize hassle and be successful.
Cords can be purchased online or locally. Check the Info sheet for specifics, it can be slightly confusing when if selecting online.
Lastly, determine if you are DIY for the programming part. This group has fantastic support and very knowledgeable members to reach out to for assistance. If you are not a DIY person and want to have more assistance, that is possible through these wonderful group members as well.
The pebble watch is the last piece in this puzzle. It is optional and some find it very valuable but without all of the previous pieces it will not work.
Basic Concept of Operations
- Dexcom G4 Sensor / Transmitter sends wireless signal to Dexcom G4 Receiver
- Dexcom G4 Receiver is connected via USB OTG (On The Go) cable to an Android Uploader Device
- Android Uploader Device sends data to MongoDB database somewhere in the Cloud
- Cloud Service hosts a Node.js server, which serves pages to endpoint devices
- Endpoint devices display glucose information and generate audible alerts
Normally, mobile phones act as usb slaves. This allows them to draw power from the connected master, and allows the master to control exchanging data such as music, pictures, and other files.
OTG cable allows the phone to switch roles, becoming the
master side of the connection.
This allows the mobile phone to control the Dexcom and provide power,
just like a laptop.
It will be easier to follow along if you print these instructions. This document describes the steps to deploy Nightscout on the following hardware / services:
- Dexcom G4 Receiver
- Moto G phone (for uploading from the Dexcom)
- Mongolab (for storing data on the cloud)
- Microsoft Azure (for serving web pages)
Setup should take about an hour. Don’t skip steps, and please see instructions at the end if you have any suggestions for improving the clarity / correctness of these instructions. If you have issues check our wiki!
Dexcom G4 Receiver
Important: the USB jack is very fragile. Many people have broken their jack.
- If a cable is plugged into the jack and the receiver is dropped it may break
- Repeated plugging / unplugging may cause it to break
- Various hacks (styrofoam, fishing tackle cases, person game system cases, pouches) have been used to protect the cable connection. Drilling a hole in the case above the jack and filling it with 5 minute epoxy may provide additional mechanical strength.
Rooting is OPTIONAL
Most phones will work perfectly fine without rooting. Rooting (also known as "jailbreaking" in the iPhone world) voids your warranty, but the advantages include the ability to:
- Disable charging of the Dexcom receiver.
- Disable software that will use your Internet connection unnecessarily.
- Disable software that your kids might use to download games.
If you would like to read a novice's guide to Rooting, please read this article on Lifehacker entitled "Everything You Need to Know About Rooting Your Android Phone". This article includes links to where to find guides to rooting your phone.
Below are instructions for rooting a Motorola Moto G phone. If you have another phone, please see the "Where to Find Rooting Methods and Tools" section of the Lifehacker article mentioned above.
Moto G phone – get a phone, unlock it, and root it
Buy the version of the phone which will work with your preferred cellular provider
- Keep in mind this phone’s primary purpose is an uploader. Because it must remain connected to the Dexcom receiver which has a fragile USB connection, it is best to minimize its use an actual phone.
The phone will need to be unlocked and “rooted” for the software to turn the USB power off between uploads (otherwise the Dexcom will charge, draining the phone’s battery) Following the unlocking and rooting instructions here:
Set up web access (wifi, cellular)
- Put the phone aside for a moment, and set up MongoLab
- Do not upgrade the Android OS or return it to factory defaults, or the phone will need to be re-rooted.
Sign up for a free account at http://www.mongolab.com and
record the information you provide:
database and a
Save this information:
account name: _______ username: _______ email: _______ password: _______ database user: _______ (e.g. sallyuser) database user password: _______ (e.g. sallypassword) Cloud Provider: _______ (e.g. amazon webservices) Location: ____________ (e.g. Amazon’s US East (Virginia) Region (us-east-1) Plan: Single-node (development), Sandbox New destination database name: _________ (e.g. nightscout) Add a collection: _______ (e.g. sally)
Once all has been configured, on the
Database summary page,
copy the link under
To connect using a driver via the standard
URI, as this will be used to configure both the Android App and the
Node.js server. Copy and paste this string. You will use it
several times below.
We will refer to it as your
mongo connection uri.
It will look something like these examples:
Make sure you have easy access to your
mongo connection uri and
collection for the following steps.
The 500MB free tier should be enough to store 10 years of data.
Compile and Install the uploader
Download and install Android Studio, along with any updates,
Through the rooting procedure on the Moto G, usb debugging should already be enabled.
Start a new project
Start a new project, and
One way to do that: is to visit https://github.com/nightscout/dexcom-uploader And download the zip file directly from github.
Then import that zip file as a new project: Select the zip file you just downloaded.
Compile, and install
Plug your phone into the computer, and select
Run: Troubleshooting tip: If the app does not install on your phone, double check the target device by selecting "Edit Configurations" under the Run tab of Android Studio. Ensure that USB device is selcted as the target device, not Emulator.
These pictures were taken on a Mac.
Go into the settings menu in the CGM android app. It is in the upper right
corner or it might be accessed by pressing the menu button to the left of the home button of the smartphone. Use your your
mongo connection uri from above and fill in your collection name where requested.
With Mongolab now set up, the application should be able to start uploading. Connect the Dexcom receiver to the Moto G.
Important: when connecting the phone to the Dexcom, the OTG cable plugs into the phone, and the regular USB cable plugs into the Dexcom. It will not work the other way, because OTG cables have pins 4 and 5 shorted on the microusb connector, the indication to the phone that an OTG device is connected.
During the initial connection, there may be a pop-up asking if the app should have permission to run / access services. Select yes. The app should load, and data should start flowing to Mongolab.
Optional: Creating an apk
Android Studio also provides a way to “package” the app as an apk, which can then be attached to an email. On Android devices, the gmail app is smart enough to install apps which are attached to emails. In this way, it is very easy to deploy the app to other devices such as tablets or micro pcs. These are especially useful for bedside monitoring, since they have their own source of external power. For more information, see:
IMPORTANT: Verify Data Flowing to Mongolab
Before moving to the next step, you must verify that the data is flowing to Mongolab.
First, ensure your Dexcom receiver is connected to your uploader device and that the app is uploading data (the dexcom blood glucose number and the uploader device's blood glucose number should match).
With the app running, log into your Mongolab account. On the home screen, you will see something like this:
If the data is reaching Mongolab, the number under the documents column will not be zero.
For more detailed information and troubleshooting, click on the database (anywhere in the gray bar of information) to locate your collection. The next screen will look like this:
To view the actual documents/packets of information received including the date and time that Mongolab receives data, click on the collection name (blocked out on the screen shot) and you will see something like this:
Once you have documents in your Mongolab collection, move on to the next step of setting up your Azure site which will allow you to monitor the cgm on the web.
Microsoft Azure – cloud service to host website free
- Sign into Github.com with a free account.
- Click “Try for free”
- Enter or create username:
- Enter or create password:
- Enter credit card information (will not be billed, ever, without your permission)
- Go to the Azure Portal Create a new Azure site
- Choose a Site Name:
Configure connection strings
FIrst, find and click on the configure tab at the top of the page.
Next, scroll down the page until you find the connection strings (it will be over three quarters of the way down the page. You will see this:
Create two rows. At the end of each row, it will initially say SQL Database. Click on the arrow and select Custom for both rows. You now have two new Custom rows.
Each row now needs a name and a value.
Name the first row mongo. For this row's value, copy and paste your
mongo connection urifrom above into the value section of this row, e.g. mongodb://sallyuser:firstname.lastname@example.org:11111/nightscout
Name the second row mongo_collection. For this row's value, enter the name of your collection. If you followed the example, the name of your collection might be one word, e.g. sally.
When finished, the section will look like this:
If you click Show Connection Strings, you will see something like this (with your own information, of course):
Finally, click Save at the bottom of the page. This ends the work with the Configure tab. The next step is deployment and it uses the Dashboard tab.
Click on the Dashboard tab at the top of the page.
Find setup deployment from source control under quick glance .
- Select Github
- Authorize Github/Azure access.
Confirm, watch the site deploy, it should deploy automatically.
Verify operation by visiting the site, e.g.
If blood glucose reaches a dangerous level, an alarm may sound and the blood glucose value in the upper right hand corner will turn into a red button. Press the button to silence / acknowledge the alarm. This will also silence the alarm for anyone else who is looking at the website.
- For support, determine your Azure ftp username / password for azure website access by following these instructions: http://weblogs.asp.net/bleroy/archive/2012/06/12/azure-web-sites-ftp-credentials.aspx
(Optional) Creating a Widget to View Azure Site on an Android Phone
If you plan on viewing the azure website on an Android phone, you can create a widget which will refresh the data and place it on one of the home screens. One widget creator that works well is WebSnap. It is available from the Google Play store, but you will need to purchase the donate version ($2.99) if you want the widget to auto update every 5 minutes (free version will update every 15 minutes). WebSnap offers a variety of widget sizes, including a scrolling version of the entire webpage.
To the right is an example of a 4 x 2 widget of Nightscout:
The Pebble works with your main phone, eg, your iPhone. After getting a pebble watch, install the official Pebble App.
- Search Watchfaces for
Nightscout cgmand install from Pebble App
If it says
Coming Soon, you can sideload the
pbw by clicking on the link in your mobile browser
If you cannot here is how to compile a new one for yourself:
- On your Phone, enable
Developer Modein the Pebble App.
- Go to http://cloudpebble.net/, sign up for free account, log in
Enter these details
Project Name: anything you want Github project: github.com/nightscout/cgm-pebble IMPORT!
Make sure the phone is running in the Pebble App in developer mode.
To enable developer mode, go to
settings -> Pebble -> Enable developer mode.
Then open the pebble app, and enable developer mode.
- Go to Compilation tab
Hit Run Build
If your phone is in developer mode and everything is working, your phone will show up in a list, select the install and run:
Visit the settings menu on the phone and enter the address of your
- If you have issues check out our wiki https://github.com/nightscout/nightscout.github.io/wiki
Pay it forward
Help a friend. Enhance Nightscout by providing feedback, ideas, bug-fixes, and enhancements.