diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 90d74042..7728bfaf 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -3,24 +3,33 @@ name: Deploy Water Linked Docs on: push: branches: - - master + - '**' # run on all branches + jobs: build: - runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 + - name: Set up Python 3.8 uses: actions/setup-python@v4 with: python-version: '3.8' + - name: Install dependencies run: | python3 -m pip install --upgrade pip python3 -m pip install -r requirements.txt + # Always build docs, e.g. for testing + - name: Build docs + run: | + mkdocs build --strict + + # Only deploy on master - name: Deploy docs + if: github.ref == 'refs/heads/master' uses: mhausenblas/mkdocs-deploy-gh-pages@master env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/docs/dvl/bluerov-integration-dvl-ugps.md b/docs/dvl/bluerov-integration-dvl-ugps.md index 863be1de..85edcb71 100644 --- a/docs/dvl/bluerov-integration-dvl-ugps.md +++ b/docs/dvl/bluerov-integration-dvl-ugps.md @@ -39,7 +39,7 @@ Before successful sensor fusion of Underwater GPS and DVL the following conditio * Make sure that the compass calibration was successful by comparing the ROV orientation shown in the map in QGroundControl to the actual ROV orientation. Land-marks like a coast-line or an analogue compass can help. !!! Note - When you want to use the position estimate for *control* of the ROV and the UGPS Topside is on land, it is highly recommended setting up the Underwater GPS to use static position and static heading mode. Alternatively when the UGPS Topside position is not static (on a boat or similar) you need to input heading and position data from an external GPS compass. [Details can be found here](../underwater-gps/gui/settings.md#topside-setup). + When you want to use the position estimate for *control* of the ROV and the UGPS Topside is on land, it is highly recommended setting up the Underwater GPS to use static position and static heading mode. Alternatively when the UGPS Topside position is not static (on a boat or similar) you need to input heading and position data from an external GPS compass. [Details can be found here](../underwater-gps/ugps-sysconfig.md#topside-settings). If you don't follow this advice, the position provided by the Underwater GPS will have more noise ("jump" too much) and also drift over time. This might cause the position hold mode to not work properly. @@ -67,7 +67,7 @@ Now both sensors should be considered for the position estimate of the ROV. You This mode can be useful when you experience issues with sensor fusion (Mode "DVL+UGPS" above) or not all the described conditions in above section are met. Otherwise, we recommend using Mode "DVL+UGPS". -In this configuration the BlueROV will base its position estimate *updates* on velocity input from the DVL as well as accelerometer, gyroscope, compass and pressure sensor but not the Underwater GPS. Although the Underwater GPS is connected and running it will only be used to *initialize* the global ROV position at the beginning. QGroundControl (or the new Cockpit) will show the ROV position estimate based on the DVL only while the [Underwater GPS GUI](../underwater-gps/gui/position.md) will show the position based on the Underwater GPS. +In this configuration the BlueROV will base its position estimate *updates* on velocity input from the DVL as well as accelerometer, gyroscope, compass and pressure sensor but not the Underwater GPS. Although the Underwater GPS is connected and running it will only be used to *initialize* the global ROV position at the beginning. QGroundControl (or the new Cockpit) will show the ROV position estimate based on the DVL only while the [Underwater GPS GUI](../underwater-gps/interface/ugps-gui.md#position) will show the position based on the Underwater GPS. !!! Note The setup procedure below is very similar to when you only use the DVL without a running Underwater GPS. That case is described [here](bluerov-integration.md#software). diff --git a/docs/modem-m16/modem-m16-gui.md b/docs/modem-m16/modem-m16-gui.md index da765a4a..23a87fe7 100644 --- a/docs/modem-m16/modem-m16-gui.md +++ b/docs/modem-m16/modem-m16-gui.md @@ -22,6 +22,6 @@ Follow the installation guide provided in README at [github for examples with Mo ## GUI layout example: -![](../../img/m16-gui.png) +![](../img/m16-gui.png) --- \ No newline at end of file diff --git a/docs/underwater-gps/interface/gui/demo-gui.md b/docs/underwater-gps/interface/gui/demo-gui.md deleted file mode 100644 index 9f0a149c..00000000 --- a/docs/underwater-gps/interface/gui/demo-gui.md +++ /dev/null @@ -1,3 +0,0 @@ -# Demo - -We offer a live [demo](https://demo.waterlinked.com) of the GUI of the UGPS G2 system. It runs on simulated data designed to illustrate various GUI features; this data is not necessarily realistic in all aspects! diff --git a/docs/underwater-gps/interface/gui/diagnostic-report.md b/docs/underwater-gps/interface/gui/diagnostic-report.md deleted file mode 100644 index 036075da..00000000 --- a/docs/underwater-gps/interface/gui/diagnostic-report.md +++ /dev/null @@ -1,5 +0,0 @@ -# Diagnostic report - -On the diagnostic report page you can generate a report if you are experiencing problems with the UPGS. First type a small description of the problem you are experiencing and then click on the generate button. Send the resulting .wdat file to support@waterlinked.com. - -![diagnostics_report](../../img/diagnostic_report_g2.png) \ No newline at end of file diff --git a/docs/underwater-gps/interface/gui/diagnostic.md b/docs/underwater-gps/interface/gui/diagnostic.md deleted file mode 100644 index 30205b23..00000000 --- a/docs/underwater-gps/interface/gui/diagnostic.md +++ /dev/null @@ -1,22 +0,0 @@ -# Diagnostics - -Verify Receiver signal strength in the diagnostic page on the web GUI by going to the diagnostic tab in the side panel on the left. This view will show the signal strength from all Receivers. It should look something like this: - -![diagnostics1](../../../img/diagnostics_1_g2.png) - -In the diagnostic plot you should see the signal from all 4 Receivers. The signals should be well above the noise floor. - -## Interference - -Acoustic interference can be observed in the diagnostic plot. Echo sounders from your boat or nearby boats typically appears like burst noise. - -![diagnostics2](../../../img/diagnostics_2.png) - -If it is coming from your boat, try to turn off the echo sounder to improve position accuracy. -In case of interference from other acoustic sources, use the GUI to try other channels to avoid the interference. - -## Diagnostic report - -On the diagnostic report page you can generate a report if you are experiencing problems with the UPGS. First type a small description of the problem you are experiencing and then click on the generate button. Send the resulting .wdat file to support@waterlinked.com. - -![diagnostics_report](../../../img/diagnostic_report_g2.png) diff --git a/docs/underwater-gps/interface/gui/position.md b/docs/underwater-gps/interface/gui/position.md deleted file mode 100644 index 81281933..00000000 --- a/docs/underwater-gps/interface/gui/position.md +++ /dev/null @@ -1,11 +0,0 @@ -# Position view - -The Underwater GPS GUI is web based. Using your favorite web browser, go the IP address as defined [here](../network-settings.md). We currently support and recommend Chrome, Firefox, Safari and Edge. - -!!! Note - You will need **internet access** on your computer that are showing the GUI if you also want to see the map and not only relative position to the locator. This is because the map is fetched from the internet. - -!!! Attention - Internet Explorer is not supported as of now. - -![gui_global_position](../../img/gui_global_position_r100.png) diff --git a/docs/underwater-gps/interface/gui/receivers.md b/docs/underwater-gps/interface/gui/receivers.md deleted file mode 100644 index eb4e6dac..00000000 --- a/docs/underwater-gps/interface/gui/receivers.md +++ /dev/null @@ -1,55 +0,0 @@ -# Baseline - -Select *Antenna* or *Receivers* in the tab at the top according to whether an [antenna](../../../antenna) or loose [receivers](../../../receiver-d1) are used. - -## Antenna - -The antenna can be placed anywhere up to 10m from the topside housing (limited by cable length). Go through the following. By the _antenna base_ is meant the joining point of the three prongs with the receivers at their ends. - - -| | | -| ------------------- | :------------------- | -| **Alignment** | Ensure that the 'Forward' direction of the antenna as defined by a label on one of its prongs (see also the figure below) is aligned with the 'Forward' direction of the topside housing (indicated by a label on the lid).

If it is not possible to physically align them, in *Baseline -> Antenna configuration -> Advanced settings*, specify the clockwise angle in degrees from the forward axis of the topside to the forward axis of the antenna.

If this alignment is not carried out, the [global](../../reference-frames#global) position outputted by UGPS G2 will be incorrect. -| **Line-of-sight** | Ensure that there will be line-of-sight between the antenna and locator. | -| **Antenna depth** | Ensure that the base of the antenna is at a depth of at least one metre (as indicated by a label upon the top folding joint of the pole of the antenna), to avoid acoustic disturbance.

The depth of the antenna base (relative to the sea surface) must be specified in *Baseline -> Antenna configuration -> Advanced settings -> Antenna depth*. If it is not, both the [acoustic](../../reference-frames#acoustic) and [global](../../reference-frames#global) positions may be incorrect. | -| **Antenna stability** | Secure the antenna tightly to the vessel using the provided Ram Mount. | - -
- Antenna configuration example -
- -Further points of note: - -* **Limit search area** : a better position will likely be obtained if the search area is restricted as far as possible in the graphical configuration pane at *Baseline -> Antenna configuration*. -* **Directivity** : the antenna and locators are omnidirectional, that is, signal strength should be good in all directions - - -## Receivers - -Loose receivers can be placed anywhere up to 100m from the topside housing. Go through the following, and configure the placement of the receivers in the graphical pane at *Baseline -> Receiver and range configuration* so that their positions relative to the origin and their depths are correct. - -| | | -| ------------------- | :------------------- | -| **Line-of-sight** | Ensure that all the receivers will have line-of-sight to the locator. | -| **Separation** | Ensure that the receivers are not too close, and are not all in a line. A grid of 2x2 metres should typically be sufficient for good performance, but experiment with different configurations if you experience sub-optimal performance. | -| **Depth** | Place the receivers at a depth of at least a metre, to avoid acoustic disturbance. | -| **Stability** | Consider adding some weight to the receiver cables just above the receivers. | - -Further points of note: - -* **Limit search area** : a better position will likely be obtained if the search area is restricted as far as possible in the graphical configuration pane at *Baseline -> Antenna configuration*.

- -
- Receiver setup -
- -
- -* **Directivity** : the receivers and locators are omnidirectional, that is, signal strength should be good in all directions - - -The figure below indicates a typical loose receiver configuration when the topside unit is upon a boat. The receivers hang from the side of the boat. The origin of the the acoustic frame is in this case a point on the topside unit. - -
- Loose receivers configuration example -
diff --git a/docs/underwater-gps/interface/gui/settings.md b/docs/underwater-gps/interface/gui/settings.md deleted file mode 100644 index 5e793395..00000000 --- a/docs/underwater-gps/interface/gui/settings.md +++ /dev/null @@ -1,53 +0,0 @@ -# Settings - -![gui_settings_topside_setup](../../img/gui_settings_topside_setup.png) - -## Locator setup - -Select the type of locator ([U1](../../locators/locator-u1), [A1](../../locators/locator-a1), or [D1](../../locators/locator-d1)) which you are using, and which [channel](#channel-overview) you wish to use. - -!!! Note - If using the [U1](../../locators/locator-u1) locator, the channel must match the rotary switch at the back of the U1 (screw the lid completely off to access the switch). - -!!! Note - If using the [A1](../../locators/locator-a1) locator, the depth of the locator must be inputted by means of the UGPS [API](../../integration/api). - -## Channel overview - -The frequency bands of the available channels are as follows. Lower frequency typically corresponds to greater range due to less acoustic absorption, though there are other factors involved: if you experience issues with signal quality (low RSSI or high NSD), try a different channel. Often channel 3 is recommended. - -| From (kHz) | To (kHz) | Channel | -|------------|----------|---------| -| 31.25 | 62.5 | 1 | -| 62.5 | 93.75 | 2 | -| 93.75 | 125.0 | 3 | -| 125.0 | 156.25 | 4 | -| 156.25 | 187.5 | 5 | -| 187.5 | 218.75 | 6 | -| 218.75 | 250.0 | 7 | - -!!! Tip - Typically, NSD (_Noise spectral density_, displayed in the [Diagnostic](../diagnostic) pane of the GUI) is around -100 dBm (in the units of version 3.3.0 or later of the software; 15 nV/sqrt(Hz) in the units of earlier software versions), or a little higher or lower. If it is much higher than this, it is likely that there is acoustic interference in the chosen channel, and a different channel should be tried. - - Note in particular that acoustic devices quite commonly operate at frequencies lying in Channel 1. - -!!! Tip - If the NSD values are normal, signal quality is mainly indicated by the RSSI values (_Received signal strength indicator_, displayed in the [Diagnostic](../diagnostic) pane of the GUI). As long as the RSSI values are not too far below the NSD values, the signal strength should be at usable levels. - - The UGPS system uses advanced signal processing techniques and can work even with rather weak signals, but an RSSI of -125 dBm or so (in the units of version 3.3.0 or later of the software; -45 dBnW in the units of earlier software versions) is around the lowest possible for an NSD of roughly -100 dBm. - - Typically one can expect a decrease in signal strength of around 6 dB for each doubling of distance due to spherical spreading, plus a little more due to additional absorption. - -## Topside setup - -The default source for the topside position and heading is *On-board*. Since version 3.3.0 of the software, the heading of the topside unit must be set periodically because only the gyroscope of the built-in IMU is used, not the magnetometer. In the on-board mode for heading you will be prompted to enter the heading manually after startup (using an analogue compass, a mobile phone, etc). - -For best performance on boats or similar with a moving topside unit, we recommend to use an *external* input of heading data (e.g. from a GPS compass) as well as global position data. This is done via the UGPS [API](../../integration/api). An external device will likely be more accurate than the topside unit's built-in GPS receiver and IMU. - -If the topside unit/antenna is at a globally stationary position (like a jetty) the *static* configuration of position and heading will give best accuracy of the system. Below you can see how the position and heading is set to static. Clicking on the map button opens a map window to help you input the static position. - -![gui_settings_topside_setup_static_pos_marked](../../img/gui_settings_topside_setup_static_pos_marked.png) - -## User preferences - -Select whether to use metric or imperial units, and/or if you would like a dummy boat to be displayed on the map and receiver configuration pages. diff --git a/docs/underwater-gps/interface/ugps-gui.md b/docs/underwater-gps/interface/ugps-gui.md index 9f562791..0be02e23 100644 --- a/docs/underwater-gps/interface/ugps-gui.md +++ b/docs/underwater-gps/interface/ugps-gui.md @@ -76,18 +76,18 @@ In the diagnostic plot you should see the signal from all 4 Receivers. The signa Acoustic interference can be observed in the diagnostic plot. Echo sounders from your boat or nearby boats typically appears like burst noise. -![diagnostics2](../../../img/diagnostics_2.png) +![diagnostics2](../../img/diagnostics_2.png) If it is coming from your boat, try to turn off the echo sounder to improve position accuracy. In case of interference from other acoustic sources, use the GUI to try other channels to avoid the interference. !!! Tip - Typically, NSD (_Noise spectral density_, displayed in the [Diagnostic](../underwater-gps/interface/ugps-gui.md#diagnostics) pane of the GUI) is around -100 dBm (in the units of version 3.3.0 or later of the software; 15 nV/sqrt(Hz) in the units of earlier software versions), or a little higher or lower. If it is much higher than this, it is likely that there is acoustic interference in the chosen channel, and a different channel should be tried. + Typically, NSD (_Noise spectral density_) is around -100 dBm (in the units of version 3.3.0 or later of the software; 15 nV/sqrt(Hz) in the units of earlier software versions), or a little higher or lower. If it is much higher than this, it is likely that there is acoustic interference in the chosen channel, and a different channel should be tried. Note in particular that acoustic devices quite commonly operate at frequencies lying in Channel 1. !!! Tip - If the NSD values are normal, signal quality is mainly indicated by the RSSI values (_Received signal strength indicator_, displayed in the [Diagnostic](../underwater-gps/interface/ugps-gui.md#diagnostics) pane of the GUI). As long as the RSSI values are not too far below the NSD values, the signal strength should be at usable levels. + If the NSD values are normal, signal quality is mainly indicated by the RSSI values (_Received signal strength indicator). As long as the RSSI values are not too far below the NSD values, the signal strength should be at usable levels. The UGPS system uses advanced signal processing techniques and can work even with rather weak signals, but an RSSI of -125 dBm or so (in the units of version 3.3.0 or later of the software; -45 dBnW in the units of earlier software versions) is around the lowest possible for an NSD of roughly -100 dBm. diff --git a/docs/underwater-gps/interface/warnings.md b/docs/underwater-gps/interface/warnings.md index e8f1d584..169fa759 100644 --- a/docs/underwater-gps/interface/warnings.md +++ b/docs/underwater-gps/interface/warnings.md @@ -11,5 +11,5 @@ Warnings that you might experience while using the UGPS. | Receiver N not detected. Please verify connection. | Receiver N is not detected by the Master-D1. Verify connection. | | External satellite position is required but not received. | External position is selected, but not received via the [API](http://demo.waterlinked.com/swagger/#/external/external#SetMaster). Typically this is an external software not started or not working. | | External orientation is required but not received. | External orientation is selected, but not received via the [API](http://demo.waterlinked.com/swagger/#/external/external#SetMaster). Typically this is an external software not started or not working. | -| IMU is not calibrated: position will not be accurate. Please rotate the kit to calibrate or use external orientation source. | See [IMU calibration](../hardware.md#imu-calibration) for details on how calibrate. | +| IMU is not calibrated: position will not be accurate. Please rotate the kit to calibrate or use external orientation source. | See [IMU calibration](../ugps-sysconfig.md#imu-calibration) for details on how calibrate. | | GPS has no position, please provide me with an unobstructed view of the sky. | The Underwater GPS needs GPS lock for time sync proposes. Move the Topside to another location where it has better view of the sky. | diff --git a/docs/underwater-gps/ugps-sysconfig.md b/docs/underwater-gps/ugps-sysconfig.md index 161d10ee..068d4afc 100644 --- a/docs/underwater-gps/ugps-sysconfig.md +++ b/docs/underwater-gps/ugps-sysconfig.md @@ -6,7 +6,7 @@ In the Baseline window in the GUI, you adjust the placement of your antenna/rece ## Basline settings Go to [Baseline](../underwater-gps/interface/ugps-gui.md#baseline) from the left menu in the GUI.
-In the tab at the top select **antenna** or **receivers** according to whether an [antenna](../antenna.md) or loose [receivers](../receiver-d1.md) are used. +In the tab at the top select **antenna** or **receivers** according to whether an [antenna](../underwater-gps/antenna.md) or loose [receivers](../underwater-gps/receiver-d1.md) are used. In the receiver view, in the graphical configuration panel, you either drag and drop the receivers to their actual position in relation to the topside, or you fill in the position manually in the input fields below the panel. (You might need to drag the receivers apart for the manual input fields to become visible) Remember to fill inn the receivers depth. @@ -14,7 +14,7 @@ In the antenna view you need to open Advanced Settings to fill in the position o Improved positioning will likely be obtained by **limiting the search area** : Restrict the search area as far as possible by dragging and dropping the arrows in the graphical configuration panel. -![Receiver setup](../../img/receiver_placemet_g2.png) +![Receiver setup](../img/receiver_placemet_g2.png) ## Locator and topside settings Cofigurations of the topside and locator settings is conducted in [Settings](../underwater-gps/interface/ugps-gui.md#settings), from the left menu in the GUI. @@ -56,7 +56,7 @@ For best performance on boats or similar, with a moving topside unit, we recomme If the topside unit/antenna is at a globally stationary position (like a jetty) the *static* configuration of position and heading will give best accuracy of the system. Below you can see how the position and heading is set to static. Clicking on the map button opens a map window to help you input the static position. -![gui_settings_topside_setup_static_pos_marked](../../img/gui_settings_topside_setup_static_pos_marked.png) +![gui_settings_topside_setup_static_pos_marked](../img/gui_settings_topside_setup_static_pos_marked.png) #### User preferences diff --git a/docs/underwater-gps/ugps-topside.md b/docs/underwater-gps/ugps-topside.md index 266077f4..9f618a95 100644 --- a/docs/underwater-gps/ugps-topside.md +++ b/docs/underwater-gps/ugps-topside.md @@ -132,4 +132,4 @@ The master electronics has an built in IMU used to provide the orientation of th ### IMU Calibration -For the IMU to work properly it needs to be calibrated. If the system is started on a new location a new calibration is needed for the IMU to work as intended. The IMU is calibrated in the [settings page](gui/settings.md) of the user interface. +For the IMU to work properly it needs to be calibrated. If the system is started on a new location a new calibration is needed for the IMU to work as intended. The IMU is calibrated in the [settings page](./interface/ugps-gui.md#settings) of the user interface. diff --git a/mkdocs.yml b/mkdocs.yml index f8f87e5a..c9b4a423 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,13 +62,6 @@ nav: - LED: underwater-gps/interface/ugps-led.md - Wiring: underwater-gps/interface/ugps-wiring.md - Warnings: underwater-gps/interface/warnings.md - # - GUI: - # - Position: underwater-gps/interface/gui/position.md - # - Baseline: underwater-gps/interface/gui/receivers.md - # - Settings: underwater-gps/interface/gui/settings.md - # - Diagnostic: underwater-gps/interface/gui/diagnostic.md - # - Diagnostic report: underwater-gps/interface/gui/diagnostic-report.md - # - Demo: underwater-gps/interface/gui/demo-gui.md - Hardware setup: - System setup: underwater-gps/ugps-sys-setup.md - Components: