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@62:9751a8504c82, 2017-03-14 (annotated)

Committer:
Matt Briggs
Date:
Tue Mar 14 08:32:55 2017 -0600
Revision:
62:9751a8504c82
Parent:
61:8d9efd33cac9
Child:
67:2115a2f1b945
First cut at pair code

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 62:9751a8504c82 68 ### Important LoRaWAN Parameters
Matt Briggs 62:9751a8504c82 69 For peer to peer only a subset of parameters apply. Many are obvious such as
Matt Briggs 62:9751a8504c82 70 power, frequency, and basic command and control. Below are a listing of the more
Matt Briggs 62:9751a8504c82 71 detailed parameters and our current understanding as to how they effect performance:
Matt Briggs 62:9751a8504c82 72
Matt Briggs 62:9751a8504c82 73 * Network address - In peer to peer this acts both as a tx and rx address. In other
Matt Briggs 62:9751a8504c82 74 words if all the modems are the same address messages act as broadcast. For the
Matt Briggs 62:9751a8504c82 75 wireless bridge, this is used as a sort of network ID since all communication is
Matt Briggs 62:9751a8504c82 76 broadcast.
Matt Briggs 62:9751a8504c82 77 * Network session key - This is one of two encryption key. Currently, in peer to peer
Matt Briggs 62:9751a8504c82 78 both are just randomly generated.
Matt Briggs 62:9751a8504c82 79 * Data session key - This is second of two encryption key. Currently, in peer to peer
Matt Briggs 62:9751a8504c82 80 both are just randomly generated.
Matt Briggs 62:9751a8504c82 81
Matt Briggs 62:9751a8504c82 82 Not applicable parameters:
Matt Briggs 62:9751a8504c82 83 * Network ID - Used for OTA
Matt Briggs 62:9751a8504c82 84 * Network Key - Used for OTA
Matt Briggs 62:9751a8504c82 85
Matt Briggs 61:8d9efd33cac9 86 ### Brute force algorithm
Matt Briggs 61:8d9efd33cac9 87 TODO
Matt Briggs 61:8d9efd33cac9 88
Matt Briggs 61:8d9efd33cac9 89 #### Brute force alert message
Matt Briggs 61:8d9efd33cac9 90 ==============================================
Matt Briggs 61:8d9efd33cac9 91 = Offset | Size (in Bytes) | Name =
Matt Briggs 61:8d9efd33cac9 92 ==============================================
Matt Briggs 61:8d9efd33cac9 93 = 0x00 | 2 Bytes | Alert Msg Flag (0xEF10) =
Matt Briggs 61:8d9efd33cac9 94 ==============================================
Matt Briggs 61:8d9efd33cac9 95 = 0x02 | 8 Bytes | xDot EUI =
Matt Briggs 61:8d9efd33cac9 96 ==============================================
Matt Briggs 61:8d9efd33cac9 97 = 0x0A | 2 Bytes | Alert Data =
Matt Briggs 61:8d9efd33cac9 98 ==============================================
Matt Briggs 61:8d9efd33cac9 99 = 0x0C | 4 Bytes | Alert Sequence Number =
Matt Briggs 61:8d9efd33cac9 100 ==============================================
Matt Briggs 61:8d9efd33cac9 101 Total of 16 bytes
Matt Briggs 61:8d9efd33cac9 102
Matt Briggs 61:8d9efd33cac9 103 #### Brute force pair request message
Matt Briggs 61:8d9efd33cac9 104 ==============================================
Matt Briggs 61:8d9efd33cac9 105 = Offset | Size (in Bytes) | Name =
Matt Briggs 61:8d9efd33cac9 106 ==============================================
Matt Briggs 61:8d9efd33cac9 107 = 0x00 | 2 Bytes | Pair Request Flag (0xFE01)=
Matt Briggs 61:8d9efd33cac9 108 ==============================================
Matt Briggs 61:8d9efd33cac9 109 = 0x02 | 8 Bytes | xDot EUI (requester) =
Matt Briggs 61:8d9efd33cac9 110 ==============================================
Matt Briggs 61:8d9efd33cac9 111 = 0x0A | 6 Bytes | Reserved =
Matt Briggs 61:8d9efd33cac9 112 ==============================================
Matt Briggs 61:8d9efd33cac9 113 * Total of 16 Bytes
Matt Briggs 61:8d9efd33cac9 114
Matt Briggs 61:8d9efd33cac9 115 Ideas for reserved:
Matt Briggs 61:8d9efd33cac9 116 * Network type desired
Matt Briggs 61:8d9efd33cac9 117 * Messages generated
Matt Briggs 61:8d9efd33cac9 118
Matt Briggs 61:8d9efd33cac9 119 #### Brute force pair accept message
Matt Briggs 61:8d9efd33cac9 120 ==============================================
Matt Briggs 61:8d9efd33cac9 121 = Offset | Size (in Bytes) | Name =
Matt Briggs 61:8d9efd33cac9 122 ==============================================
Matt Briggs 61:8d9efd33cac9 123 = 0x00 | 2 Bytes | Pair Accept Flag (0xFD02) =
Matt Briggs 61:8d9efd33cac9 124 ==============================================
Matt Briggs 61:8d9efd33cac9 125 = 0x02 | 8 Bytes | xDot EUI (RX Master) =
Matt Briggs 61:8d9efd33cac9 126 ==============================================
Matt Briggs 61:8d9efd33cac9 127 = 0x0A | 4 Bytes | Reserved for Frequency =
Matt Briggs 61:8d9efd33cac9 128 ==============================================
Matt Briggs 62:9751a8504c82 129 = 0x0E | 4 Bytes | Network Address =
Matt Briggs 61:8d9efd33cac9 130 ==============================================
Matt Briggs 62:9751a8504c82 131 = 0x12 | 16 Bytes | Network Session Key =
Matt Briggs 61:8d9efd33cac9 132 ==============================================
Matt Briggs 62:9751a8504c82 133 = 0x22 | 16 Bytes | Data session Key =
Matt Briggs 61:8d9efd33cac9 134 ==============================================
Matt Briggs 61:8d9efd33cac9 135 * Total of 34 Bytes
Matt Briggs 61:8d9efd33cac9 136
Matt Briggs 45:f146a8ef5ea6 137 ## Peer to Peer Pair
Matt Briggs 45:f146a8ef5ea6 138 Pairing needs to support many topologies including one TX to one RX, many TX to
Matt Briggs 45:f146a8ef5ea6 139 one RX, and finally many TX to many RX. The pairing process not only has the
Matt Briggs 45:f146a8ef5ea6 140 units sharing their unique IDs but also their encryption keys. To better
Matt Briggs 45:f146a8ef5ea6 141 understand the pairing logic an example with a single RX and TX is described
Matt Briggs 45:f146a8ef5ea6 142 and then extended to include other topologies.
Matt Briggs 45:f146a8ef5ea6 143
Matt Briggs 45:f146a8ef5ea6 144 ### Pair a single RX to TX:
Matt Briggs 45:f146a8ef5ea6 145 1. Set oen unit to RX via DIP switch.
Matt Briggs 45:f146a8ef5ea6 146 2. Hold the pair button for 10 seconds which clears current pair settings and generates
Matt Briggs 45:f146a8ef5ea6 147 new pair values (This is indicated by TBD blink sequence).
Matt Briggs 45:f146a8ef5ea6 148 3. On the RX press the pair button which will place the unit pairing mode for 30 seconds
Matt Briggs 45:f146a8ef5ea6 149 4. Set the second unit to TX via DIP switch
Matt Briggs 45:f146a8ef5ea6 150 5. Hold TX pair button for 5 seconds to send pair request
Matt Briggs 45:f146a8ef5ea6 151 6. If pairing was successful both RX and TX will show TBD2 blink sequence
Matt Briggs 45:f146a8ef5ea6 152 7. Now both units will have the same encryption keys and be able to wireless bridge to
Matt Briggs 45:f146a8ef5ea6 153 each other. Pairing is complete.
Matt Briggs 45:f146a8ef5ea6 154
Matt Briggs 45:f146a8ef5ea6 155 Now that the general pairing work flow is introduced it can be extended to add additional TXs
Matt Briggs 45:f146a8ef5ea6 156 and RXs to pair group.
Matt Briggs 45:f146a8ef5ea6 157
Matt Briggs 45:f146a8ef5ea6 158 ### Adding additional TX to pair group:
Matt Briggs 45:f146a8ef5ea6 159 1. Set an already paired RX to enter pairing mode by pressing pair button
Matt Briggs 45:f146a8ef5ea6 160 2. Set new unit to TX via DIP switch
Matt Briggs 45:f146a8ef5ea6 161 3. Hold TX pair button for 5 seconds to send pair request
Matt Briggs 45:f146a8ef5ea6 162 4. If pairing was successful both RX and TX will show TBD2 blink sequence
Matt Briggs 45:f146a8ef5ea6 163 5. The additional TX is now paired and RX will receive alerts from all paired TXs
Matt Briggs 45:f146a8ef5ea6 164
Matt Briggs 45:f146a8ef5ea6 165 ### Add additional RXs to pair group:
Matt Briggs 45:f146a8ef5ea6 166 1. To add an additional RX. Pair it using the exact same process as adding a TX
Matt Briggs 55:79ab0bbc5008 167 utilizing the above instructions _i.e. pair the unit whichh will eventually become a
Matt Briggs 55:79ab0bbc5008 168 RX as if was a TX_.
Matt Briggs 45:f146a8ef5ea6 169 2. When pairing as a TX is complete; Convert the paired TX to a paired RX by switching the DIP
Matt Briggs 45:f146a8ef5ea6 170 switch to RX mode. This RX will now receive any TX alerts which are in range an in pair group.
Matt Briggs 45:f146a8ef5ea6 171
Matt Briggs 45:f146a8ef5ea6 172 #### Additional pairing thoughts
Matt Briggs 45:f146a8ef5ea6 173 * With this scheme it is easy to add additional nodes to pair group since within the
Matt Briggs 45:f146a8ef5ea6 174 pair group all RXs that are paired can receive any new/existing TX.
Matt Briggs 45:f146a8ef5ea6 175 * Another way to thing of this is each pair group has a single key and does not keep
Matt Briggs 45:f146a8ef5ea6 176 track of the copies.
Matt Briggs 45:f146a8ef5ea6 177 * This scheme does not support hybrid pairing where two RX can receive one TX
Matt Briggs 45:f146a8ef5ea6 178 and one of the two can receive additional TX messages the other cannot. It might be
Matt Briggs 61:8d9efd33cac9 179 possible to support this but the pairing process would become more complex.
Matt Briggs 61:8d9efd33cac9 180
Matt Briggs 61:8d9efd33cac9 181 #### Pair message details
Matt Briggs 45:f146a8ef5ea6 182
Matt Briggs 45:f146a8ef5ea6 183 ## LoRaWAN
Matt Briggs 45:f146a8ef5ea6 184 Just use the xDots and the conduit as they are designed to be used. No pairing just straight LoRaWAN.
Matt Briggs 45:f146a8ef5ea6 185
Matt Briggs 45:f146a8ef5ea6 186 * Future idea maybe a RX with WAN enabled acts as a repeater to conduit.
Matt Briggs 49:18f1354f9e51 187
Matt Briggs 49:18f1354f9e51 188 # Nonvolatile Memory Map
Matt Briggs 55:79ab0bbc5008 189 ## Stored by dot firmware
Matt Briggs 55:79ab0bbc5008 190 * 64-bit EUI
Matt Briggs 55:79ab0bbc5008 191 * DLC
Matt Briggs 55:79ab0bbc5008 192 * ULC
Matt Briggs 55:79ab0bbc5008 193
Matt Briggs 55:79ab0bbc5008 194 ## Protocol Parameters
Matt Briggs 55:79ab0bbc5008 195 ==============================================
Matt Briggs 55:79ab0bbc5008 196 = Dot Relative Addr | Size (in Bytes) | Name =
Matt Briggs 55:79ab0bbc5008 197 ==============================================
Matt Briggs 62:9751a8504c82 198 = 0x1000 | 02 Bytes | Protocol Flag =
Matt Briggs 62:9751a8504c82 199 ==============================================
Matt Briggs 62:9751a8504c82 200 = 0x1002 | 02 Bytes | Protocol Rev =
Matt Briggs 55:79ab0bbc5008 201 ==============================================
Matt Briggs 62:9751a8504c82 202 = 0x1004 | 04 Bytes | Reserved for Frequency =
Matt Briggs 62:9751a8504c82 203 ==============================================
Matt Briggs 62:9751a8504c82 204 = 0x1008 | 04 Bytes | Network Address =
Matt Briggs 55:79ab0bbc5008 205 ==============================================
Matt Briggs 62:9751a8504c82 206 = 0x1010 | 16 Bytes | Network Session Key =
Matt Briggs 62:9751a8504c82 207 ==============================================
Matt Briggs 62:9751a8504c82 208 = 0x1020 | 16 Bytes | Data Session Key =
Matt Briggs 55:79ab0bbc5008 209 ==============================================
Matt Briggs 62:9751a8504c82 210 = 0x1030 | 02 Bytes | Logical Address Serial =
Matt Briggs 55:79ab0bbc5008 211 ==============================================
Matt Briggs 62:9751a8504c82 212 = 0x1032 | 04 Bytes | Last Message SeqNum =
Matt Briggs 62:9751a8504c82 213 ==============================================
Matt Briggs 62:9751a8504c82 214 Space needed is 54 bytes. Spaced used is 50 bytes
Matt Briggs 62:9751a8504c82 215 for better word alignment.
Matt Briggs 49:18f1354f9e51 216
Matt Briggs 49:18f1354f9e51 217 ## IO Baseboard Parameters
Matt Briggs 49:18f1354f9e51 218 ==============================================
Matt Briggs 49:18f1354f9e51 219 = Dot Relative Addr | Size (in Bytes) | Name =
Matt Briggs 49:18f1354f9e51 220 ==============================================
Matt Briggs 62:9751a8504c82 221 = 0x1100 | 2 Bytes | Baseboard Flag =
Matt Briggs 55:79ab0bbc5008 222 ==============================================
Matt Briggs 62:9751a8504c82 223 = 0x1102 | 2 Bytes | Baseboard Rev =
Matt Briggs 49:18f1354f9e51 224 ==============================================
Matt Briggs 62:9751a8504c82 225 = 0x1104 | 2 Bytes | Baseboard Serial =
Matt Briggs 49:18f1354f9e51 226 ==============================================
Matt Briggs 62:9751a8504c82 227 = 0x1106 | 2 Bytes | Baseboard Configuration =
Matt Briggs 49:18f1354f9e51 228 ==============================================
Matt Briggs 62:9751a8504c82 229 = 0x1110 | 8 Bytes | PortEx0 64 bit ROM Addr =
Matt Briggs 55:79ab0bbc5008 230 ==============================================
Matt Briggs 62:9751a8504c82 231 = 0x1118 | 8 Bytes | PortEx1 64 bit ROM Addr =
Matt Briggs 49:18f1354f9e51 232 ==============================================
Matt Briggs 55:79ab0bbc5008 233
Matt Briggs 62:9751a8504c82 234 Space needed is 24 bytes. Space used is 32 bytes.
Matt Briggs 55:79ab0bbc5008 235