Skip to content

Update the LED documentation #489

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

Merged
merged 3 commits into from
Feb 21, 2023
Merged

Update the LED documentation #489

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1223973
Intro: Update the introduction to point at the quick start guide
LeeLeahy2 Feb 18, 2023
a8d9b5c
Quick Start: Add references to command mode
LeeLeahy2 Feb 18, 2023
21a467b
Update the LED documentation
LeeLeahy2 Feb 17, 2023
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
6 changes: 3 additions & 3 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Introduction

Out of the box, the SparkFun LoRaSerial products are simple-to-use serial radios and can be used with little or no configuration. This Product Manual provides detailed descriptions of all the available features of the LoRaSerial products.
Out of the box, the SparkFun LoRaSerial products are simple-to-use point-to-point serial radio pair and can be used with little or no configuration. This [Product Manual](http://docs.sparkfun.com/SparkFun_LoRaSerial/quick_start/) provides detailed descriptions of all the available features of the LoRaSerial products.

The line of LoRaSerial products offered by SparkFun all run identical firmware. The [LoRaSerial](https://github.com/sparkfun/SparkFun_LoRaSerial) and this guide cover the following products:
The line of LoRaSerial products offered by SparkFun all run identical firmware. The [LoRaSerial repo](https://github.com/sparkfun/SparkFun_LoRaSerial) and this guide cover the following products:

<table class="table table-hover table-striped table-bordered">
<tr align="center">
Expand All @@ -15,4 +15,4 @@ The line of LoRaSerial products offered by SparkFun all run identical firmware.
</tr>
</table>

If you have an issue, feature request, bug report, or a general question about the LoRaSerial firmware specifically we encourage you to post your comments on the [firmware's repository](https://github.com/sparkfun/SparkFun_LoRaSerial/issues).
If you have an issue, feature request, bug report, or a general question about the LoRaSerial firmware specifically we encourage you to post your comments on the [firmware's repository](https://github.com/sparkfun/SparkFun_LoRaSerial/issues).
4 changes: 2 additions & 2 deletions docs/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Introduction

Out of the box, the SparkFun LoRaSerial products are simple-to-use serial radios and can be used with little or no configuration. This Product Manual provides detailed descriptions of all the available features of the LoRaSerial products.
Out of the box, the SparkFun LoRaSerial products are simple-to-use point-to-point serial radio pair and can be used with little or no configuration. This [Product Manual](http://docs.sparkfun.com/SparkFun_LoRaSerial/quick_start/) provides detailed descriptions of all the available features of the LoRaSerial products.

The line of LoRaSerial products offered by SparkFun all run identical firmware. The [LoRaSerial repo](https://github.com/sparkfun/SparkFun_LoRaSerial) and this guide cover the following products:

Expand All @@ -15,4 +15,4 @@ The line of LoRaSerial products offered by SparkFun all run identical firmware.
</tr>
</table>

If you have an issue, feature request, bug report, or a general question about the LoRaSerial firmware specifically we encourage you to post your comments on the [firmware's repository](https://github.com/sparkfun/SparkFun_LoRaSerial/issues).
If you have an issue, feature request, bug report, or a general question about the LoRaSerial firmware specifically we encourage you to post your comments on the [firmware's repository](https://github.com/sparkfun/SparkFun_LoRaSerial/issues).
152 changes: 140 additions & 12 deletions docs/led_states.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,154 @@
# LED States

A variety of LEDs are visible on the LoRaSerial radio to give the user feedback about the state of the system.
A variety of LEDs are visible on the LoRaSerial radio to give the user feedback about the state of the system.

![LEDs on the LoRaSerial](img/SparkFun_LoRaSerial_LEDs.png)

*LEDs on the LoRaSerial*

## LED Mode 1
First lets define the LEDs on the LoRaSerial device. The following diagram shows the various LEDs:

In the default mode (selectedLedUse = 1):
Antenna Qwiic
+---------------------------+
| |
| G4 G3 G2 G1 |
| |
| |
| Red |
| |
| |
| Blue Yellow |
| |
+---------------------------+
USB Serial

* The RSSI LEDs indicate the signal strength of the last received packet.
The red LED is the power indicator. G1 through G4 in the diagram above are all green LEDs.

The LED behavior may be changed by using the AT-SelectLedUse command and setting the value to one of the mode numbers described in the sections below. As an example, if the radio is in multipoint mode the following serial data sequence causes the LEDs to display more information about the radio behavior.

+++
AT-SelectLedUse=0
ATO

## LED Mode 0 (LEDS_MULTIPOINT)

When the radio is in multipoint mode, selecting this mode for the LEDs provides additional insight into the radio's behavior.

* The G4 LED pulses when the radio transmits a frame.
* The G3 LED is pulse width modulated to indicate the last received RSSI level.
* The G2 LED turns on when the link is up (data can pass).
* The G1 LED pulses when the radio successfully receives a frame.
* The blue LED pulses on the server radio when the server transmits a HEARTBEAT frame. The blue LED pulses on the client radio when the client successfully receives a HEARTBEAT frame from the server.
* The yellow LED pulses each time a channel hop (frequency change) occurs.

## LED Mode 1 (Default: LEDS_P2P)

When the radio is in point-to-point mode, selecting this mode for the LEDs provides additional insight into the radio's behavior.

* The G4 LED pulses when the radio transmits a frame.
* The G3 LED is pulse width modulated to indicate the last received RSSI level.
* The G2 LED is off.
* The G1 LED pulses when the radio successfully receives a frame.
* The blue LED pulses on the radio successfully receives a HEARTBEAT frame.
* The yellow LED pulses each time a channel hop (frequency change) occurs.

## LED Mode 2 (LEDS_VC)

When the radio is in virtual-circuit mode, selecting this mode for the LEDs provides additional insight into the radio's behavior.

* The G4 LED pulses when the radio transmits a frame.
* The G3 LED is pulse width modulated to indicate the last received RSSI level.
* The G2 LED pulses when serial data is received.
* The G1 LED pulses when the radio successfully receives a frame.
* The blue LED pulses on the server radio when the server transmits a HEARTBEAT frame. The blue LED pulses on the client radio when the client successfully receives a HEARTBEAT frame from the server.
* The yellow LED pulses each time a channel hop (frequency change) occurs.

## LED Mode 3 (LEDS_RADIO_USE)

This mode is useful for users who want additional LED feedback about the RF link.

* The G4 LED pulses when the radio transmits a frame.
* The G3 LED is pulse width modulated to indicate the last received RSSI level.
* The G2 LED turns on when the link is up (data can pass).
* The G1 LED pulses when the radio successfully receives a frame.
* The blue LED will blink when the radio receives a bad frame.
* The yellow LED will blink when the radio receives a duplicate frame or receives frame where the software CRC does not match.

## LED Mode 4 (Default: LEDS_RSSI)

In the Received Signal Strength Indicator (RSSI) mode uses the green LEDs to indicate ranges of signal strengths:

* The RSSI LEDs indicate the signal strength of the last received packet:
* -70 < RSSI: All green LEDs lit (strong)
* -100 < RSSI <= -70: G3, G2, G1 LEDs lit, G4 off
* -120 < RSSI <= -100: G2, G1 LEDs lit, G4 and G3 off
* -150 < RSSI <= -120: G1 LED lit, all G4, G3 and G2 off (weak)
* RSSI <= -150: <= All green LEDs off
* The blue TX LED indicates when serial data is received over the radio and sent to the host, either over USB or hardware serial.
* The yellow RX LED indicates when serial data is received from the host and sent over the radio.

## LED Mode 2
## LED Mode 5 (LEDS_BUTTON_PRESS)

The button press mode is an internal mode used to indicate the state of the button press. The green LEDs are counting seconds. The following blue and yellow LED behavior occurs:

* Press time < 4 seconds: Blue LED is off and if in command mode or not performing training the yellow LED is off. Otherewise if not in command mode and performing training the yellow LED is flashing and upon button release the radio exits training.

* 4 seconds <= button press time < 8 seconds: Yellow LED is off and if in command mode or not performing training the blue LED is off. Otherewise if not in command mode and performing training the blue LED is flashing and upon button release the radio enters training in client mode.

* 8 seconds <= button press time < 16 seconds: If in command mode or not performing training both LEDs are off. Otherewise if not in command mode and performing training the both LEDs are flashing and upon button release the radio enters training in server mode.

* 16 seconds <= button press time: Reset pattern caused by a system reset

## LED Mode 7 (LEDS_CYLON)

The cylon eye pattern in green is typically used to indicate radio training. One green LED is lit at a time and the lit LED moves from side to side.

G4 G3 G2 G1
X
X
X
X
X
X
X
X
...

* The blue LED will blink when the radio transmits a frame.
* The yellow LED will blink when the radio successfully receives a frame.

## LED Mode 8 (LEDS_ALL_OFF)

This is a testing pattern with all LEDs off.

## LED Mode 9 (LEDS_BLUE_ON)

This is a testing pattern with only the blue LED on.

## LED Mode 10 (LEDS_YELLOW_ON)

This is a testing pattern with only the yellow LED on.

## LED Mode 11 (LEDS_GREEN_1_ON)

This is a testing pattern with only the G1 LED on.

## LED Mode 12 (LEDS_GREEN_2_ON)

This is a testing pattern with only the G2 LED on.

## LED Mode 13 (LEDS_GREEN_3_ON)

This is a testing pattern with only the G3 LED on.

## LED Mode 14 (LEDS_GREEN_4_ON)

This is a testing pattern with only the G4 LED on.

## LED Mode 15 (LEDS_ALL_OFF)

This is a testing pattern with all LEDs on.

For users who want additional LED feedback about the RF link, setting selectedLedUse to 2 has the following effects:
## Other LED modes

* The blue LED will blink any time a heartbeat is received.
* The yellow LED will blink when a channel hop occurs.
* The 1st RSSI LED from the top indicates data is being transmitted.
* The 2nd RSSI LED from the top turns on when the link is up (data can pass).
* The 3rd RSSI LED from the top indicates the last received RSSI.
* The 4th RSSI LED from the top indicates data being successfully received.
Undefined LED modes display the RSSI pattern (mode 4).
40 changes: 33 additions & 7 deletions docs/quick_start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,44 @@ LoRaSerial radios are very easy to use and ship ready to connect out of the box.
The default settings are as follows:

* **Mode:** Point to Point
* **Frequency:** 902 to 928MHz
* **Frequency:** 902 to 928 MHz
* **Channels:** 50
* **Frequency Hopping:** Enabled
* **Broadcast Power:** 30dbm
* **Airspeed:** 4800bps
* **Serial:** 57600bps
* **Broadcast Power:** 30 dbm
* **Airspeed:** 4800 bps
* **Serial:** 57600 bps
* **Encryption:** Enabled
* **Encryption Key:** Default<sup>1</sup>
* **Software CRC:** Enabled

Serial can be passed into the unit either through the USB port, or over the serial connector. If the serial connector is used, the baud rate is 57600bps by default.
<sup>1</sup> The radios default to a published encryption key. For maximum security, we recommend changing the key and network ID value using command mode or the [training process](http://docs.sparkfun.com/SparkFun_LoRaSerial/training/).

<sup>1</sup> The radios default to a published encryption key. For maximum security, we recommend changing the key using the [training process](http://docs.sparkfun.com/SparkFun_LoRaSerial/training/).
Serial can be passed into the unit either through the USB port, or over the serial connector. If the serial connector is used, the baud rate is 57600 bps by default.

LoRaSerial is designed to get small amounts of data from point A to point B as easily as possible. If you've got a sensor, or Arduino, or any device that can output serial, then it can transmit data over long distances. LoRaSerial has been used to send data over 9 miles (14km) line-of-sight.
LoRaSerial is designed to get small amounts of data from point A to point B as easily as possible. If you've got a sensor, or Arduino, or any device that can output serial, then it can transmit data over long distances. LoRaSerial has been used to send data over 9 miles (14 km) line-of-sight.

## Additional Documentation

The LoRaSerial products are described in the [introduction](http://docs.sparkfun.com/SparkFun_LoRaSerial/intro/). The [radios](http://docs.sparkfun.com/SparkFun_LoRaSerial/hardware_overview/) support several [operating modes](http://docs.sparkfun.com/SparkFun_LoRaSerial/operating_modes/).

* [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 realtime 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.

The green LEDs by default display a received signal strength indication. The more LEDs that are on the better the signal. However other [LED patterns](http://docs.sparkfun.com/SparkFun_LoRaSerial/led_states/) are available to provide more data on the radio behavior.

Occasionally, SparkFun may release new firmware for LoRaSerial. The
[firmware update](http://docs.sparkfun.com/SparkFun_LoRaSerial/firmware_update/) procedure enables you to load the firmware into the LoRaSerial radio. Advanced users may also want to [build](http://docs.sparkfun.com/SparkFun_LoRaSerial/firmware_build/) the [open source LoRaSerial firmware](https://github.com/sparkfun/SparkFun_LoRaSerial).

### Hardware Documentation

The following hardware documents are available:

* [Schematic](https://cdn.sparkfun.com/assets/b/e/9/a/d/SparkFun_LoRaSerial_915MHz_-_1W.pdf)
* [Eagle Files](https://cdn.sparkfun.com/assets/f/b/b/6/f/SparkFun_LoRaSerial_915MHz_-_1W.zip)
* [Semtech SX1276 datasheet](https://cdn.sparkfun.com/assets/7/7/3/2/2/SX1276_Datasheet.pdf)
* [Ebyte E19-915M30S Datasheet](https://cdn.sparkfun.com/assets/6/3/e/e/3/E19-915M30S_Usermanual_EN_v1.20.pdf)
* [Atmel SAMD-21 datasheet](https://cdn.sparkfun.com/datasheets/Dev/Arduino/Boards/Atmel-42181-SAM-D21_Datasheet.pdf)
* [Understanding LoRa PHY](https://wirelesspi.com/understanding-lora-phy-long-range-physical-layer/) - A good article on the math behind Semtec's Long Range modulation technique