Matt Briggs / Mbed OS xDotBridge_update_dev_latest

Fork to see if I can get working

Dependencies:   BufferedSerial OneWire WinbondSPIFlash libxDot-dev-mbed5-deprecated

Fork of xDotBridge_update_test20180823 by Matt Briggs

xDotBridge/README.md@45:f146a8ef5ea6, 2017-02-02 (annotated)

Committer:
Matt Briggs
Date:
Thu Feb 02 14:07:20 2017 -0700
Revision:
45:f146a8ef5ea6
Child:
49:18f1354f9e51
first cut at readme file

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Matt Briggs 45:f146a8ef5ea6 1 # xDotBridge Documentation {#mainpage}
Matt Briggs 45:f146a8ef5ea6 2 # Introduction
Matt Briggs 45:f146a8ef5ea6 3 This project is intended to support multiple products including Wireless
Matt Briggs 45:f146a8ef5ea6 4 Bridge, MTS comm board, and camera comm board. The stretch goal of using a
Matt Briggs 45:f146a8ef5ea6 5 single binary and intuiting all the different configurations. At a minimum it
Matt Briggs 45:f146a8ef5ea6 6 should allow at compile time switches to generate different flavors.
Matt Briggs 45:f146a8ef5ea6 7
Matt Briggs 45:f146a8ef5ea6 8 # Software Design
Matt Briggs 45:f146a8ef5ea6 9 ## File structure
Matt Briggs 45:f146a8ef5ea6 10 The software is written using mbed's standard layout and is compatible with
Matt Briggs 45:f146a8ef5ea6 11 their online compiler.
Matt Briggs 45:f146a8ef5ea6 12
Matt Briggs 45:f146a8ef5ea6 13 ### Top Level Contents
Matt Briggs 45:f146a8ef5ea6 14 * 3rd party libraries such as libxDot, mbed-os, and OneWire.
Matt Briggs 45:f146a8ef5ea6 15 * Doxyfile used to generate nice looking documentation.
Matt Briggs 45:f146a8ef5ea6 16
Matt Briggs 45:f146a8ef5ea6 17 ### xDotBridge (subfolder)
Matt Briggs 45:f146a8ef5ea6 18 * Contains standard folders for C++ headers and source
Matt Briggs 45:f146a8ef5ea6 19 * This readme file
Matt Briggs 45:f146a8ef5ea6 20 * config.h which contains compile time options
Matt Briggs 45:f146a8ef5ea6 21
Matt Briggs 45:f146a8ef5ea6 22 ## Code organization
Matt Briggs 45:f146a8ef5ea6 23 The software has been designed in a object oriented way and separates
Matt Briggs 45:f146a8ef5ea6 24 functionality such that communication protocol can be changed separately
Matt Briggs 45:f146a8ef5ea6 25 from I/O SCADA. The design will hopefully allow additional modules to utilize
Matt Briggs 45:f146a8ef5ea6 26 both IO and communication without major software revisions. The main
Matt Briggs 45:f146a8ef5ea6 27 components are listed below:
Matt Briggs 45:f146a8ef5ea6 28
Matt Briggs 45:f146a8ef5ea6 29 ### CommProtocol
Matt Briggs 45:f146a8ef5ea6 30 This set of classes implements different protocols this allows the user to
Matt Briggs 45:f146a8ef5ea6 31 select between P2P or WAN.
Matt Briggs 45:f146a8ef5ea6 32
Matt Briggs 45:f146a8ef5ea6 33 ### Baseboard IO
Matt Briggs 45:f146a8ef5ea6 34 This class allows for control and status of various GPIO either directly
Matt Briggs 45:f146a8ef5ea6 35 connect to uC or through OneWire port expanders. The idea is to make the
Matt Briggs 45:f146a8ef5ea6 36 main code less busy with implementation details.
Matt Briggs 45:f146a8ef5ea6 37
Matt Briggs 45:f146a8ef5ea6 38 ### Additional daughter board module (MTS)
Matt Briggs 45:f146a8ef5ea6 39 Mostly TBD. Hopefully can just register to commModule to communicate alerts and
Matt Briggs 45:f146a8ef5ea6 40 receive configuration information.
Matt Briggs 45:f146a8ef5ea6 41
Matt Briggs 45:f146a8ef5ea6 42 ### Bootloader Staging
Matt Briggs 45:f146a8ef5ea6 43 This future class will load firmware from over the air into a on-board flash.
Matt Briggs 45:f146a8ef5ea6 44 Provide integrity checking functions and eventually reset uC for main bootloader.
Matt Briggs 45:f146a8ef5ea6 45
Matt Briggs 45:f146a8ef5ea6 46 ### Main
Matt Briggs 45:f146a8ef5ea6 47 The main file has a while loop which will sample IO, stimulate IO, apply
Matt Briggs 45:f146a8ef5ea6 48 configuration changes, then put the uC to sleep and wait for either a timer
Matt Briggs 45:f146a8ef5ea6 49 event or an external interrupt i.e. each iteration of the while loop is
Matt Briggs 45:f146a8ef5ea6 50 relatively independent and all state should be stored in other classes.
Matt Briggs 45:f146a8ef5ea6 51
Matt Briggs 45:f146a8ef5ea6 52 ### Bootloader
Matt Briggs 45:f146a8ef5ea6 53 The bootloader is a separate program which is ran during the boot of uC and
Matt Briggs 45:f146a8ef5ea6 54 is used to load new firmware either though serial (via a TBD protocol) or if
Matt Briggs 45:f146a8ef5ea6 55 a firmware is properly staged in the flash will automatically check and apply
Matt Briggs 45:f146a8ef5ea6 56 this firmware to main memory. Finally it will exit by jumping to the main program.
Matt Briggs 45:f146a8ef5ea6 57
Matt Briggs 45:f146a8ef5ea6 58 TODO Figure out best way to compile these projects with offsets or with a combiner
Matt Briggs 45:f146a8ef5ea6 59 program.
Matt Briggs 45:f146a8ef5ea6 60
Matt Briggs 45:f146a8ef5ea6 61 # Theory of operation
Matt Briggs 45:f146a8ef5ea6 62 ## Peer to Peer Operation
Matt Briggs 45:f146a8ef5ea6 63 After pairing (described in separate section) a set of transmitters (TXs) and
Matt Briggs 45:f146a8ef5ea6 64 receivers (RXs) will have a network addresses?, unique network session keys,
Matt Briggs 45:f146a8ef5ea6 65 and data session keys. This guarantees by design that all message sent can
Matt Briggs 45:f146a8ef5ea6 66 only be received and decoded by units in the pair group.
Matt Briggs 45:f146a8ef5ea6 67
Matt Briggs 45:f146a8ef5ea6 68 ## Peer to Peer Pair
Matt Briggs 45:f146a8ef5ea6 69 Pairing needs to support many topologies including one TX to one RX, many TX to
Matt Briggs 45:f146a8ef5ea6 70 one RX, and finally many TX to many RX. The pairing process not only has the
Matt Briggs 45:f146a8ef5ea6 71 units sharing their unique IDs but also their encryption keys. To better
Matt Briggs 45:f146a8ef5ea6 72 understand the pairing logic an example with a single RX and TX is described
Matt Briggs 45:f146a8ef5ea6 73 and then extended to include other topologies.
Matt Briggs 45:f146a8ef5ea6 74
Matt Briggs 45:f146a8ef5ea6 75 ### Pair a single RX to TX:
Matt Briggs 45:f146a8ef5ea6 76 1. Set oen unit to RX via DIP switch.
Matt Briggs 45:f146a8ef5ea6 77 2. Hold the pair button for 10 seconds which clears current pair settings and generates
Matt Briggs 45:f146a8ef5ea6 78 new pair values (This is indicated by TBD blink sequence).
Matt Briggs 45:f146a8ef5ea6 79 3. On the RX press the pair button which will place the unit pairing mode for 30 seconds
Matt Briggs 45:f146a8ef5ea6 80 4. Set the second unit to TX via DIP switch
Matt Briggs 45:f146a8ef5ea6 81 5. Hold TX pair button for 5 seconds to send pair request
Matt Briggs 45:f146a8ef5ea6 82 6. If pairing was successful both RX and TX will show TBD2 blink sequence
Matt Briggs 45:f146a8ef5ea6 83 7. Now both units will have the same encryption keys and be able to wireless bridge to
Matt Briggs 45:f146a8ef5ea6 84 each other. Pairing is complete.
Matt Briggs 45:f146a8ef5ea6 85
Matt Briggs 45:f146a8ef5ea6 86 Now that the general pairing work flow is introduced it can be extended to add additional TXs
Matt Briggs 45:f146a8ef5ea6 87 and RXs to pair group.
Matt Briggs 45:f146a8ef5ea6 88
Matt Briggs 45:f146a8ef5ea6 89 ### Adding additional TX to pair group:
Matt Briggs 45:f146a8ef5ea6 90 1. Set an already paired RX to enter pairing mode by pressing pair button
Matt Briggs 45:f146a8ef5ea6 91 2. Set new unit to TX via DIP switch
Matt Briggs 45:f146a8ef5ea6 92 3. Hold TX pair button for 5 seconds to send pair request
Matt Briggs 45:f146a8ef5ea6 93 4. If pairing was successful both RX and TX will show TBD2 blink sequence
Matt Briggs 45:f146a8ef5ea6 94 5. The additional TX is now paired and RX will receive alerts from all paired TXs
Matt Briggs 45:f146a8ef5ea6 95
Matt Briggs 45:f146a8ef5ea6 96 ### Add additional RXs to pair group:
Matt Briggs 45:f146a8ef5ea6 97 1. To add an additional RX. Pair it using the exact same process as adding a TX
Matt Briggs 45:f146a8ef5ea6 98 utilizing the above instructions.
Matt Briggs 45:f146a8ef5ea6 99 2. When pairing as a TX is complete; Convert the paired TX to a paired RX by switching the DIP
Matt Briggs 45:f146a8ef5ea6 100 switch to RX mode. This RX will now receive any TX alerts which are in range an in pair group.
Matt Briggs 45:f146a8ef5ea6 101
Matt Briggs 45:f146a8ef5ea6 102 #### Additional pairing thoughts
Matt Briggs 45:f146a8ef5ea6 103 * With this scheme it is easy to add additional nodes to pair group since within the
Matt Briggs 45:f146a8ef5ea6 104 pair group all RXs that are paired can receive any new/existing TX.
Matt Briggs 45:f146a8ef5ea6 105 * Another way to thing of this is each pair group has a single key and does not keep
Matt Briggs 45:f146a8ef5ea6 106 track of the copies.
Matt Briggs 45:f146a8ef5ea6 107 * This scheme does not support hybrid pairing where two RX can receive one TX
Matt Briggs 45:f146a8ef5ea6 108 and one of the two can receive additional TX messages the other cannot. It might be
Matt Briggs 45:f146a8ef5ea6 109 possible to support this but the pairing process would become more complex.
Matt Briggs 45:f146a8ef5ea6 110
Matt Briggs 45:f146a8ef5ea6 111 ## LoRaWAN
Matt Briggs 45:f146a8ef5ea6 112 Just use the xDots and the conduit as they are designed to be used. No pairing just straight LoRaWAN.
Matt Briggs 45:f146a8ef5ea6 113
Matt Briggs 45:f146a8ef5ea6 114 * Future idea maybe a RX with WAN enabled acts as a repeater to conduit.