Updated documentation for p2p demo

Signed-off-by: Magnus <mfeuer@jaguarlandrover.com>

5 files changed, 215 insertions, 170 deletions

diff --git a/CONFIGURE.md b/CONFIGURE.md
index 5c1f0d1..0974f98 100644
--- a/CONFIGURE.md
+++ b/CONFIGURE.md
@@ -143,7 +143,7 @@ An example entry is given below:
 The external rvi node address is the address, as seen from the outside
 world, where this node's data link can be contacted. In IP based
 networks, this is usually a ```hostname:port``` value. In SMS-only
-networks, this would be the MSISDN of the node's mobile subscription.
+networks, this will be the MSISDN of the node's mobile subscription.
 Any traffic directed to the given address should be forwarded to the 
 Data Link component.
 
@@ -252,6 +252,13 @@ An example entry is gven below:
 *Please note that IP addresses, not DNS names, should be used in all
  network addresses.*
 
+**Please note that all nodes configured in ```static_nodes``` must be
+up and running, listening on their specified addresses, before the
+node with the ```static_nodes``` configuration entry comes up.  All
+static nodes are connected to during the startup sequence, and if one
+or more are not available, the startup sequence will fail. This will
+be fixed in future versions.**
+
 
 # SPECIFY SERVICE EDGE URL #
 
diff --git a/hvac_demo/README.md b/hvac_demo/README.md
index 505d46a..68a86dc 100644
--- a/hvac_demo/README.md
+++ b/hvac_demo/README.md
@@ -18,7 +18,6 @@ protocol (See http://mqtt.org). The first milestone of the RVI project
 will migrate the HVAC demo to the RVI technology.
 
 ## READER ASSUMPTIONS
-
 The reader is assumed to be able to:
 
 1. Have a basic understanding of Linux directory structures.
@@ -26,71 +25,120 @@ The reader is assumed to be able to:
 
 
 # PREREQUISITES
+1. Erlang runtime R16B01 or later has to be installed on the hosting
+system.
+
+2. The RVI system has been checked out from
+[gerrit](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/RVI/rvi).
 
-1. Erlang runtime R16B01 or later has to be installed on the hosting system.
-2. The ```setup_rvi_node.sh``` tool is available to build a release.
-3. The ```rvi_node.sh``` tool is available to execute a release.
-4. ```hvac_demo/``` is available with its demo code and configuration files.
+3. The RVI system has been built. See
+[build instructions](../BUILD.md) for details.
 
+*Please do not execute the configuration instructions in [CONFIGURE.md](../CONFIGURE.md)*
 
 # DEMO COMPONENTS
 
-The demo is broken into three components that connect to two RVI
-nodes. All components can be run on a single system.
+In order to test the RVI milestone 1 without having to bring up a
+complete Tizen IVI and mobile device environment, a simple emulator
+for these two components have been provided in hvac\_emulator.py and
+mobile\_emulator.py
+
+All components can be run on a single system.
 
 Please see schematics below for an overview:
 
-![Demo Schematics](hvac_demo.png "Demo Schematics")
-*Figure 1. Demo schematics*
+![Demo Schematics](hvac_demo.png "Demo Schematics")<br>
+*Figure 1. Demo schematics. See HVAC and mobile device emulator chapters for details*
 
-## SUBSCRIPTION SERVICE
-This directory contains a simple subscription service
-(subscription\_service.py) replacing the MQTT broker. The
-subscription service lets the vehicle and mobile devices setup
-subscriptions so that they receive notifications when the HVAC values
-for a specific VIN (Vehicle Identification Number) have been
-updated. The service is, in effect, a standard publish/subscribe
-setup. 
 
-## HVAC EMULATOR
-In order to test the RVI milestone 1 and the subscription service
-without having to bring up a complete Tizen IVI and mobile device
-environment, a simple emulator for these two components have been
-provided in hvac\_emulator.py and mobile\_emulator.py
+## HVAC EMULATOR TECHNICAL DETAILS
+The HVAC emulator simulates an HVAC application unit installed in a
+vehicle.
 
-The HVAC emulator simulates the HVAC application running on a head unit
-in a vehicle. It uses a VIN number, a part of the service prefix
-of the vehicle RVI node, as a unique identifier and subscribes to HVAC
-updates, such as fan speed, originating from the mobile device
-emulator. 
+The emulator connects to the Service Edge of the vehicle RVI node,
+started with "rvi_node -n vehicle" and registers two services with it:
 
-The HVAC emulator can also have new HVAC values entered on
-the command line and send them to any connected mobile device
-emulators.
+* ```jlr.com/vin/[vin]/hvac/subscribe```<br>
+  Used by the mobile emulator to subscribe to updates entered on the
+  HVAC emulator's command line.
 
-All subscriptions and updates are bounced off the subscription service
-connected to the backend RVI node.
+* ```jlr.com/vin/[vin]/hvac/publish```<br>
+   Used by the mobile emulator to report updated values entered on 
+   its command line
 
-## MOBILE DEVICE EMULATOR
+In both cases, ```jlr.com/vin/[vin]``` is the vehicle RVI node's service
+prefix specified in
+```vehicle.configure```->```env```->```rvi```->```node_service_prefix```.
 
-The mobile device emulator connects to the backend server and
-registers itself as a service where a phone number, provided as a
-command line argument, is a part of the service name. The mobile
-controls a specific VIN, also provided as a command line argument. 
 
-Just like the HVAC emulator, the all subscriptions and updates are
-bounced of the subscription service.
+The mobile emulator invokes the subscribe service above in order
+to receive new HVAC values published by the HVAC emulator.
+  
+When a new key/value pair is entered on the HVAC emulator's command line,
+The mobile emulator services registered through an /hvac/subscribe
+message will be invoked with the key, value, and VIN number
+of the HVAC's RVI node. The receiving mobile emulators will
+print out the information.
 
+If a new key/value pair is entered on a mobile emulator's command
+line, they will be sent to the HVAC emulator's /hvac/publish service, 
+which will print them on screen.
 
-# DEMO SETUP
 
+## MOBILE DEVICE EMULATOR TECHNICAL DETAILS
+
+The mobile device emulator connects to Service Edge of the backend
+  server, started with "./rvi_node -n backend", and subscribes to
+  HVAC updates (temp, fan speed, etc) updates from the vehicle with a
+  given VIN. 
+
+At startup, the mobile emulator will do two things:
+ 
+1. Register a service with the backend RVI node<br>
+   This service is invoked by the HVAC emulator to transmit 
+   key/value pairs entered on its commandd line.
+
+   The service name has the following layout:
+
+       ```jlr.com/backend/mobile/[phone_nr]/hvac/publish```
+ 
+   The ```jlr.com/backend``` prefix is the backend RVI node's service prefix specified in
+   ```backend.configure```->```env```->```rvi```->```node_service_prefix```.
+
+   The ```[phone_nr]``` is the phone number specified on the command
+   line when the mobile emulator is started.
+
+2. Send a suscription request to the HVAC emulator<br>
+   The HVAC emulator's subscription service is invoked as
+ 
+      ```jlr.com/vin/[vin]/hvac/subscribe```
+
+   where ```[vin]``` is the command-line specified VIN of the 
+   vehicle RVI node to connect to.
+   The subscription request's single parameter is the full name of
+   the publish service registered in step 1.  When the HVAC
+   emulator has a key/value pair entered at its command line, the
+   key/value/vin will be sent to the publish service on the mobile
+   emulator.
+    
+
+   When a new key/value pair is entered on the mobile emulator's
+   command line, simulating screen input on the HVAC app, the
+   key/value pair will be sent to:
+
+      ```jlr.com/vin/[vin]/hvac/publish```
+
+   The HVAC emulator will receive the published key/value pair and
+   print it on screen.
+
+
+# DEMO SETUP
 Two RVI nodes, both hosted by a single machine, will be involved in
 the test:
 
-The backend RVI node will host the subscription service
-(subscription\_service.py) and the mobile emulator (mobile\_emulator.py).
-
-The vehicle RVI node will host the HVAC emulator (hvac\_emulator.py).
+The backend RVI node will the mobile emulator
+(mobile\_emulator.py). The vehicle RVI node will host the HVAC
+emulator (hvac\_emulator.py).
 
 ## COMPILE THE RVI SYSTEM
 See ../BUILD.md for details.
@@ -108,7 +156,6 @@ The new developer release will be created in a subdiretory named
 
 
 ## CREATE THE BACKEND DEVELOPMENT RELEASE
-
 In a similar manner, setup the backend node:
 
     ./setup_rvi_node.sh backend hvac_demo/backend.config
@@ -116,24 +163,8 @@ In a similar manner, setup the backend node:
 
 The release will be created in a subdiretory named ```backend```
 
-
-## LAUNCH THE VEHICLE RVI NODE
-
-In its own window, launch the vehicle RVI node that will serve the HVAC emulator.
-
-	./rvi_node.sh -n vehicle
-
-The VIN number that will be used by the mobile device are the digits
-at the end of the "Node Service Prefix" printed out at the end of the
-launch process. 
-
-By default, the ```hvac_demo/vehicle.config``` file has its
-```node_service_prefix``` entry set to ```jlr.com/vin/1234/```,
-yielding a VIN of "1234". 
-
 # DEMO LAUNCH
 
-
 ## LAUNCH THE BACKEND RVI NODE
 
 In its own window, launch the backend rvi node that the subscription
@@ -144,16 +175,21 @@ service and mobile device emulator will connect to.
 Make a note of the Service Edge URL address printed out by the logging service.
 
 
-## LAUNCH THE SUBSCRIPTION SERVICE
+## LAUNCH THE VEHICLE RVI NODE
 
-In its own window, launch the subscription service and specify the URL
-of the backend RVI node's Service Edge:
+* Please note that the backend node must be started before the vehicle node. *
 
-    cd hvac_demo
-    ./subscription_service.py http://127.0.0.1:8801 
-	
-Modify the ```http://127.0.0.1:8801``` to match the URL reported by
-the backend RVI node.
+In its own window, launch the vehicle RVI node that will serve the HVAC emulator.
+
+	./rvi_node.sh -n vehicle
+
+The VIN number that will be used by the mobile device are the digits
+at the end of the "Node Service Prefix" printed out at the end of the
+launch process. 
+
+By default, the ```hvac_demo/vehicle.config``` file has its
+```node_service_prefix``` entry set to ```jlr.com/vin/1234/```,
+yielding a VIN of "1234". 
 
 
 ## LAUNCH THE HVAC EMULATOR
@@ -177,8 +213,8 @@ node.
 
 ## LAUNCH THE MOBILE DEVICE EMULATOR
 
-In its own window, launch the mobile device emulator and have it connect to
-the backend RVI node.
+In its own window, launch the mobile device emulator and have it
+connect to the backend RVI node.
 
     cd hvac_demo
     ./mobile_emulator.py  http://127.0.0.1:8801 +1941231234 1234
@@ -189,7 +225,8 @@ reported by the backend RVI node.
 The phone number (+19491231234) is arbitrary, but has to be unique
 across all running mobile device emulators.
 
-The VIN number (1234) is the VIN number reported by the HVAC emulator at startup.
+The VIN number (1234) is the VIN number reported by the HVAC emulator
+at startup.
 
 The mobile device emulator accepts \[key\] \[value\] input lines that
 are distributed to the vehicle with the matching VIN.
@@ -222,5 +259,3 @@ Terminate the subscription service by pressing Ctrl-c.
 Terminate the vehicle RVI node by pressing Ctrl-c Ctrl-c.
 
 Terminate the backend RVI node by pressing Ctrl-c Ctrl-c.
-
-
diff --git a/hvac_demo/hvac_demo.png b/hvac_demo/hvac_demo.png
index b3f48a0..e31b864 100644
--- a/hvac_demo/hvac_demo.png
+++ b/hvac_demo/hvac_demo.png
diff --git a/hvac_demo/hvac_emulator.py b/hvac_demo/hvac_emulator.py
index 6f48ef0..75989f0 100755
--- a/hvac_demo/hvac_emulator.py
+++ b/hvac_demo/hvac_emulator.py
@@ -11,45 +11,39 @@
 #
 # Emulate an HVAC apoplication
 #
-#  This emulator connects to an RVI Service Edge as a service and
-#  simulates an HVAC application unit installed in a vehicle.
-#
-#  The emulator connects to the Service Edge of locally accessible RVI
-#  node and subscribes to updates from one or more mobile
-#  devices. Local updates, simulating GUI input on the HVAC screen,
-#  can be entered at the command line and will be distributed to the
-#  phone(s) subscribing to updates from the HVAC.
-#
-#  Any HVAC values updated on the command line are sent to the
-#  service jlr.com/backend/hvac/subscription_service/publish. This
-#  service will look up VIN targeted by the update and send out the
-#  same data to all services that are subscribing to that VIN.
+#  This emulator connects to the Service Edge of the vehicle RVI node
+#  as a service and simulates an HVAC application unit installed in a
+#  vehicle.
+#
+#  The emulator connects to the Service Edge of its local RVI node,
+#  started with "rvi_node -n vehicle" and registers two services with it:
+#
+#  /hvac/subscribe - Used by the mobile emulator to subscribe to
+#                    updates entered on the HVAC emulator's command
+#                    line.
+#
+#  /hvac/publish - Used by the mobile emulator to report updated
+#                  values entered on its command line
+#
+#  Mobile emulators invoke the subscribe service above in order
+#  to receive new HVAC values published by the HVAC emulator.
 #  
-#  I, the emulator will subscribe to updated
-#  values published to to the VIN value "hvac_[vin]" where vin is the
-#  VIN number of the vehicle.  When a emulator, still in mobile device
-#  mode, sends out an updated value (entered in the python console),
-#  it will publish the value using the vin "mobile_[vin]"
-#
-#  Converesely, an the HVAC emulator will sbuscribe to
-#  "mobile_[vin]", and publish to "hvac_[vin]".
-#
-#  This setup allows the mobile device emulator to receive updates
-#  entered on the IVI HVAC screen (sent out by the HVAC emulator to
-#  "hvac_[vin]"), while the HVAC emulator receives updates entered on
-#  the mobile device screen (sent out by the mobile device to
-#  "mobile_[vin]".
-#
-#  When the HVAC emulatore connects to the vehicle RVI node, the
-#  node's configured service prefix (see hvac_demo/vehicle.config,
-#  node_service_prefix) will have the VIN number as a part of the
-#  prefix. The emulator will thus register its service as /hvac/publish,
-#  which, prefixed with the node service prefix, gives it a complete name
-#  of jlr.com/vin/[vin]/hvac/publish.
-#
-#
-# Example:
-#  python hvac_mobile_emulator.pyh 9491231234 http://127.0.0.1:8811
+#  When a new key/value pair is entered on the HVAC emulator's command line,
+#  The mobile emulator services registered through an /hvac/subscribe
+#  message will be invoked with the key, value, and VIN number
+#  of the HVAC's RVI node. The receiving mobile emulators will
+#  print out the information.
+#
+#  If a new key/value pair is entered on a mobile emulator's command
+#  line, they will be sent to the HVAC emulator's /hvac/publish service, 
+#  which will print them on screen.
+#
+# Invocation Example:
+#  python hvac_emulator.py http://127.0.0.1:8811
+#
+#  http://127.0.0.1:8811 is the RVI node's Service Edge URL.
+#  See vehicle.conf's env -> rvi -> components -> service_edge -> url
+#  for the correct value.
 #
 import sys
 from rvi_json_rpc_server import RVIJSONRPCServer
diff --git a/hvac_demo/mobile_emulator.py b/hvac_demo/mobile_emulator.py
index eabb4fc..c9078da 100755
--- a/hvac_demo/mobile_emulator.py
+++ b/hvac_demo/mobile_emulator.py
@@ -11,57 +11,65 @@
 #
 # Emulate a mobile device.
 #
-#  The mobile device emulator connects to Service Edge of the
-#  backend server, and subscribes to HVAC updates (temp, fan speed,
-#  etc) updates from an vehicle with a given VIN. The emulator can also
-#  update HVAC values, simulating HVAC GUI input on the mobile device
-#  screen, and send it off to the backend server Service Edge for
-#  further distribution to the targeted vehicle.
+#  The mobile device emulator connects to Service Edge of the backend
+#  server, started with "./rvi_node -n backend", and subscribes to
+#  HVAC updates (temp, fan speed, etc) updates from the vehicle with a
+#  given VIN. 
 #
+#  At startup, the mobile emulator will do two things:
 #  
-#  Updates entered on the command line are are sent to the backend node
-#  service jlr.com/backend/hvac/subscription_service/publish. This
-#  service will look up VIN targeted by the update and send out the
-#  same data to all services that are subscribing to that VIN.
-#  
-#  The mobile device emulator will subscribe to updated values
-#  published to to the VIN value "hvac_[vin]" where vin is the VIN
-#  number of the vehicle.  When a mobile device emulator
-#  sends out an updated value (entered in the python console), it will
-#  publish the value using the vin "mobile_[vin]"
-#
-#  Converesely, an HVAC emulator will sbuscribe to
-#  "mobile_[vin]", and publish to "hvac_[vin]".
-#
-#  This setup allows the mobile device emulator to receive updates
-#  entered at the HVAC emulator's command promp (sent out by the HVAC
-#  emulator to "hvac_[vin]"), while the HVAC emulator receives updates
-#  entered on the mobile device screen (sent out by the mobile device
-#  to "mobile_[vin]").
-#
-#  The emulator will register with a phone number as a part of its
-#  service name, where the phone number is specified as a command line
-#  argument.
-#
-#  Since the backend RVI node that the mobile device emulator connects
-#  to has a service prefix of jlr.com/backend (see
-#  backend.config), the mobile device emulator will have a
-#  complete service name of:
-#  jlr.com/backend/mobile/[phone_number]/hvac/publish
-#
-#  The VIN of the vehicle whose HVAC to manage is also provided as a
-#  command line argument.
+#  1. Register a service with the backend RVI node. 
+#   
+#     This service is invoked by the HVAC emulator to transmit 
+#     key/value pairs entered on its commandd line.
 #
+#     The service name has the following layout:
+#       jlr.com/backend/mobile/[phone_nr]/hvac/publish
+# 
+#     The jlr.com/backend prefix is added by the RVI node to make
+#     the service globally unique. The [phone_nr] is the command-line
+#     specified phone number.
+#
+#  2. Send a suscription request to the HVAC emulator.
+#     The HVAC emulator's subscription service is invoked as
+#       jlr.com/vin/[vin]/hvac/subscribe
+#
+#     where [vin] is the command-line specified VIN of the 
+#     vehicle RVI node to connect to.
+#     The subscription request's only parameter is the full name of
+#     the publish service registered in step 1.  When the HVAC
+#     emulator has a key/value pair entered at its command line, the
+#     key/value/vin will be sent to the publish service on the mobile
+#     emulator.
+#    
+#
+#  When a new key/value pair is entered on the mobile emulator's
+#  command line, simulating screen input on the HVAC app, the
+#  key/value pair will be sent to:
+#    jlr.com/vin/[vin]/hvac/publish
+#
+#  The HVAC emulator will receive the published key/value pair and
+#  print it on screen.
+#  
 # Usage:
 #
-# python hvac_emulator.py <rvi_url> <phone_number> <vin>
+# python mobile_emulator.py <rvi_url> <phone_number> <vin>
 #
-# Example:
-#  Regsiter on Service edge with URL http://127.0.0.1:8811, using
-#  phone number +19491231234 and controlling the vehicle with VIN 1234.
-#
-#    python hvac_emulator.py http://127.0.0.1:8811 +19491231234 1234
+# Example: mobile_emulator.py http://127.0.0.1:8801 +19491231234 1234
 #
+#  http://127.0.0.1:8801 is the RVI node's Service Edge URL.
+#  See backend.conf's env -> rvi -> components -> service_edge -> url
+#  for the correct value.
+# 
+#  +19491231234 is the phone number. 
+#  It can be an arbitrary value, but has to be unique across all
+#  registered mobile emulators.
+#
+#  1234 is the VIN number of the vehicle RVI node.
+#  Please see the last field in the vehicle.config's 
+#  env -> rvi -> node_prefix configuration entry for
+#  the correct value.
+#  
 
 import sys
 from rvi_json_rpc_server import RVIJSONRPCServer
@@ -69,6 +77,20 @@ import jsonrpclib
 import random
 import threading
 
+def usage():
+    print "Usage:", sys.argv[0], " <rvi_url> <phone_number> <vin>"
+    print "  <rvi_url>        URL of RVI Service Edge on local host."
+    print "  <phone_number>   Phone number to register emulator as."
+    print "  <vin>            The VIN that the mobile device is to control."
+    print
+    print "The RVI Service Edge URL can be found in"
+    print "[backend,vehicle].config as"
+    print "env -> rvi -> components -> service_edge -> url"
+    print
+    print "The Service Edge URL is also logged as a notice when the"
+    print "RVI node is started."
+    sys.exit(255)
+
 #
 # Publish command is invoked by the 
 # subscriber server above when it receives a publish command
@@ -85,19 +107,6 @@ def publish(vin, key, value):
     sys.stdout.flush()
     return ['ok']
 
-def usage():
-    print "Usage:", sys.argv[0], " <rvi_url> <phone_number> <vin>"
-    print "  <rvi_url>        URL of RVI Service Edge on local host."
-    print "  <phone_number>   Phone number to register emulator as."
-    print "  <vin>            The VIN that the mobile device is to control."
-    print
-    print "The RVI Service Edge URL can be found in"
-    print "[backend,vehicle].config as"
-    print "env -> rvi -> components -> service_edge -> url"
-    print
-    print "The Service Edge URL is also logged as a notice when the"
-    print "RVI node is started."
-    sys.exit(255)
 
 
 #