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@61:8d9efd33cac9, 2017-03-09 (annotated)

Committer:
Matt Briggs
Date:
Thu Mar 09 16:47:42 2017 -0700
Revision:
61:8d9efd33cac9
Parent:
55:79ab0bbc5008
Child:
62:9751a8504c82
Slight modification of pair code and documentation.  Also some test code to all xDot dev boards to act like bridges.

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