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:
- 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.
- 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.
- 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.