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@100:0882cf295f8e, 2017-11-29 (annotated)

Committer:
mbriggs_vortex
Date:
Wed Nov 29 13:54:36 2017 -0700
Revision:
100:0882cf295f8e
Parent:
67:2115a2f1b945 
Adding relaese bin to repo

Who changed what in which revision?

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