From 122397301f2827233da2496f52cb755d1bfae94a Mon Sep 17 00:00:00 2001 From: Lee Leahy Date: Sat, 18 Feb 2023 09:24:27 -1000 Subject: [PATCH 1/3] Intro: Update the introduction to point at the quick start guide --- docs/index.md | 6 +++--- docs/intro.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index 3f8a11e9..f4a59ba5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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: @@ -15,4 +15,4 @@ The line of LoRaSerial products offered by SparkFun all run identical firmware.
-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). \ No newline at end of file +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). diff --git a/docs/intro.md b/docs/intro.md index c6b3d8ed..f4a59ba5 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -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: @@ -15,4 +15,4 @@ The line of LoRaSerial products offered by SparkFun all run identical firmware. -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). \ No newline at end of file +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). From a8d9b5c6643897dc7daafb41ff17bc55db433c3c Mon Sep 17 00:00:00 2001 From: Lee Leahy Date: Sat, 18 Feb 2023 07:49:57 -1000 Subject: [PATCH 2/3] Quick Start: Add references to command mode Mention that command mode can be used to change the network ID and encryption key. Add links to the other documentation. ------ Note that the various web browsers behave differently. While Microsoft Edge might display the menu as a list of items on the left, Google Chrome only displays a menu icon and unless the user knows that there is a menu, the icon is easy to miss. As such, I recommend adding a short paragraphs describing the other sections of the documentation and include a link in the paragraph. This way if the user does not notice the menu button they still have access to the full documentation. --- docs/quick_start.md | 40 +++++++++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/docs/quick_start.md b/docs/quick_start.md index 27a890f4..f2c31913 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -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:** Default1 * **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. +1 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/). -1 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. \ No newline at end of file +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 From 21a467b3c22605d030d86d438c048aff323d407a Mon Sep 17 00:00:00 2001 From: Lee Leahy Date: Fri, 17 Feb 2023 05:37:35 -1000 Subject: [PATCH 3/3] Update the LED documentation --- docs/led_states.md | 152 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 140 insertions(+), 12 deletions(-) diff --git a/docs/led_states.md b/docs/led_states.md index fcc45dcd..f3c3df20 100644 --- a/docs/led_states.md +++ b/docs/led_states.md @@ -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. \ No newline at end of file +Undefined LED modes display the RSSI pattern (mode 4).