getting started on openaps hitchhiker's guide

Author: bewest

docs/docs/openaps-guide/core/alias.md

@@ -0,0 +1,3 @@
+
+# Alias - shortcut for any command
+

docs/docs/openaps-guide/core/devices.md

@@ -0,0 +1,2 @@
+
+# Devices - aka **using** openaps

docs/docs/openaps-guide/core/reports.md

@@ -0,0 +1,2 @@
+
+# Reports - the value of reproducibility

docs/docs/openaps-guide/core/vendors.md

@@ -0,0 +1,4 @@
+
+# Vendors - discovering uniformity
+
+

docs/docs/openaps-guide/index.rst

@@ -0,0 +1,21 @@
+
+Hitchhiker's Guide to openaps
+-----------------------------
+
+Welcome to openaps
+
+.. toctree::
+   :maxdepth: 4
+
+   installing
+   overview
+   core/vendors
+   core/devices
+   core/reports
+   core/alias
+   tutorial
+   
+
+
+
+

docs/docs/openaps-guide/installing.md

@@ -0,0 +1,45 @@
+
+# Installing openaps
+
+The recommended way to install openaps is to use python's package management system.
+The [openaps] project is distributed on [pypi][openaps on pypi].
+The following apt-get dependencies are required (they can be installed through
+variety of means, in debian/ubuntu and apt based systems the following packages
+are required:
+
+    sudo apt-get install python python-dev python-pip python-software-properties python-numpy
+    sudo pip install setuptools
+
+[openaps]: https://github.com/openaps/openaps
+[openaps on pypi]: https://pypi.python.org/pypi/openaps
+
+#### From pypi
+
+To [install from pypi](https://pypi.python.org/pypi/openaps):
+
+    sudo easy_install -Z openaps
+
+This installs `openaps` system wide.
+
+##### Updating
+To update `openaps`, append the `-U` option:
+
+    sudo easy_install -ZU openaps
+
+
+#### From source
+Sometimes, it's useful to use a development version to help test or debug
+features.  Here's how to install the project from source.
+
+    git clone git://github.com/openaps/openaps.git
+    cd openaps
+    # checkout desired branch (dev)?
+    git checkout dev
+    sudo python setup.py develop
+
+Do not use `openaps` commands in the the openaps repo.  Only use the
+`openaps` directory for hacking on the core library, or for managing
+upgrades through git.  Running `openaps` inside of the openaps
+source directory will error in the best case, and mess up your
+`openaps` install in the worst case.
+

docs/docs/openaps-guide/overview.md

@@ -0,0 +1,179 @@
+
+# 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.
+
+1. **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.
+
+1. **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.
+
+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.
+
+``` eval_rst
+.. 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 <[email protected]>
+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.
+
+  * [Vendors](core/vendors.md)
+  * [Devices](core/devices.md)
+  * [Reports](core/reports.md)
+  * [Alias](core/alias.md)
+

docs/docs/openaps-guide/tutorial.md

@@ -0,0 +1,5 @@
+
+# Tutorial: putting it together
+
+## Hello world device
+

docs/index.rst

@@ -7,6 +7,7 @@ Welcome to OpenAPS's documentation!
 
    docs/introduction/index
    docs/walkthrough/index
+   docs/openaps-guide/index
 
    Resources <docs/Resources/index>
    reference/index