From 19f18fe0968a8738a9da6ef86d81b9c95dca8c16 Mon Sep 17 00:00:00 2001 From: Lee Leahy Date: Sat, 4 Mar 2023 07:53:43 -1000 Subject: [PATCH] Add the virtual circuit documentation --- docs/at_commands.md | 28 ++-- docs/operating_modes.md | 289 +++++++++++++++++++++++++++++++++++++++- docs/quick_start.md | 1 + docs/training.md | 53 ++++++++ 4 files changed, 360 insertions(+), 11 deletions(-) diff --git a/docs/at_commands.md b/docs/at_commands.md index 647ea0e1..e729ce2a 100644 --- a/docs/at_commands.md +++ b/docs/at_commands.md @@ -11,7 +11,9 @@ Below is a brief list of commands: |+++ | Enter command mode | |AT | Reports OK | |AT? | Display help text | +|ATA | Get the current VC status | |ATB | Break the link | +|ATC | Establish VC connection for data | |ATD | Display the debug settings | |ATF | Restore factory settings | |ATG | Generate new netID and encryption key | @@ -23,6 +25,7 @@ Below is a brief list of commands: |ATR | Display radio settings | |ATS | Display the serial settings | |ATT | Enter training mode | +|ATV | Display virtual circuit settings | |ATW | Save current settings to NVM | |ATZ | Reboot the radio | |AT-Param=xxx| Set parameter's value to xxx by name (Param)| @@ -70,7 +73,7 @@ A table of the subset of the common Radio Link Parameters is available [here](im | AT-MaxResends | Attempts before dropping packet | AT-NetID | Network ID | AT-NumberOfChannels | Divide available spectrum by this amount -| AT-OperatingMode | Multipoint or P2P +| AT-OperatingMode | Multipoint, P2P, or VC | AT-OverHeadtime | Additional ms before ACK timeout occurs | AT-PreambleLength | Set LoRa preamble length | AT-SelectLedUse | Define LED behavior @@ -118,7 +121,7 @@ A table of the subset of the common Radio Link Parameters is available [here](im * **FrequencyMin/FrequencyMax** - These are the lower and upper bounds for the allowed transmission frequencies in megahertz. By default, this is 902.0 to 928.0. -* **HeartbeatTimeout** - Heartbeats are transmitted on a regular basis by the server and in point-to-point mode 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 link is broken. The default heartbeatTimeout is 5000 milliseconds (5 seconds). +* **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). * **MaxDwellTime** - The number of milliseconds of transmission allowed on a given frequency before hopping intra-packet. The default is 400ms to be compliant with FCC Part 15.247. This means the radio will change its frequency to the next channel in the hop table during the packet transmission. Note this is the maximum dwell time; depending on the air speed setting the radio may have a hopping period that is shorter than the dwell time. @@ -128,19 +131,21 @@ A table of the subset of the common Radio Link Parameters is available [here](im * **NumberOfChannels** - The available spectrum (default is 902MHz to 928MHz) is divided by this number of channels to create the channel spacing and allowed frequency list (aka the ‘hop table’). The default is 50 channels to meet FCC Part 15.247 compliance and may be changed to meet local regulations. -* **OperatingMode** - The radios can operate in one of two different modes: Multipoint and Point-To-Point. See [Operating Modes](http://docs.sparkfun.com/SparkFun_LoRaSerial/operating_modes/) for more information. +* **OperatingMode** - The radios can operate in one of three different modes: Multipoint, Point-To-Point and Virtual Circuit. See [Operating Modes](http://docs.sparkfun.com/SparkFun_LoRaSerial/operating_modes/) for more information. + MODE_MULTIPOINT (0) - A single server with multiple clients. All radios may broadcast to all other radios, but data is not guaranteed to be received by the other radios. This mode is great when real-time transmission is necessary and the application can tolerate some loss of data. + MODE_POINT_TO_POINT (1, default) - Communications between two LoRaSerial radios with guaranteed delivery of frames or the link breaks. + + MODE_VIRTUAL_CIRCUIT (2) - A single server with multiple clients that supports multipoint communications with guaranteed 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](http://docs.sparkfun.com/SparkFun_LoRaSerial/operating_modes/#virtual-circuits). + * **OverheadTime** - The number of milliseconds to add to ACK and datagram times before ACK timeout occurs. The default is 10 milliseconds. * **PreambleLength** - The number of sync words to send at the start of a packet. Note that two LoRa radios with the same settings but different preamble lengths have been shown to intermittently receive packets from each other. Therefore, using a unique preamble length does *not* guarantee exclusivity. Allowed values: 6 to 65535. * **SelectLedUse** - Select how to display information on the LEDs. See [LED States](http://docs.sparkfun.com/SparkFun_LoRaSerial/led_states/) for more information. -* **Server** - Enable (1) or disable (0) the server mode for training and for multipoint operation. The default is client mode (0). The radio designated as Server synchronizes the network. A server is required for Multipoint and Training modes. +* **Server** - Enable (1) or disable (0) the server mode for training and for multipoint or virtual circuit operation. The default is client mode (0). The radio designated as Server synchronizes the network. A server is required for Multipoint, Virtual Circuit and Training modes. * **SpreadFactor** - The spread factor used during LoRa transmissions. It is recommended to use the airspeed setting unless you are very aware of the consequences. This setting is overwritten if the AirSpeed setting is changed. In general, a higher spread factor provides a longer range, but a lower overall data rate. Allowed spread factors: 6 to 12 (inclusive). @@ -198,8 +203,9 @@ A table of the subset of the common Radio Link Parameters is available [here](im | ATI8 | Display system unique ID | ATI9 | Display the maximum datagram size | ATI10 | Display radio metrics -| ATI13 | Display the SX1276 registers -| ATI14 | Dump the radioTxBuffer +| ATI30 | Return myVc value +| ATI31 | Display the VC details +| ATI32 | Dump the NVM unique ID table * **ATI0** - List all available AT commands. @@ -217,15 +223,17 @@ A table of the subset of the common Radio Link Parameters is available [here](im * **ATI7** - Displays the current channel number. For example: "29". -* **ATI8** - Displays the unique 32-character, 16-byte, 128-bit value marked into the SAMD21 microcontroller. For example: "5BCEDAE13630595020312E32102317FF". +* **ATI8** - Displays the unique 32-character, 16-byte, 128-bit value marked into the SAMD21 microcontroller. Used during Virtual Circuit mode to assign destination IDs. For example: "5BCEDAE13630595020312E32102317FF". * **ATI9** - Displays the maximum number of bytes that can be transmitted. Different radio settings will use fewer or a greater number of bytes for overhead. For example: "249". * **ATI10** - Displays a large number of metrics related to the radio link including datagrams sent, link uptime, ACK counts, buffer states, etc. -* **ATI13** - Displays the contents of all the registers in the SX1276 LoRa transceiver. +* **ATI30** - Displays the assigned simplified Virtual Circuit ID assigned by the server. For example, "myVc: 3". + +* **ATI31** - Displays the Virtual Circuit state of this radio as it relates to the network. -* **ATI14** - Displays the contents of the current transmit buffer. +* **ATI32** - Displays a list of all the unique IDs of the known clients used in Virtual Circuit mode. ## Remote Training @@ -233,7 +241,7 @@ Currently, only one remote command is supported - **RTT**. Issuing this command This command is generally used to remotely configure a radio. First, the **RTT** command is issued, the local radio is configured (including enabling Server), then the **ATT** is issued to push the local radio into training. Because the local radio is the server, its settings are set to the remote radio. The remote radio will reset and start with these newly issued settings. The local radio needs to reset with an **ATZ** command and the link should be re-established with new settings. Below is a command script to achieve this remote configuration. We assume the radios are currently linked at the start of the script. -*Note:* RTT is only supported in P2P mode. +*Note:* RTT is only supported in P2P and VC modes. +++ RTT diff --git a/docs/operating_modes.md b/docs/operating_modes.md index c1c14f2c..552f2833 100644 --- a/docs/operating_modes.md +++ b/docs/operating_modes.md @@ -1,9 +1,10 @@ # Operating Modes -LoRaSerial radios can operate in one of two modes. +LoRaSerial radios can operate in one of three modes. * [Point to Point](https://docs.sparkfun.com/SparkFun_LoRaSerial/operating_modes/#point-to-point) * [Multipoint](https://docs.sparkfun.com/SparkFun_LoRaSerial/operating_modes/#multipoint) +* [Virtual Circuits](https://docs.sparkfun.com/SparkFun_LoRaSerial/operating_modes/#virtual-circuits) ## Point to Point @@ -43,3 +44,289 @@ Disadvantages of Multipoint: * Data is not retransmitted if lost. * Additional setup requirements: One radio must be configured as Server. + +## Virtual Circuits + +Virtual Circuit mode combines the data guarantee of P2P but allows multiple radios to coexist. + +VC mode is ideal for small amounts of data (tens of bytes) to be delivered to a given recipient in the network. Because of the nature of VC more radio overhead means there is less usable bandwidth for user data. VC mode should not be used to transmit long streams of data. + +Benefits of Virtual Circuits: + +* Guaranteed delivery of a given data packet to a specific host (broadcast also supported). +* Up to 32 radios can co-exist on the network. + +Disadvantages of Virtual Circuits: + +* Additional setup requirements: One radio must be configured as Server. +* Data packets must be fully formed. The application layer must add a four-byte header to all outgoing data, as well as correctly parse incoming data packets. +* The user must obtain the radio's unique system ID as the network is built in order to know where to address data to (and from). +* Lots of data being sent across a spotty link can lead to the link going down. +* Retransmits will add to latency. + + +### Virtual Circuit Network Configuration + +A LoRaSerial virtual circuit network consists of a single server radio and up to 31 client radios. The server transmits HEARTBEAT frames that provide the synchronization signal for the channel hop timer. Each time the timer fires, the radio switches to a new center frequency (channel). + +Clients wait to receive a HEARTBEAT frame from the server on channel 0. After receiving the server's HEARTBEAT frame the client synchronizes its hop timer and starts hopping channels. + +The virtual circuit server assigns virtual circuit ID numbers to all of the client radios. This may be done during radio training or during the first time the radio is connected to the network. After receiving a HEARTBEAT frame from the server, the client sends a HEARTBEAT frame with the source VC address of VC_UNASSIGNED and the radio's 16-byte unique ID. The server echoes this HEARTBEAT replacing the source VC with the assigned VC number. While the client is using VC_UNASSIGNED as its VC number, the client radio compares the unique ID in the HEARTBEAT frame to the local radio's unique ID value. If the values match then the client replaces its VC number with the assigned VC number. + +For consistent processing, the server records the clients' unique ID values in the non-volatile memory. These values are read and loaded into the virtual circuit table when the system boots again. + +### Radio Parameters + +Select a LoRaSerial radio for the virtual circuit server. Set the following parameters on the server radio. + +The following parameters should be set to enable virtual circuit mode: + +* AT=OperatingMode=2 - Select virtual circuit mode +* AT-NetID=n - Choose a unique value (n) for your network +* AT-VerifyNetID=1 - Eliminate communications from other radios which are not using the NetID value +* AT-EnableCRC16=? - Enable software CRC-16 by setting the value to 1, otherwise set the value to zero to disable software CRC +* AT-EncryptionKey=? - Choose a unique encryption key for the network +* AT-SelectLedUse=2 - The use of LEDS_VC (2) flashes the blue LED when server HEARTBEAT frames are received by the clients, providing a visual indication that the radio is synchronizing with the server +* AT-Server=1 - Define this radio as the virtual circuit server +* ATW - Write the parameters to the non-volatile memory (NVM). + +Now enter training mode with the ATT command. The training enables the server to pass these parameters (excluding the AT-Server setting itself) to the client radios. On the client radios, with power applied, press the button at the top of the client radio to enter training mode. The radio will obtain the parameters from the server, write them to NVM and then reboot using the new parameters. + +After all of the client radios are trained, the ATZ command may be entered on the server radio to cause it to reboot. + +#### Example Virtual Circuit Initialization Script for Training + + +++ + AT=OperatingMode=2 + AT-NetID=3 + AT-VerifyNetID=1 + AT-EnableCRC16=1 + AT-EncryptionKey=54637374546373745463737454637374 + AT-SelectLedUse=2 + AT-Server=1 + ATW + ATT + +### Virtual Circuit Communications + +Communication is possible between the server and client or between clients. A three-way handshake must be performed prior to normal data communications to synchronize the ACK numbers. By default, the three-way handshake is not performed. The user or application initiates the handshake using the AT-CmdVc=n to select the client or server radio (n) for communications. Next, the ATC command initiates the three-way handshake between the local radio and the remote radio (n). + +After the three-way handshake, communication between the two radios is possible in virtual circuit mode. + +### Virtual Circuit Number + +The virtual circuit number of the local radio is obtained by issuing the ATI30 command to the local radio. The response returns a number in the range of zero (0) to MAX_VC. The value VC_UNASSIGNED is returned between reset until the server assigns a virtual circuit number to the local radio. + +### Virtual Circuit Serial Interface + +In virtual circuit mode, all communications over the serial port must be proceeded by a VC_SERIAL_MESSAGE_HEADER. Data not proceeded by a VC_SERIAL_MESSAGE_HEADER data structure is discarded! The VC_SERIAL_MESSAGE_HEADER is defined in the [Virtual_Circuit_Protocol.h](https://github.com/sparkfun/SparkFun_LoRaSerial/blob/release_candidate/Firmware/LoRaSerial_Firmware/Virtual_Circuit_Protocol.h) header file. This data structure is four (4) bytes long starting with the value START_OF_VC_SERIAL (2). The next byte specifies the length of the binary data following the VC_SERIAL_MESSAGE_HEADER plus the size of VC_RADIO_MESSAGE_HEADER (3). The other two bytes are virtual circuit numbers for the destination and source virtual circuits. + +The server radio is identified by VC_SERVER (0) and client radios have VC numbers between 1 and MAX_VC. A data message sent from the server to client 3 would have the source VC set to VC_SERVER (0) and the destination VC set to 3. Example: + + START_OF_VC_SERIAL + +-----+-----+-----+-----+-----+-----+-----+-----+-----+ + | 2 | 8 | 3 | 0 | H | e | l | l | o | + +-----+-----+-----+-----+-----+-----+-----+-----+-----+ + Length Dest Src Data + +### Radio Responses + +The LoRaSerial radio will return the following responses: + +* Data response +* Local command response +* Remote command response +* VC state response +* Reconnect serial response + +#### Data Response + +When sending a data message, the radio returns a VC_DATA_ACK_NACK_MESSAGE. The response is sent to PC_DATA_ACK (0xe2) when the data is acknowledged by the remote radio. A response of PC_DATA_NACK (0xe3) is returned when the link is broken. + + START_OF_VC_SERIAL + +-----+-----+-----+-----+-----+-----+-----+-----+-----+ + | 2 | 8 | B | A | H | e | l | l | o | + +-----+-----+-----+-----+-----+-----+-----+-----+-----+ + Length Dest Src Data + + Host A Radio A Radio B Host B + Data Message ---> + Data Message ---> + <--- ACK + Data Message ---> + <--- VC_DATA_ACK_NACK_MESSAGE + + START_OF_VC_SERIAL + +-----+-----+--------+-----+ + | 2 | 3 | 0xe2 | B | + +-----+-----+--------+-----+ + Length Dest Src + +#### Local Command Response +When sending a local command, the radio responds with VC_COMMAND_COMPLETE_MESSAGE sent to PC_COMMAND_COMPLETE (0xe5) with the status VC_CMD_SUCCESS (0) or VC_CMD_ERROR (1). + +One pair of virtual circuit numbers allows the local host to communicate with the command interface on the local radio. The data portion of the message contains the command to be executed. + +* VC_COMMAND (0xfe): Destination VC used by the host computer to send a command to the local radio to be executed immediately + +* PC_COMMAND (0xe0): Source VC for the local command message + + + START_OF_VC_SERIAL + +-----+-----+------+------+-----+-----+-----+-----+-----+------+------+ + | 2 | 8 | 0xe5 | 0xe0 | A | T | I | 1 | 1 | 0x0d | 0x0a | + +-----+-----+------+------+-----+-----+-----+-----+-----+------+------+ + Length Dest Src Command + + Host A Radio A + Command Message ---> + <--- Command response (ASCII text) + +------+------+---+---+---+---+---+---+...+------+------+---+---+------+------+ + | 0x0d | 0x0a | m | y | V | c | : | | A | 0x0d | 0x0a | O | K | 0x0d | 0x0a | + +------+------+---+---+---+---+---+---+...+...+--+------+---+---+------+------+ + <--- VC_COMMAND_COMPLETE_MESSAGE + + START_OF_VC_SERIAL + +-----+-----+--------+-----+-----+ + | 2 | 4 | 0xe2 | A | 0 | + +-----+-----+--------+-----+-----+ + Length Dest Src VC_CMD_SUCCESS + +#### Remote Command Response + +A command sent to a remote radio is acknowledged with a VC_DATA_ACK_NACK_MESSAGE sent to the PC_DATA_ACK (0xe2) or PC_DATA_NACK (0xe3) destination port. The actual command response is sent to the local radio's VC ored with PC_REMOTE_RESPONSE (0xc0). After the command response text is delivered, the command status is returned to the destination VC of PC_COMMAND_COMPLETE (0xe5) with the status of VC_CMD_SUCCESS (0) or VC_CMD_ERROR (1). + +The VC number range from 32 to 63 is reserved for remote command execution. The VC number equals the target radio number (0 - 31) or-ed with PC_REMOTE_COMMAND (0x20). This VC number is placed in the destination VC field and the local radio VC number is placed in the source VC field. + +The following example sends an ATI30 command from radio A to radio B to get radio +B's VC number: + + START_OF_VC_SERIAL + +-----+------+----------+-----+-----+-----+-----+-----+-----+------+------+ + | 2 | 10 | 0x20 + B | A | A | T | I | 3 | 3 | 0x0d | 0x0a | + +-----+------+----------+-----+-----+-----+-----+-----+-----+------+------+ + Length Dest Src Command + + Host A Radio A Radio B + Command Message ---> + Remote Command ---> + <--- ACK + <--- VC_DATA_ACK_NACK_MESSAGE + + START_OF_VC_SERIAL + +-----+-----+--------+-----+ + | 2 | 3 | 0xe2 | B | + +-----+-----+--------+-----+ + Length Dest Src + + <--- Remote Command Response + <--- Remote Command Response + +---+---+---+---+---+------+------+ + | A | T | I | 3 | 0 | 0x0d | 0x0a | + +---+---+---+---+---+------+------+ + +---+----+----------+---+------+------+---+---+---+---+---+---+...+------+------+---+---+------+------+ + | 2 | 18 | 0xc0 + A | B | 0x0d | 0x0a | m | y | V | c | : | | B | 0x0d | 0x0a | O | K | 0x0d | 0x0a | + +---+----+----------+---+------+------+---+---+---+---+---+---+...+...+--+------+---+---+------+------+ + + <--- VC_COMMAND_COMPLETE_MESSAGE + <--- VC_COMMAND_COMPLETE_MESSAGE + + START_OF_VC_SERIAL + +-----+-----+--------+-----+-----+ + | 2 | 4 | 0xe5 | B | 0 | + +-----+-----+--------+-----+-----+ + Length Dest Src VC_CMD_SUCCESS + +#### VC State Response + +As VC links change states, the host is notified of the state changes with a VC_STATE_MESSAGE sent to PC_LINK_STATUS (0xe1). An example where radio A detects the initial HEARTBEAT frame from radio B and notifies host A of the VC link change: + + Host A Radio A Radio B + + <--- HEARTBEAT + <--- VC_STATE_MESSAGE + + START_OF_VC_SERIAL + +-----+-----+--------+-----+---------+-------------+ + | 2 | 4 | 0xe1 | B | State | Unique ID | + +-----+-----+--------+-----+---------+-------------+ + Length Dest Src + +The state values are: + +* VC_STATE_LINK_DOWN (0): HEARTBEATs not received +* VC_STATE_LINK_ALIVE (1): Receiving HEARTBEATs, waiting for UNKNOWN_ACKS +* VC_STATE_SEND_UNKNOWN_ACKS (2): ATC command received, sending UNKNOWN_ACKS +* VC_STATE_WAIT_SYNC_ACKS (3): UNKNOWN_ACKS sent, waiting for SYNC_ACKS +* VC_STATE_WAIT_ZERO_ACKS (4): SYNC_ACKS sent, waiting for ZERO_ACKS +* VC_STATE_CONNECTED (5): ZERO_ACKS received, ACKs cleared, ready to send data + +The unique ID value is 16 bytes long and contains the unique ID value of the LoRaSerial radio. + +#### Reconnect Serial Response + +The ATZ command causes the system to reboot. Prior to the reboot, the radio responds with a message sent to PC_SERIAL_RECONNECT (0xe4). The local radio takes a couple of seconds to reset and causes the USB serial device to go offline. The timing is critical here, the application must close the serial connection before the LoRaSerial USB device goes offline. If the host is still holding the USB serial connection open when the LoRaSerial USB serial port goes offline then the host may not be able to release it in time before the LoRaSerial attempts to connect its USB serial port. In this case, the LoRaSerial serial port may show up as a new device on the host system and +further communications with the radio would no longer be possible using the previous device path. + +An example is below: + + START_OF_VC_SERIAL + +-----+-----+------+------+-----+-----+-----+------+------+ + | 2 | 8 | 0xe5 | 0xe0 | A | T | Z | 0x0d | 0x0a | + +-----+-----+------+------+-----+-----+-----+------+------+ + Length Dest Src Command + + Host A Radio A + Command Message ---> + <--- Command response (ASCII text) + + +---+---+------+------+ + | O | K | 0x0d | 0x0a | + +---+---+------+------+ + + <--- Reconnect message + + START_OF_VC_SERIAL + +-----+-----+--------+-----+ + | 2 | 3 | 0xe4 | A | + +-----+-----+--------+-----+ + Length Dest Src + + <--- VC_COMMAND_COMPLETE_MESSAGE + + START_OF_VC_SERIAL + +-----+-----+--------+-----+-----+ + | 2 | 4 | 0xe2 | A | 0 | + +-----+-----+--------+-----+-----+ + Length Dest Src VC_CMD_SUCCESS + +### Example Program + +The [VcServerTest.c](https://github.com/sparkfun/SparkFun_LoRaSerial/blob/release_candidate/Firmware/Tools/VcServerTest.c) is an example C program that communicates with the VC server using the virtual circuit serial interface. The first parameter is the device path to the local LoRaSerial radio. The second parameter specifies the destination VC number to send commands or data. + +The example program has the following features: + +* --reset command line option +* --break command line option +* Gets the local radio's virtual circuit number +* Opens a virtual circuit to the target VC +* Passes entered serial data to the target VC +* Displays responses from the target VC + +### Debug Defines + +There are some useful defines that may be set to one (1) to display the host's interaction with the radio. These defines are: + +* DEBUG_PC_TO_RADIO +* DEBUG_RADIO_TO_PC +* DUMP_RADIO_TO_PC + +Setting these defines will display the radio communications in hexadecimal and ASCII. + +### --reset + +The reset command line option is not used very often but sends an ATZ command to the local radio. + +### --break + +The break command line option sends an ATB command to the local radio causing it to delay for 5 times the heartbeatTimeout interval. This delay is sufficient to break all links with any remote virtual circuits. Following the delay, the radio returns to the RADIO_RESET state and brings up links to the other radios. diff --git a/docs/quick_start.md b/docs/quick_start.md index baa994f0..6f445b04 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -33,6 +33,7 @@ The LoRaSerial products are described in the [introduction](http://docs.sparkfun * [Point-to-Point](https://docs.sparkfun.com/SparkFun_LoRaSerial/operating_modes/#point-to-point) with guaranteed delivery or the link breaks * [Multipoint](https://docs.sparkfun.com/SparkFun_LoRaSerial/operating_modes/#multipoint), two or more LoRaSerial radios, is best for real-time applications but uses broadcast datagrams that may be lost +* [Virtual-Circuit](https://docs.sparkfun.com/SparkFun_LoRaSerial/operating_modes/#virtual-circuits) supports multipoint with guaranteed delivery or the link breaks. This mode uses a special serial interface. Enter [command mode](http://docs.sparkfun.com/SparkFun_LoRaSerial/at_commands/) to change modes and adjust the parameters for that mode of operation. [Training](http://docs.sparkfun.com/SparkFun_LoRaSerial/training/) is the process to distribute the set of parameters from a server radio (server=1) to the other client radios (server=0). Training can be done one radio at a time or multiple radios at once. diff --git a/docs/training.md b/docs/training.md index 5ba7dd51..03e0089e 100644 --- a/docs/training.md +++ b/docs/training.md @@ -83,6 +83,59 @@ A command script is simply a text file containing the AT commands the user would Copying and pasting command scripts into a terminal program is an efficient way of configuring a radio. +## Virtual Circuit Training + +It is recommended to use a command script to initialize the server radio when performing virtual-circuit training. The client radios can either use command mode or the training button to enter training mode. + +Temporary Server (Doesn't save settings): + +* If the radio is not already in point-to-point or multi-point mode, hold the training button down for 15 seconds +* Connect to the LoRaSerial radio via USB or the serial port +* Enter command mode with +++ +* Start from factory defaults by issuing the ATF command +* Issue the following commands: + * AT-OperatingMode=2 + * AT-Server=1 + * AT-SelectLedUse=2 + * ATG +* Set any of the other parameters +* Enter training mode with ATT command +* Wait for clients to be trained +* Exit command mode with ATO command or reboot with ATZ command + +Server (Saves settings): + +* If not already at factory reset, hold the training button down for 15 seconds +* Connect to the LoRaSerial radio via USB or the serial port +* Enter command mode with +++ +* Start from factory defaults by issuing the ATF command +* Issue the following commands: + * AT-OperatingMode=2 + * AT-Server=1 + * AT-SelectLedUse=2 + * ATG +* Set any of the other parameters +* Enter training mode with ATT command +* Wait for clients to be trained +* Save parameters with ATW command +* Always reboot with ATZ command + +Client: + +* 2 second training button press +* Receives training parameters from server +* Saves new parameters +* Reboots + +Client: + +* Connect to the LoRaSerial radio via USB or the serial port +* Enter command mode using +++ +* Enter training using the ATT command +* Receives training parameters from server +* Saves new parameters +* Reboots + ## Training Parameters The training parameters for radio communication fall into two groups: