Devices - aka using openaps¶
There are several vendors that built into the core of openaps. There are two tools we can use to examine which vendors are available for use by a device.
What can we use?¶
The openaps use
command allows us to interact with devices. Let’s ask it for help:
openaps use -h
usage: openaps-use [-h] [--format {text,json,base,stdout}] [--output OUTPUT]
[--version]
device ...
[... edited for brevity ...]
Known Devices Menu:
These are the devices openaps knows about:
device Name and description:
Once a device is registered in openaps.ini, it can be used.
Notice the Known Devices Menu:
is empty, this means openaps
doesn’t know
about anything yet.
Let’s try the openaps device
command instead:
usage: openaps-device [-h] {add,remove,show} ...
openaps-device - Manage device configurations.
positional arguments:
{add,remove,show} Operation
add add - add a new device configuration
remove remove - remove a device configuration
show show - show all devices
optional arguments:
-h, --help show this help message and exit
show - lists all known devices
add - add a new device
remove - remove a device
Lots of options there: the devices
command allows us to teach openaps about our devices.
The use command above had an empty devices menu what does device show
say?
Nothing yet! Both openaps use
and openaps device show
indicate nothing for us
to interact with yet. Let’s look at the --help
output for device add
:
usage: openaps-device add [-h] [--extra EXTRA]
name {dexcom,medtronic,process,units} ...
add - add a new device configuration
positional arguments:
name
optional arguments:
-h, --help show this help message and exit
--extra EXTRA, -e EXTRA
Name of extra ini file to use.
## VendorConfigurations:
{dexcom,medtronic,process,units}
Operation
dexcom Dexcom - openaps driver for dexcom
medtronic Medtronic - openaps driver for Medtronic
process process - a fake vendor to run arbitrary commands
units Units - units tool for openaps
Notice VendorConfigurations
. These are the default vendors that ship
with openaps
. However, openaps
doesn’t know we want to use
them yet. openaps device add
allows us to name our device. The
name we add to openaps will be the name we use later.
Devices configure use¶
A trivial device¶
Let’s use echo
to create a trivial device that just says “hello
world.”
echo
is a unix process, the VendorConfigurations above include a
process
vendor we can use to illustrate the relationship between uses
and devices.
Let’s warm up with some examples:
echo 'hello world!'
That should print hello world on the screen. We can run this over and
over again just for fun, but let’s discover how to teach openaps
how
to do this.
openaps device add howdy process echo 'hello world!'
added process://howdy/echo/hello world!
What did this do? Let’s check git show
:
commit 8e198ad8556ea6df4d4f6459d212eee316b89a0e
Author: Ben West <bewest@gmail.com>
Date: Sun Mar 27 15:45:16 2016 -0700
openaps-device add howdy process echo hello world!
TODO: better change descriptions
/usr/local/bin/openaps-device add howdy process echo hello world!
diff --git a/openaps.ini b/openaps.ini
index e69de29..d4a23d0 100644
--- a/openaps.ini
+++ b/openaps.ini
@@ -0,0 +1,4 @@
+[device "howdy"]
+vendor = openaps.vendors.process
+extra = howdy.ini
+
The openaps * add
commands all change some of the INI configurations.
Did the use menu change at all? openap use -h
[...]
Known Devices Menu:
These are the devices openaps knows about:
device Name and description:
howdy process - a fake vendor to run arbitrary commands
Now there’s a howdy device in the use menu. The use menu adapts
to our custom devices. Now we can use the device interactively: openaps use howdy -h
, remember, we can always add -h
to get more help/hints.
Take note of that --format text
option... our trivial howdy
tool just
prints a line of text. Most tools actually use a format called json (and it’s
the default), but for this example, we’ll stick with --format text
.
usage: openaps-use howdy [-h] USAGE ...
optional arguments:
-h, --help show this help message and exit
## Device howdy:
vendor openaps.vendors.process
process - a fake vendor to run arbitrary commands
USAGE Usage Details
shell run a process in a subshell
Hmm, because this a unix process, the use for this one is called
shell. What happens if we just add that word to the end? openaps use --format text howdy shell
$ openaps use --format text howdy shell
hello world!
Now it prints hello world!
because we are interactively using the
device. The device was configured through the add
command, and
saved in the INI as the process
vendor. The process
vendor only
exposes a single use: the shell
use allows us to run any unix process.
The device commands configure the uses. The use menu adapts to
the registered devices. We can interact with a device by using it.
Summary¶
Hopefully this illustrates the relationship between the openaps device and
use tools. The device
command allows bringing devices into your
instance, and use allows interacting with them. Let’s take a deeper look
at this relationship looking at the other vendors that might share a closer
relationship to diabetes.