About openaps

openaps is a toolkit to make developing an artificial pancreas easy for humans. What is an artificial pancreas? What are the requirements of this toolkit and how does it work?

While most people learning about this project may be interested in assembling their own “AP” as soon as possible, it may be helpful to pause and get a high level overview of openaps.

What is an artificial pancreas?

The term artificial pancreas can be misleading, as it can include or exclude different ideas or projects. For our purposes, an artificial pancreas does the following things:

  1. Monitor therapeutic data (especially from pumps and CGM) in real time to provide relevant decision making data points. In order to do this, we must be able to manage data from disparate systems in a uniform manner.
  2. Predict what is likely to happen. For example, when administering insulin, we naturally expect glucose to fall along a given curve. High fidelity therapy means communicating expectations like this, learning when it is wrong, and responding accordingly. Since clinical therapy is an application of science, this process must be reproducible, so that we can properly assess what works, and what does not.
  3. Enact shared plans like a good teammate. When humans get distracted, or sick, or are asleep, the tools can and should provide assistance to improve safety and increase control over dangerous conditions.

Bring your own device

Circa 2016-03-27, we have access to a variety of insulin pumps and glucose monitors. openaps provides a modular framework to manipulate a variety of insulin pumps, and glucose monitors, as well as devices by different vendors. openaps exposes the uses of a device from a particular vendor for you to explore your own menagerie of devices in a uniform and interoperable manner. openaps also provides reports to track data as it flows through each phase, and an alias feature to logically group commands and workflows.

When the community discovers how to communicate with a device, we can create an openaps vendor module for the new device.

What is a toolkit?

openaps is not an artificial pancreas by itself. So far in discussing some of the philosophy and overview of openaps, we’ve seen that it needs to interact with a lot of different devices in a lot of different circumstances. The solution to solving this problem was to provide a suite of tools that allows us to interact with the properties of the system, easily see what is going on inside and inspect the data. Because we often intend for the system to operate while we’re asleep, the tools also provide several facilities for easily changing and saving configuration.

This means we’ll be using the command line a lot, because it’s very easy to teach, reproduce, and automate. Any series of commands you type in the command line can be put in a file and made into a script.

Because most people intend to use this as a medical device, we also wanted to track the data as it moves through the system. openaps checkpoints all the data so that it can be inspected and verified at anytime.

The toolkit provides many tools to realize the values enumerated by our design philosophy. Here are a few, but don’t panic, we’ll go through how to use each one methodically:

  openaps
  openaps-device
  openaps-report
  openaps-vendor
  openaps-use
  openaps-alias

Now that openaps is installed, we can ask any of these tools for help to explain themselves:

`openaps --help`

Many of the tools depend on some configuration though, how do we provide the configuration it needs? If it needs configuration, the tool might refuse to run, like this:

  bewest@bewest-MacBookPro:~/Documents$ openaps use -h
  Not an openaps environment, run: openaps init

Don’t worry, it’s time to create our first workspace!

My first workspace

This guide aims to help users become comfortable navigating the openaps commands. Most of the commands read saved configuration. openaps needs a location to store all the data and configuration generated as we explore. We’ll often refer to this location as your openaps instance. The toolkit helps you create an instance of openaps on your computer. We can think about this location as a workspace for openaps.

Get familiar with ls, cat, echo, cd, pwd commands. To create our first openaps instance, we use openaps init with the location we’d like to use:

cd ~/Documents
openaps init tutorial-hello
cd tutorial-hello
pwd

This creates a new openaps instance in ~/Documents/tutorial-hello. Take a look at what is in your workspace, using ls and cat. A valid instance must have an openaps.ini file. It can be empty, which simply means it doesn’t (yet) know about your devices or vendors or anything.

Note

For the rest of this tutorial, all of our work will be done in the ~/Documents/tutorial-hello directory.

Inspecting the log

We mentioned earlier that the requirements for openaps demand that we track data as it flows through the system. Is there a log of all the transactions that have occurred? If so, it should include the fact that we just created an instance of openaps. A valid instance of openaps has two requirements: it must be a git repository containing an openaps.ini file at it’s root.

This means many operations are tracked using git, try git log or git show; there should an event in the log showing the time and date (and who!) created this instance.

bewest@bewest-MacBookPro:~/Documents/tutorial-hello$ ls
openaps.ini
bewest@bewest-MacBookPro:~/Documents/tutorial-hello$ cat openaps.ini 
bewest@bewest-MacBookPro:~/Documents/tutorial-hello$ wc -l openaps.ini 
0 openaps.ini
bewest@bewest-MacBookPro:~/Documents/tutorial-hello$ git show
commit 04715a67099c19ae220220d474aa67e470d07e0e
Author: Ben West <bewest@gmail.com>
Date:   Sun Mar 27 14:37:56 2016 -0700

    initializing openaps 0.1.0-dev

diff --git a/openaps.ini b/openaps.ini
new file mode 100644
index 0000000..e69de29
bewest@bewest-MacBookPro:~/Documents/tutorial-hello$ 

Knowledge of git is not usually needed or expected in order to use openaps, however, openaps does use it to store and track all data. This has several side-effects including easy mesh/backup. Many events in the log will also include a comment on the commands used to create the transaction. This allows us to share, find and debug problems quickly and easily.

Many software programs attempt to hide the inner workings. However because openaps has to meet exacting requirements, the design enables openaps to easily examine and adjust how it works using standard tools.

Summary

Congratulations, you’re now the owner of a new openaps instance. It’s time to start exploring openaps core in more detail.