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@55:79ab0bbc5008, 2017-02-27 (annotated)

Committer:
Matt Briggs
Date:
Mon Feb 27 08:06:36 2017 -0700
Revision:
55:79ab0bbc5008
Parent:
49:18f1354f9e51
Child:
61:8d9efd33cac9
Adding lots of NVM code to store parameters in eeprom.  Also some work on documentation.

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 55:79ab0bbc5008 98 utilizing the above instructions _i.e. pair the unit whichh will eventually become a
Matt Briggs 55:79ab0bbc5008 99 RX as if was a TX_.
Matt Briggs 45:f146a8ef5ea6 100 2. When pairing as a TX is complete; Convert the paired TX to a paired RX by switching the DIP
Matt Briggs 45:f146a8ef5ea6 101 switch to RX mode. This RX will now receive any TX alerts which are in range an in pair group.
Matt Briggs 45:f146a8ef5ea6 102
Matt Briggs 45:f146a8ef5ea6 103 #### Additional pairing thoughts
Matt Briggs 45:f146a8ef5ea6 104 * With this scheme it is easy to add additional nodes to pair group since within the
Matt Briggs 45:f146a8ef5ea6 105 pair group all RXs that are paired can receive any new/existing TX.
Matt Briggs 45:f146a8ef5ea6 106 * Another way to thing of this is each pair group has a single key and does not keep
Matt Briggs 45:f146a8ef5ea6 107 track of the copies.
Matt Briggs 45:f146a8ef5ea6 108 * This scheme does not support hybrid pairing where two RX can receive one TX
Matt Briggs 45:f146a8ef5ea6 109 and one of the two can receive additional TX messages the other cannot. It might be
Matt Briggs 45:f146a8ef5ea6 110 possible to support this but the pairing process would become more complex.
Matt Briggs 45:f146a8ef5ea6 111
Matt Briggs 45:f146a8ef5ea6 112 ## LoRaWAN
Matt Briggs 45:f146a8ef5ea6 113 Just use the xDots and the conduit as they are designed to be used. No pairing just straight LoRaWAN.
Matt Briggs 45:f146a8ef5ea6 114
Matt Briggs 45:f146a8ef5ea6 115 * Future idea maybe a RX with WAN enabled acts as a repeater to conduit.
Matt Briggs 49:18f1354f9e51 116
Matt Briggs 49:18f1354f9e51 117 # Nonvolatile Memory Map
Matt Briggs 55:79ab0bbc5008 118 ## Stored by dot firmware
Matt Briggs 55:79ab0bbc5008 119 * 64-bit EUI
Matt Briggs 55:79ab0bbc5008 120 * Network ID
Matt Briggs 55:79ab0bbc5008 121 * DLC
Matt Briggs 55:79ab0bbc5008 122 * ULC
Matt Briggs 55:79ab0bbc5008 123 * Enc keys
Matt Briggs 55:79ab0bbc5008 124
Matt Briggs 55:79ab0bbc5008 125
Matt Briggs 55:79ab0bbc5008 126 ## Protocol Parameters
Matt Briggs 55:79ab0bbc5008 127 ==============================================
Matt Briggs 55:79ab0bbc5008 128 = Dot Relative Addr | Size (in Bytes) | Name =
Matt Briggs 55:79ab0bbc5008 129 ==============================================
Matt Briggs 55:79ab0bbc5008 130 = 0x1000 | 2 Bytes | Protocol Flag =
Matt Briggs 55:79ab0bbc5008 131 ==============================================
Matt Briggs 55:79ab0bbc5008 132 = 0x1002 | 2 Bytes | Protocol Rev =
Matt Briggs 55:79ab0bbc5008 133 ==============================================
Matt Briggs 55:79ab0bbc5008 134 = 0x1004 | 2 Bytes | Logical Address Serial =
Matt Briggs 55:79ab0bbc5008 135 ==============================================
Matt Briggs 55:79ab0bbc5008 136 = 0x1006 | 4 Bytes | Last Message SeqNum =
Matt Briggs 55:79ab0bbc5008 137 ==============================================
Matt Briggs 55:79ab0bbc5008 138 Space used is 10 bytes
Matt Briggs 49:18f1354f9e51 139
Matt Briggs 49:18f1354f9e51 140 ## IO Baseboard Parameters
Matt Briggs 49:18f1354f9e51 141 ==============================================
Matt Briggs 49:18f1354f9e51 142 = Dot Relative Addr | Size (in Bytes) | Name =
Matt Briggs 49:18f1354f9e51 143 ==============================================
Matt Briggs 55:79ab0bbc5008 144 = 0x2000 | 2 Bytes | Baseboard Flag =
Matt Briggs 55:79ab0bbc5008 145 ==============================================
Matt Briggs 55:79ab0bbc5008 146 = 0x2002 | 2 Bytes | Baseboard Rev =
Matt Briggs 49:18f1354f9e51 147 ==============================================
Matt Briggs 55:79ab0bbc5008 148 = 0x2004 | 2 Bytes | Baseboard Serial =
Matt Briggs 49:18f1354f9e51 149 ==============================================
Matt Briggs 55:79ab0bbc5008 150 = 0x2006 | 2 Bytes | Baseboard Configuration =
Matt Briggs 49:18f1354f9e51 151 ==============================================
Matt Briggs 55:79ab0bbc5008 152 = 0x2010 | 8 Bytes | PortEx0 64 bit ROM Addr =
Matt Briggs 55:79ab0bbc5008 153 ==============================================
Matt Briggs 55:79ab0bbc5008 154 = 0x2018 | 8 Bytes | PortEx1 64 bit ROM Addr =
Matt Briggs 49:18f1354f9e51 155 ==============================================
Matt Briggs 55:79ab0bbc5008 156
Matt Briggs 55:79ab0bbc5008 157 Space used is 32 bytes
Matt Briggs 55:79ab0bbc5008 158