dexctrack
A program to graphically display information from Dexcom Continuous Glucose Monitor receivers. This is implemented in python version 2.7.* for Linux, OSX, or Windows. It has been tested with G5 and G6 receivers on Linux, Mac OSX High Sierra, and Windows 10.
About 95% of this code runs fine under python 3.*, but readdata.py and packetwriter.py (borrowed from the dexcom_reader project), which includes code to write commands to and read data from the Receiver device, don't work under python 3.* due to the change from ASCII implicit string types to Unicode implicit string types.
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.
Installing
Install the latest 2.7.* version of 'python' for whatever operating system you are running on your computer.
Also install 'pip', a tool for installing and managing Python packages. This is included in the installation packages from www.python.org, but if you instead, use a package manager such as 'apt', 'synaptic', 'rpm', or 'dnf' to install 'python2.7.*', you may need to specify an additional package to get 'pip' installed.
- Linux
- Install 'python' and 'pip'
On apt-based Linux systems (e.g. Mint, Ubuntu, or Debian):
sudo apt-get install python python-pip python-tk python-wxtools python-matplotlib libpython2.7-dev
On rpm-based Linux systems (e.g. Fedora or Red Hat):
sudo dnf install redhat-rpm-config python2 python2-devel 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'
sudo pip install --upgrade setuptools
sudo pip install matplotlib pyserial pytz tzlocal numpy pympler wxPython
- 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.* release under
- Install 'git'
The following steps should be run from a Terminal. Finder -> Go -> Utilities -> Terminal
- Update path
Update your PATH environmental variable to include paths to the 'python' and 'pip' executables. This can be done by ...
echo 'export PATH="/usr/local/opt/python@2/bin:$PATH"' >> ~/.bashrc
- Install dexctrack, using 'git'
- Install required python libraries, using 'pip'
pip install --upgrade setuptools
pip install matplotlib pyserial pytz tzlocal numpy pympler
pip install 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. 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'
pip install --upgrade setuptools
pip install matplotlib pyserial pytz tzlocal numpy pympler wxPython
Running
To launch the program, move into the dexctrack/ directory and invoke
python dexctrack.py
You can add a '-d' option on the end to run in Debug mode. This causes messages to be printed out which can help track down issues. For example ...
python dexctrack.py -d
Once the application is running,
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. You may want to try switching to a different USB port, if available.
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 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. If you want to set a different target range, use the left mouse button to click the 'Set New Target Range' button in the bottom right corner of the screen. This will switch the color of that button from yellow to red.
Next, use the left mouse button to select a new range. Move the mouse into the plotting area and press the mouse button at the start of the desired vertical range. Hold that button down while moving vertically up or down. Release the button at the end of the desired range. In the example below, the new range is set from 97 to 205 mg/dL.
The Target range (highlighted in gold color) will then move to the new range. Glucose values higher than this range will be colored red and glucose values lower than this range will be colored magenta.
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.
This application supports use of mmol/L units. If your receiver is configured to use those units, that's the way the information will be displayed.
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.