A program to graphically display information from Dexcom Continuous Glucose Monitor receivers. This runs using python version 2.7.* or 3.*, on Linux, OSX, or Windows. It has been tested with G5 and G6 receivers on Linux, Mac OSX High Sierra, and Windows 10.
All data read from your Receiver device is stored locally in a database file on your computer. Nothing is written to a remote server or sent to "the cloud". You have complete control and ownership of your private data.
This application supports use of both mg/dL and mmol/L units. It displays using to the units configured on your receiver.
Install the latest 2.7.* or 3.* version of 'python' for whatever operating system you are running on your computer. For MacOS or Windows, www.python.org/downloads has installation packages with built executables. For Linux, they only provide source code, so you are generally better off using your Linux package manager to install the latest built version.
Also install 'pip' (for python 2.7.) or 'pip3' (for python 3.), a tool for installing and managing Python packages. This is included in the installation packages from www.python.org, but if you use a Linux package manager such as 'apt', 'synaptic', 'rpm', or 'dnf' to install 'python' or 'python3', you may need to specify an additional package to get 'pip' or 'pip3' installed.
- Linux
- Install 'python' and 'pip'
On apt-based Linux systems (e.g. Mint, Ubuntu, or Debian):
For python2.7.*
sudo apt-get install python python-pip python-tk libpython2.7-dev
For python3.*
sudo apt-get install python3 python3-pip python3-tk
On rpm-based Linux systems (e.g. Fedora or Red Hat):
For python2.7.*
sudo dnf install python2 python2-devel python-tkinter
For python3.*
sudo dnf install python3 python3-pip python3-tkinter
- Install 'git'
On apt-based Linux systems (e.g. Mint, Ubuntu, or Debian):
sudo apt-get install git
On rpm-based Linux systems (e.g. Fedora or Red Hat):
sudo dnf install git
- Install dexctrack, using 'git'
- Install required python libraries, using 'pip'
For python2.7.*
sudo pip install --upgrade setuptools
sudo pip install matplotlib pyserial pytz tzlocal numpy pympler
For python3.*
sudo pip3 install --upgrade setuptools
sudo pip3 install matplotlib pyserial pytz tzlocal numpy pympler
- Set up permissions to provide the user serial port access to a connected USB device. Implement one of the following options to accomplish this.
a) Add the user account to the dialout group.
On Debian-based or Ubuntu-based Linux systems:
sudo addgroup <username> dialout
On Fedora-based Linux systems:
sudo usermod -a -G <username> dialout
You may need to log out and back in to make sure the group membership is updated.
b) Install udev rules to get access to device.
sudo cp dexctrack/etc/udev/rules.d/80-dexcom.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
- MacOs
- Install 'python' and 'pip'
Mac OSX High Sierra includes python version 2.7.10 as a standard part of the OS, but that version is quite old, and is missing the fivethirtyeight style which will provide the best looking graphs. Install the latest 2.7.* or 3.* release under
The macOS 64-bit installer will update your PATH to include the newly installed versions of 'python' and 'pip', or 'python3' and 'pip3', by adding a few lines to your ~/.bash_profile file.
- Install 'git'
The following steps should be run from a Terminal. Finder -> Go -> Utilities -> Terminal
- Install dexctrack, using 'git'
- Install required python libraries, using 'pip'
For python2.7.*
pip install --upgrade setuptools
pip install matplotlib pyserial tzlocal pytz numpy pympler pyobjc
For python3.*
pip3 install --upgrade setuptools
pip3 install matplotlib pyserial tzlocal pytz numpy pympler pyobjc
- Windows
- Install 'python' and 'pip'
Update your Path environmental variable to include paths to the 'python' and 'pip' executables. Menu->Settings and then search for "Edit environment variables for your account". This will open an "Environment Variables" window. Click on the "Path" variable, and then the Edit button. For example, if you've installed into the directory C:\Python27, then add
C:\Python27 C:\Python27\Scripts
to the Path variable.
- Install 'git'
Update your Path environmental variable to include a path to the 'git' executable.
C:\Program Files\Git\bin
- Install dexctrack, using 'git'
- Install required python libraries, using 'pip'
For python2.7.*
pip install --upgrade setuptools
pip install matplotlib pyserial tzlocal pytz numpy pympler
For python3.*
pip3 install --upgrade setuptools
pip3 install matplotlib pyserial tzlocal pytz numpy pympler
After your initial git clone operation, you can update to the latest release, at any time, by running the following command from within your dexctrack directory.
git pull origin master
To launch the program, move into the dexctrack/ directory and invoke
python dexctrack.py
or
python3 dexctrack.py
You can add a '-d' option on the end to run in Debug mode. This causes messages to be printed out to the terminal, which can help track down issues. For example ...
python dexctrack.py -d
or
python3 dexctrack.py -d
> python3 dexctrack.py -d
DexcTrack Copyright (C) 2018 Steve Erlenborn
This program comes with ABSOLUTELY NO WARRANTY.
get_screen_size width = 1920 , get_screen_size height = 1080 , dispRatio = 1.8
sys.platform = linux2
backend = TkAgg
matplotlib version = 3.1.1
sqlite_file = /home/steve/dexc_PL75130020.sqlite
rcParams[timezone] = America/Chicago
Latest glucose at 2020-06-02 10:43:36-05:00 = 90
A user reported that all of their time values were off by 8 hours. This may be due to a change in newer firmware releases of the Receiver, or possibly different hardware based on target region. To work around this issue, the '-t' option can be used to set a time offset. The general format is +/-hours:min:sec, but the sign, the minutes and the seconds parts are optional.
python dexctrack.py -t+8
will add eight hours to all of the data read from the Receiver.
python dexctrack.py -t-8
will subtract eight hours from all of the data read from the Receiver.
python dexctrack.py -t-0:30
will subtract 30 minutes from all of the data read from the Receiver.
python dexctrack.py -t0
will return to the default of no offset.
Setting this time offset only needs to be done once. The offset value will be stored into your database. The next time you launch, without a '-t' option, the previously specified offset will be used.
Once the application is running, a graphical window will be opened. In the lower left corner, the status of the connection to the Receiver device will be displayed.
Connect your Dexcom receiver device to your computer using the USB cable. The device will be detected within about 20 seconds, and all of the data on it will be read into an SQLITE database in your home directory.
Note for the Windows 10 operating system, the USB serial port driver (Usbser.sys) does not properly support USB3 -> USB2 backwards compatibility, so you need to plug into to a USB2 port. Plugging into a USB2 or USB3 port will work fine on Linux or MacOS systems.
The name of that database includes the serial number of the Dexcom receiver, so if you have multiple users with separate Dexcom devices, their data will not conflict. Each will be written to their own database.
By default, glucose readings from the last day get displayed, and every 5 minutes a new reading is added to the graph.
In the upper right corner, the latest glucose value, the Average and Standard Deviation of glucose values over the last 90 days, and the Hemoglobin A1C value corresponding to the average is displayed. In addition, a Trend arrow indicates whether the glucose value is rising quickly, rising, flat, falling, or falling quickly. In the example below, the Trend is falling.
Use arrow keys <- (Left) or -> (Right) to scroll the display Date and Time backwards or forwards a screen width at a time. Use Alt+Left or Alt+Right to scroll one hour backwards or forwards. You can also hover over a position in the Start Date slider (in blue near the bottom of the screen). The hover position will show the target starting date in parentheses. Click the left mouse button to immediately move to that hover position.
The Scale slider (in green at the bottom of the screen) can be used to zoom the displayed time period in or out. Hover over the slider until the time period you desire is visible in parentheses. Click to set that period.
When you scale out to a large time period, the graph could get cluttered with a large number of Event or Note strings. When the number of such strings gets too large (> 30), they get dropped from the display.
With a smaller time period, user added Events get plotted onto the graph. Some effort is taken to avoid collisions between multiple Events, but there will still be collisions fairly often. Each of the Event strings is draggable, so the user can click on a string with the left mouse button to grab a string, drag it to a better location, and then release the mouse button. For example, here you can see that the plotting position for "10 min light exercise" intersects with the plotted line.
Grab it and drag it a bit higher, and we get ...
This gives a cleaner image. The new position will get stored in the database, so after quitting and relaunching, this better position will be restored.
Usually, when the Receiver is connected to a USB port, its battery gets recharged. On rare occasions, a computer may stop providing power to a particular USB port. I had mine connected for many hours, but when I detached it to depart from home, I found it had no charge. That was frustrating, so I added a display of the current battery status in the lower right corner, above the "Set New Target Range" button. When the battery is currently charging, the percentage of full charge is displayed in a light green color.
When fully charged, this switches to a darker green.
If no power is being provided, and battery charge is decreasing, the status will be labeled "Draining" with a red color.
If you see such a condition, try disconnecting and reconnecting the USB cable. This usually fixes the problem. If not, you may want to try switching to a different USB port, if available.
On the far right side of the graph, there is a grey patch which projects from the current time to one hour in the future. The program uses recent data points to calculate polynomials which estimate the trend of future glucose values.
The red dashed line is a one-degree polynomial, also known as a linear equation. The green dashed line is a two-degree polynomial, also known as a quadratic equation. The two-degree polynomial is better at detecting the top or bottom of a parabola in values being mapped, but can swing wildly from one graph draw to the next. The one-degree polynomial is more stable, but is slower to respond to direction changes.
Sometimes the Receiver is off in its glucose estimates and you need to enter User Calibration values to nudge it into alignment. Calibrations show up as black diamonds in the graph. When the calibration value does not match the current estimated glucose, a pink arrow pointing to the User Calibration value shows the difference between the estimated glucose value and the entered calibration value. Below is an example of a scenario where the Receiver was estimating a glucose value of 88. A blood glucose test showed the actual value to be 107. A little while later, the Receiver estimated a value of 164. A blood glucose test revealed the actual value to be 138.
If you have many large differences between the estimated and actual blood glucose values, you may be having problems with your current Sensor.
You can also use User Calibrations to add data points to your graph. During a 2 hour Sensor warm-up period, the Receiver does not store any automatically detected glucose values, but it will store calibration values. If you draw a drop of blood from your finger and measure your glucose using a test strip, you can enter that value as a User Calibration on your Receiver device. This value will be displayed as a data point in your Dexctrack graph.
If don't have a new Sensor available yet, you can use your test strips and User Calibrations to track your data over many hours or days.
You can add a Note using the following procedure. First click within the Note box, and enter a string. Hit return when you are done.
Next, click on a point in the graph with the right or middle mouse button. The string from the Note box will be transferred to that location.
Later on, say you want to either remove or edit that Note. Select the graph point with your right or middle mouse button.
The note is removed from the graph, and placed back into the Note box. You can now click in the Note box, and backspace over the string until it is empty before hitting Return to remove the Note, or you can edit the note string
and hit Return to place the new Note string into the graph.
Like Events, Notes are draggable, so you can click on the string with your left mouse button, drag it to a better location and then release the mouse button. The updated position will be saved into the database.
By default, the Target range is 75 - 200 mg/dL. This range is displayed in the lower right corner of the screen. If you hover the mouse pointer over the low end or high end of the displayed range, the background color will switch to light salmon. This is a hint that the text value can be edited. If you want to set a different target range, use the left mouse button to click in the box showing the low end of the range. This will give you a text cursor which can be used to set a different value. For example, you can switch 75 to 95,
and then either click outside of that text box or hit the Enter key on your keyboard. After doing so, the horizontal gold bar showing the Target range will be adjusted to display the new low end of the range.
Next, you can click within the box showing the high end of the Target Range, and switch that from 200 to 180.
Click outside of that text box or hit the Enter key on your keyboard. After doing so, the horizontal gold bar showing the Target range will be adjusted to display the new high end of the range.
Glucose values higher than the new range will be colored red and glucose values lower than the new range will be colored magenta.
The Target Range values are saved in your database, so if you quit, and relaunch later, your new Target Range values will be restored. For Receivers with glucose values in mg/dL units, the allowable range values are (40 - 400).
For Receivers with glucose values in mmol/L units, the allowable range values are (4.2 - 22.2).
To the right of the graph there are 3 percentages displayed.
The upper one, colored red shows the percentage of glucose values (in the last 90 days) which are above the Target range. The middle one, colored light blue, shows the percentage of values within the Target range. The lower one, colored magenta, shows the percentage of values below the Target range.
Your goal is to stay within your Target Range. If you can do so for at least one day, this accomplishment will be highlighted with a light blue background above and below the Target Range, and a display of the number of hours you've been in range.
When you disconnect your Receiver device from the computer, say to go exercise, a display of the number of minutes disconnected will be shown.
When you reconnect, this time will be switched from black to grey for a short while, before disappearing.
For some graph resolutions, the Legend is not placed in an ideal location. It is draggable, so you can move it to a better position. Click on the Legend
and drag it to a new spot before releasing the mouse button.
The new location will be saved to your database, and will be restored the next time you launch the program.
Many thanks to the dexcom_reader project, https://github.com/openaps/dexcom_reader, which provided code used to read information off of Dexcom G4 or G5 receivers, and to the developers of the awesome matplotlib library which is great for drawing graphs.
