moved files to subdirs, w.i.p. on fragmentation

15 files changed, 133 insertions, 11 deletions

diff --git a/CONFIGURE.md b/CONFIGURE.md
index 1b848a5..9364ba3 100644
--- a/CONFIGURE.md
+++ b/CONFIGURE.md
@@ -596,23 +596,23 @@ external node address chapter:
 
 Communication between the RVi components can be either JSON-RPC or
 Erlang-internal gen\_server calls.
-	
-JSON-RPC calls provide compatability with replacement components
+
+JSON-RPC calls provide compatibility with replacement components
 written in languages other than Erlang. gen\_server calls provide
 native erlang inter-process calls that are signficantly faster than
 JSON-RPC when transmitting large data volumes.
-	
+
 If one or more of the RVI components are replaced with external
 components, use JSON-RPC by ```json_rpc_address```
 for all components.
-	
+
 If an all-native erlang system is configured, use gen\_server calls
 by configuring ```gen_server```.
 
 If both ```gen_server``` and ```json_rpc_address``` are specified, the
 gen\_server communicaiton path will be used for inter component
 communication.
-	
+
 Please note that communication between two RVI nodes are not affected
 by this since data_link_bert_rpc will use the protocol and data links
 specified by the matching routing rule to communicate. See
diff --git a/doc/images/frag-overview.png b/doc/images/frag-overview.png
new file mode 100644
index 0000000..ad866c4
--- /dev/null
+++ b/doc/images/frag-overview.png
diff --git a/doc/rvi_protocol_double_connect1.png b/doc/images/rvi_protocol_double_connect1.png
index 21ad892..21ad892 100644
--- a/doc/rvi_protocol_double_connect1.png
+++ b/doc/images/rvi_protocol_double_connect1.png
diff --git a/doc/rvi_protocol_double_connect2.png b/doc/images/rvi_protocol_double_connect2.png
index d14f92d..d14f92d 100644
--- a/doc/rvi_protocol_double_connect2.png
+++ b/doc/images/rvi_protocol_double_connect2.png
diff --git a/doc/rvi_protocol_flow.png b/doc/images/rvi_protocol_flow.png
index eb06363..eb06363 100644
--- a/doc/rvi_protocol_flow.png
+++ b/doc/images/rvi_protocol_flow.png
diff --git a/doc/rvi_protocol_frag1.png b/doc/images/rvi_protocol_frag1.png
index aedb46e..aedb46e 100644
--- a/doc/rvi_protocol_frag1.png
+++ b/doc/images/rvi_protocol_frag1.png
diff --git a/doc/rvi_protocol_stack.png b/doc/images/rvi_protocol_stack.png
index 043beaa..043beaa 100644
--- a/doc/rvi_protocol_stack.png
+++ b/doc/images/rvi_protocol_stack.png
diff --git a/doc/rvi_protocol_x509_credential.png b/doc/images/rvi_protocol_x509_credential.png
index d63bb24..d63bb24 100644
--- a/doc/rvi_protocol_x509_credential.png
+++ b/doc/images/rvi_protocol_x509_credential.png
diff --git a/doc/rvi_protocol_x509_pub_key.png b/doc/images/rvi_protocol_x509_pub_key.png
index f685ad7..f685ad7 100644
--- a/doc/rvi_protocol_x509_pub_key.png
+++ b/doc/images/rvi_protocol_x509_pub_key.png
diff --git a/doc/rvi_protocol_double_connect1.msc b/doc/msc/rvi_protocol_double_connect1.msc
index eb22f83..eb22f83 100644
--- a/doc/rvi_protocol_double_connect1.msc
+++ b/doc/msc/rvi_protocol_double_connect1.msc
diff --git a/doc/rvi_protocol_double_connect2.msc b/doc/msc/rvi_protocol_double_connect2.msc
index 0240df5..0240df5 100644
--- a/doc/rvi_protocol_double_connect2.msc
+++ b/doc/msc/rvi_protocol_double_connect2.msc
diff --git a/doc/rvi_protocol_flow.msc b/doc/msc/rvi_protocol_flow.msc
index f4a84b3..f4a84b3 100644
--- a/doc/rvi_protocol_flow.msc
+++ b/doc/msc/rvi_protocol_flow.msc
diff --git a/doc/rvi_protocol_frag1.msc b/doc/msc/rvi_protocol_frag1.msc
index 11d467f..11d467f 100644
--- a/doc/rvi_protocol_frag1.msc
+++ b/doc/msc/rvi_protocol_frag1.msc
diff --git a/doc/rvi_fragmentation.md b/doc/rvi_fragmentation.md
new file mode 100644
index 0000000..077cb49
--- /dev/null
+++ b/doc/rvi_fragmentation.md
@@ -0,0 +1,122 @@
+# The RVI Core Fragmentation Protocol
+
+## Abstract
+
+The Remote Vehicle Interaction (RVI) system is a framework for secure interaction between
+vehicles and other devices and/or cloud services. RVI is designed to be agnostic in regard
+to connectivity options and intermittent connectivity. One consequence of this is that
+large messages may have to be partially transmitted via one type of connection, and completed
+on another. The fragmentation protocol described below allows for varying Message Transfer
+Unit (MTU) and lets the remote client request fragments as needed.
+
+## Status of This Memo
+
+This document is not an Internet Standards Track specification; it is
+published for informational purposes.
+
+## Copyright Notice
+
+Copyright (C) 2016 Jaguar Land Rover
+
+This document is licensed under Creative Commons
+Attribution-ShareAlike 4.0 International.
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Terminology](#terminology)
+3. [System Overview](#system-overview)
+4. [Notation](#notation)
+5. [References](#references)
+
+## Introduction
+
+
+
+## Terminology
+
+Term      | Meaning
+----------|--------------------------------
+`Client`  | Sending side of the interaction
+`Server`  | Receiving side of the interaction
+`MTU`     | Message Transfer Unit
+
+## System Overview
+
+The fragmentation support is intended to operate immediately on top of the transport
+layer. In
+
+<img src="images/frag-overview.png" alt="Overview" style="width:600">
+
+## Notation
+
+The fragmentation protocol does not specify any particular encoding method.
+In this document, JSON notation is used. In practice, a byte-oriented JSON-like
+encoding, like msgpack [MSGP] would be more suitable.
+
+## Messages
+
+The fragment messages are deliberately compact, in order to steal as little of
+the available transfer window from the fragment itself.
+
+**Fragment message:**
+
+    { "frg": [ id, size, offset, fragment ] }
+
+The sending side initiates fragment transfer by sending a first fragment. The
+size of the first fragment is determined by the sending side. Subsequent fragments
+are requested by the receiver, in which case the receiver also decides how large
+a fragment it wants. The sender is allowed to send a smaller fragment, but not
+a larger one.
+
+Note that `size` denotes the size of the *whole* message, not the fragment.
+
+**Fragment request message:**
+
+    { "frg-get": [ id, offset, size ] }
+
+This message is sent by the receiving side in order to request the next fragment.
+The `offset` will typically be the position following the most recently received
+fragment, but could also represent a "hole" in the message from a missing fragment.
+
+**Fragment acknowledgement message:**
+
+    { "frg-end": [ id, result_code ] }
+
+**Fragment error message:**
+
+    { "frg-err": [ id, result_code ] }
+
+`id` (string): Message identity. This value needs to be unique within the scope
+of the current connection.
+
+`size` (integer): A positive integer denoting either the size of the whole message
+(as in the `"frg"` message) or the size of the requested fragment (as in the `"frg-get"`
+message).
+
+`offset` (integer): A positive integer denoting the starting byte of the fragment,
+relative to the whole message. The first fragment starts at `1`.
+
+`fragment` (binary): A byte sequence denoting the current fragment. Note that the
+`"frg"` message doesn't contain a size indicator for the fragment. However an
+encoding such as [MSGP] does include a size indicator.
+
+`result_code` (integer): A number denoting the outcome of the transfer and reassembly.
+A zero (`0`) means all went well; a negative number indicates failure. Predefined values
+are:
+
+Code or range | Definition
+--------------| ----------------------
+`0`           | Message was successfully transfered and reassembled
+`-99 ... -1`  | Reserved for standard error codes
+`-1`          | Unknown message (i.e. in a `"frg-err"` response to a `"fgr-get"` message)
+`-2`          | Protocol error
+`-3`          | Timeout error
+`< -99`       | Application-defined error codes
+
+## References
+
+[RVI]  Remote Vehicle Interaction (RVI)
+       https://github.com/PDXOstc/rvi_core
+[MSGP] msgpack encoding
+       http://msgpack.org
\ No newline at end of file
diff --git a/doc/rvi_protocol.md b/doc/rvi_protocol.md
index fc0a2f8..62765a3 100644
--- a/doc/rvi_protocol.md
+++ b/doc/rvi_protocol.md
@@ -1,4 +1,4 @@
-Copyright (C) 2015 Jaguar Land Rover
+Copyright (C) 2015-16 Jaguar Land Rover
 
 This document is licensed under Creative Commons
 Attribution-ShareAlike 4.0 International.
@@ -56,7 +56,7 @@ nodes once they have become aware of each other's presence.
 
 The stack schematics is shown below.
 
-<img src="rvi_protocol_stack.png" alt="RVI Core protocol Stack">
+<img src="images/rvi_protocol_stack.png" alt="RVI Core protocol Stack">
 
 ## RVI Core protocol codec
 The RVI core protocol uses MessagePack [3] as its
@@ -94,7 +94,7 @@ RVI credentials.
 
 The figure below shows how this is done.
 
-<img src="rvi_protocol_x509_credential.png" alt="X.509 - RVI Protocol integration">
+<img src="images/rvi_protocol_x509_credential.png" alt="X.509 - RVI Protocol integration">
 
 ## JSON Web token usage
 JSON Web Tokens (JWT) [2] are used to encode RVI credentials, which are
@@ -109,7 +109,7 @@ Please note that the protocol is fully symmetrical and that the
 client-server terminology only denotes who initiates the connection
 (client), and who receives that connection (server).
 
-<img src="rvi_protocol_flow.png" alt="RVI Core protocol Sequence Diagram" style="width:800">
+<img src="images/rvi_protocol_flow.png" alt="RVI Core protocol Sequence Diagram" style="width:800">
 
 ## Authorize command
 The ```authorize``` command contains a list of RVI credentials, each specifying
@@ -138,7 +138,7 @@ shown below.
 
 Connection 1 | Connection 2
 :------:|:------:
-<img src="rvi_protocol_double_connect1.png" alt="RVI Core protocol Double Connect" style="width:400"> | <img src="rvi_protocol_double_connect2.png" alt="RVI Core protocol Double Connect" style="width:400">
+<img src="images/rvi_protocol_double_connect1.png" alt="RVI Core protocol Double Connect" style="width:400"> | <img src="images/rvi_protocol_double_connect2.png" alt="RVI Core protocol Double Connect" style="width:400">
 
 A double connect can be detected by either side by checking if the
 remote peer address already has a connection established.
@@ -181,7 +181,7 @@ fragmented.
 
 The protocol is as follows:
 
-<img src="rvi_protocol_frag1.png" alt="RVI Core fragmentation Sequence Diagram" style="width:800">
+<img src="images/rvi_protocol_frag1.png" alt="RVI Core fragmentation Sequence Diagram" style="width:800">
 
 ### Enabling fragmentation