Diff: xDotBridge/README.md

Revision:

45:f146a8ef5ea6

Child:

49:18f1354f9e51

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/xDotBridge/README.md	Thu Feb 02 14:07:20 2017 -0700
@@ -0,0 +1,114 @@
+# xDotBridge Documentation {#mainpage}
+# Introduction 
+This project is intended to support multiple products including Wireless
+Bridge, MTS comm board, and camera comm board.  The stretch goal of using a
+single binary and intuiting all the different configurations.  At a minimum it
+should allow at compile time switches to generate different flavors.
+
+# Software Design
+## File structure
+The software is written using mbed's standard layout and is compatible with
+their online compiler.
+
+### Top Level Contents
+ * 3rd party libraries such as libxDot, mbed-os, and OneWire.
+ * Doxyfile used to generate nice looking documentation.
+
+### xDotBridge (subfolder)
+ * Contains standard folders for C++ headers and source
+ * This readme file
+ * config.h which contains compile time options
+
+## Code organization
+The software has been designed in a object oriented way and separates
+functionality such that communication protocol can be changed separately
+from I/O SCADA. The design will hopefully allow additional modules to utilize
+both IO and communication without major software revisions.  The main
+components are listed below:
+
+### CommProtocol
+This set of classes implements different protocols this allows the user to
+select between P2P or WAN.
+
+### Baseboard IO
+This class allows for control and status of various GPIO either directly
+connect to uC or through OneWire port expanders.  The idea is to make the
+main code less busy with implementation details.
+
+### Additional daughter board module (MTS)
+Mostly TBD.  Hopefully can just register to commModule to communicate alerts and
+receive configuration information.
+
+### Bootloader Staging
+This future class will load firmware from over the air into a on-board flash.
+Provide integrity checking functions and eventually reset uC for main bootloader. 
+
+### Main
+The main file has a while loop which will sample IO, stimulate IO, apply
+configuration changes, then put the uC to sleep and wait for either a timer
+event or an external interrupt i.e. each iteration of the while loop is
+relatively independent and all state should be stored in other classes.
+
+### Bootloader
+The bootloader is a separate program which is ran during the boot of uC and
+is used to load new firmware either though serial (via a TBD protocol) or if
+a firmware is properly staged in the flash will automatically check and apply
+this firmware to main memory.  Finally it will exit by jumping to the main program.
+
+TODO Figure out best way to compile these projects with offsets or with a combiner
+program.
+
+# Theory of operation
+## Peer to Peer Operation
+After pairing (described in separate section) a set of transmitters (TXs) and
+receivers (RXs) will have a network addresses?, unique network session keys,
+and data session keys.  This guarantees by design that all message sent can
+only be received and decoded by units in the pair group.
+
+## Peer to Peer Pair
+Pairing needs to support many topologies including one TX to one RX, many TX to
+one RX, and finally many TX to many RX.  The pairing process not only has the
+units sharing their unique IDs but also their encryption keys.  To better
+understand the pairing logic an example with a single RX and TX is described
+and then extended to include other topologies.
+
+### Pair a single RX to TX:
+1.  Set oen unit to RX via DIP switch.  
+2.  Hold the pair button for 10 seconds which clears current pair settings and generates
+new pair values (This is indicated by TBD blink sequence).
+3.  On the RX press the pair button which will place the unit pairing mode for 30 seconds
+4.  Set the second unit to TX via DIP switch
+5.  Hold TX pair button for 5 seconds to send pair request
+6.  If pairing was successful both RX and TX will show TBD2 blink sequence
+7.  Now both units will have the same encryption keys and be able to wireless bridge to
+each other.  Pairing is complete.
+
+Now that the general pairing work flow is introduced it can be extended to add additional TXs
+and RXs to pair group.
+
+### Adding additional TX to pair group:
+1.  Set an already paired RX to enter pairing mode by pressing pair button
+2.  Set new unit to TX via DIP switch
+3.  Hold TX pair button for 5 seconds to send pair request
+4.  If pairing was successful both RX and TX will show TBD2 blink sequence
+5.  The additional TX is now paired and RX will receive alerts from all paired TXs
+
+### Add additional RXs to pair group:
+1.  To add an additional RX.  Pair it using the exact same process as adding a TX
+utilizing the above instructions.
+2.  When pairing as a TX is complete; Convert the paired TX to a paired RX by switching the DIP
+switch to RX mode.  This RX will now receive any TX alerts which are in range an in pair group.
+
+#### Additional pairing thoughts
+* With this scheme it is easy to add additional nodes to pair group since within the
+pair group all RXs that are paired can receive any new/existing TX.
+* Another way to thing of this is each pair group has a single key and does not keep
+track of the copies.
+* This scheme does not support hybrid pairing where two RX can receive one TX
+and one of the two can receive additional TX messages the other cannot.  It might be
+possible to support this but the pairing process would become more complex. 
+
+## LoRaWAN
+Just use the xDots and the conduit as they are designed to be used.  No pairing just straight LoRaWAN.
+
+* Future idea maybe a RX with WAN enabled acts as a repeater to conduit.