Skip to content

Add the virtual circuit documentation #506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add the virtual circuit documentation #506

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 18 additions & 10 deletions docs/at_commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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)|
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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).

Expand Down Expand Up @@ -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.

Expand All @@ -217,23 +223,25 @@ 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

Currently, only one remote command is supported - **RTT**. Issuing this command to the local radio when the link is up will cause the remote radio to drop from the link and enter training mode. The remote radio will wait in this mode until training is completed, a local **ATZ** command is entered into the remote device, or the Train button is pressed on the remote device.

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
Expand Down
Loading