Helmut Tschemernjak / RadioShuttle-STM32L4

RadioShuttle Lib for the STM32 L4 Heltec Board

Dependents:   Turtle_RadioShuttle

RadioShuttleProtocol.rtf@11:91bc7ef20f21, 2019-03-04 (annotated)

Committer:
Helmut Tschemernjak
Date:
Mon Mar 04 09:41:41 2019 +0100
Revision:
11:91bc7ef20f21
Parent:
2:50e8a3c35d1f 
Updated lib

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Helmut Tschemernjak 2:50e8a3c35d1f 1 {\rtf1\ansi\ansicpg1252\cocoartf1404\cocoasubrtf470
Helmut Tschemernjak 2:50e8a3c35d1f 2 {\fonttbl\f0\fswiss\fcharset0 Helvetica;\f1\fnil\fcharset0 Menlo-Regular;}
Helmut Tschemernjak 2:50e8a3c35d1f 3 {\colortbl;\red255\green255\blue255;\red255\green0\blue0;}
Helmut Tschemernjak 2:50e8a3c35d1f 4 \paperw11900\paperh16840\margl1440\margr1440\vieww20480\viewh16280\viewkind0
Helmut Tschemernjak 2:50e8a3c35d1f 5 \pard\tx566\tx1133\tx1700\tx2267\tx2834\tx3401\tx3968\tx4535\tx5102\tx5669\tx6236\tx6803\pardirnatural\partightenfactor0
Helmut Tschemernjak 2:50e8a3c35d1f 6
Helmut Tschemernjak 2:50e8a3c35d1f 7 \f0\b\fs28 \cf0 The RadioShuttle protocol\
Helmut Tschemernjak 2:50e8a3c35d1f 8
Helmut Tschemernjak 2:50e8a3c35d1f 9 \b0 \
Helmut Tschemernjak 2:50e8a3c35d1f 10 The protocol is designed to send little messages between two or more devices. For simplification, we call the pair
Helmut Tschemernjak 2:50e8a3c35d1f 11 \i node
Helmut Tschemernjak 2:50e8a3c35d1f 12 \i0 and
Helmut Tschemernjak 2:50e8a3c35d1f 13 \i station
Helmut Tschemernjak 2:50e8a3c35d1f 14 \i0 . Here is the communication order:\
Helmut Tschemernjak 2:50e8a3c35d1f 15 \
Helmut Tschemernjak 2:50e8a3c35d1f 16
Helmut Tschemernjak 2:50e8a3c35d1f 17 \b a) Simple on-demand message (RS_Node_Online/RS_Node_Checking/RS_Node_Offline)\
Helmut Tschemernjak 2:50e8a3c35d1f 18
Helmut Tschemernjak 2:50e8a3c35d1f 19 \b0 1. Node sends a message request before sending the data, containing only the
Helmut Tschemernjak 2:50e8a3c35d1f 20 \f1\fs26 \CocoaLigature0 RadioHeader.\
Helmut Tschemernjak 2:50e8a3c35d1f 21 \'93MF_Response\'94 must be switched off in the flags. The header contains\
Helmut Tschemernjak 2:50e8a3c35d1f 22 the msgSize in the used RadioHeader, declaring hereby the expected data size,\
Helmut Tschemernjak 2:50e8a3c35d1f 23 the app ID, a msgID, and a response Window.\
Helmut Tschemernjak 2:50e8a3c35d1f 24 \
Helmut Tschemernjak 2:50e8a3c35d1f 25 2. The response from the station should be sent immediately with the\
Helmut Tschemernjak 2:50e8a3c35d1f 26 \'93MF_Response\'94 flag. In case the response cannot be sent\
Helmut Tschemernjak 2:50e8a3c35d1f 27 immediately, the response window is used by the station for the\
Helmut Tschemernjak 2:50e8a3c35d1f 28 scheduled time to send the response. In case the station cannot\
Helmut Tschemernjak 2:50e8a3c35d1f 29 handle the app it stays quiet and forgets about this request. The station\
Helmut Tschemernjak 2:50e8a3c35d1f 30 response may contain the flag \'93MF_SwitchOptions\'94 which allows turning on \
Helmut Tschemernjak 2:50e8a3c35d1f 31 additional options (channel, spreading factor and windowScale). An empty \
Helmut Tschemernjak 2:50e8a3c35d1f 32 options field means no change.\
Helmut Tschemernjak 2:50e8a3c35d1f 33 \
Helmut Tschemernjak 2:50e8a3c35d1f 34 3. After the node has received the station response, it knows when it is allowed \
Helmut Tschemernjak 2:50e8a3c35d1f 35 to send the final message data. The stations provided respWindow tells\
Helmut Tschemernjak 2:50e8a3c35d1f 36 the node when to send the data (usually when there is no other traffic scheduled).\
Helmut Tschemernjak 2:50e8a3c35d1f 37 The data message can contain the \'93flag MF_MoreDataToCome\'94, to indicate that\
Helmut Tschemernjak 2:50e8a3c35d1f 38 there are more messages pending for this app, In this case the station\
Helmut Tschemernjak 2:50e8a3c35d1f 39 sends a confirmation message (see 4.) with a new respWindow to send the\
Helmut Tschemernjak 2:50e8a3c35d1f 40 next data message.\
Helmut Tschemernjak 2:50e8a3c35d1f 41 \
Helmut Tschemernjak 2:50e8a3c35d1f 42 4. Optional confirmation message. In case the request contains the \
Helmut Tschemernjak 2:50e8a3c35d1f 43 flag \'93MF_SentCompletedConfirmed\'94 or \'93MF_MoreDataToCome\'94 the station must\
Helmut Tschemernjak 2:50e8a3c35d1f 44 confirm the reception using the \'93MF_RecvDataConfirmed\'94 flag in a \
Helmut Tschemernjak 2:50e8a3c35d1f 45 radio header response when requested. In case of \'93MF_MoreDataToCome\'94\
Helmut Tschemernjak 2:50e8a3c35d1f 46 the response message has be to sent with a new respWindow to\
Helmut Tschemernjak 2:50e8a3c35d1f 47 allow the node to send the next message. \
Helmut Tschemernjak 2:50e8a3c35d1f 48 \
Helmut Tschemernjak 2:50e8a3c35d1f 49 Example:\
Helmut Tschemernjak 2:50e8a3c35d1f 50 Node Station\
Helmut Tschemernjak 2:50e8a3c35d1f 51 - - - > Node to Station message request (\'93RadioHeader\'94 with 12 or 16 bytes)\
Helmut Tschemernjak 2:50e8a3c35d1f 52 < - - - Station to Node response (only \'93RadioHeader\'94 with response window time)\
Helmut Tschemernjak 2:50e8a3c35d1f 53 Channel switching may apply if \'93MF_SwitchOptions\'94 is specified\
Helmut Tschemernjak 2:50e8a3c35d1f 54 - - - > Node data to Station (communication completed, header + data)\
Helmut Tschemernjak 2:50e8a3c35d1f 55 < - - - Optionally acknowledge (when RadioHeader contains \'93
Helmut Tschemernjak 2:50e8a3c35d1f 56 \fs22 MF_NeedsConfirm\'94)
Helmut Tschemernjak 2:50e8a3c35d1f 57 \fs26 \
Helmut Tschemernjak 2:50e8a3c35d1f 58 \
Helmut Tschemernjak 2:50e8a3c35d1f 59 \
Helmut Tschemernjak 2:50e8a3c35d1f 60 \
Helmut Tschemernjak 2:50e8a3c35d1f 61
Helmut Tschemernjak 2:50e8a3c35d1f 62 \f0\b\fs28 \CocoaLigature1 b) Simple on-demand message RS_StationBasic/RS_StationServer\
Helmut Tschemernjak 2:50e8a3c35d1f 63
Helmut Tschemernjak 2:50e8a3c35d1f 64 \b0 As the stations have an own recording when the air is busy they can just send messages\
Helmut Tschemernjak 2:50e8a3c35d1f 65 anytime when there is no scheduled traffic for a given time window.\
Helmut Tschemernjak 2:50e8a3c35d1f 66
Helmut Tschemernjak 2:50e8a3c35d1f 67 \b \
Helmut Tschemernjak 2:50e8a3c35d1f 68 c) Receiving messages for RS_Node_Online\
Helmut Tschemernjak 2:50e8a3c35d1f 69
Helmut Tschemernjak 2:50e8a3c35d1f 70 \b0 As these types of node are always powered on, they stay always in receive mode
Helmut Tschemernjak 2:50e8a3c35d1f 71 \f1\fs26 \CocoaLigature0 ,
Helmut Tschemernjak 2:50e8a3c35d1f 72 \f0\fs28 \CocoaLigature1 which\
Helmut Tschemernjak 2:50e8a3c35d1f 73 means they can handle message requests as described. The station basically sends a \
Helmut Tschemernjak 2:50e8a3c35d1f 74 message to the
Helmut Tschemernjak 2:50e8a3c35d1f 75 \f1\fs26 \CocoaLigature0 \'93
Helmut Tschemernjak 2:50e8a3c35d1f 76 \f0\fs28 \CocoaLigature1 RS_Node_Online
Helmut Tschemernjak 2:50e8a3c35d1f 77 \f1\fs26 \CocoaLigature0 \'94
Helmut Tschemernjak 2:50e8a3c35d1f 78 \f0\fs28 \CocoaLigature1 including the data because the station knows when \
Helmut Tschemernjak 2:50e8a3c35d1f 79 the air is free to send messages.\
Helmut Tschemernjak 2:50e8a3c35d1f 80
Helmut Tschemernjak 2:50e8a3c35d1f 81 \f1\fs26 \CocoaLigature0 \
Helmut Tschemernjak 2:50e8a3c35d1f 82 Example:\
Helmut Tschemernjak 2:50e8a3c35d1f 83 Node Station\
Helmut Tschemernjak 2:50e8a3c35d1f 84 < - - - Station to Node message request (RadioHeader with 12 or 16 bytes)\
Helmut Tschemernjak 2:50e8a3c35d1f 85 Channel switching may apply if \'93MF_SwitchOptions\'94 are specified\
Helmut Tschemernjak 2:50e8a3c35d1f 86 - - - > Node to Station response (only RadioHeader with response window time = 0)\
Helmut Tschemernjak 2:50e8a3c35d1f 87 < - - - Station to Node_Online (Request with data, header + data)\
Helmut Tschemernjak 2:50e8a3c35d1f 88 - - - > Optionally acknowledge (when RadioHeader contains \'93
Helmut Tschemernjak 2:50e8a3c35d1f 89 \fs22 MF_NeedsConfirm\'94)
Helmut Tschemernjak 2:50e8a3c35d1f 90 \fs26 \
Helmut Tschemernjak 2:50e8a3c35d1f 91 \
Helmut Tschemernjak 2:50e8a3c35d1f 92 \
Helmut Tschemernjak 2:50e8a3c35d1f 93
Helmut Tschemernjak 2:50e8a3c35d1f 94 \f0\b\fs28 \CocoaLigature1 d) Receiving messages for RS_Node_Offline/RS_Node_Checking\
Helmut Tschemernjak 2:50e8a3c35d1f 95
Helmut Tschemernjak 2:50e8a3c35d1f 96 \b0 The node
Helmut Tschemernjak 2:50e8a3c35d1f 97 \f1\fs26 \CocoaLigature0 \'93
Helmut Tschemernjak 2:50e8a3c35d1f 98 \f0\fs28 \CocoaLigature1 RS_Node_Offline
Helmut Tschemernjak 2:50e8a3c35d1f 99 \f1\fs26 \CocoaLigature0 \'94
Helmut Tschemernjak 2:50e8a3c35d1f 100 \f0\fs28 \CocoaLigature1 is completely turned off (sleep mode) unless it starts. During the sleep period it will not be able to receive messages, unless it wakes up and sends a message request.\
Helmut Tschemernjak 2:50e8a3c35d1f 101 \
Helmut Tschemernjak 2:50e8a3c35d1f 102 The \'93RS_Node_Checking\'94 can send a checking window time slot where it repeatedly turns into receive\
Helmut Tschemernjak 2:50e8a3c35d1f 103 mode
Helmut Tschemernjak 2:50e8a3c35d1f 104 \f1\fs26 \CocoaLigature0 ,
Helmut Tschemernjak 2:50e8a3c35d1f 105 \f0\fs28 \CocoaLigature1 to allow listening to a RadioHeader packet at a specified time, e.g. every 90.010 seconds. The response of the checking window includes the current timestamp in milliseconds to allow to use correct sending slots. From time to time the checking node should repeat the checking window requests to update its timestamp in milliseconds. The time slot resolution is in milliseconds.\
Helmut Tschemernjak 2:50e8a3c35d1f 106 In case
Helmut Tschemernjak 2:50e8a3c35d1f 107 \f1\fs26 \CocoaLigature0 \'93
Helmut Tschemernjak 2:50e8a3c35d1f 108 \f0\fs28 \CocoaLigature1 RS_Node_Checking
Helmut Tschemernjak 2:50e8a3c35d1f 109 \f1\fs26 \CocoaLigature0 \'94
Helmut Tschemernjak 2:50e8a3c35d1f 110 \f0\fs28 \CocoaLigature1 receives responses from multiple stations it should use the response from the station with the best rssi and the second best rssi signal. (Main and backup stations.)\
Helmut Tschemernjak 2:50e8a3c35d1f 111 The checking node should be able to request the specified checking window, e.g. 6500 ms
Helmut Tschemernjak 2:50e8a3c35d1f 112 \f1\fs26 \CocoaLigature0 ,
Helmut Tschemernjak 2:50e8a3c35d1f 113 \f0\fs28 \CocoaLigature1 \
Helmut Tschemernjak 2:50e8a3c35d1f 114 and the station should respond with a window equal or less. The checking node should enter only in receive mode for reading the preamble and a few bytes (CAD detection). If no signal is active it\
Helmut Tschemernjak 2:50e8a3c35d1f 115 goes to sleep until the next checking period arrives. (The duration of the preamble detection depends in the spreading factor and bandwidth.)\cf2 \
Helmut Tschemernjak 2:50e8a3c35d1f 116 \cf0 \
Helmut Tschemernjak 2:50e8a3c35d1f 117
Helmut Tschemernjak 2:50e8a3c35d1f 118 \b Response windows\
Helmut Tschemernjak 2:50e8a3c35d1f 119
Helmut Tschemernjak 2:50e8a3c35d1f 120 \b0 To keep it simple without syncing the time of all devices, the response window is specified in milliseconds, the window time starts counting after the complete packet has been received. The sender needs to take into account the air duration of the packet, the receiver starts counting the response window after it received the message. The packet RadioHeader response window allows windows of up to 2048 ms, the \
Helmut Tschemernjak 2:50e8a3c35d1f 121 full RadioHeader allows 65536 ms. The option \'93
Helmut Tschemernjak 2:50e8a3c35d1f 122 \f1\fs26 \CocoaLigature0 MF_SwitchOptions\'94 allows a winScale scaling which will multiply the windows size.\
Helmut Tschemernjak 2:50e8a3c35d1f 123 \pard\tx543\pardeftab543\pardirnatural\partightenfactor0
Helmut Tschemernjak 2:50e8a3c35d1f 124
Helmut Tschemernjak 2:50e8a3c35d1f 125 \fs22 \cf0 winScale 1 uses respWindow * 1\
Helmut Tschemernjak 2:50e8a3c35d1f 126 winScale 2 uses respWindow * 2\
Helmut Tschemernjak 2:50e8a3c35d1f 127 winScale 3 uses respWindow * 3\
Helmut Tschemernjak 2:50e8a3c35d1f 128 \'85\
Helmut Tschemernjak 2:50e8a3c35d1f 129 winScale 15 use respWindow * 15
Helmut Tschemernjak 2:50e8a3c35d1f 130 \fs26 \
Helmut Tschemernjak 2:50e8a3c35d1f 131 \pard\tx566\tx1133\tx1700\tx2267\tx2834\tx3401\tx3968\tx4535\tx5102\tx5669\tx6236\tx6803\pardirnatural\partightenfactor0
Helmut Tschemernjak 2:50e8a3c35d1f 132 \cf0 \
Helmut Tschemernjak 2:50e8a3c35d1f 133 \
Helmut Tschemernjak 2:50e8a3c35d1f 134
Helmut Tschemernjak 2:50e8a3c35d1f 135 \f0\b\fs28 \CocoaLigature1 Password authentication\
Helmut Tschemernjak 2:50e8a3c35d1f 136
Helmut Tschemernjak 2:50e8a3c35d1f 137 \b0 Each app can use an optional password when specified with the RegisterApplication() call. The password can be a simple string or a block of binary data. For binary data it is required to specify the password length parameter. A 16 byte long random password is recommended or even 32 bytes to avoid simple password attacks. The password can be empty (NULL) which means there is no password authentication. If the app password is specified it must be identical on all nodes and station communicating together. When the password is set, the node must call Connect() with the app ID and the remote station ID. The password is never transferred directly over the air, instead of the client receives a random number which is used to create a hash code of the password and send the hash product for authentication to the station which compares the product with its password/random number hash.\
Helmut Tschemernjak 2:50e8a3c35d1f 138 The RadioSecurityInterface specifies an API for providing the password hashing and data encryption algorithm. It uses SHA256 for passwords and AES128 for content encryption.\
Helmut Tschemernjak 2:50e8a3c35d1f 139 \
Helmut Tschemernjak 2:50e8a3c35d1f 140
Helmut Tschemernjak 2:50e8a3c35d1f 141 \b Message content encryption\
Helmut Tschemernjak 2:50e8a3c35d1f 142
Helmut Tschemernjak 2:50e8a3c35d1f 143 \b0 If passwords are specified (see Password Authentication), message data encryption can be enabled per
Helmut Tschemernjak 2:50e8a3c35d1f 144 \f1\fs26 \CocoaLigature0 \'93
Helmut Tschemernjak 2:50e8a3c35d1f 145 \f0\fs28 \CocoaLigature1 SendMsg()
Helmut Tschemernjak 2:50e8a3c35d1f 146 \f1\fs26 \CocoaLigature0 \'94
Helmut Tschemernjak 2:50e8a3c35d1f 147 \f0\fs28 \CocoaLigature1 call specifying \'93MF_Encrypted\'94 in the flags field. For encrypting the data the RadioSecurityInterface provided security implementation uses AES 128-bit which ensures nobody in the middle can decrypt the messages and send fake messages. For non-encrypted messages the size of an app message can be as little as one byte. Encrypted messages are automatically padded to a multiple of 128-bit which means at 16 bytes per message.\
Helmut Tschemernjak 2:50e8a3c35d1f 148 \
Helmut Tschemernjak 2:50e8a3c35d1f 149 Encrypted messages considerations/disadvantages\
Helmut Tschemernjak 2:50e8a3c35d1f 150 - Minimum data size is 16 bytes (consider that this is a 50 ms data transfer overhead using SF7, with SF11 it is many times longer).\
Helmut Tschemernjak 2:50e8a3c35d1f 151 - The communication works only between one node and one station (connected pair)\
Helmut Tschemernjak 2:50e8a3c35d1f 152 Non-encrypted messages can be sent to multiple stations (e.g.: broadcast messages for device ID 0)\
Helmut Tschemernjak 2:50e8a3c35d1f 153 which can be processed by any station supporting this app ID, which allows failover solutions.\
Helmut Tschemernjak 2:50e8a3c35d1f 154 - For simple data like a temperature sensor
Helmut Tschemernjak 2:50e8a3c35d1f 155 \f1\fs26 \CocoaLigature0 ,
Helmut Tschemernjak 2:50e8a3c35d1f 156 \f0\fs28 \CocoaLigature1 or similar
Helmut Tschemernjak 2:50e8a3c35d1f 157 \f1\fs26 \CocoaLigature0 ,
Helmut Tschemernjak 2:50e8a3c35d1f 158 \f0\fs28 \CocoaLigature1 it may not be required to use encrypted messages, however for security concerned messages (e.g. door alarm, light switch) encrypted messages are a must have.\
Helmut Tschemernjak 2:50e8a3c35d1f 159 \
Helmut Tschemernjak 2:50e8a3c35d1f 160
Helmut Tschemernjak 2:50e8a3c35d1f 161 \b Device IDs\
Helmut Tschemernjak 2:50e8a3c35d1f 162
Helmut Tschemernjak 2:50e8a3c35d1f 163 \b0 Each node communicating with the RadioShuttle protocol must have a unique number \'96\'a0each node as well as each station. Think about this like MAC addresses. This unique device IDs are required to allow secure and reliable communication. RadioShuttle licenses will find the device ID labeled on the RadioShuttle enabled board with an access code
Helmut Tschemernjak 2:50e8a3c35d1f 164 \f1\fs26 \CocoaLigature0 ,
Helmut Tschemernjak 2:50e8a3c35d1f 165 \f0\fs28 \CocoaLigature1 or can purchase licenses at www.radioshuttle.de.\
Helmut Tschemernjak 2:50e8a3c35d1f 166 \
Helmut Tschemernjak 2:50e8a3c35d1f 167
Helmut Tschemernjak 2:50e8a3c35d1f 168 \b App IDs\
Helmut Tschemernjak 2:50e8a3c35d1f 169
Helmut Tschemernjak 2:50e8a3c35d1f 170 \b0 Each node or station can support multiple different services which are called app IDs (application IDs) which are unique worldwide. These app IDs are, similar to TCP/IP port numbers, just an ID to route communication messages. The worldwide unique app IDs can be obtained free of charge for developers at www.radioshuttle.de by agreeing to stay compatible with the RadioShuttle protocol.\
Helmut Tschemernjak 2:50e8a3c35d1f 171 The central app registration has also the benefit to share the app data content with others, to ensure solution compatibility. However is not needed to share any app ID content details. Think about a basic communication that goes from one device ID (e.g. 1111) using app ID 1234 to device ID 2222 being received by app ID 1234 when available on this device. Node/stations receiving unknown app ID requests will automatically ignore these.\
Helmut Tschemernjak 2:50e8a3c35d1f 172 \
Helmut Tschemernjak 2:50e8a3c35d1f 173
Helmut Tschemernjak 2:50e8a3c35d1f 174 \b Message Retry Count considerations\
Helmut Tschemernjak 2:50e8a3c35d1f 175
Helmut Tschemernjak 2:50e8a3c35d1f 176 \b0 The Radioshuttle protocol uses a retry count of three attempts to complete a message communication. It makes no sense to have this retry count adjustable because when there is not reliable communication the retry attempts just keeps the network busy. More over the message request/response is not retrying every single sent or acknowledge packet three times, if the message transaction does not complete it tries it again. Single packets like acknowledge and a receives message are not retried, instead the entire message transaction is retried when needed.\
Helmut Tschemernjak 2:50e8a3c35d1f 177 \
Helmut Tschemernjak 2:50e8a3c35d1f 178 In case the message transfers are not reliable and often time out check the following:\
Helmut Tschemernjak 2:50e8a3c35d1f 179 - Is the antenna and its connection correct?\
Helmut Tschemernjak 2:50e8a3c35d1f 180 - Is it a long distance than switch a a higher spreading factor (e.g. from SF7 to SF9 or up to SF11)\
Helmut Tschemernjak 2:50e8a3c35d1f 181 - Maybe the bandwidth setting is to high (e.g. 500 kHz switch to a smaller bandwidth (125 kHz, lower than 125 kHz require a TCXO crystal)\
Helmut Tschemernjak 2:50e8a3c35d1f 182 - Is the station location optimal?\
Helmut Tschemernjak 2:50e8a3c35d1f 183 Lets say in a case covering a multi-family house, it may be a smart to but the station across the building. Another option is to put the station into the middle of the building. \
Helmut Tschemernjak 2:50e8a3c35d1f 184 \
Helmut Tschemernjak 2:50e8a3c35d1f 185 }