Skip to content

Commit 16038f2

Browse files
nseidlenseidle
authored
Merge pull request #481 from LeeLeahy2/doc-training
Document LoRaSerial radio training
2 parents 46e054e + 8585e95 commit 16038f2

File tree

2 files changed

+302
-0
lines changed

2 files changed

+302
-0
lines changed

‎Documents/Readme.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,12 @@ The LoRaSerial radio operates in one of three modes:
1717
* Point-to-Point (default)
1818
* Multipoint
1919
* Virtual Circuit
20+
* Training
2021

2122
Point-to-Point mode provides guaranteed message delivery or the link breaks. The radio performs data retransmission if either the data frame was lost or its acknowledgement was lost. This can continue indefinitely if MaxResends equals zero (default) or for a limited number of retries in the range of (1 - 255).
2223

2324
Multipoint mode provides a datagram service. The LoRaSerial radios will send the data frame without a guarantee that the frame will be received by the remote radio. Lost frames are lost, the radio does no perform retransmission. If the application is not able to tolerate the lost frames then another protocol layer needs to be implemented on the host computer between the radio and the application that provides the necessary services to the application.
2425

2526
Virtual circuit mode enables a group of radios to communicate with each other. The radio links provide guaranteed message delivery or the link is broken. One radio in the group is designated as the server and provides the channel timer synchronization for the client radios, think of a star configuration with the server at the center. Data communications with the virtual circuit mode is all point-to-point. Communications between the radio and the host CPU use a special virtual circuit header to identify where to send the host to radio data, or where to deliver the radio to host data. More information is available [here](https://github.com/sparkfun/SparkFun_LoRaSerial/blob/release_candidate/Documents/Virtual_Circuits.md).
27+
28+
Training is a temporary mode of operation to initialize a set of radios for one of the other modes of operation. There are one or more clients and a single server during training. The mode specific parameters for the other mode of operation are passed from the server to each of the clients. Upon completion all of the radios in the set will be able to communicate with one another. More information on training is available [here](https://github.com/sparkfun/SparkFun_LoRaSerial/blob/release_candidate/Documents/Training.md).

‎Documents/Training.md‎

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
LoRaSerial Training
2+
===================
3+
4+
# Goals
5+
6+
There are two goals for LoRaSerial training:
7+
8+
1 Establish a common set of communication parameters between a set of LoRaSerial radios.
9+
2 Make it easy to test an initial pair of LoRaSerial radios through the use of the training button.
10+
11+
# Methods of Training
12+
13+
There are two methods of initiating training:
14+
15+
* Pressing the training button on the top of the LoRaSerial module
16+
* Entering the ATT command
17+
18+
Training is performed by a server radio sending parameters to the client radio. Upon reception the client radio saves the parameters in non-volatile memory and then reboots with the new parameters.
19+
20+
## Training Button Behavior
21+
22+
Pressing and releasing the training button for different lengths of time initiates the following behaviors:
23+
24+
* 2 Seconds:
25+
* Enter training as a client, cylon pattern appears on the green LEDs
26+
* Exit training (client or server) without saving parameter changes, cylon pattern stops and previous LED pattern returns
27+
* 5 Seconds - Enter training as a server, yellow LED flashes 3 times when 5 seconds of press time is detected, cylon pattern appears on the green LEDs when the button is released
28+
* 15 Seconds - Reset LoRaSerial to factory settings and erase NVM, blue LED flashes 3 times when 15 seconds of press time is detected
29+
30+
# Temporary Training Server
31+
32+
It is possible to use temporary training servers for multipoint and virtual circuit modes. The only difference with a temporary server and a regular server is that the parameters are not saved to the non-volatile storage using the ATW command before exiting command mode.
33+
34+
# Point-To-Point Training
35+
36+
To get a known set of parameters on the client radio, use command mode to initialize the parameters on the server. Using the training buttons on both radios only changes
37+
the network ID and encryption key values, it does not change any of the other parameters such as AirSpeed.
38+
39+
Point-to-Point Training Examples:
40+
41+
Server:
42+
* Enter command mode using +++
43+
* Optional, start from factory defaults by issuing the ATF command
44+
* Set the desired parameters
45+
* Set Server=1
46+
* Enter training mode using ATT command
47+
* After the client is trained
48+
* Saves new parameters for netID and encryptionKey
49+
* Reboots
50+
51+
Server (no clients):
52+
* Enter command mode with +++
53+
* Set any of the desired parameters
54+
* Enter training mode with ATT command
55+
* No client to be trained
56+
* Exit command mode with ATO or ATZ
57+
58+
Assuming the radios are already able to communicate, use the training button to select a random NetID and EncryptionKey value.
59+
60+
Server:
61+
* 2 second training button press
62+
* Does not receive training from a server
63+
* After 3 seconds, generates new netID and encryption key and automatically switches to server mode
64+
* Wait for client to be trained
65+
* Saves new parameters for netID and encryptionKey
66+
* Reboots
67+
68+
Server:
69+
* 5 second training button press
70+
* Generates new netID and encryption key
71+
* Wait for client to be trained
72+
* Saves new parameters for netID and encryptionKey
73+
* Reboots
74+
75+
Client:
76+
* 2 second training button press
77+
* Receives training parameters from server
78+
* Saves new parameters
79+
* Reboots
80+
81+
Client:
82+
* Enter command mode using +++
83+
* Enter training using the ATT command
84+
* Receives training parameters from server
85+
* Saves new parameters
86+
* Reboots
87+
88+
Point-To-Point Timeout Examples:
89+
90+
Client:
91+
* 2 second training button press
92+
* Before three seconds
93+
* 2 second training button press, exits training without receiving any new parameters
94+
95+
Server:
96+
* 2 second training button press
97+
* Does not receive training from a server
98+
* After 3 seconds, generates new netID and encryption key and automatically switches to server mode
99+
* 2 second training button press, exits training and does not save new netID or encryption key
100+
101+
Server:
102+
* 5 second training button press
103+
* Generates new netID and encryption key
104+
* 2 second training button press, exits training and does not save new netID or encryption key
105+
106+
# Multi-Point Training
107+
108+
It is recommend to use a command script to initialize the server radio when performing multipoint traning. The client radios can either use command mode or the training button to enter training mode.
109+
110+
Temporary Server (Doesn't save settings):
111+
* If not already at factory reset, hold the training button down for 15 seconds
112+
* Connect to the LoRaSerial radio via USB or the serial port
113+
* Enter command mode with +++
114+
* Start from factory defaults by issuing the ATF command
115+
* Issue the following commands:
116+
* AT-OperatingMode=0
117+
* AT-Server=1
118+
* AT-SelectLedUse=1
119+
* ATG
120+
* Set any of the other parameters
121+
* Enter training mode with ATT command
122+
* Wait for clients to be trained
123+
* Exit command mode with ATO command or reboot with ATZ command
124+
125+
Server (Saves settings):
126+
* If not already at factory reset, hold the training button down for 15 seconds
127+
* Connect to the LoRaSerial radio via USB or the serial port
128+
* Enter command mode with +++
129+
* Start from factory defaults by issuing the ATF command
130+
* Issue the following commands:
131+
* AT-OperatingMode=0
132+
* AT-Server=1
133+
* AT-SelectLedUse=1
134+
* ATG
135+
* Set any of the other parameters
136+
* Enter training mode with ATT command
137+
* Wait for clients to be trained
138+
* Save parameters with ATW command
139+
* Always reboot with ATZ command
140+
141+
Client:
142+
* 2 second training button press
143+
* Receives training parameters from server
144+
* Saves new parameters
145+
* Reboots
146+
147+
Client:
148+
* Connect to the LoRaSerial radio via USB or the serial port
149+
* Enter command mode using +++
150+
* Enter training using the ATT command
151+
* Receives training parameters from server
152+
* Saves new parameters
153+
* Reboots
154+
155+
# Virtual Circuit Training
156+
157+
It is recommend to use a command script to initialize the server radio when performing virtual-circuit traning. The client radios can either use command mode or the training button to enter training mode.
158+
159+
Temporary Server (Doesn't save settings):
160+
* If not already at factory reset, hold the training button down for 15 seconds
161+
* Connect to the LoRaSerial radio via USB or the serial port
162+
* Enter command mode with +++
163+
* Start from factory defaults by issuing the ATF command
164+
* Issue the following commands:
165+
* AT-OperatingMode=2
166+
* AT-Server=1
167+
* AT-SelectLedUse=2
168+
* ATG
169+
* Set any of the other parameters
170+
* Enter training mode with ATT command
171+
* Wait for clients to be trained
172+
* Exit command mode with ATO command or reboot with ATZ command
173+
174+
Server (Saves settings):
175+
* If not already at factory reset, hold the training button down for 15 seconds
176+
* Connect to the LoRaSerial radio via USB or the serial port
177+
* Enter command mode with +++
178+
* Start from factory defaults by issuing the ATF command
179+
* Issue the following commands:
180+
* AT-OperatingMode=2
181+
* AT-Server=1
182+
* AT-SelectLedUse=2
183+
* ATG
184+
* Set any of the other parameters
185+
* Enter training mode with ATT command
186+
* Wait for clients to be trained
187+
* Save parameters with ATW command
188+
* Always reboot with ATZ command
189+
190+
Client:
191+
* 2 second training button press
192+
* Receives training parameters from server
193+
* Saves new parameters
194+
* Reboots
195+
196+
Client:
197+
* Connect to the LoRaSerial radio via USB or the serial port
198+
* Enter command mode using +++
199+
* Enter training using the ATT command
200+
* Receives training parameters from server
201+
* Saves new parameters
202+
* Reboots
203+
204+
# Training Parameters
205+
206+
The training parameters for radio communication fall into two groups:
207+
208+
* Radio parameters
209+
* Radio protocol parameters
210+
211+
Other optional sets of training parameters may be communicated between the radios when the corresponding copyXxxx parameter is set to true (1). The optional parameter sets are:
212+
213+
* Serial parameters
214+
* Debug parameters
215+
* Trigger parameters
216+
217+
The following sections describe the communication parameters.
218+
219+
## Radio Parameters
220+
221+
The following parameters describe the radio transmit operation:
222+
223+
* AutoTuneFrequency - Adjust the frequency based upon the last received frame's frequency error.
224+
225+
* FrequencyHop - Enable or disable frequency hopping. Legal operation in the United States requires that this value be set to true (1) which is the default. This parameter specifies whether the radio will change frequencies to a new channel every MaxDwellTime milliseconds.
226+
227+
* FrequencyMax - Maximum frequency the radio will use specified in MegaHertz. The default value is 928.0 MHz.
228+
229+
* FrequencyMin - Minimum frequency the radio will use specified in MegaHertz. The default value is 902.0 MHz.
230+
231+
* MaxDwellTime - Number of milliseconds that the LoRaSerial radio uses a specific frequency (channel). After this time, the radio switches (hops) to another frequency. For operation within the United States this value must not be greater than 400 milliseconds which is the default.
232+
233+
* NumberOfChannels - Specify the number of unique frequencies that will be used by the LoRaSerial radio. For operation within the United States this value needs to be a minimum of 50 which is the default value.
234+
235+
* RadioBroadcastPower_dbm - Transmit power level for the LoRaSerial radio. The valid range for this parameter is from 14 (25 milliWatts) to 30 dBm (1 Watt). The default value is 30 dBm.
236+
237+
### Frame Synchronization Parameters
238+
239+
The following parameters specify data that the radios use for data synchronization and frame reception:
240+
241+
* RadioPreambleLength - Number of symbols to transmit at the beginning of the frame to notify the receiving radios of the incoming frame. The range of values are 6 to 65535 with the default being 8. The preamble is used to synchronize the PLLs in the radio to properly detect the symbol boundaries. NOTE: Different lengths does *not* guarantee a remote radio privacy. 8 to 11 works. 8 to 15 drops some. 8 to 20 is silent.
242+
243+
* RadioSyncWord - The sync word following the preamble indicates the destination set of radios. Note that different sync words do *not* guarantee a remote radio will not receive a rogue frame.
244+
245+
### AirSpeed
246+
247+
The parameter AirSpeed is a simplification that selects values for the following parameters to approximate the baud rate implied by the AirSpeed.
248+
249+
* HeartbeatTimeout
250+
* RadioBandwidth
251+
* RadioCodingRate
252+
* RadioSpreadFactor
253+
* TxToRxUsec
254+
255+
Valid values for AirSpeed are (40, 150, 400, 1200, 2400, 4800, 9600, 19200, 28800 and 38400) and the default is 4800. After AirSpeed is set, it is possible to modify any of the parameters above. Note that AirSpeed is just an easy way to set the parameters above to known value. AirSpeed is not an actual parameter that is used for training, only the parameters listed above are used during training. More detail for these parameters is provided below:
256+
257+
* HeartbeatTimeout - Heartbeats are transmitted on a regular basis by the server and in point-to-point and virtual circuit modes by the clients. This parameter specifies the time in milliseconds during which a HEARTBEAT frame should be transmitted. If a HEARTBEAT frame is not received within three (3) times this interval then the point-to-point or virtual circuit link is broken. The default heartbeatTimeout is 5000 milliseconds (5 seconds).
258+
259+
* RadioBandwidth - Bandwidth of the spread spectrum signal specified in kiloHertz. The default is 500.0 kHz and other supported values are: 10.4, 15.6, 20.8, 31.25, 41.7, 62.5, 125 and 250 kHz.
260+
261+
* RadioCodingRate - Number of bits to send 4 data bits of information. This is used for forward error correction, allowing the receiver to correct the incoming bit stream. Valid values are 5 through 8 where higher coding rates ensure less frames are dropped. The default value is 8.
262+
263+
* RadioSpreadFactor - Number of bits in a symbol. Valid values are 6 to 12 with the default value of 9. Larger values enable longer range while reducing the data rate.
264+
265+
* TxToRxUsec - Transition time from end of transmission to the end of reception on the remote radio specified in microseconds.
266+
267+
## Radio protocol parameters
268+
269+
The following parameters describe the contents of the data frame sent between the LoRaSerial radios:
270+
271+
* DataScrambling - Enable (1) or disable (0) the use of IBM's Data Whitening algorithm to reduce DC bias
272+
273+
* EnableCRC16 - Enable (1) or disable (0) adding a software generated CRC-16 to the end of the data frame.
274+
275+
* EncryptData - Enable (1) or disable (0) the use of AES encryption for each data frame
276+
277+
* EncryptionKey - The 16 byte encryption key specified in hexadecimal. While SparkFun provides a default value, it is strongly recomended to change this value for your own networks.
278+
279+
* FramesToYield - When requested by the remote radio, suppress transmission for this number of max packet frames. The valid range is 0 to 255 with a default value of 3.
280+
281+
* MaxResends - Number of retransmission attempt to make for a each frame when an ACK is not received from the destination radio. The valid range is 0 to 255. The default of zero represents infinite and retries will continue as long as the two radios are receiving HEARTBEAT frames from each other. The transmission will fail only when the link breaks due to not receiving HEARTBEAT frames.
282+
283+
* NetID - A unique value denoting the network of LoRaSerial radios. All radios in the network must share the same ID value. This value is in addition to the radioSyncWord.
284+
285+
* OperatingMode - The following modes of operation are supported by the LoRaSerial radios:
286+
287+
* MODE_MULTIPOINT (0) - A single server with multiple clients, all radios are sending datagram frames which are not guarranteed to be received by the other radios. This mode is great when real-time transmission is necessary and the application is able to tolerate some loss of data.
288+
289+
* MODE_POINT_TO_POINT (1, default) - Communications between only two LoRaSerial radios with guarranteed delivery of frames or the link breaks.
290+
291+
* MODE_VIRTUAL_CIRCUIT - A single server with multiple clients that supports multipoint communications with guarranteed delivery or the link breaks. This mode uses a special protocol over the serial link to be able to specify the destination radio for transmission and the receive radio for reception. More information is available [here](https://github.com/sparkfun/SparkFun_LoRaSerial/blob/release_candidate/Documents/Virtual_Circuits.md).
292+
293+
* OverheadTime - The number of milliseconds to add to ACK and datagram times before ACK timeout occurs. The default is 10 milliseconds.
294+
295+
* SelectLedUse - Select how to display information on the LEDs
296+
297+
* Server - Enable (1) or disable (0) the server mode for training and for multipoint or virtual circuit operation. The default is client mode (0).
298+
299+
* VerifyRxNetID - Enable (1) or disable (0) the verification of the netID value during reception. The default is enabled (1).

0 commit comments

Comments
 (0)