search

nightscout / cgm-remote-monitor

nightscout web monitor
GNU Affero General Public License v3.0
2.35k stars 71.33k forks source link

readme

Nightscout Web Monitor (a.k.a. cgm-remote-monitor)

nightscout horizontal

Build Status Dependency Status Coverage Status Codacy Badge Discord chat

This acts as a web-based CGM (Continuous Glucose Monitor) to allow multiple caregivers to remotely view a patient's glucose data in real time. The server reads a MongoDB which is intended to be data from a physical CGM, where it sends new SGV (sensor glucose values) as the data becomes available. The data is then displayed graphically and blood glucose values are predicted 0.5 hours ahead using an autoregressive second order model. Alarms are generated for high and low values, which can be cleared by any watcher of the data.

Looking for documentation?

End user?

Nightscout documentation is currently split to two locations. This page lists all the configuration options in Nightscout and is useful for users who've already gone through the installation process. IF you're looking for the documentation that looks like it's written for non-programmers, that's located at nightscout.github.io.

Older documentation is available at nightscout.info.

Developer?

See CONTRIBUTING.md

#WeAreNotWaiting and this is why.

Coverage Status

Table of Contents

Install

Supported configurations:

While you can install Nightscout on a virtual server or a Raspberry Pi, we do not recommend this unless you have at least some experience hosting Node applications and development using the toolchain in use with Nightscout.

If you're a hosting provider and want to provide our users additional hosting options, you're welcome to issue a documentation pull request with instructions on how to setup Nightscout on your system.

Recommended minimum browser versions for using Nightscout:

Our browserslist policy is documented in .browserlistrc.
We currently support approximately 91% of all browsers globally used. These include:

Older versions or other browsers might work, but are untested and unsupported. We'll try to to keep Nightscout compatible with older iPads (e.g. Safari on iOS 10.3.4), but note that those devices are not supported by Apple anymore and have known security issues. Debugging these old devices gets harder due to Apple not supporting debugging the old devices on Macs that have been updated. Some features may not work with devices/browsers on the older end of these requirements.

Installation software requirements:

As a non-root user clone this repo then install dependencies into the root of the project:

$ npm install

Installation notes for users with nginx or Apache reverse proxy for SSL/TLS offloading:

Installation notes for Microsoft Azure, Windows:

Development

Want to help with development, or just see how Nightscout works? Great! See CONTRIBUTING.md for development-related documentation.

Usage

The data being uploaded from the server to the client is from a MongoDB server such as [MongoDB Atlas][https://www.mongodb.com].

Updating my version?

The easiest way to update your version of cgm-remote-monitor to the latest version is to use the update tool. A step-by-step guide is available [here][http://www.nightscout.info/wiki/welcome/how-to-update-to-latest-cgm-remote-monitor-aka-cookie]. To downgrade to an older version, follow [this guide][http://www.nightscout.info/wiki/welcome/how-to-deploy-an-older-version-of-nightscout].

Configure my uploader to match

Use the autoconfigure tool to sync an uploader to your config.

Nightscout API

The Nightscout API enables direct access to your data without the need for Mongo access. You can find CGM data in /api/v1/entries, Care Portal Treatments in /api/v1/treatments, and Treatment Profiles in /api/v1/profile. The server status and settings are available from /api/v1/status.json.

By default the /entries and /treatments APIs limit results to the the most recent 10 values from the last 2 days. You can get many more results, by using the count, date, dateString, and created_at parameters, depending on the type of data you're looking for.

Once you've installed Nightscout, you can access API documentation by loading /api-docs/ URL in your instance.

Example Queries

(replace http://localhost:1337 with your own URL)

The API is Swagger enabled, so you can generate client code to make working with the API easy. To learn more about the Nightscout API, visit https://YOUR-SITE.com/api-docs/ or review swagger.yaml.

Environment

VARIABLE (default) - description

Required

Features

Data Rights

These are useful to help protect your rights to portability and autonomy for your data:

Alarms

These alarm setting affect all delivery methods (browser, Pushover, IFTTT, etc.). Values and settings entered here will be the defaults for new browser views, but will be overridden if different choices are made in the settings UI.

Core

Predefined values for your browser settings (optional)

Predefined values for your server settings (optional)

Views

Nightscout allows to create custom, simplified views using a predefined set of elements. This option is available under [+] link in the main menu.

List of available items:

Split View

Some users will need easy access to multiple Nightscout views at the same time. We have a special view for this case, accessed on /split path on your Nightscout URL. The view supports any number of sites between 1 to 8 way split, where the content for the screen can be loaded from multiple Nightscout instances. Note you still need to host separate instances for each Nightscout being monitored including the one that hosts the split view page - these variables only add the ability to load multiple views into one browser page. To set the URLs from which the content is loaded, set:

Plugins

Plugins are used extend the way information is displayed, how notifications are sent, alarms are triggered, and more.

The built-in/example plugins that are available by default are listed below. The plugins may still need to be enabled by adding to the ENABLE environment variable.

Default Plugins

These can be disabled by adding them to the DISABLE variable, for example DISABLE="direction upbat"

delta (BG Delta)

Calculates and displays the change between the last 2 BG values.

direction (BG Direction)

Displays the trend direction.

upbat (Uploader Battery)

Displays the most recent battery status from the uploader phone. . Use these extended setting to adjust behavior:

timeago (Time Ago)

Displays the time since last CGM entry. Use these extended setting to adjust behavior:

devicestatus (Device Status)

Used by upbat and other plugins to display device status info. Supports the DEVICESTATUS_ADVANCED="true" extended setting to send all device statuses to the client for retrospective use and to support other plugins.

errorcodes (CGM Error Codes)

Generates alarms for CGM codes 9 (hourglass) and 10 (???).

ar2 (AR2 Forecasting)

Generates alarms based on forecasted values. See Forecasting using AR2 algorithm

simplealarms (Simple BG Alarms)

Uses BG_HIGH, BG_TARGET_TOP, BG_TARGET_BOTTOM, BG_LOW thresholds to generate alarms.

profile (Treatment Profile)

Add link to Profile Editor and allow to enter treatment profile settings. Also uses the extended setting:

Advanced Plugins:

careportal (Careportal)

An optional form to enter treatments.

boluscalc (Bolus Wizard)
food (Custom Foods)

An option plugin to enable adding foods from database in Bolus Wizard and enable .

rawbg (Raw BG)

Calculates BG using sensor and calibration records from and displays an alternate BG values and noise levels. Defaults that can be adjusted with extended setting

iob (Insulin-on-Board)

Adds the IOB pill visualization in the client and calculates values that used by other plugins. Uses treatments with insulin doses and the dia and sens fields from the treatment profile.

cob (Carbs-on-Board)

Adds the COB pill visualization in the client and calculates values that used by other plugins. Uses treatments with carb doses and the carbs_hr, carbratio, and sens fields from the treatment profile.

bwp (Bolus Wizard Preview)

This plugin in intended for the purpose of automatically snoozing alarms when the CGM indicates high blood sugar but there is also insulin on board (IOB) and secondly, alerting to user that it might be beneficial to measure the blood sugar using a glucometer and dosing insulin as calculated by the pump or instructed by trained medicare professionals. The values provided by the plugin are provided as a reference based on CGM data and insulin sensitivity you have configured, and are not intended to be used as a reference for bolus calculation. The plugin calculates the bolus amount when above your target, generates alarms when you should consider checking and bolusing, and snoozes alarms when there is enough IOB to cover a high BG. Uses the results of the iob plugin and sens, target_high, and target_low fields from the treatment profile. Defaults that can be adjusted with extended setting

cage (Cannula Age)

Calculates the number of hours since the last Site Change treatment that was recorded.

sage (Sensor Age)

Calculates the number of days and hours since the last Sensor Start and Sensor Change treatment that was recorded.

iage (Insulin Age)

Calculates the number of days and hours since the last Insulin Change treatment that was recorded.

bage (Battery Age)

Calculates the number of days and hours since the last Pump Battery Change treatment that was recorded.

treatmentnotify (Treatment Notifications)

Generates notifications when a treatment has been entered and snoozes alarms minutes after a treatment.

basal (Basal Profile)

Adds the Basal pill visualization to display the basal rate for the current time. Also enables the bwp plugin to calculate correction temp basal suggestions. Uses the basal field from the treatment profile. Also uses the extended setting:

bolus (Bolus Rendering)

Settings to configure Bolus rendering

connect (Nightscout Connect)

Connect common diabetes cloud resources to Nightscout. Include the keyword connect in the ENABLE list. Nightscout connection uses extended settings using the environment variable prefix CONNECT_.

Work in progress

To sync from another Nightscout site, include CONNECT_SOURCE_ENDPOINT and CONNECT_SOURCE_API_SECRET.

The CONNECT_SOURCE_ENDPOINT must be a fully qualified URL and may contain a ?token=<subject> query string to specify an accessToken. The CONNECT_SOURCE_API_SECRET, if provided, will be used to create a token called nightscout-connect-reader. This information or the token provided in the query will be used to read information from Nightscout and is optional if the site is readable by default.

Select this driver by setting CONNECT_SOURCE equal to nightscout.

Dexcom Share

To synchronize from Dexcom Share use the following variables.

Optional, CONNECT_SHARE_REGION and CONNECT_SHARE_SERVER do the same thing, only specify one.

Glooko

Note: Experimental.

To synchronize from Glooko use the following variables.

By default, CONNECT_GLOOKO_SERVER is set to api.glooko.com because the default value for CONNECT_GLOOKO_ENV is default.

If both, CONNECT_GLOOKO_SERVER and CONNECT_GLOOKO_ENV are set, only CONNECT_GLOOKO_SERVER will be used.

Libre Link Up

To synchronize from Libre Link Up use the following variables.

By default, CONNECT_LINK_UP_SERVER is set to api-eu.libreview.io because the default value for CONNECT_LINK_UP_REGION is EU. Other available values for CONNECT_LINK_UP_REGION:

For folks connected to many patients, you can provide the patient ID by setting the CONNECT_LINK_UP_PATIENT_ID variable.

Minimed Carelink

To synchronize from Medtronic Minimed Carelink, set the following environment variables.

For folks using the new Many to Many feature, please provide the username of the patient to follow using CONNECT_CARELINK_PATIENT_USERNAME variable.

bridge (Share2Nightscout bridge)

Deprecated Please consider using the connect plugin instead.

Fetch glucose reading directly from the Dexcom Share service, uses these extended settings:

mmconnect (MiniMed Connect bridge)

Deprecated Please consider using the connect plugin instead.

Transfer real-time MiniMed Connect data from the Medtronic CareLink server into Nightscout (read more)

pump (Pump Monitoring)

Generic Pump Monitoring for OpenAPS, MiniMed Connect, RileyLink, t:slim, with more on the way

openaps (OpenAPS)

Integrated OpenAPS loop monitoring, uses these extended settings:

loop (Loop)

iOS Loop app monitoring, uses these extended settings:

For remote overrides, the following extended settings must be configured:

override (Override Mode)

Additional monitoring for DIY automated insulin delivery systems to display real-time overrides such as Eating Soon or Exercise Mode:

xdripjs (xDrip-js)

Integrated xDrip-js monitoring, uses these extended settings:

alexa (Amazon Alexa)

Integration with Amazon Alexa, detailed setup instructions

googlehome (Google Home/DialogFLow)

Integration with Google Home (via DialogFlow), detailed setup instructions

speech (Speech)

Speech synthesis plugin. When enabled, speaks out the blood glucose values, IOB and alarms. Note you have to set the LANGUAGE setting on the server to get all translated alarms.

cors (CORS)

Enabled CORS so other websites can make request to your Nightscout site, uses these extended settings:

dbsize (Database Size)

Show size of Nightscout Database, as a percentage of declared available space or in MiB.

Many deployments of Nightscout use free tier of MongoDB Atlas on Heroku, which is limited in size. After some time, as volume of stored data grows, it may happen that this limit is reached and system is unable to store new data. This plugin provides pill that indicates size of Database and shows (when configured) alarms regarding reaching space limit.

IMPORTANT: This plugin can only check how much space database already takes, but cannot infer max size available on server for it. To have correct alarms and realistic percentage, DBSIZE_MAX need to be properly set - according to your mongoDB hosting configuration.

NOTE: This plugin rely on db.stats() for reporting logical size of database, which may be different than physical size of database on server. It may work for free tier of MongoDB on Atlas, since it calculate quota according to logical size too, but may fail for other hostings or self-hosted database with quota based on physical size.

NOTE: MongoDB Atlas quota is for all databases in cluster, while each instance will get only size of its own database only. It is ok when you only have one database in cluster (most common scenario) but will not work for multiple parallel databases. In such case, spliting known quota equally beetween databases and setting DBSIZE_MAX to that fraction may help, but wont be precise.

All sizes are expressed as integers, in Mebibytes 1 MiB == 1024 KiB == 1024*1024 B

Extended Settings

Some plugins support additional configuration using extra environment variables. These are prefixed with the name of the plugin and a _. For example setting MYPLUGIN_EXAMPLE_VALUE=1234 would make extendedSettings.exampleValue available to the MYPLUGIN plugin.

Plugins only have access to their own extended settings, all the extended settings of client plugins will be sent to the browser.

Pushover

In addition to the normal web based alarms, there is also support for Pushover based alarms and notifications.

To get started install the Pushover application on your iOS or Android device and create an account.

Using that account login to Pushover, in the top left you’ll see your User Key, you’ll need this plus an application API Token/Key to complete this setup.

You’ll need to Create a Pushover Application. You only need to set the Application name, you can ignore all the other settings, but setting an Icon is a nice touch. Maybe you'd like to use this one?

Pushover is configured using the following Environment Variables:

* `ENABLE` - `pushover` should be added to the list of plugin, for example: `ENABLE="pushover"`.
* `PUSHOVER_API_TOKEN` - Used to enable pushover notifications, this token is specific to the application you create from in [Pushover](https://pushover.net/), ***[additional pushover information](#pushover)*** below.
* `PUSHOVER_USER_KEY` - Your Pushover user key, can be found in the top left of the [Pushover](https://pushover.net/) site, this can also be a pushover delivery group key to send to a group rather than just a single user.  This also supports a space delimited list of keys.  To disable `INFO` level pushes set this to `off`.
* `PUSHOVER_ALARM_KEY` - An optional Pushover user/group key, will be used for system wide alarms (level > `WARN`).  If not defined this will fallback to `PUSHOVER_USER_KEY`.  A possible use for this is sending important messages and alarms to a CWD that you don't want to send all notification too.  This also support a space delimited list of keys.  To disable Alarm pushes set this to `off`.
* `PUSHOVER_ANNOUNCEMENT_KEY` - An optional Pushover user/group key, will be used for system wide user generated announcements.  If not defined this will fallback to `PUSHOVER_USER_KEY` or `PUSHOVER_ALARM_KEY`.  This also support a space delimited list of keys. To disable Announcement pushes set this to `off`.
* `BASE_URL` - Used for pushover callbacks, usually the URL of your Nightscout site, use https when possible.
* `API_SECRET` - Used for signing the pushover callback request for acknowledgments.

If you never want to get info level notifications (treatments) use `PUSHOVER_USER_KEY="off"`
If you never want to get an alarm via pushover use `PUSHOVER_ALARM_KEY="off"`
If you never want to get an announcement via pushover use `PUSHOVER_ANNOUNCEMENT_KEY="off"`

If only `PUSHOVER_USER_KEY` is set it will be used for all info notifications, alarms, and announcements

For testing/development try [localtunnel](http://localtunnel.me/).

IFTTT Maker

In addition to the normal web based alarms, and pushover, there is also integration for IFTTT Webhooks.

With Maker you are able to integrate with all the other IFTTT Services. For example you can send a tweet when there is an alarm, change the color of hue light, send an email, send and sms, and so much more.

  1. Setup IFTTT account: login or create an account
  2. Follow the Detailed IFTTT setup Instructions

  3. Configure Nightscout by setting these webpage environment variables:

    • ENABLE - maker should be added to the list of plugins, for example: ENABLE="maker".
    • MAKER_KEY - Set this to your secret key (see [Detailed Instructions ) MAKER_KEY="abcMyExampleabc123defjt1DeNSiftttmak-XQb69p" This also supports a space delimited list of keys.
    • MAKER_ANNOUNCEMENT_KEY - An optional Maker key, will be used for system wide user generated announcements. If not defined this will fallback to MAKER_KEY. A possible use for this is sending important messages and alarms to another device that you don't want to send all notification too. This also support a space delimited list of keys.

    Plugins can create custom events, but all events sent to IFTTT webhooks will be prefixed with ns-. The core events are:

    • ns-event - This event is sent to the maker service for all alarms and notifications. This is good catch all event for general logging.
    • ns-allclear - This event is sent to the maker service when an alarm has been ack'd or when the server starts up without triggering any alarms. For example, you could use this event to turn a light to green.
    • ns-info - Plugins that generate notifications at the info level will cause this event to also be triggered. It will be sent in addition to ns-event.
    • ns-warning - Alarms at the warning level with cause this event to also be triggered. It will be sent in addition to ns-event.
    • ns-urgent - Alarms at the urgent level with cause this event to also be triggered. It will be sent in addition to ns-event.
    • see the full list of events

Treatment Profile

Some of the plugins make use of a treatment profile that can be edited using the Profile Editor, see the link in the Settings drawer on your site.

Treatment Profile Fields:

Setting environment variables

Easy to emulate on the commandline:

    echo 'MONGO_CONNECTION=mongodb://sally:sallypass@ds099999.mongolab.com:99999/nightscout' >> my.env
    echo 'MONGO_COLLECTION=entries' >> my.env

From now on you can run using

    $ (eval $(cat my.env | sed 's/^/export /') && PORT=1337 node server.js)

Your hosting provider probably has a way to set these through their GUI.

Vagrant install

Optionally, use Vagrant with the included Vagrantfile and bin/setup.sh to install OS and node packages to a virtual machine.

host$ vagrant up
host$ vagrant ssh
vm$ ./bin/setup.sh

The setup script will install OS packages then run npm install.

The Vagrant VM serves to your host machine only on 192.168.33.10, you can access the web interface on http://192.168.33.10:1337

More questions?

Feel free to post an issue, but read the wiki first.

Browser testing suite provided by

BrowserStack

License

cgm-remote-monitor - web app to broadcast cgm readings
Copyright (C) 2017 Nightscout contributors.  See the COPYRIGHT file
at the root directory of this distribution and at
https://github.com/nightscout/cgm-remote-monitor/blob/master/COPYRIGHT

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.