Merge pull request #59 from NTIA/smss-200

SMSS-200

README.md

@@ -3,36 +3,82 @@ NTIA/ITS SCOS Sensor
 
 The SCOS sensor is a RESTful API for any sensor that can be controlled via python.
 
-It provides:
-  - ready-made containers for x86 and arm32v7 hardware
-  - TODO
+Features:
+  - Ready-made containers for x86 and arm32v7 hardware
+  - An easy-to-use front end that subverts the need for client code to send http requests.
+  - Remote sensor deployment and administration via Foreman and Puppet.
+
+
+Browsable API
+-------------
+The API provides a browsable front end through which all valid requests can be made,
+and all operations performed. 
+
+All endpoints are easily discoverable, and it's simple
+to navigate from function to function:
+
+![Browsable API Root](/docs/img/browsable_api_root.png?raw=true)
+
+Scheduling an action is as simple as filling out a short form:
+
+![Browsable API Submission](/docs/img/browsable_api_submit.png?raw=true)
+
+Actions that have been scheduled show up in the schedule list:
+
+![Browsable API Schedule List](/docs/img/browsable_api_schedule_list.png?raw=true)
+
+See the [API Documentation](xxx) for more information on the features and functions
+of each endpoint.
 
-![Browsable API Screenshot](docs/img/browsable_api_screenshot.png)
 
 Quickstart
 ----------
 
 (See [INSTALL](INSTALL.md) for step-by-step instructions)
 
   - Install `git`, `Docker`, `docker-compose`, and `virtualenvwrapper` (optional)
+
+It's recommended that you activate a virtual environment via `conda` or 
+`virtualenv`/`virtualenvwrapper` before following the instructions below.
 
+Copy the environment template file and *modify* the copy if necessary, then source 
+it and run deploy.sh to properly configure the sensor code based on the machine on
+which it will run.
 ```bash
-$ git clone https://github.com/NTIA/scos-sensor
-$ cd scos-sensor
-$ mkvirtualenv scos-sensor  # `workon scos-sensor` hereafter
-$ cp env.template env       # modify env
+$ cp env.template env
 $ source ./env
 $ ./scripts/deploy.sh       # `deploy.sh` uses `env` to modify other templates
+```
+
+Install all Python requirements, set up the database, and create an admin user.
+```bash
 $ pip install -r ./src/requirements-dev.txt
 $ python ./src/manage.py makemigrations && ./src/manage.py migrate
 $ python ./src/manage.py createsuperuser
-# now, to run a Dockerized production-grade stack:
+```
+
+To run a Dockerized production-grade stack:
+```bash
 $ ./scripts/run.sh          # this make take a while the first time
-# or, for a local development server:
-$ ./src/manage.py runsslserver
+```
 
+For a local development server:
+```bash
+$ ./src/manage.py runsslserver
 ```
 
+Foreman and Puppet
+------------------
+The optimal way to manage individual SCOS Sensor machines in via Foreman
+and Puppet. Detailed instructions on how to do this are contained in 
+[the Foreman and Puppet README.md](puppet/README.md).
+
+
+Architecture
+------------
+![SCOS Sensor Architecture Diagram](/docs/img/architecture_diagram.png?raw=true)
+
+
 REST API Reference
 ------------------
 
@@ -44,6 +90,7 @@ REST API Reference
 
  - [Download PDF](https://github.com/NTIA/scos-sensor/raw/master/docs/api/openapi.pdf)
 
+
  License
  -------
  See [LICENSE.md](LICENSE.md).