Docs: Add LoRa

docs/firmware_update_stm32.md

@@ -4,9 +4,9 @@ Torch: ![Feature Supported](img/Icons/GreenDot.png) / EVK: ![Feature Not Support
 
 The STM32WLE firmware runs the 915MHz LoRa radio inside the RTK Torch. 
 
-![Menu showing firmware version 2.0.1](<img/Firmware/SparkFun RTK Everywhere - STM32 Firmware.png>)
+![Menu showing firmware version 2.0.2](<img/Firmware/SparkFun RTK Everywhere - STM32 Firmware.png>)
 
-*RTK Torch LoRa radio firmware version 2.0.1*
+*RTK Torch LoRa radio firmware version 2.0.2*
 
 The firmware version number is displayed in the radio menu. If the device does not show this menu option the [ESP32 firmware](firmware_update_esp32.md) will need to be updated first.
 
@@ -16,7 +16,7 @@ Firmware updates to the STM32WLE can only be done over the serial interface. Fol
 
 1. Download and install [STM32CubeProgrammer](https://www.st.com/en/development-tools/stm32cubeprog.html). While it *is* available for Windows/Linux/iOS, ST makes it rather difficult to get this software. We're sorry!
 
-2. Download the latest STM32 LoRa binary from the [RTK Everywhere Firmware Binaries](https://github.com/sparkfun/SparkFun_RTK_Everywhere_Firmware_Binaries/tree/main/STM32_LoRa) repo. As of writing, this is **RTK_Torch_STM32_LoRa_v2_0_1.bin**.
+2. Download the latest STM32 LoRa binary from the [RTK Everywhere Firmware Binaries](https://github.com/sparkfun/SparkFun_RTK_Everywhere_Firmware_Binaries/tree/main/STM32_LoRa) repo. As of writing, this is **RTK_Torch_STM32_LoRa_v2_0_2.bin**.
 
     ![Debug menu showing the STM32 direct connect option](<img/Firmware/SparkFun RTK Everywhere - STM32 Passthrough Menu.png>)
 
@@ -56,6 +56,6 @@ Firmware updates to the STM32WLE can only be done over the serial interface. Fol
 
 13. Now press and release the power button on the Torch. The device will beep indicating it has exited pass-through mode. You can now use your device normally.
 
-    ![Menu showing firmware version 2.0.1](<img/Firmware/SparkFun RTK Everywhere - STM32 Firmware.png>)
+    ![Menu showing firmware version 2.0.2](<img/Firmware/SparkFun RTK Everywhere - STM32 Firmware.png>)
 
-14. To confirm the version, open the Radio menu and enable the radio. Above, version 2.0.1 is seen.
+14. To confirm the version, open the Radio menu and enable the radio. Above, version 2.0.2 is seen.

docs/menu_radios.md

@@ -1,59 +1,99 @@
 # Radios Menu
 
-## ESP-Now
+The radio menu allows the configuration of various radios that are included with a given RTK platform.
 
-Torch: ![Feature Supported](img/Icons/GreenDot.png) / EVK: ![Feature Supported](img/Icons/GreenDot.png)
+## ESP-NOW
 
-![Radio menu showing ESP-Now](<img/Terminal/SparkFun RTK Everywhere - Radios Menu.png>)
+Torch: ![Feature Supported](img/Icons/GreenDot.png) / EVK: ![Feature Supported](img/Icons/GreenDot.png)
 
-*Radio menu showing ESP-Now*
+![Radio menu showing ESP-NOW](<img/Terminal/SparkFun RTK Everywhere - Radios Menu.png>)
 
-Pressing 'r' from the main menu will open the Configure Radios menu. This allows a user to enable or disable the use of the internal ESP-Now radio.
+*Radio menu showing ESP-NOW*
 
-ESP-Now is a 2.4GHz protocol that is built into the internal ESP32 microcontroller; the same microcontroller that provides Bluetooth and WiFi. ESP-Now does not require WiFi or an Access Point. This is most useful for connecting a Base to Rover (or multiple Rovers) without the need for an external radio. Simply turn two SparkFun RTK products on, enable their radios, pair them, and data will be passed between units.
+Pressing 'r' from the main menu will open the Configure Radios menu. This allows a user to enable or disable the use of the internal ESP-NOW radio.
 
-Additionally, ESP-Now supports point-to-multipoint transmissions. This means a Base can transmit to multiple Rovers simultaneously.
+ESP-NOW is a 2.4GHz protocol that is built into the internal ESP32 microcontroller; the same microcontroller that provides Bluetooth and WiFi. ESP-NOW does not require WiFi or an Access Point. This is most useful for connecting a Base to Rover (or multiple Rovers) without the need for an external radio. Simply turn two SparkFun RTK products on, enable their radios, and data will be passed between units.
 
-ESP-Now is a free radio included in every RTK product and works well, but it has a few limitations: 
+Additionally, ESP-NOW supports point-to-multipoint transmissions. This means a Base can transmit to multiple Rovers simultaneously.
 
-1. Limited use with Bluetooth SPP. The ESP32 is capable of [simultaneously transmitting](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/coexist.html) ESP-Now and Bluetooth LE, but not classic Bluetooth SPP. Unfortunately, SPP (Serial Port Profile) is the most common method for moving data between a GNSS receiver and the GIS software. Because of this, using ESP-Now while connecting to the RTK product using Bluetooth SPP is not stable. SparkFun RTK products support Bluetooth LE and ESP-Now works flawlessly with Bluetooth LE. There are a few GIS applications that support Bluetooth LE including SW Maps. Another option is to use ESP-Now for the Base-Rover link and a GIS app such as [Vespucci](gis_software.md#vespucci) or [QGIS](gis_software.md#qgis) that can obtain PVT data over WiFi (TCP) rather than use Bluetooth to gather the NMEA data from the RTK device.
+ESP-NOW is a free radio included in every RTK product and works well, but it has a few limitations: 
 
-    ![Max transmission range of about 250m](img/Radios/SparkFun%20RTK%20ESP-Now%20Distance%20Testing.png)
+![Max transmission range of about 250m](img/Radios/SparkFun%20RTK%20ESP-Now%20Distance%20Testing.png)
 
-2. Limited range. You can expect two RTK devices to be able to communicate approximately 250m (845 ft) line of sight but any trees, buildings, or objects between the Base and Rover will degrade reception. This range is useful for many applications but may not be acceptable for some applications. We recommend using ESP-Now as a quick, free, and easy way to get started with Base/Rover setups. If your application needs longer RF distances consider cellular NTRIP, WiFi NTRIP, or an external serial telemetry radio plugged into the **RADIO** port.
+1. Limited range. You can expect two RTK devices to be able to communicate approximately 250m (845 ft) line of sight but any trees, buildings, or objects between the Base and Rover will degrade reception. This range is useful for many applications but may not be acceptable for some applications. We recommend using ESP-NOW as a quick, free, and easy way to get started with Base/Rover setups. If your application needs longer RF distances consider cellular NTRIP, WiFi NTRIP, or an external serial telemetry radio plugged into the **RADIO** port.
 
-3. ESP-Now can co-exist with WiFi, but both the receiver and transmitter must be on the same WiFi channel. 
+2. ESP-NOW can co-exist with WiFi, but both the receiver and transmitter must be on the same [WiFi channel](https://docs.sparkfun.com/SparkFun_RTK_Everywhere_Firmware/menu_radios/#setting-the-wifi-channel). 
 
-## Pairing
+### Pairing
 
 ![Pairing Menu](img/Displays/SparkFun%20RTK%20Radio%20E-Pair.png)
 
-On devices that have a display, clicking the Mode button will display the various submenus. Double-clicking on E-Pair will put the unit into ESP-Now pairing mode. If another RTK device is detected nearby in pairing mode, they will exchange MAC addresses and pair with each other. Multiple Rover units can be paired to a Base in the same fashion.
+For most setups, pairing is not needed. By default, any device that has ESP-NOW enabled will receive communication from any other device that has ESP-NOW enabled. This allows a Base to communicate with dozens of Rovers without further configuration, simply enable ESP-NOW and enter Base mode. However, if you are in an environment where other Base units may be setup and broadcasting using the ESP-NOW radios, then devices can be paired to each other to limit communication to only paired devices. Note: A Base can be paired with multiple Rovers. This allows multipoint or multicasting of corrections to multiple Rovers.
+
+On devices that have a display, clicking the Mode button will display the various submenus. Double-clicking on E-Pair will put the unit into ESP-NOW pairing mode. If another RTK device is detected nearby in pairing mode, they will exchange MAC addresses and pair with each other. Multiple Rover units can be paired to a Base in the same fashion.
 
 ![Radio menu during AP-Config](<img/WiFi Config/SparkFun%20RTK%20Radio%20Config.png>)
 
 *Radio configuration through WiFi*
 
-The radio system can be configured over WiFi. The radio subsystem is disabled by default. Enabling the radio to ESP-Now will expose the above options. The unit's radio MAC can be seen as well as a button to forget all paired radios. This button is disabled until the 'Enable Forget All Radios' checkbox is checked. The 'Broadcast Override' function changes all data transmitted by this radio to be sent to all radios in the vicinity, instead of only the radios it is paired with. This override feature is helpful if using a base that has not been paired: a base can transmit to multiple rovers regardless if they are paired or not.
+The radio system can be configured over WiFi. The radio subsystem is disabled by default. Enabling the radio to ESP-NOW will expose the above options. The unit's radio MAC can be seen as well as a button to forget all paired radios. This button is disabled until the 'Enable Forget All Radios' checkbox is checked. If a Base device has no paired radios, it will broadcast its correction data to any listening Rover by default.
 
-![Radio menu showing ESP-Now](<img/Terminal/SparkFun RTK Everywhere - Radios Menu.png>)
+![Radio menu showing ESP-NOW](<img/Terminal/SparkFun RTK Everywhere - Radios Menu.png>)
 
-*Radio menu showing ESP-Now*
+*Radio menu showing ESP-NOW*
 
 A serial menu is also available. This menu allows users to enter pairing mode, change the channel (ie, set of frequencies) used for communication, view the unit's current Radio MAC, the MAC addresses of any paired radios, as well as the ability to remove all paired radios from memory.
 
-## Setting the WiFi Channel
+### Setting the WiFi Channel
 
-![Radio menu showing ESP-Now](<img/Terminal/SparkFun RTK Everywhere - Radios Menu.png>)
+![Radio menu showing ESP-NOW](<img/Terminal/SparkFun RTK Everywhere - Radios Menu.png>)
 
 *Radio menu showing channel 11*
 
-All devices must be on the same WiFi channel to communicate over ESP-Now. Option **4 - Current channel** shows the current channel and allows a user to select a new one. Allowable channel numbers are 1 to 14. By default, devices will communicate on Channel 1. A user may select any channel they prefer.
+All devices must be on the same WiFi channel to communicate over ESP-NOW. Option **4 - Current channel** shows the current channel and allows a user to select a new one. Allowable channel numbers are 1 to 14. By default, devices will communicate on Channel 1. A user may select any channel they prefer.
+
+**Note:** ESP-NOW can operate at the same time as WiFi but the user should be aware of the channel numbers of the devices. When a device connects to a WiFi network, the ESP-NOW channel number may be altered by the WiFi radio so that the RTK device can communicate with the WiFi Access Point.
+
+Using a single device to communicate corrections to multiple devices (no WiFi involved) is the most common use case for ESP-NOW.
+
+Using WiFi on one of the devices in an ESP-NOW network is possible. Take the example of a Base that needs to communicate corrections over ESP-NOW and will also be pushing the corrections to a Caster over NTRIP using WiFi: The Base is started, WiFi is activated, and the channel is overwritten to 9 (for example) when the device connects to the Access Point. All Rovers in the area who wish to obtain corrections over ESP-NOW also need to have their channels set to 9.
+
+Using multiple devices on *different* WiFi networks, while attempting to use them in an ESP-NOW network, is likely impossible because the device's channel numbers will be modified to match the different channels of the Access Points.
+
+## LoRa
+
+Torch: ![Feature Supported](img/Icons/GreenDot.png) / EVK: ![Feature Not Supported](img/Icons/RedDot.png)
+
+![RTK Torch's combination GNSS, 2.4GHz, and 915MHz antenna](img/SparkFun_RTK_Torch_Open_Antenna.png)
+
+*RTK Torch's combination GNSS, 2.4GHz, and 915MHz antenna*
+
+The RTK Torch has a built-in 1W LoRa radio that allows Base to Rover communication. This radio is based on the STM32WLE5CC which contains a microcontroller and a LoRa radio. Attached to this radio is a 1W power amplifier. The radio transmits in the ISM band from 902 to 928MHz and is legal to use in North America, South America, Australia, and New Zealand. The radio implements frequency hopping spread spectrum (FHSS) techniques as well as LoRa modulation to maximize transmission distance while switching frequencies to abide by FCC requirements. Additionally, the LoRa system supports multipoint allowing one Base to communicate with dozens of Rovers.
+
+**Note:** RTK Torch LoRa radio uses a different frequency hopping algorithm from other radios that SparkFun sells. Therefore, RTK Torches are currently only compatible with each other and cannot be used interoperably with other LoRa or 915MHz radios.
+
+![1500ft (450m) range between Base and Rover using LoRa radios](<img/Radios/SparkFun RTK LoRa Non-Line-Of-Sight Distance Test.png>)
+
+*1500ft (450m) range between Base and Rover using LoRa radios*
+
+The RTK Torch has an internal planar 915MHz antenna allowing good reception in harsh environments. Above is shown a non-line-of-sight test between a Base setup on a tripod on the ground transmitting to a Rover that was able to achieve RTK Fix using corrections over the LoRa radio. This test included multiple large commercial buildings blocking or partially blocking the transmission as well as multiple trees and berms.
+
+![1.83 mile (2.95km) range between Base and Rover using LoRa radios](<img/Radios/SparkFun RTK LoRa Line-Of-Sight Distance Test.png>)
+
+*1.83 mile (2.95km) range between Base and Rover using LoRa radios*
+
+The 1 Watt power output of the radio allows for long range transmissions when obstacles are fewer. Above is a line-of-sight test using a Base unit with line-of-sight to a near by hill-top approximately (ok, with great accuracy) of 1.83 miles (2.95km).
+
+### Configuration
+
+![Configuring the LoRa radio](<img/Terminal/SparkFun RTK Everywhere - Radios LoRa Menu.png>)
+
+*Configuring the LoRa radio*
 
-**Note:** ESP-Now can operate at the same time as WiFi but the user should be aware of the channel numbers of the devices. When a device connects to a WiFi network, the ESP-Now channel number may be altered by the WiFi radio so that the RTK device can communicate with the WiFi Access Point.
+From the radios menu, the LoRa radio can be enabled and configured. 
 
-Using a single device to communicate corrections to multiple devices (no WiFi involved) is the most common use case for ESP-Now.
+**Don't see a LoRa menu?** Support was added starting in version v1.4. Please upgrade the [ESP32 firmware](firmware_update_esp32.md) on your device. Additionally, you may need to update the firmware on the [LoRa radio](firmware_update_stm32.md).
 
-Using WiFi on one of the devices in an ESP-Now network is possible. Take the example of a Base that needs to communicate corrections over ESP-Now and will also be pushing the corrections to a Caster over NTRIP using WiFi: The Base is started, WiFi is activated, and the channel is overwritten to 9 (for example) when the device connects to the Access Point. All rovers in the area who wish to obtain corrections over ESP-Now also need to have their channels set to 9.
+The *LoRa Coordination Frequency* must be the same between all Base and Rovers. The default is usually sufficient but if other RTK Torches are operating LoRa radios in the area, switching frequencies will allow multiple networks to operate simultaneously.
 
-Using multiple devices on *different* WiFi networks, while attempting to use them in an ESP-Now network, is likely impossible because the device's channel numbers will be modified to match the different channels of the Access Points.
+The *Seconds without user serial that must elapse before LoRa radio goes into dedicated listening mode* is our longest user setting name to date! Because of hardware limitations, the device cannot communicate over USB at the same time it communicates with the LoRa radio. For normal Rover operation in the field where a device is usually connected over Bluetooth or other wireless protocols, LoRa operation happens seamlessly and this setting can be ignored. But if a device is connected over USB, and no serial input is received over USB for 30 seconds (default), the USB connection will be severed and LoRa communication will be prioritized. A user may want to increase this timeout if  a system is communicating with the device over USB, or decrease it if a device is connected to USB (ie, for charging) and LoRa communication should initiate as quickly as possible. Note: If a timeout has occurred, USB communication can be restored by unplugging and plugging the cable back in.