Merge branch '53177' of git://github.com/tjamison/rvi_core into uw-tjamison-53177

6 files changed, 402 insertions, 49 deletions

diff --git a/BUILD.md b/BUILD.md
index fb196c0..f63581b 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -8,8 +8,10 @@ Attribution-ShareAlike 4.0 International.
 
 # BUILD INSTRUCTIONS FOR RVI #
 
-This document describes the build process for the RVI project on an
-Ubuntu 14.04 Linux machine.
+This document describes the build process from source for the RVI 
+project on an Ubuntu 14.04 Linux machine. Packages are also available
+for [Ubuntu](INSTALL_ubuntu.md), [Debian](INSTALL_debian.md), 
+and [Raspbian](INSTALL_raspbian.md).
 
 Please see ```README.md``` for a general description of the project
 and its structure.
@@ -49,7 +51,8 @@ Grade Linux repositories where the code resides:
 
     sudo apt-get install git 
 
-Also ensure that you have the latest BlueZ Linux Bluetooth headers and that g++ is installed on your system:
+Also ensure that you have the latest BlueZ Linux Bluetooth headers 
+and that g++ is installed on your system:
 
     sudo apt-get install libbluetooth-dev g++
 
@@ -57,22 +60,25 @@ Also ensure that you have the latest BlueZ Linux Bluetooth headers and that g++
 
 Install Erlang 18.2, or a later version 18 release:
 
-Tested packages of the latest versions of Erlang can be downloaded from [packages.erlang-solutions.com](https://www.erlang-solutions.com/resources/download.html)
+Tested packages of the latest versions of Erlang can be downloaded from 
+[packages.erlang-solutions.com](https://www.erlang-solutions.com/resources/download.html)
 
 Add the following line to your /etc/apt/sources.list
 
     deb http://packages.erlang-solutions.com/ubuntu trusty contrib
 
-Update and install erlang
+Update and install esl-erlang
 
     sudo apt-get update
-    sudo apt-get install erlang
+    sudo apt-get install esl-erlang
 
-**If you receive an authentication error** (such as NO_PUBKEY): note the hexadecimal value (e.g., 6D975C4791E7EE5E) and request the key:
+**If you receive an authentication error** (such as NO_PUBKEY): 
+note the hexadecimal value (e.g., 6D975C4791E7EE5E) and request the key:
 
-   sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys HEXVALUE
+    sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys HEX
 
-where HEXVALUE is the hexadecimal value specified in the error. Then rerun the ```update``` and ```install``` commands.
+where HEX is the hexadecimal value specified in the error. 
+Then rerun the ```update``` and ```install``` commands.
 
 ## CLONE THE RVI REPOSITORY ##
 
diff --git a/INSTALL_debian.md b/INSTALL_debian.md
new file mode 100644
index 0000000..590bc12
--- /dev/null
+++ b/INSTALL_debian.md
@@ -0,0 +1,111 @@
+Copyright (C) 2014-2016, Jaguar Land Rover
+
+This document is licensed under Creative Commons
+Attribution-ShareAlike 4.0 International.
+
+**Version 0.5.0**
+
+# INSTALLATION OF RVI (DEBIAN) #
+
+This document describes the installation process for the RVI project 
+on a Debian 8 ("jessie") Linux machine. Packages are also available 
+for [Ubuntu](INSTALL_ubuntu.md) and [Raspbian](INSTALL_raspbian.md). 
+See ```BUILD.md``` for building from source.
+
+Please see ```README.md``` for a general description of the project
+and its structure.
+
+Please see ```CONFIGURE.md``` for details on configuring and launching
+the system once it has been built.
+
+The first milestone of the RVI project is the HVAC demo. Please see
+```hvac_demo/README.md``` for details on how to setup, launch and
+drive the demo.
+
+# READER ASSUMPTIONS #
+In order to build the system, the reader is assumed to be able to:
+
+1. Have a basic understanding of Linux system operations.
+2. Install packages on the system.
+
+Please note that the configuration process described in
+```CONFIGURE.md``` may have additional skill requirements.
+
+# PREREQUISITES #
+
+1. The Debian 8 system has the latest updates installed.
+2. The user can gain root access to install packages.
+3. There is at least 5GB of space availabled for packages and code.
+
+----
+
+# INSTALLATION PROCESS #
+
+## INSTALL DEPENDENCIES ##
+
+Install dependent libraries via ```apt-get``` - note you must be root:
+
+    apt-get install python-jsonrpclib
+
+## INSTALL ESL-ERLANG ##
+
+Install `esl-erlang` 18.2, or a later version 18 release:
+
+Tested packages of the latest versions of Erlang can be downloaded from 
+[packages.erlang-solutions.com](https://www.erlang-solutions.com/resources/download.html)
+
+Add the following line to your /etc/apt/sources.list
+
+    deb http://packages.erlang-solutions.com/debian jessie contrib
+
+Update and install `esl-erlang`:
+
+    apt-get update
+    apt-get install esl-erlang
+
+**If you receive an authentication error** (such as NO_PUBKEY): note 
+the hexadecimal value (e.g., 6D975C4791E7EE5E) and request the key:
+
+    apt-key adv --keyserver keyserver.ubuntu.com --recv-keys HEX
+
+where HEX is the hexadecimal value specified in the error. 
+Then rerun the ```update``` and ```install``` commands.
+
+## DOWNLOAD AND INSTALL RVI ##
+
+Download the RVI package from https://github.com/PDXostc/rvi_core/releases.
+
+Then install RVI via dpkg:
+
+    sudo dpkg -i rvi_0.5.0-1_amd64.deb
+
+----
+
+## TEST THE RVI SYSTEM ##
+
+To confirm that RVI has started, use `systemctl` as root user:
+
+    systemctl status rvi
+
+Expected output:
+
+    ● rvi.service - Remote Vehicle Interaction Service
+       Loaded: loaded (/lib/systemd/system/rvi.service; disabled)
+       Active: active (running) since Mon 2016-02-22 14:16:27 PST; 15min ago
+      Process: 1922 ExecStart=/usr/bin/rvi_ctl -c /etc/rvi/rvi.config start (code=exited, status=0/SUCCESS)
+     Main PID: 1954 (run_erl)
+       CGroup: /system.slice/rvi.service
+           ├─1954 run_erl -daemon /tmp/rvi_1922/ /var/log/rvi exec erl -boot /tmp/rvi_1922/rvi/start -sname rvi -config /tmp/rvi_1922/rvi/sys -setcookie rvi_cookie
+           ├─1955 /usr/lib/erlang/erts-7.2/bin/beam.smp -- -root /usr/lib/erlang -progname erl -- -home /usr/lib/rvi_core -- -boot /tmp/rvi_1922/rvi/start -sname rvi -config /tmp/rvi_1922/rvi/sys -setcookie rvi_cookie
+           ├─1962 /usr/lib/erlang/erts-7.2/bin/epmd -daemon
+           ├─1983 /usr/lib/rvi_core/deps/bt/priv/bt
+           ├─1989 inet_gethost 4
+           └─1990 inet_gethost 4
+
+## CREATE A RELEASE ##
+
+The installer configures a release with default (insecure) credentials.
+
+See ```CONFIGURE.md``` for additional details on configuring and
+creating a developer and production release.
+
diff --git a/INSTALL_raspbian.md b/INSTALL_raspbian.md
new file mode 100644
index 0000000..7d0da34
--- /dev/null
+++ b/INSTALL_raspbian.md
@@ -0,0 +1,102 @@
+Copyright (C) 2014-2016, Jaguar Land Rover
+
+This document is licensed under Creative Commons
+Attribution-ShareAlike 4.0 International.
+
+**Version 0.5.0**
+
+# INSTALLATION OF RVI (RASPBIAN) #
+
+This document describes the installation process for the RVI project 
+on Raspbian. Packages are also available for 
+[Ubuntu](INSTALL_ubuntu.md) and [Raspbian](INSTALL_raspbian.md). 
+See ```BUILD.md``` for building from source.
+
+Please see ```README.md``` for a general description of the project
+and its structure.
+
+Please see ```CONFIGURE.md``` for details on configuring and launching
+the system once it has been built.
+
+The first milestone of the RVI project is the HVAC demo. Please see
+```hvac_demo/README.md``` for details on how to setup, launch and
+drive the demo.
+
+# READER ASSUMPTIONS #
+In order to build the system, the reader is assumed to be able to:
+
+1. Have a basic understanding of Linux system operations.
+2. Install packages on the system.
+
+Please note that the configuration process described in
+```CONFIGURE.md``` may have additional skill requirements.
+
+# PREREQUISITES #
+
+1. The Raspbian system has the latest updates installed.
+2. The user has sudo access to install packages.
+3. There is at least 5GB of space availabled for packages and code.
+
+----
+
+# INSTALLATION PROCESS #
+
+## GET RASPBIAN PACKAGES ##
+
+Download the Raspbian package from https://github.com/PDXostc/rvi_core/releases. Then extract the tarball to get packages for Erlang and RVI, as well as an install script.
+
+## INSTALL ERLANG AND RVI ##
+
+Make the install script executable:
+
+    sudo chmod +x installRVI
+
+Then run the install script:
+
+    ./installRVI
+
+This does the following:
+
+1. Extracts the Erlang tarball
+2. Installs the required Erlang packages
+  * `erlang-base`
+  * `erlang-asnl`
+  * `erlang-crypto`
+  * `erlang-eunit`
+  * `erlang-public key`
+  * `erlang-ssl`
+  * `erlang-syntax-tools`
+3. Installs other dependencies (`bluez` and `python-jsonrpclib`)
+4. Installs `rvi`
+5. Starts `rvi` via `systemctl`
+6. Checks the status of `rvi` via `systemctl`.
+
+----
+
+## TEST THE RVI SYSTEM ##
+
+To confirm that RVI has started, use `systemctl` as root user:
+
+    systemctl status rvi
+
+Expected output:
+
+    ● rvi.service - Remote Vehicle Interaction Service
+       Loaded: loaded (/lib/systemd/system/rvi.service; disabled)
+       Active: active (running) since Tue 2016-02-23 18:30:03 UTC; 48ms ago
+      Process: 6049 ExecStart=/usr/bin/rvi_ctl -c /etc/rvi/rvi.config start (code=exited, status=0/SUCCESS)
+     Main PID: 6081 (run_erl)
+       CGroup: /system.slice/rvi.service
+               ├─6081 run_erl -daemon /tmp/rvi_6049/ /var/log/rvi exec erl -boot /tmp/rvi_6049/rvi/start -sname rvi -config /tmp/rvi_6049/rvi/sys -setcookie rvi_cookie
+               ├─6084 /usr/lib/erlang/erts-7.2/bin/erlexec -boot /tmp/rvi_6049/rvi/start -sname rvi -config /tmp/rvi_6049/rvi/sys -setcookie rvi_cookie
+           ├─6093 sh -c "/usr/lib/erlang/erts-7.2/bin/epmd" -daemon
+               └─6094 /usr/lib/erlang/erts-7.2/bin/epmd -daemon
+
+
+## CREATE A RELEASE ##
+
+The installer configures a release with default (insecure) credentials.
+
+See ```CONFIGURE.md``` for additional details on configuring and
+creating a developer and production release.
+
diff --git a/INSTALL_ubuntu.md b/INSTALL_ubuntu.md
new file mode 100644
index 0000000..36ca07c
--- /dev/null
+++ b/INSTALL_ubuntu.md
@@ -0,0 +1,143 @@
+Copyright (C) 2014-2016, Jaguar Land Rover
+
+This document is licensed under Creative Commons
+Attribution-ShareAlike 4.0 International.
+
+**Version 0.5.0**
+
+# INSTALLATION OF RVI (UBUNTU 14.04 TRUSTY) #
+
+This document describes the installation process for the RVI project on 
+an Ubuntu 14.04 Linux machine. Packages are also available for 
+[Debian](BUILD_debian.md) and [Raspbian](BUILD_raspbian.md). 
+See [```BUILD.md```](BUILD.md) for building from source.
+
+Please see [```README.md```](README.md) for a general description of the project
+and its structure.
+
+Please see [```CONFIGURE.md```](CONFIGURE.md) for details on configuring and launching
+the system once it has been built.
+
+The first milestone of the RVI project is the HVAC demo. Please see
+```hvac_demo/README.md``` for details on how to setup, launch and
+drive the demo.
+
+# READER ASSUMPTIONS #
+In order to build the system, the reader is assumed to be able to:
+
+1. Have a basic understanding of Linux system operations.
+2. Install packages on the system.
+
+Please note that the configuration process described in
+```CONFIGURE.md``` may have additional skill requirements.
+
+# PREREQUISITES #
+
+1. The Ubuntu 14.04 system have the latest updates installed.
+2. The user can gain root access to install packages.
+3. There is at least 5GB of space availabled for packages and code.
+
+----
+
+<div class="pagebreak"></div>
+
+# INSTALLATION PROCESS #
+
+## INSTALL DEPENDENCIES ##
+
+Install dependent libraries via `apt-get`:
+
+    sudo apt-get install python-jsonrpclib
+
+## INSTALL ESL-ERLANG ##
+
+Install `esl-erlang` 18.2, or a later version 18 release:
+
+Tested packages of the latest versions of Erlang can be downloaded from 
+[packages.erlang-solutions.com](https://www.erlang-solutions.com/resources/download.html)
+
+Add the following line to your /etc/apt/sources.list
+
+    deb http://packages.erlang-solutions.com/ubuntu trusty contrib
+
+Update and install esl-erlang
+
+    sudo apt-get update
+    sudo apt-get install esl-erlang
+
+**If you receive an authentication error** (such as NO_PUBKEY): 
+note the hexadecimal value (e.g., 6D975C4791E7EE5E) and request the key:
+
+    sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys HEX
+
+where HEX is the hexadecimal value specified in the error. 
+Then rerun the ```update``` and ```install``` commands.
+
+## DOWNLOAD AND INSTALL RVI ##
+
+Download the RVI package from https://github.com/PDXostc/rvi_core/releases. 
+
+Then install RVI via dpkg:
+
+    sudo dpkg -i rvi_0.5.0-1ubuntu1_amd64.deb
+
+----
+
+## TEST THE RVI SYSTEM ##
+
+To confirm that RVI has installed successfully, run:
+
+    sudo service rvi start
+
+Expected output:
+
+     * Starting Remote Vehicle Interaction Node... rvi                       [ OK ] 
+
+Find out which services are registered through `rvi_get_services`:
+
+    /usr/lib/rvi_core/rvi_get_services
+
+The command should return no output, since we have not registered any services yet.
+
+Register a service by calling `rvi_service` -- start with "hello":
+
+    /usr/lib/rvi_core/rvi_service hello
+
+Expected output:
+
+    RVI General Service.
+    RVI node URL:         http://localhost:9001
+    Service:              genivi.org/vin/default_vin/hello
+    Press enter to quit: 
+
+In another terminal, call `rvi_get_services` again to see the newly registered service:
+
+    genivi.org/vin/default_vin/hello
+
+Invoke the service through `rvi_call` and the full service name:
+
+    /usr/lib/rvi_core/rvi_call genivi.org/vin/default_vin/hello
+
+In terminal 1 (where you called `rvi_service`), you should see the following output:
+
+    Service invoked!
+    args: {}
+
+In terminal 2 (where you called `rvi_call`), you should see the following output:
+
+    RVI Node:          http://localhost:9001
+    Service:           genivi.org/vin/default_vin/hello
+    args:              {}
+
+You can pass arguments to a service call with the format name=value:
+
+    /usr/lib/rvi_core/rvi_call genivi.org/vin/default_vin/hello \
+    a=b message=hello
+
+## CREATE A RELEASE ##
+
+The installer configures a release with default (insecure) values.
+
+See ```CONFIGURE.md``` for details on configuring and creating a
+developer and production release that can be launched.
+
diff --git a/README.debian_build b/README.debian_build
deleted file mode 100644
index 8614727..0000000
--- a/README.debian_build
+++ /dev/null
@@ -1,14 +0,0 @@
-Erlang
-
-apt-get install devscripts
-apt-get install bluez
-apt-get install libbluetooth-dev 
-apt-get install git
-apt-get install g++
-apt-get install make
-apt-get install python-jsonrpclib
-apt-get install libwxgtk3.0-0
-apt-get install dh-systemd
-
-wget https://packages.erlang-solutions.com/erlang/esl-erlang/FLAVOUR_1_general/esl-erlang_18.2-1~debian~jessie_amd64.deb
-dpkg -i esl-erlang_18.2-1~debian~jessie_amd64.deb
diff --git a/README.md b/README.md
index 3f1db3b..ef8e0c3 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
-Copyright (C) 2014-2015 Jaguar Land Rover
+Copyright (C) 2014-2016 Jaguar Land Rover
 
 This document is licensed under Creative Commons
 Attribution-ShareAlike 4.0 International.
 
-# REMOTE VEHICLE INTERACTION (RVI) 0.4.0 #
+# REMOTE VEHICLE INTERACTION (RVI) 0.5.0 #
 
 This document gives a brief introduction to the codebase of the RVI
 project and explains the reasoning behind some of the technical
@@ -15,6 +15,10 @@ For a high level description, with an exhaustive master use-case
 walkthrough, please see the High Level Design document 
 [here](https://wiki.automotivelinux.org/_media/eg-rvi/15-456-poc-rvi-hld_reva.pdf) (**NOTE: HLD not updated to reflect RVI Core 0.5.0**)
 
+Packages are available for some distributions. See installation
+instructions for [Ubuntu](INSTALL_ubuntu.md), [Debian](INSTALL_debian.md),
+and [Raspbian](INSTALL_raspbian.md).
+
 For build instructions, please check the **build instructions**:
 [Markdown](BUILD.md) | 
 [PDF](doc/pdf/BUILD.pdf)
@@ -87,8 +91,8 @@ RVI shall be able to function over transient and unreliable data channels, but a
 # TECHNOLOGY CHOICES #
 The following chapters describe the technology choices made for the
 reference implementation.  An overall goal was to avoid technology
-lock-in while easing adoption by allowing organiztions to replace
-individual components with in-house developted variants using their
+lock-in while easing adoption by allowing organizations to replace
+individual components with in-house developed variants using their
 own technology.
 
 ## INTERCHANGEABILITY ##
@@ -109,7 +113,7 @@ and a backend server, in an RVI network. An organization is free to
 integrate with any existing protocols, or develop new ones, as
 necessary.
 
-The reference implemantation provides an example of how to handle a
+The reference implementation provides an example of how to handle a
 classic client-server model. The RVI design, however, can easily
 handle such cases such as wakeup-SMS (used to get a vehicle to call in
 to a server), packet-based data, peer-to-peer networks without any
@@ -121,7 +125,7 @@ management and data encoding / decoding over any media (IP or non-IP).
 [Erlang](http://www.erlang.org) was chosen to implementation the core
 components of the RVI system. Each component (see the
 [HLD](https://wiki.automotivelinux.org/_media/eg-rvi/15-456-poc-rvi-hld_reva.pdf)
-for details) run as an erlang application inside a single erlang node.
+for details) run as an Erlang application inside a single Erlang node.
 
 Several reasons exist for this somewhat unorthodox choice of
 implementation language:
@@ -129,32 +133,32 @@ implementation language:
 * **Robustness**<br>
 Erlang has the ability to gracefully handle component crashes /
 restarts without availability degradation. This makes a deployment
-resiliant against the occasional bug and malfunction. In a similar
+resilient against the occasional bug and malfunction. In a similar
 manner, redundant sites can be setup to handle catastrophic failures
 and geographically distributed deployments.
 
 * **Tool availability**<br>
-There are a multitude of open source erlang components available to
+There are a multitude of open source Erlang components available to
 handle SMS, GPIO, CAN buses, GPS, PPP links, and almost any protocol
-out there. Since erlang was designed to handle the mobile
+out there. Since Erlang was designed to handle the mobile
 communication requirements that is at the center of the connected
 vehicle, integrating with existing systems and protocols is often a
 straight-forward process.
 
 * **Scalability**<br>
-The concurrent nature of an erlang system sets the stage for
+The concurrent nature of an Erlang system sets the stage for
 horizontal scalaility by simply adding hosts to a deployment, allowing
-an organziation to expand from a pilot fleet to a full fledged
+an organization to expand from a pilot fleet to a full fledged
 international deployment.
 
 * **Carrier grade availability**<br>
-The robustness and scalaiblity, in conjunction with the built-in
-erlang feature of runtime code upgrades, is a part of erlang's
+The robustness and scalability, in conjunction with the built-in
+Erlang feature of runtime code upgrades, is a part of Erlang's
 five-nines uptime design that is rapidly becoming a core requirement
 of the automotive industry.
  
 * **Proven embedded system solution**<br>
-Erlang has been adapted to operate well in embeded environments
+Erlang has been adapted to operate well in embedded environments
 with unreliable power, limited resources, and the need to integrate
 with a wide variety of hardware.
 
@@ -162,7 +166,7 @@ with a wide variety of hardware.
 Python is used to implement all demonstrations, beginning
 with the HVAC demo available in the `hvac_demo` subdirectory.
 
-By using Python for the demos, which is better known than erlang,
+By using Python for the demos, which is better known than Erlang,
 examples are given on how to write applications and services
 interfacing with the RVI system.
 
@@ -175,38 +179,39 @@ understanding and adoption.
 One example is the use of JSON-RPC (over HTTP) to handle internal
 communication between components in a single Erlang node.
 
-Using a traditional erlang solution such as genserver, the
+Using a traditional Erlang solution such as genserver, the
 overhead for internal transactions could be cut to a few percent in
 comparison with the current JSON-RPC implementation. That route,
 however, would force all components of the RVI system to be
-implemented in Erlang, thus severly limiting an organizations
+implemented in Erlang, thus severely limiting an organization's
 abilities to replace individual components with their own versions.
 
 
 ## CODE STRATEGY ##
-All code in the RVI reference implementaion and its demonstrations are
+All code in the RVI reference implementation and its demonstrations are
 written with a minimum of complexity and "magic". Readability is
-paramount, even if it severly impact performance and memory usage.
+paramount, even if it severely impacts performance and memory usage.
+
 
-All components in the RVI are kept small and distcinct, with a
-well-defined JSON-RPC external interface and a simple call flows.
+All components in the RVI are kept small and distinct, with a
+well-defined JSON-RPC external interface and simple call flows.
 
 Only three external modules (lager, bert and exo) are used by the
 code, with two more (setup and edown) used for release and
 documentation management.
 
 The reason for minimizing external module usage is to make the code
-comprehensible and minimize the time a developer has to travesrse
+comprehensible and minimize the time a developer has to traverse
 through obscure libraries trying to understand what a specific call
 flow actually does.
 
-The entire reference implementation (as of the first alpa release) is
+The entire reference implementation (as of the first alpha release) is
 2800 lines of code, broken down into six standalone modules and one
 library of shared primitive functions.
 
 ## JSON-RPC ##
-JSON-RPC is  used for all  communication between components in  an RVI
-system, and  also to  communicate with services  connected to  it. The
-ubiquity of JSON-RPC, and its close relationship with Java/Javascript,
+JSON-RPC is used for all communication between components in an RVI
+system, and also to communicate with services connected to it. The
+ubiquity of JSON-RPC, and its close relationship with Java/JavaScript,
 provides maximum of freedom of technology choices when new components,
 services, and applications are developed.