Merge pull request #562 from sparkfun/PC_add_mosaic_docs

Add mosaic docs

Author: PaulZC

docs/configure_with_ethernet_over_usb.md

@@ -0,0 +1,102 @@
+# Configure with Ethernet Over USB
+
+<!--
+Compatibility Icons
+====================================================================================
+
+:material-radiobox-marked:{ .support-full title="Feature Supported" }
+:material-radiobox-indeterminate-variant:{ .support-partial title="Feature Partially Supported" }
+:material-radiobox-blank:{ .support-none title="Feature Not Supported" }
+-->
+
+<div class="grid cards fill" markdown>
+
+- EVK: :material-radiobox-blank:{ .support-none title="Feature Not Supported" }
+- Facet mosaic: :material-radiobox-marked:{ .support-full title="Feature Supported" }
+- Postcard: :material-radiobox-blank:{ .support-none title="Feature Not Supported" }
+- Torch: :material-radiobox-blank:{ .support-none title="Feature Not Supported" }
+
+</div>
+
+On the RTK Facet mosaic, it is possible to configure the mosaic-X5 GNSS module using Ethernet-over-USB and the X5's internal web page.
+
+However, because the ESP32 does considerable configuration of the mosaic-X5 and the _Boot_ and _Current_ receiver configurations at power on, you need to use a little care when modifying the settings of the X5 using the internal web page. Nothing will break, but your changes could be overwritten at the next power cycle or if you [Factory Reset](./menu_system.md#factory-reset) the settings.
+
+Download and install [Septentrio's RxTools](https://www.septentrio.com/en/products/gps-gnss-receiver-software/rxtools) before continuing. This will also install the USB drivers needed to communicate with the mosaic-X5 using Ethernet-over-USB.
+
+Connect the RTK Facet mosaic to your computer using a USB-C cable. Power on the RTK and wait a few seconds for the mosaic-X5 to boot up. The OLED display will show the Satellites In View count and Horizontal Accuracy once the mosaic-X5 is running. Open a web browser and navigate to **192.168.3.1**. You should see the mosaic-X5's internal web page.
+
+<figure markdown>
+![The mosaic-X5 internal web page](./img/mosaic-X5/mosaic-X5_web_config_1.png)
+<figcaption markdown>
+The mosaic-X5 internal web page
+</figcaption>
+</figure>
+
+## RTK Facet mosaic Essentials
+
+You can do **SO** much with the mosaic-X5's internal web page that it is difficult to know where to begin. In this section we summarise the essentials: how the mosaic-X5 is interfaced; how it is configured by the ESP32 processor and the RTK Everywhere firmware; and how it is possible to change and save that configuration using the internal web page.
+
+The mosaic-X5's internal web page is (probably) the easiest way to view and change the X5's configuration. But it is far from the only way. The configuration can also be changed using [Sepentrio's RxTools](./configure_with_rxtools.md). Or, if you study the [mosaic-X5 Firmware Reference Guide](https://docs.sparkfun.com/SparkFun_RTK_Facet_mosaic/assets/component_documentation/mosaic-X5%20Firmware%20v4.14.0%20Reference%20Guide.pdf), you can also do all of the following manually by entering Commands over any COM (Serial) port.
+
+### mosaic-X5 Interfaces
+
+The following is a summary of the mosaic-X5's interfaces and how they can be accessed on the RTK Facet mosaic:
+
+- **Ethernet-over-USB:**
+    - If you have followed the instructions above, the X5's internal web page can be viewed at **192.168.3.1**. This address is fixed and cannot be changed. If any of your computers other interfaces (WiFi, Ethernet) also the nnn.nnn.3.nnn subnet, you will run into conflicts. You will need to change the configuration of the other device to use a different subnet.
+- **USB COM (Serial) Ports:**
+    - When connected via USB, two additional COM ports will appear. Internally to the X5, these are named _USB1_ and _USB2_. RxTools can connect directly to these ports. Or, if you wish, you can open a serial console / terminal emulator and enter commands directly.
+- **RADIO Port**:
+    - The RTK Facet mosaic RADIO port is connected directly to the mosaic-X5 **COM2** serial / UART port. Normally this port carries NMEA and/or RTCM data to/from an external radio module. But, if you wish, you can enter commands direct to this port too.
+- **DATA Port:**
+    - The RTK Facet mosaic DATA port is connected to the mosaic-X5 **COM3** serial / UART port via a hardware multiplexer. Please see [Ports Menu](./menu_ports.md) for more details, and the section on the [Mux Channel](./menu_ports.md#mux-channel) in particular. Set the multiplexer to **NMEA** to connect X5 COM3 to the **DATA** port. The baud rate can be changed through the menu; the default baud rate is **230400** (8 data bits, no parity, 1 stop bit). Commands can be entered over this port too.
+- **ESP32 and RTK Everywhere Firmware:**
+    - The ESP32 processor is connected to the mosaic-X5 **COM1** and **COM4** serial / UART ports. Configuration is performed over COM4. COM1 is used to: provide RTCM correction data _to_ the X5 in Rover mode; carry NMEA and / or RTCM data _from_ the X5 in Base mode. If you have a mobile phone connected to the RTK Facet mosaic over Bluetooth, corrections received over Bluetooth are pushed to the X5 on COM1. If the ESP32 is connected directly to WiFi, TCP (NTRIP) corrections received over WiFi are also pushed over COM1. COM1 also carries the raw L-Band correction stream from the X5, when the X5 is configured to use the u-blox PointPerfect corrections (only available in the contiguous USA).
+
+### mosaic-X5 microSD
+
+If you are familiar with the other SparkFun RTK products, you will know that most provide data storage on microSD card. On the RTK Facet mosaic, the microSD card is connected directly to the mosaic-X5. It is not connected to the ESP32 processor. This provides many advantages and some disadvantages.
+
+The mosaic-X5 can be configured to log NMEA messages direct to SD card. It also supports data logging in RINEX format, opening a new log file every 15 mins / 1 hour / 6 hours / 24 hours if desired.
+
+Because the SD card is connected directly to the mosaic-X5 using SDIO, the X5 is able to log data at much higher rates than our other RTK products. The data does not need to be passed to the ESP32 via UART for logging via SPI.
+
+The mosaic-X5 SD card must be mounted for data logging. But it can also be unmounted, causing it to appear as a mass-storage device ("thumb drive"). Files can be downloaded or uploaded very quickly over the USB interface. The RTK Everywhere Firmware does not currently support mounting / unmounting, but it is [something we will add](https://github.com/sparkfun/SparkFun_RTK_Everywhere_Firmware/issues/559) in the near future.
+
+The RTK Everywhere Firmware [Data Logging Menu](./menu_data_logging.md) can be used to enable logging to microSD. The messages which are logged are the NMEA messages defined in the [Configure GNSS Messages](./menu_messages.md) menu.
+
+### Receiver Configuration
+
+The mosaic-X5 supports five Receiver Configurations:
+
+- _RxDefault_
+- _Boot_
+- _Current_
+- _User1_
+- _User2_
+
+_RxDefault_ is read-only. During a [Factory Reset](./menu_system.md#factory-reset), _RxDefault_ is copied into both _Current_ and _Boot_.
+
+_Boot_ contains the configuration which is loaded when the mosaic-X5 boots up. The RTK Everywhere Firmware modifies the _Boot_ configuration to (e.g.): change the COM port settings; enable a stream of NMEA and RTCM messages.
+
+_Current_ is the current configuration. Commands can be used to alter the current configuration. _Current_ can be copied to _Boot_ if desired. During a [Factory Reset](./menu_system.md#factory-reset) the RTK Everywhere Firmware: copies _RxDefault_ into both _Current_ and _Boot_; makes changes to _Current_; and then copies _Current_ to _Boot_.
+
+If you want to save the X5 configuration after you have changed it, we recommend using either of the _User1_ or _User2_ Receiver Configurations. The RTK Everywhere firmware will modify the _Current_ and _Boot_ Receiver Configurations, but it leaves _User1_ and _User2_ for your use. Copy the _Current_ configuration into (e.g.) _User1_ to save the modified configuration. You can restore it later by copying _User1_ into _Current_.
+
+The _Admin \ Configurations_ tab can be used to view and copy the receiver configurations:
+
+<figure markdown>
+![The mosaic-X5 configurations web page](./img/mosaic-X5/mosaic-X5_web_config_2.png)
+<figcaption markdown>
+The mosaic-X5 configurations web page
+</figcaption>
+</figure>
+
+Clicking on the small **+** icon next to **Current** will show how the current configuration differs from the RxDefault.
+
+### Expert Control
+
+The _Admin \ Expert Control \ Expert Console_ option can be very useful when modifying the mosaic-X5 configuration. It provides full access to configuration and makes it possible to use script files.
+
+_Expert Control_ is so powerful, you may wish to use the _Admin \ User Administration_ settings to limit access to the X5's configuration. But be careful that you do not prevent the firmware on the ESP32 from accessing the COM ports.

docs/configure_with_rxtools.md

@@ -0,0 +1,36 @@
+# Configure with RxTools
+
+<!--
+Compatibility Icons
+====================================================================================
+
+:material-radiobox-marked:{ .support-full title="Feature Supported" }
+:material-radiobox-indeterminate-variant:{ .support-partial title="Feature Partially Supported" }
+:material-radiobox-blank:{ .support-none title="Feature Not Supported" }
+-->
+
+<div class="grid cards fill" markdown>
+
+- EVK: :material-radiobox-blank:{ .support-none title="Feature Not Supported" }
+- Facet mosaic: :material-radiobox-marked:{ .support-full title="Feature Supported" }
+- Postcard: :material-radiobox-blank:{ .support-none title="Feature Not Supported" }
+- Torch: :material-radiobox-blank:{ .support-none title="Feature Not Supported" }
+
+</div>
+
+On the RTK Facet mosaic, it is possible to configure the mosaic-X5 GNSS module using [Septentrio's RxTools: GNSS receiver control and analysis software](https://www.septentrio.com/en/products/gps-gnss-receiver-software/rxtools).
+
+However, because the ESP32 does considerable configuration of the mosaic-X5 and the _Boot_ and _Current_ receiver configurations at power on, you need to use a little care when modifying the settings of the X5 using RxTools. Nothing will break, but your changes could be overwritten at the next power cycle or if you [Factory Reset](./menu_system.md#factory-reset) the settings.
+
+We have only used RxTools on Windows, but it is also Linux compatible.
+
+Download and install RxTools before continuing. This will also install the USB drivers needed to communicate with the mosaic-X5.
+
+There are multiple ways to connect to the mosaic-X5 using RxTools:
+
+- While the RTF Facet mosaic is connected to your computer via USB, two additional serial COM ports will appear in Device Manager: Septentrio Virtual USB COM Port 1 and 2. RxTools can be configured to use either serial port. The X5 firmware names these ports _USB1_ and _USB2_.
+- The mosaic-X5 also supports Ethernet-Over-USB and can be configured via TCP/IP. In RXControl \ Change Connection, select **TCP/IP Connection** and enter **192.168.3.1** as the Receiver Address.
+- The RTK Facet mosaic **DATA** JST connector is connected the mosaic-X5 _COM3_ UART port via a multiplexer. Please see [Ports Menu](./menu_ports.md) for more details, and the section on the [Mux Channel](./menu_ports.md#mux-channel) in particular. Set the multiplexer to **NMEA** to connect X5 _COM3_ to the **DATA** port. The baud rate can be changed through the menu; the default baud rate is **230400** (8 data bits, no parity, 1 stop bit). To connect the **DATA** port to your computer, you will need a [Serial Basic Breakout](https://www.sparkfun.com/sparkfun-serial-basic-breakout-ch340c-and-usb-c.html) or similar.
+
+If you want to save the X5 configuration after you have changed it, we recommend using either of the _User1_ or _User2_ Receiver Configurations. The RTK Everywhere firmware will modify the _Current_ and _Boot_ Receiver Configurations, but it leaves _User1_ and _User2_ for your use. Copy the _Current_ configuration into (e.g.) _User1_ to save the modified configuration. You can restore it later by copying _User1_ into _Current_.
+

docs/img/Terminal/SparkFun RTK Everywhere Facet Logging Menu.png

@@ -92,6 +92,8 @@ If the device is configured for *Survey-In* base mode, the survey will begin. Th
 
 In *Fixed Base* mode the GNSS receiver will go into Base mode with the defined coordinates and immediately begin outputting RTCM correction data.
 
+On RTK Facet mosaic, the minimum observation time and required initial positional accuracy do not apply. The mosaic-X5 continually refines its base position.
+
 ## NTRIP Server
 
 **NTRIP** is where the real fun begins. The Base needs a method for getting the correction data to the Rover. This can be done using radios but that's limited to a few kilometers at best. If you've got WiFi reception, use the internet!

docs/img/Terminal/SparkFun_RTK_Everywhere_Facet_NMEA_Menu.png

@@ -21,6 +21,9 @@ Compatibility Icons
 !!! note
 	Not all devices support external SD (ie, RTK Torch). This section applies only to devices that support an external SD card, and have one inserted.
 
+!!! note
+	Do you have a RTK Facet mosaic? Skip to the dedicated [RTK Facet mosaic](#rtk-facet-mosaic) section below as the menu options are different.
+
 <figure markdown>
 ![RTK Data Logging Configuration Menu](./img//Terminal/SparkFun%20RTK%20Logging%20Menu.png)
 <figcaption markdown>
@@ -40,3 +43,29 @@ From the Main Menu, pressing 5 will enter the Logging Menu. This menu will repor
 
 !!! note
 	If you want to log RAWX sentences to create RINEX files useful for post-processing the position of the receiver please see the GNSS Configuration Menu. For more information on how to use a RAWX GNSS log to get a higher accuracy base location please see the [How to Build a DIY GNSS Reference Station](https://learn.sparkfun.com/tutorials/how-to-build-a-diy-gnss-reference-station#gather-raw-gnss-data) tutorial.
+
+## RTK Facet mosaic
+
+The Data Logging menu on the RTK Facet mosaic is much simpler:
+
+<figure markdown>
+![RTK Facet mosaic Data Logging Configuration Menu](./img//Terminal/SparkFun%20RTK%20Everywhere%20Facet%20Logging%20Menu.png)
+<figcaption markdown>
+RTK Facet mosaic Data Logging Configuration Menu
+</figcaption>
+</figure>
+
+By default, only NMEA logging is enabled. The NMEA messages are those configured with the [Configure GNSS Messages](./menu_messages.md#rtk-facet-mosaic) menu.
+
+Optionally, RINEX data can be logged. The file duration and logging interval can be configured:
+
+<figure markdown>
+![RTK Facet mosaic RINEX Logging Configuration Menu](./img//Terminal/SparkFun_RTK_Everywhere_Facet_RINEX_Menu.png)
+<figcaption markdown>
+RTK Facet mosaic RINEX Logging Configuration Menu
+</figcaption>
+</figure>
+
+The defaults set the logging interval to 30 seconds and the file duration to 24 hours. Logging will be continuous - a new file will be opened every 24 hours (cyclic logging).
+
+If you are familiar with our other RTK products, you may be wondering where the "Log Antenna Reference Position from RTCM 1005/1006" has gone. On RTK Facet mosaic, the mosaic-X5 can log the Rover-Base Position in North-East-Up format via the proprietary RBP ($PSSN,RBP) NMEA message. We believe this trumps the position extracted from RTCM 1005/1006 on ZED-F9P platforms.

docs/img/Terminal/SparkFun_RTK_Everywhere_Facet_RINEX_Menu.png

@@ -18,6 +18,9 @@ Compatibility Icons
 
 </div>
 
+!!! note
+	Do you have a RTK Facet mosaic? Skip to the dedicated [RTK Facet mosaic](#rtk-facet-mosaic) section below as the menu options are different.
+
 <figure markdown>
 ![Message rate configuration](./img/Terminal/SparkFun RTK Everywhere - Messages Menu.png)
 <figcaption markdown>
@@ -143,3 +146,81 @@ The following messages are supported for Bluetooth output and logging (if availa
 </div>
 
 </div>
+
+## RTK Facet mosaic
+
+The GNSS Messages menu on the RTK Facet mosaic is different, due to the way message streams and itervals need to be configured.
+
+### RTK Facet mosaic NMEA Messages
+
+Opening the _Configure GNSS Messages \ Set NMEA Messages_ menu produces:
+
+<figure markdown>
+![RTK Facet mosaic NMEA configuration](./img/Terminal/SparkFun_RTK_Everywhere_Facet_NMEA_Menu.png)
+<figcaption markdown>
+The NMEA messages configuration menu on RTK Facet mosaic
+</figcaption>
+</figure>
+
+The available NMEA messages are:
+
+<div markdown>
+- NMEA-ALM (GPS Almanac Data)
+- NMEA-AVR (Trimble Navigation proprietary sentence)
+- NMEA-DTM (Datum Reference)
+- NMEA-GBS (GNSS Satellite Fault Detection)
+- NMEA-GFA (GNSS Fix Accuracy and Integrity)
+- NMEA-GGA (GPS Fix Data)
+- NMEA-GGK (Trimble Navigation proprietary sentence)
+- NMEA-GGQ (Leica Real-Time Position with CQ)
+- NMEA-GLL (Geographic Position - Latitude/Longitude)
+- NMEA-GMP (GNSS Map Projection Fix Data)
+- NMEA-GNS (GNSS Fix Data)
+- NMEA-GRS (GNSS Range Residuals)
+- NMEA-GSA (GNSS DOP and Active Satellites)
+- NMEA-GST (GNSS Pseudorange Error Statistics)
+- NMEA-GSV (GNSS Satellites in View)
+- NMEA-HDT (Heading, True)
+- NMEA-HRP (Heading, Roll, Pitch)
+- NMEA-LLK (Leica Local Position and GDOP)
+- NMEA-LLQ (Leica Local Position and Quality)
+- NMEA-RBD (Rover-Base Direction)
+- NMEA-RBP (Rover-Base Position)
+- NMEA-RBV (Rover-Base Velocity)
+- NMEA-RMC (Recommended Minimum Specific GNSS Data)
+- NMEA-ROT (Rate of Turn)
+- NMEA-SNC (NTRIP Client Status)
+- NMEA-TFM (Used Coordinate Transformation Messages)
+- NMEA-THS (True Heading and Status)
+- NMEA-TXTbase (RTCM 1029 Text Transmission)
+- NMEA-VTG (Course Over Ground and Ground Speed)
+- NMEA-ZDA (Time and Date)
+</div>
+
+To output and log a message, set its Stream to _Stream1_ or _Stream2_. To disable a message, set its Stream to _Off_.
+
+E.g. for the ALM message, select "1" to change the Stream from _Off_ to _Stream1_. Select "1" again to select _Stream2_. Select "1" again to return to _Off_.
+
+Menu options 31 and 32 can be used to set the interval of _Stream1_ and _Stream2_. The interval can be adjusted between 10 milliseconds and 60 seconds. Be careful when setting the interval to less than 200 milliseconds, the load on the X5 CPU and the SD card will increase significantly.
+
+### RTK Facet mosaic RTCM Messages
+
+Opening the _Configure GNSS Messages \ Set Rover RTCM Messages_ menu produces:
+
+<figure markdown>
+![RTK Facet mosaic Rover RTCM configuration](./img/Terminal/SparkFun_RTK_Everywhere_Facet_RTCM_Menu.png)
+<figcaption markdown>
+The Rover RTCM messages configuration menu on RTK Facet mosaic
+</figcaption>
+</figure>
+
+RTCM messages are configured differently compared to NMEA. It is necessary to first set the message interval for the message group, then enable / disable the individual message. Streams do not apply to RTCM messages.
+
+E.g. to set the RTCM1230 message to an interval of 10 seconds:
+
+- Use menu option 23 to set an interval of 10.0
+- Use menu option 52 to toggle RTCM1230 to Enabled
+
+The interval can be adjusted between 0.1 and 600.0 seconds.
+
+Enabling the MSM1 message group causes the Multiple Signal Message - Type 1 to be output: RTCM1071 + RTCM1081 + RTCM1091 + RTCM1101 + RTCM1111 + RTCM1121 + RTCM1131