diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 7728bfaf..95d9b511 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,4 +1,4 @@ -name: Deploy Water Linked Docs +name: Build Docs on: push: @@ -26,6 +26,7 @@ jobs: - name: Build docs run: | mkdocs build --strict + ./check-links.sh # Only deploy on master - name: Deploy docs diff --git a/README.md b/README.md index 7cea4ee8..716e60ce 100644 --- a/README.md +++ b/README.md @@ -14,23 +14,33 @@ This is done by creating a pull request. Make sure you have Python3 installed. ``` -git clone https://github.com/waterlinked/waterlinked.github.io -cd waterlinked.github.io +git clone https://github.com/waterlinked/docs.git +cd docs python -m venv venv source venv/bin/activate (Linux) venv\Scripts\activate.bat (Windows) pip install -r requirements.txt -mkdocs serve +./install-hooks.sh # (Optional) To automatically check links on git push ``` 2. Make changes using your favorite editor 3. Test them +``` +mkdocs serve # Allow you to view the changes on your browser +``` * Fire up your browser and go to localhost:8000 +Verify links are valid: + +``` +./check-links.sh +``` + ## Deploy changes to server -After the changes have been tested and they work, push the changes to the master branch and Github will build the website and publish it on https://docs.waterlinked.com. +After the changes have been tested and they work, push the changes to a branch, and make a merge request. The documentation site will built automatically and links will be verified. +Once the pull request is merged the documentation will be automatically built and published to https://docs.waterlinked.com. diff --git a/check-internal-links.py b/check-internal-links.py new file mode 100644 index 00000000..2c8c57ae --- /dev/null +++ b/check-internal-links.py @@ -0,0 +1,99 @@ +#!/usr/bin/env python3 +import re +import sys +from pathlib import Path + +# Regex for Markdown links: [text](target) +LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)") + +def slugify_heading(text: str) -> str: + """Convert Markdown heading text to MkDocs anchor format.""" + slug = text.strip().lower() + slug = re.sub(r"[^\w\s-]", "", slug) # remove punctuation + slug = re.sub(r"\s+", "-", slug) # spaces -> dashes + return slug + + +def extract_headings(md_file: Path): + """Return a set of anchor slugs from headings in md files.""" + headings = set() + if not md_file.is_file(): + return headings + for line in md_file.read_text(encoding="utf-8").splitlines(): + if line.startswith("#"): + heading_text = line.lstrip("#").strip() + headings.add(slugify_heading(heading_text)) + return headings + +def check_md_file(md_file: Path): + """Check links in md files.""" + errors = [] + if not md_file.is_file(): # <-- add this check + return errors + + for line_number, line in enumerate(md_file.read_text(encoding="utf-8").splitlines(), start=1): + + stripped = line.strip() + # Skip HTML and python comments + if stripped.startswith("#"): + continue + elif stripped.startswith(""): + continue + + for match in LINK_RE.finditer(line): + text, target = match.groups() + + # Skip external links + if target.startswith(("http://", "https://", "mailto:")): + continue + + # Remove leading slash for site-root relative links + elif target.startswith("/"): + target = target[1:] + + # Split anchor from file + if "#" in target: + if target.startswith("#"): + file_part, anchor = md_file, target[1:] + else: + file_part, anchor = target.split("#", 1) + else: + file_part, anchor = target, None + + # Resolve relative path' + target_path = Path(file_part) if isinstance(file_part, Path) else Path(file_part) #Make sure it's a Path object + target_file = (md_file.parent / target_path).resolve() + + if not target_file.exists() and not target_file.suffix: + target_file = (md_file.parent / (target_path.name + ".md")).resolve() + if not target_file.exists(): + errors.append(f"{md_file}:{line_number}: File not found -> {target}") + continue + + if target_file.is_file() and anchor: + headings = extract_headings(target_file) + if anchor not in headings: + errors.append(f"{md_file}:{line_number}: Anchor not found -> {target}") + + if target_file.is_dir(): + continue + + return errors + + +def main(md_dir): + md_dir = Path(md_dir) + all_errors = [] + for md_file in md_dir.rglob("*.md"): + all_errors.extend(check_md_file(md_file)) + + if all_errors: + print(f'Found {len(all_errors)} internal link errors in md files:') + for e in all_errors: + print(e) + return 1 + print("No internal link errors found.") + return 0 + +if __name__ == "__main__": + exit(main(sys.argv[1])) diff --git a/check-links.sh b/check-links.sh new file mode 100755 index 00000000..402711df --- /dev/null +++ b/check-links.sh @@ -0,0 +1,74 @@ +#!/bin/bash +# Pre-push hook: Custom linkchecker for local links, Build MkDocs locally and run LinkChecker on external links + +# Exit on error +set -e + +# === Paths === +PROJECT_ROOT="$(git rev-parse --show-toplevel)" +VENV_BIN="$PROJECT_ROOT/venv/bin" +TMP_BUILD_DIR="$PROJECT_ROOT/.tmp-mkdocs-build" +DOCS_DIR="$PROJECT_ROOT/docs" + +# Activate venv if not already activated +if [ -f "$VENV_BIN/activate" ]; then + . "$VENV_BIN/activate" +fi + +#Checking internal links in markdown files only +echo "Checking internal links in markdown files..." + +set +e +#Using custom python script for internal link checking: +python "$PROJECT_ROOT/check-internal-links.py" "$DOCS_DIR" +RESULT_INTERNAL=$? + +set -e + +if [ $RESULT_INTERNAL -ne 0 ]; then + echo "Internal linkcheck failed! Please fix Markdown links before pushing." + exit 1 +fi + +echo "Internal linkcheck passed!" + +# Check if linkchecker exists +if ! command -v linkchecker >/dev/null 2>&1; then + echo "Error: linkchecker executable not found in PATH" + exit 1 +fi + +# Remove old temp build if it exists +rm -rf "$TMP_BUILD_DIR" + +# Build MkDocs into temporary directory +echo "Building MkDocs locally into $TMP_BUILD_DIR..." +python -m mkdocs build -d "$TMP_BUILD_DIR" + +echo "Running LinkChecker on external links against local build..." +set +e +# Only report broken links +linkchecker "file://$TMP_BUILD_DIR/index.html" \ + --no-status \ + --check-extern \ + --recursion-level=2 \ + --ignore-url='sitemap\.xml\.gz' \ + --ignore-url='https://github.com/.*/edit/' \ + --ignore-url='https://www.youtube.com/' \ + --ignore-url='.*/assets/.*' \ + --ignore-url='.*/images/.*' + + +RESULT_EXTERNAL=$? +set -e + +# Clean up +rm -rf "$TMP_BUILD_DIR" + +if [ $RESULT_EXTERNAL -ne 0 ]; then + echo "External linkcheck failed! Please fix broken links before pushing." + exit 1 +fi + +echo "External linkcheck passed!" +exit 0 \ No newline at end of file diff --git a/docs/dvl/axes.md b/docs/dvl/axes.md index f801b934..97e3899c 100644 --- a/docs/dvl/axes.md +++ b/docs/dvl/axes.md @@ -52,7 +52,7 @@ By default, the body frame and vehicle frame is the same and align with the DVL' The DVL can be mounted at an angle to the forward direction of a vehicle to which it is attached. -To be precise, the clockwise angle θ in degrees around the Z axis (i.e. in the X-Y plane) from the forward axis of the vehicle to the forward axis of the DVL can be entered as a 'mounting rotation offset' in the [GUI](../gui/configuration), or via the TCP or serial [protocols](../dvl-protocol/). +To be precise, the clockwise angle θ in degrees around the Z axis (i.e. in the X-Y plane) from the forward axis of the vehicle to the forward axis of the DVL can be entered as a 'mounting rotation offset' in the [GUI](../dvl/gui/configuration.md), or via the TCP or serial [protocols](../dvl-protocol/). The DVL will then output data in the vehicle frame obtained by rotating the [DVL body frame](#body-frame) anti-clockwise around the Z-axis by θ degrees: the X-axis of the velocities outputted by the DVL will be aligned with the forward axis of the vehicle, and, at time zero, the X-axis of the DVL's [frame](../dead-reckoning#frame) for dead reckoning will be aligned with the forward axis of the vehicle. diff --git a/docs/dvl/bluerov-integration.md b/docs/dvl/bluerov-integration.md index 05f64d87..4db755b5 100644 --- a/docs/dvl/bluerov-integration.md +++ b/docs/dvl/bluerov-integration.md @@ -47,7 +47,7 @@ You will also need: * Utility knife * Wire stripping tool * Zip ties -* 4 x 30 cm (12") wires (options discussed under [Connect DVL-A50 and BlueROV2](#connect-dvl-a50-and-bluerov2)). If possible, use 2 x red and 2 x black wires. +* 4 x 30 cm (12") wires (options discussed under [Connect DVL-A50 and BlueROV2](#attach-dvl-a50-to-bluerov2)). If possible, use 2 x red and 2 x black wires. * 15 cm (6") ethernet cable ## Preparation diff --git a/docs/dvl/dead-reckoning.md b/docs/dvl/dead-reckoning.md index 67815afb..9cc69621 100644 --- a/docs/dvl/dead-reckoning.md +++ b/docs/dvl/dead-reckoning.md @@ -4,8 +4,8 @@ The DVL-A50 and DVL-A125 run a dead reckoning algorithm which estimates the orie ## Starting dead reckoning -1. Calibrate the gyroscope by pressing *More -> Calibrate gyro* in the [GUI](../gui/dashboard) whilst the DVL is stationary. -2. Click the 'Reset' button ![](../img/dvl_gui_icon_reset.png) in the [GUI](../gui/dashboard), or send a reset command over the TCP or serial [protocol](../dvl-protocol). +1. Calibrate the gyroscope by pressing *More -> Calibrate gyro* in the [GUI](../dvl/gui/dashboard.md) whilst the DVL is stationary. +2. Click the 'Reset' button ![](../img/dvl_gui_icon_reset.png) in the [GUI](../dvl/gui/dashboard.md), or send a reset command over the TCP or serial [protocol](../dvl-protocol). Failure to perform gyro calibration will result in less accurate dead reckoning. @@ -22,11 +22,11 @@ When the DVL fails in its determination of velocity, speed and position are pred !!! note When the DVL is powered on in the air, its position will drift significantly. This should be ignored, and dead reckoning should be [started](#starting-dead-reckoning) in water when ready. -The position of the DVL can be viewed in the GUI [dashboard](../gui/dashboard/) or be fetched by [API](../dvl-protocol/#dead-reckoning-report). +The position of the DVL can be viewed in the GUI [dashboard](../dvl/gui/dashboard.md) or be fetched by [API](../dvl-protocol/#dead-reckoning-report). ## Orientation -The calculation of the orientation of the DVL is based upon the accelerometer and gyroscope measurements of its IMU. The orientation is represented by roll, pitch, and yaw angles, and can be viewed in the GUI [dashboard](../gui/dashboard/) or be fetched by [API](../dvl-protocol/#dead-reckoning-report). +The calculation of the orientation of the DVL is based upon the accelerometer and gyroscope measurements of its IMU. The orientation is represented by roll, pitch, and yaw angles, and can be viewed in the GUI [dashboard](../dvl/gui/dashboard.md) or be fetched by [API](../dvl-protocol/#dead-reckoning-report). - Roll is a rotation around the X axis of the DVL - Pitch is a rotation around the Y axis of the DVL diff --git a/docs/dvl/dvl-protocol.md b/docs/dvl/dvl-protocol.md index 3b8713bf..2ff713ac 100644 --- a/docs/dvl/dvl-protocol.md +++ b/docs/dvl/dvl-protocol.md @@ -538,7 +538,7 @@ The new configuration will not be returned in the response, but can be obtained ### Velocity report, old format (wrx) [Deprecated] -Same purpose as the [velocity report](#velocity-report), but in an older format: +Same purpose as the [velocity report](#velocity-report-wrz), but in an older format: `wrx,`*[time],[vx],[vy],[vz],[fom],[altitude],[valid],[status]* @@ -571,7 +571,7 @@ wrx,1164.94,0.000,0.000,0.000,2.707,-1.00,n,1*39 ### Transducer report, old format (wrt) [Deprecated] -Same purpose as the [transducer report](#transducer-report), but in an older format, and combining the data of all four transducers: +Same purpose as the [transducer report](#transducer-report-wru), but in an older format, and combining the data of all four transducers: `wrt,`*[dist_1],[dist_2],[dist_3],[dist_4]* @@ -605,7 +605,7 @@ Checksum is formatted as a hexadecimal number using 2 lower-case characters (ex: Compatible implementations: * Python 3: [crcmod](https://pypi.org/project/crcmod/) `crcmod.predefined.mkPredefinedCrcFun("crc-8")` -* Golang: [github.com/sigurn/crc8](github.com/sigurn/crc8) `crc8.MakeTable(crc8.CRC8)` +* Golang: [github.com/sigurn/crc8](https://github.com/sigurn/crc8) `crc8.MakeTable(crc8.CRC8)` Example for how to verify checksum using Python 3 and [crcmod](https://pypi.org/project/crcmod/): diff --git a/docs/dvl/dvl-troubleshooting.md b/docs/dvl/dvl-troubleshooting.md index c66d1f0d..711f6589 100644 --- a/docs/dvl/dvl-troubleshooting.md +++ b/docs/dvl/dvl-troubleshooting.md @@ -6,7 +6,7 @@ Below is a small list to check if your DVL is not performing as expected or you In the Support Portal please describe the test environment or test setup you have used and how the DVL is mounted. If possible, open the DVL GUI and go to Diagnostic Log in the left menu. Press the Create Diagnostic Report button. This will automatically record a log file that you can download to your computer. Please add the [Diagnostic reports](gui/diagnostic-report.md) and pictures of the test setup in the support portal. This will help our support team greatly! -If the troubleshooting guide do not help, please check out [FAQ DVL](faq.md#faq-dvl)! +If the troubleshooting guide do not help, please check out [FAQ DVL](../dvl/faq.md)! ### Check if DVL is powered 1. Put the DVL under water and power it on with an adequate power supply. @@ -14,7 +14,7 @@ If the troubleshooting guide do not help, please check out [FAQ DVL](faq.md#faq- * Does the LED turn on? ### LED -1. For LED status, see [LED Signals](../interfaces#LED-Signals). +1. For LED status, see [LED Signals](../dvl/interfaces.md#led-signals). ### Wiring 1. Check that you have wired your DVL correctly, see [Wiring interface](../interfaces#wiring-interface). diff --git a/docs/dvl/gui/dashboard.md b/docs/dvl/gui/dashboard.md index 9a23f697..7c4b359d 100644 --- a/docs/dvl/gui/dashboard.md +++ b/docs/dvl/gui/dashboard.md @@ -1,8 +1,8 @@ # Dashboard -Both the DVL-A50 and the DVL-A125 have a web-based GUI. In your favorite web browser, simply navigate to the DVL's [IP address](../../networking). +Both the DVL-A50 and the DVL-A125 have a web-based GUI. In your favorite web browser, simply navigate to the DVL's [IP address](../networking.md). -The default page is a dashboard which provides a summary and visualisation of both the velocity and [dead reckoning](../../dead-reckoning) data outputted by the DVL, as well as an indication of current status. +The default page is a dashboard which provides a summary and visualisation of both the velocity and [dead reckoning](../dead-reckoning.md) data outputted by the DVL, as well as an indication of current status. ## Screenshot diff --git a/docs/dvl/interfaces.md b/docs/dvl/interfaces.md index 62a06840..8c88cac7 100644 --- a/docs/dvl/interfaces.md +++ b/docs/dvl/interfaces.md @@ -91,7 +91,7 @@ See the DVL's [serial protocol](../dvl-protocol#serial-protocol). ## Ethernet Interface -See [networking](../networking) and the DVL's [TCP protocol](../dvl-protocol#ethernet-protocol-tcp). +See [networking](../networking) and the DVL's [TCP protocol](../dvl/dvl-protocol.md#json-protocol-tcp). ## Code examples diff --git a/docs/dvl/networking.md b/docs/dvl/networking.md index 2162088f..942586e1 100644 --- a/docs/dvl/networking.md +++ b/docs/dvl/networking.md @@ -3,7 +3,7 @@ The DVL has several services available over ethernet: * [Multicast DNS](#multicast-dns-mdns) (mDNS) for easy discovery -* Web [GUI](../gui/dashboard), providing a visualisation of the data outputted by the DVL, as well as configuration, [updating of software](../sw-update), diagnostics, and more. +* Web [GUI](../dvl/gui/dashboard.md), providing a visualisation of the data outputted by the DVL, as well as configuration, [updating of software](../sw-update), diagnostics, and more. * TCP [data stream](#tcp-data-stream) * [Software updates](../sw-update) @@ -11,7 +11,7 @@ The DVL has several services available over ethernet: ### Multicast DNS (mDNS) -The DVL runs a DHCP client which will attempt to obtain an IP address from a DHCP server (e.g. in a router) on the same network, and supports mDNS: the mDNS name of the DVL is `waterlinked-dvl`. On a computer which supports mDNS, one can then simply access the web [GUI](../gui/dashboard) at [http://waterlinked-dvl](http://waterlinked-dvl). +The DVL runs a DHCP client which will attempt to obtain an IP address from a DHCP server (e.g. in a router) on the same network, and supports mDNS: the mDNS name of the DVL is `waterlinked-dvl`. On a computer which supports mDNS, one can then simply access the web [GUI](../dvl/gui/dashboard.md) at [http://waterlinked-dvl](http://waterlinked-dvl). !!! note If no DHCP server is available on the network, it is recommended to use the [fallback IP](#fallback-ip) or configure a [static IP address](#via-the-gui), as the DVL can spend up to 5 minutes searching for a DHCP server. @@ -23,11 +23,11 @@ The DVL will always be available with the static IP address: **192.168.194.95**. * Connect an ethernet cable directly from the DVL to your computer. * For an/the ethernet interface of your computer, configure it to have a static IP address in the same subnet as 192.168.194.95, e.g. 192.168.194.90 or anything else of the form 192.168.194.xxx if using a subnet of the form 255.255.255.0 (aka 192.168.194.0/24). * Activate the ethernet interface of your computer which you configured in the previous step. -* In a web browser, open http://192.168.194.95 to access the web [GUI](../gui/dashboard). +* In a web browser, open http://192.168.194.95 to access the web [GUI](../dvl/gui/dashboard.md). ### Via the GUI -The IP address of the DVL can be configured in two ways via the web [GUI](../gui/dashboard): +The IP address of the DVL can be configured in two ways via the web [GUI](../dvl/gui/dashboard.md): * DCHP client: an IP address is obtained from a DHCP server (e.g. in a router) on the same network, as in the discussion of [mDNS](#multicast-dns-mdns) above. * Static: equip the DVL with a certain static IP address. @@ -39,4 +39,4 @@ After the IP configuration of the DVL is modified, the DVL needs to be rebooted ## TCP data stream -The DVL can output data and receive commands over Transmission Control Protocol (TCP). A TCP server is available on port **16171** which outputs the latest data to all connected clients, and which listens to commands from any of these connected clients. See the DVL's TCP [protocol](./dvl-protocol.md#ethernet-protocol-tcp). +The DVL can output data and receive commands over Transmission Control Protocol (TCP). A TCP server is available on port **16171** which outputs the latest data to all connected clients, and which listens to commands from any of these connected clients. See the DVL's TCP [protocol](../dvl/dvl-protocol.md#json-protocol-tcp). diff --git a/docs/dvl/sw-update.md b/docs/dvl/sw-update.md index 8adbf4e2..c6bfdd8d 100644 --- a/docs/dvl/sw-update.md +++ b/docs/dvl/sw-update.md @@ -2,7 +2,7 @@ It is recommended to always run the latest DVL software where possible. The latest software can be obtained [automatically](#automatic-software-update) or [manually](#offline-software-update). -The release notes for each release is available in the [GUI](../gui/dashboard) and also in the [GUI demo](https://dvl.demo.waterlinked.com/#/about). +The release notes for each release is available in the [GUI](../dvl/gui/dashboard.md) and also in the [GUI demo](https://dvl.demo.waterlinked.com/#/about). !!! Warning During the software upgrade, the thermal protection feature is turned off. To prevent the DVL from overheating, it is important to submerge the DVL in water throughout the update process. @@ -12,7 +12,7 @@ The release notes for each release is available in the [GUI](../gui/dashboard) a ## Automatic software update -The DVL's [GUI](../gui/dashboard) automatically checks and indicates if a new software version is available. +The DVL's [GUI](../dvl/gui/dashboard.md) automatically checks and indicates if a new software version is available. * Connect the DVL over ethernet to a network connected to the internet. If on a personal computer, it may be necessary to make a network bridge between a network interface (such as wifi) which has access to the internet and the ethernet interface through which the DVL is connected. * Go to http://[IP_ADDRESS_OF_THE_DVL]:9000 in a web browser. @@ -22,7 +22,7 @@ The DVL's [GUI](../gui/dashboard) automatically checks and indicates if a new so If it is not possible to connect the DVL to the internet, one can proceed as follows. -* Find the current version and chip ID of the DVL at *Menu -> About* in the [GUI](../gui/dashboard). +* Find the current version and chip ID of the DVL at *Menu -> About* in the [GUI](../dvl/gui/dashboard.md). * Manually download an update package (`.wlup`) from the [update server](https://update.waterlinked.com/) using the chip ID. * Verify if the downloaded version is newer than the currently running version. * Set system time as shown below. diff --git a/docs/explorer-kit/gui/api.md b/docs/explorer-kit/gui/api.md index 7f7b8850..91e9a7d7 100644 --- a/docs/explorer-kit/gui/api.md +++ b/docs/explorer-kit/gui/api.md @@ -16,7 +16,7 @@ See [demo.waterlinked.com/swagger](http://demo.waterlinked.com/swagger) for the Any programming language can be used to interact with the API. We have examples in both [python](https://github.com/waterlinked/examples) and [go](https://github.com/waterlinked/ugps-nmea-go), which currently cover, for instance: -* Sending of locator depth when using the [A1 locator](../locators/locator-a1) (see the script `externaldepth.py`). +* Sending of locator depth when using the [A1 locator](../locators/locator-a1.md) (see the script `externaldepth.py`). * Sending in of satellite GPS data (positioning and/or heading) from an external GPS receiver (see the script `nmeainput.py` or its [go analogue](https://github.com/waterlinked/ugps-nmea-go)) * Export of tracks to a GPX file (see the script `tracklog.py`) * Output of the positions calculated by the UGPS G2 system in NMEA format (see the script `nmeaoutput.py` or its [go analogue](https://github.com/waterlinked/ugps-nmea-go)) diff --git a/docs/explorer-kit/gui/settings.md b/docs/explorer-kit/gui/settings.md index 5f1e5351..4bff93f4 100644 --- a/docs/explorer-kit/gui/settings.md +++ b/docs/explorer-kit/gui/settings.md @@ -7,7 +7,7 @@ In this section you choose which locator you are using with the system and on which channel it is sending. The Water Linked default channel is 17 and this is the channel that the Locator-S1 is running on. If using the Locator-U1 the channel needs to macth the rotary switch at the back of the U1. !!! warning - If you are using the Locator-A1 or S1, you need to provid depth information to the topside unit. Description on how to do this is found [here](api.md#providing-depth-to-system-when-using-locator-a1s1). + If you are using the Locator-A1 or S1, you need to provid depth information to the topside unit. This is implemented through the explorer-kit's[API](../gui/api.md). ## Top-side Setup diff --git a/docs/explorer-kit/locators/locator-a1.md b/docs/explorer-kit/locators/locator-a1.md index b8b25c39..80372081 100644 --- a/docs/explorer-kit/locators/locator-a1.md +++ b/docs/explorer-kit/locators/locator-a1.md @@ -4,7 +4,7 @@ ## Description -The Locator-A1 has the smallest physical footprint in our series of locators. It can be integrated into even the most compact ROVs. The Locator-A1 does not carry its own depth sensor, and the Master-D1 requires that the depth be provided from your underwater vehicle (ROV etc.) This can be achieved by means of the [UGPS API](../gui/api). +The Locator-A1 has the smallest physical footprint in our series of locators. It can be integrated into even the most compact ROVs. The Locator-A1 does not carry its own depth sensor, and the Master-D1 requires that the depth be provided from your underwater vehicle (ROV etc.) This can be achieved by means of the [UGPS API](../gui/api.md). ## Wiring interface diff --git a/docs/explorer-kit/locators/locator-s1.md b/docs/explorer-kit/locators/locator-s1.md index 15092b4f..28f9e25d 100644 --- a/docs/explorer-kit/locators/locator-s1.md +++ b/docs/explorer-kit/locators/locator-s1.md @@ -11,7 +11,7 @@ Some Locator-S1 attributes can be configured using an integrated UART (3V3) inte Locator-S1 supports channel 16,17 and 18. -As the Locator-S1 does not carry its own depth sensor, the depth needs to be provided from the underwater vehicle (ROV etc.) to the topside Master-D1 using the software API. Example of how to perform this can be found [here](../gui/api.md#providing-depth-to-system-when-using-locator-a1s1). +As the Locator-S1 does not carry its own depth sensor, the depth needs to be provided from the underwater vehicle (ROV etc.) to the topside Master-D1 using the software API. This can be achieved by means of the [UGPS API](../gui/api.md). ## LED Signals diff --git a/docs/explorer-kit/quickstart.md b/docs/explorer-kit/quickstart.md index 1d07cc2b..ed0e8050 100644 --- a/docs/explorer-kit/quickstart.md +++ b/docs/explorer-kit/quickstart.md @@ -41,7 +41,7 @@ Now that everything is connected and ready it is time to select the right locato After selecting the correct locator, you need to provide the correct placement of the receivers to the GUI for the positioning to work correctly. This is done by drag'n drop of each receiver to the correct placment relative to the topside unit. The position of each receiver is seen below in the map view. It you click on the receiver you get a pop up with the possibility to write its exact placment. Once this is done you can limit the search range by using the same drag and drop feature. !!! warning - If you are using the Locator-A1 or S1, you need to provide depth information to the topside unit. Description on how to do this is found [here](gui/api.md#providing-depth-to-system-when-using-locator-a1s1). + If you are using the Locator-A1 or S1, you need to provide depth information to the topside unit. This is achieved using the explorer-kit [API](../explorer-kit/gui/api.md). !!! tip Reducing the search range helps to improve the performance of the system. It is recomended to limith this range if you are operating in a smaller area. This is especially important in tanks. diff --git a/docs/explorer-kit/upgrader.md b/docs/explorer-kit/upgrader.md index 98cd056e..e40d9c81 100644 --- a/docs/explorer-kit/upgrader.md +++ b/docs/explorer-kit/upgrader.md @@ -10,7 +10,7 @@ A software update package (.wlup file) includes all files required to update the Please select the update process that is best suited to you: -* If the Underwater GPS GUI is visible to you on [http://192.168.2.94](http://192.168.2.94) please use the [Update with static IP](#update-using-static-ip). +* Type *http://192.168.2.94* in your web browser. If the Underwater GPS GUI is visible to you, please use the [Update with static IP](#update-using-static-ip). * If the Underwater GPS GUI is not shown when using the link above, please use the [Update with DHCP](#update-using-dhcp). !!! warning @@ -33,12 +33,12 @@ This procedure works if you have haven't changed the jumpers on the Master-D1, y | 2 | Power off the system | | | 3 | Connect the upgrade plug included in the kit or connect GPIO0 to ground using a jumper cable | ![upgrade_plug](../img/upgrade_plug.jpg) ![upgrade_jumper](/../img/upgrade_jumper.jpg) | | 4 | Power on the system | | -| 6 | Go to web gui [http://192.168.2.94](http://192.168.2.94) | If you see a blank or partly broken page, try to clean browser cache by pressing Ctrl-F5 or opening the page in "Private"/"Incognito" mode | +| 6 | Open the web gui by typing *http://192.168.2.94* in your web browser.| If you see a blank or partly broken page, try to clean browser cache by pressing Ctrl-F5 or opening the page in "Private"/"Incognito" mode | | 7 | Remove the upgade plug or the jumper grounding GP0. | | | 8 | Click “Browse file” and select correct <>.wlup file | | | 9 | Wait for update process to complete | | | 10 | When the update process is complete and successful, the system will automatically reboot to standard mode | If process fails, please try again | -| 11 | Verify that the SW version has updated by going to the web gui [http://192.168.2.94](http://192.168.2.94) | If you see a blank or partly broken page, try to clean browser cache by pressing Ctrl-F5 or opening the page in "Private"/"Incognito" mode | +| 11 | Verify that the SW version has updated by going to the web gui *http://192.168.2.94* | If you see a blank or partly broken page, try to clean browser cache by pressing Ctrl-F5 or opening the page in "Private"/"Incognito" mode | | 12 | Upgrade process complete | Celebrate with your favorite beverage | @@ -55,11 +55,11 @@ This procedure works if you don't know how to set a static IP address on your co | 5 | Configure the network on your computer to get IP address from DHCP | (this is default on most computers, so if you haven't set a static ip you're good) | | 6 | Connect the upgrade plug included in the kit or connect GPIO0 to ground using a jumper cable | ![upgrade_plug](../img/upgrade_plug.jpg) ![upgrade_jumper](/../img/upgrade_jumper.jpg) | | 7 | Power on the system | | -| 8 | Go to web GUI [http://192.168.0.1](http://192.168.0.1) | If you see a blank or partly broken page, try to clean browser cache by pressing Ctrl-F5 or opening the page in "Private"/"Incognito" mode | +| 8 | In your web browser, open *http://192.168.0.1* | If you see a blank or partly broken page, try to clean browser cache by pressing Ctrl-F5 or opening the page in "Private"/"Incognito" mode | | 9 | Remove the grounding of GP0. | | | 10 | Click “Browse file” and select correct <>.wlup file | | | 11 | Wait for update process to complete | | | 12 | When the update process is complete and successful, the system will automatically reboot to standard mode | If process fails, please try again | -| 13 | Verify that the SW version has updated by going to the web gui [http://192.168.0.1](http://192.168.0.1) | If you see a blank or partly broken page, try to clean browser cache by pressing Ctrl-F5 or opening the page in "Private"/"Incognito" mode | +| 13 | Verify that the SW version has updated by opeing the web gui in your browser: *http://192.168.0.1* | If you see a blank or partly broken page, try to clean browser cache by pressing Ctrl-F5 or opening the page in "Private"/"Incognito" mode | | 14 | Reset network settings to original setting from step 2 | See [network settings](hardware.md). | | 15 | Upgrade process complete | Celebrate with your favorite beverage | diff --git a/docs/img/ugps-img/ugps-imu-calibration.png b/docs/img/ugps-img/ugps-imu-calibration.png new file mode 100644 index 00000000..7f1d66ce Binary files /dev/null and b/docs/img/ugps-img/ugps-imu-calibration.png differ diff --git a/docs/modem-m64/modem-m64-protocol.md b/docs/modem-m64/modem-m64-protocol.md index 85534991..ecbe8eb1 100644 --- a/docs/modem-m64/modem-m64-protocol.md +++ b/docs/modem-m64/modem-m64-protocol.md @@ -50,7 +50,7 @@ The modem with role B will go back to listen mode if several consecutive packets Payload where every byte is \0 is reserved. It is used to keep modems in sync if no data packet is queued by the user. This sync packet is filtered out by the receiver. Avoid this payload by compressing the data or otherwise ensuring atleast 1 bit is non-zero. Checksum is optional when sending commands to the modem. The modem always returns a checksum. The checksum algorithm -is CRC-8 and it is formatted as a hexadecimal number using 2 lower-case charaters (ex: `*c3`). See the [checksum section](../../dvl/dvl-protocol/#checksum) of the manual for our DVL product (which uses the same CRC-8 algorithm) for further details and example code. +is CRC-8 and it is formatted as a hexadecimal number using 2 lower-case charaters (ex: `*c3`). See the [checksum section](../dvl/dvl-protocol.md#checksum) of the manual for our DVL product (which uses the same CRC-8 algorithm) for further details and example code. ## Commands diff --git a/docs/sonar-3d/sonar-3d-15-config.md b/docs/sonar-3d/sonar-3d-15-config.md index f614dd55..ea926f8b 100644 --- a/docs/sonar-3d/sonar-3d-15-config.md +++ b/docs/sonar-3d/sonar-3d-15-config.md @@ -25,7 +25,7 @@ Acoustics are disabled when the Sonar first boot. You'll see a message in the 3D ### Network -Set how the Sonar 3D-15 is assigned an IP on your network: Automatic IP (DHCP) or Static IP. Default is Automatic IP. For further details regarding network setup, [see Networking](/Sonar-3d/Sonar-3d-15-networking/). +Set how the Sonar 3D-15 is assigned an IP on your network: Automatic IP (DHCP) or Static IP. Default is Automatic IP. For further details regarding network setup, [see Networking](../sonar-3d/sonar-3d-15-networking.md). !!! Note Saved Network Settings are persistent, meaning it is kept on restart. @@ -83,7 +83,7 @@ Allows for upgrading the Sonar's firmware. Click the button to open a new tab to ![Upgrade firmware](../img/Sonar-3D-15-config-advanced-firmware.png) -The firmware upgrader allows for automatically checking and upgrading the Sonar firmware if neccessary. This requires a working Internet connection to work. Alternatively, an offline (manual) upgrade can be used. [Read more about offline firmware upgrades](/sonar-3d-15-software-update/#offline-software-update). +The firmware upgrader allows for automatically checking and upgrading the Sonar firmware if neccessary. This requires a working Internet connection to work. Alternatively, an offline (manual) upgrade can be used. [Read more about offline firmware upgrades](../sonar-3d/sonar-3d-15-software-update.md#offline-software-update). If needed, follow the steps to complete the upgrade. Upon completion, the Sonar will reset all settings back to factory default and restart. Firmware upgrade can take a couple of minutes. @@ -105,7 +105,7 @@ Submit a [support ticket](https://waterlinked.com/support) and attach the diagno ### Integration API -Change how the Sonar transmits data and at what address the integration API is available from. Options are Disabled, Multicast (Default) and Unicast. [Read more about the Integration API](/sonar-3d/sonar-3d-15-api). +Change how the Sonar transmits data and at what address the integration API is available from. Options are Disabled, Multicast (Default) and Unicast. [Read more about the Integration API](../sonar-3d/sonar-3d-15-api.md). ### Update Rate diff --git a/docs/sonar-3d/sonar-3d-15-networking.md b/docs/sonar-3d/sonar-3d-15-networking.md index 568ba91b..30ddaab0 100644 --- a/docs/sonar-3d/sonar-3d-15-networking.md +++ b/docs/sonar-3d/sonar-3d-15-networking.md @@ -15,7 +15,7 @@ The Sonar 3D-15 has several services available over ethernet: The Sonar 3D-15 runs a DHCP client which will attempt to obtain an IP address from a DHCP server (e.g. in a router) on the same network, and supports mDNS: the mDNS name of the Sonar 3D-15 is `waterlinked-sonar`. On a computer which supports mDNS, one can then simply access the web [GUI](sonar-3d-15-gui.md) at [http://waterlinked-sonar](http://waterlinked-sonar). !!! note - If no DHCP server is available on the network, it is recommended to use the [fallback IP](#fallback-ip) or configure a [static IP address](#via-the-gui), as the Sonar 3D-15 can spend up to 5 minutes searching for a DHCP server. + If no DHCP server is available on the network, it is recommended to use the [fallback IP](#fallback-ip) or configure a [static IP address](#user-set-ip), as the Sonar 3D-15 can spend up to 5 minutes searching for a DHCP server. ### Fallback IP diff --git a/docs/underwater-gps/integration/bluerov-integration-a1.md b/docs/underwater-gps/integration/bluerov-integration-a1.md index 24a57689..cffb5675 100644 --- a/docs/underwater-gps/integration/bluerov-integration-a1.md +++ b/docs/underwater-gps/integration/bluerov-integration-a1.md @@ -1,6 +1,6 @@ # Installation of Locator-A1 on BlueROV2 with integration kit -This guide describes the hardware modifications to the ROV, FXTI and UGPS Topside in order to integrate the [Locator-A1](../../locators/locator-a1). To summarize, two main changes are performed: A spare twisted wire pair in the tether is used to connect the Locator-A1 and the UGPS Topside. Secondly, the UGPS Topside is connected directly to the communication between ROV and topside computer. +This guide describes the hardware modifications to the ROV, FXTI and UGPS Topside in order to integrate the [Locator-A1](../locators/locator-a1.md). To summarize, two main changes are performed: A spare twisted wire pair in the tether is used to connect the Locator-A1 and the UGPS Topside. Secondly, the UGPS Topside is connected directly to the communication between ROV and topside computer. ## Required parts and tools @@ -291,7 +291,7 @@ Now that all hardware modifications are done, you will connect UGPS Topside, FXT * Set your topside computer to have a static IP address of 192.168.2.1 with subnet mask 255.255.255.0. The BlueROV2 typically has IP address 192.168.2.2, so you probably already have this set up. Make sure your firewall allows QGroundControl to communicate with the network. Look at the [Network Setup steps at Blue Robotics](https://bluerobotics.com/learn/bluerov2-software-setup/#network-setup) if you need more details. -* Set the [IP switch](../../network-settings/#ethernet) inside the UGPS Topside unit to `192.168.2.94` (the down position). This equips the G2 topside unit with the static IP address 192.168.2.94. +* Set the [IP switch](../network-settings.md#ethernet) inside the UGPS Topside unit to `192.168.2.94` (the down position). This equips the G2 topside unit with the static IP address 192.168.2.94. * Connect the Binder-connector named "Locator" at the UGPS Topside with the newly installed Binder-connector at the FXTI using the deck extension cable, which came with the BlueROV integration kit. (Power up the UGPS Topside)[https://waterlinked.github.io/underwater-gps/power-supply/]. It is on when the power button is lit. diff --git a/docs/underwater-gps/integration/bluerov-integration-u1.md b/docs/underwater-gps/integration/bluerov-integration-u1.md index c753495d..689259c6 100644 --- a/docs/underwater-gps/integration/bluerov-integration-u1.md +++ b/docs/underwater-gps/integration/bluerov-integration-u1.md @@ -1,6 +1,6 @@ # Installation of Locator-U1 on BlueROV2 -This guide contains instructions for installation of the [Locator-U1](../../locators/locator-u1) to a BlueROV2. The first part describes the mechanical installation and the second part describes how to establish a network bridge between UGPS Topside and FXTI/BlueROV2. +This guide contains instructions for installation of the [Locator-U1](../locators/locator-u1.md) to a BlueROV2. The first part describes the mechanical installation and the second part describes how to establish a network bridge between UGPS Topside and FXTI/BlueROV2. ## Mount the Locator-U1 to the BlueROV2 frame @@ -15,7 +15,7 @@ See the [general Locator-U instructions](../locators/locator-u1.md) for daily op In this guide it is described how to establish a network connection between UGPS Topside, FXTI/BlueROV2 and topside computer without hardware modifications to the UGPS Topside. This is opposed to the method used with the BlueROV integration kit for Locator-A1. To put it short, the connection between the three devices is established with a network bridge and a static IP address of 192.168.2.1 (subnet mask 255.255.255.0) for your computer. -1. Set the [IP switch](../../network-settings/#ethernet) inside the UGPS G2 topside unit to `192.168.2.94` (the down position). This equips the G2 topside unit with the static IP address 192.168.2.94. +1. Set the [IP switch](../network-settings.md#ethernet) inside the UGPS G2 topside unit to `192.168.2.94` (the down position). This equips the G2 topside unit with the static IP address 192.168.2.94. 2. [Connect power](https://waterlinked.github.io/underwater-gps/power-supply/) to the UGPS Topside and switch on the power, resulting in the power switch lighting up. diff --git a/docs/underwater-gps/integration/bluerov-integration.md b/docs/underwater-gps/integration/bluerov-integration.md index 085c3c4e..53a3ba54 100644 --- a/docs/underwater-gps/integration/bluerov-integration.md +++ b/docs/underwater-gps/integration/bluerov-integration.md @@ -4,26 +4,26 @@ The Water Linked Underwater GPS G2 (from now UGPS) system can be integrated with ## Most common integration methods -* We recommend you to use the [Locator-A1](../../locators/locator-a1) together with the [BlueROV2 Integration Kit](https://waterlinked.com/shop/underwater-gps-g2-bluerov2-integration-kit-103) when integrating the UGPS system with the BlueROV2. The integration steps are described in [BlueROV2 Integration Locator-A1](bluerov-integration-a1.md). Hardware modification must be carried out on the ROV, FXTI and UGPS Topside which serve two purposes: Firstly, a spare twisted wire pair in the tether is used to connect the Locator-A1 to the UGPS Topside. Secondly, the UGPS Topside is modified to connect directly to the communication between ROV and topside computer. The advantage of integrating using this method is that there is no additional topside computer configuration required, which can be challenging with different operating systems (i.e. Linux, iOS). +* We recommend you to use the [Locator-A1](../locators/locator-a1.md) together with the [BlueROV2 Integration Kit](https://waterlinked.com/shop/underwater-gps-g2-bluerov2-integration-kit-103) when integrating the UGPS system with the BlueROV2. The integration steps are described in [BlueROV2 Integration Locator-A1](bluerov-integration-a1.md). Hardware modification must be carried out on the ROV, FXTI and UGPS Topside which serve two purposes: Firstly, a spare twisted wire pair in the tether is used to connect the Locator-A1 to the UGPS Topside. Secondly, the UGPS Topside is modified to connect directly to the communication between ROV and topside computer. The advantage of integrating using this method is that there is no additional topside computer configuration required, which can be challenging with different operating systems (i.e. Linux, iOS). -* If you wish to avoid carrying out hardware changes to the ROV, as they are required to integrate the A1-Locator, then we recommend you to use the [Locator-U1](../../locators/locator-u1). The locator can simply be attached to the BlueROV2 in any convenient way. However some configuration steps in the topside computer are required to establish a network bridge, so the position calculated by the UGPS Topside is available in QGroundControl. These steps are described in [BlueROV2 Integration Locator-U1](bluerov-integration-u1.md). Be aware that setting up a network bridge in operating systems other than Windows can be challenging. +* If you wish to avoid carrying out hardware changes to the ROV, as they are required to integrate the A1-Locator, then we recommend you to use the [Locator-U1](../locators/locator-u1.md). The locator can simply be attached to the BlueROV2 in any convenient way. However some configuration steps in the topside computer are required to establish a network bridge, so the position calculated by the UGPS Topside is available in QGroundControl. These steps are described in [BlueROV2 Integration Locator-U1](bluerov-integration-u1.md). Be aware that setting up a network bridge in operating systems other than Windows can be challenging. ## Alternative integration methods -* If you wish to use a [Locator-A1](../../locators/locator-a1), however you wish to avoid purchasing the full integration kit then this can be done. The Locator-A1 must be installed on the ROV and connected to the G2 Topside and then it is necessary to set-up a network bridge. The steps in these sections are relevant +* If you wish to use a [Locator-A1](../locators/locator-a1.md), however you wish to avoid purchasing the full integration kit then this can be done. The Locator-A1 must be installed on the ROV and connected to the G2 Topside and then it is necessary to set-up a network bridge. The steps in these sections are relevant * [Modifications to the BlueROV2](bluerov-integration-a1.md#modifications-to-the-bluerov2) * [Modifications to the FXTI](bluerov-integration-a1.md#modifications-to-the-fxti) with the deviation that the blue/white twisted pair between Tether Connection PCB and Binder-connector-pigtail-assembly does not need to be connected. * [Establish a network connection with a network bridge](bluerov-integration-u1.md#establish-a-network-connection-between-ugps-topside-bluerov2-and-topside-computer) * [Final steps](#final-steps-of-integration-independent-of-locator) -* If you wish to use the [Locator-U1](../../locators/locator-u1), however you wish to avoid the complication in setting up a network bridge, it is possible to integrate by using the [BlueROV2 Integration Kit](https://waterlinked.com/shop/underwater-gps-g2-bluerov2-integration-kit-103). The steps in these sections are relevant +* If you wish to use the [Locator-U1](../locators/locator-u1.md), however you wish to avoid the complication in setting up a network bridge, it is possible to integrate by using the [BlueROV2 Integration Kit](https://waterlinked.com/shop/underwater-gps-g2-bluerov2-integration-kit-103). The steps in these sections are relevant * [Mount the Locator-U1 to the BlueROV2 frame](bluerov-integration-u1.md#mount-the-locator-u1-to-the-bluerov2-frame) * [Modifications to the UGPS Topside](bluerov-integration-a1.md#modifications-to-the-ugps-topside) * [Modifications to the FXTI](bluerov-integration-a1.md#modifications-to-the-fxti) with the deviation that the green/white twisted pair between tether and Binder-connector-pigtail-assembly does not need to be connected. * [Establish a network connection with powerline communication](bluerov-integration-a1.md#establish-a-network-connection-between-ugps-topside-bluerov2-and-topside-computer) * [Final steps](#final-steps-of-integration-independent-of-locator) -* If using a [Locator-D1](../../locators/locator-d1), use the D1's cable and attach the D1 locator to the BlueROV2 in any convenient way. No further hardware integration is then required. As with the Locator-U1, +* If using a [Locator-D1](../locators/locator-d1.md), use the D1's cable and attach the D1 locator to the BlueROV2 in any convenient way. No further hardware integration is then required. As with the Locator-U1, * [Establish a network connection with a network bridge](bluerov-integration-u1.md#establish-a-network-connection-between-ugps-topside-bluerov2-and-topside-computer) * and follow the [final steps](#final-steps-of-integration-independent-of-locator) @@ -119,4 +119,4 @@ The current draw by the FXTI can exceed 500 mA when connecting the Underwater GP ## Water Linked software updates -Keep the Water Linked software [up to date](../../sw-update). The GUI should notify when an update is available, but the current version can also be checked at [192.168.2.94/#/about](http://192.168.2.94/#/about). \ No newline at end of file +Keep the Water Linked software [up to date](../sw-update.md). The GUI should notify when an update is available, but the current version can also be checked at [192.168.2.94/#/about](http://192.168.2.94/#/about). \ No newline at end of file diff --git a/docs/underwater-gps/integration/external-gps.md b/docs/underwater-gps/integration/external-gps.md index e2a085d9..9835ab0a 100644 --- a/docs/underwater-gps/integration/external-gps.md +++ b/docs/underwater-gps/integration/external-gps.md @@ -2,16 +2,16 @@ In very dynamic conditions with rapid changes in angles, the IMU will drift too much to provide sufficient heading accuracy. In this case it is recommended to implement an external compass to provide updated heading information. ## Which compass to use -If the UGPS is permanently installed on a boat, the simple solution is to use the boats compass, if it provides the possibility to output the NMEA data. Otherwise it is possible to use any portable compass that provide NMEA0185 or NMEA2000 information. +If the UGPS is permanently installed on a boat, the simple solution is to use the boats compass, if it provides the possibility to output NMEA data. Otherwise it is possible to use any portable compass that provide NMEA0185 or NMEA2000 information. ## External compass on the UGPS: -To use an external compass with the UGPS it has to be integrated in the software on your computer. As for now there are no hardware connection. +To use an external compass with the UGPS it has to be integrated in the software on your computer. As for now there are no direct hardware connection available. The needed firmware can be installed by following this procedure: !!! Note This is valid only for compasses that provides NMEA0183 -- Go to: https://github.com/waterlinked/ugps-nmea-go under “Readme” and “Installation” and “Download the application”, choose v.1.7.1 +- Go to: https://github.com/waterlinked/ugps-nmea-go under “Readme” and “Installation” and “Download the application”, choose v.1.8.0 - Download the .zip-file. - In windows: run the file. Follow the instructions you get. (It is advisable to create a folder on your computer specifically for this configuration) - In linux, in the directory you saved the file in: use chmod +x (It is advisable to create a folder on your computer specifically for this configuration) diff --git a/docs/underwater-gps/interface/ugps-led.md b/docs/underwater-gps/interface/ugps-led.md index 1747b3e6..6798d560 100644 --- a/docs/underwater-gps/interface/ugps-led.md +++ b/docs/underwater-gps/interface/ugps-led.md @@ -1,6 +1,8 @@ # LED Indicators Only the topside box and the Locator U1 has LED indicators. +Here is a broken [link](http://dennelinken.fungererikke) + ## Topside |LED name | Description | diff --git a/docs/underwater-gps/interface/warnings.md b/docs/underwater-gps/interface/warnings.md index 169fa759..a8035acb 100644 --- a/docs/underwater-gps/interface/warnings.md +++ b/docs/underwater-gps/interface/warnings.md @@ -4,7 +4,7 @@ Warnings that you might experience while using the UGPS. | Message | Solution | |---------|----------| -| No external depth received. Is it being sent correctly? | The Underwater GPS is not receiving the depth of the Locator from the ROV. This normally means software on the ROV is not working correctly. Details on how the depth is sent to the system can be found [here](../integration/api.md#providing-depth-to-system-when-using-locator-a1). | +| No external depth received. Is it being sent correctly? | The Underwater GPS is not receiving the depth of the Locator from the ROV. This normally means software on the ROV is not working correctly. Depth is sent to the system through the [API](../integration/api.md). | | No signal from Locator-U1. Have you selected the correct channel? | Verify that the Locator-U1 is powered on and that it has GPS lock (See [LED signals](../locators/locator-u1.md#led-signals) ). Verify that the same channel is selected on the settings page and the Locator rotary switch. Verify that the Locator and Receivers are in the water | | Missing GPS lock/position. Please provide me with an unobstructed view of the sky | The Underwater GPS needs GPS lock for time sync purposes. Move the Topside to another location where it has better view of the sky. | | Locator-D1 not detected. Please verify connection. | Locator-D1 selected but not detected by the Master-D1. Verify connection. | diff --git a/docs/underwater-gps/introduction.md b/docs/underwater-gps/introduction.md index 982b3fd1..5f530b19 100644 --- a/docs/underwater-gps/introduction.md +++ b/docs/underwater-gps/introduction.md @@ -13,9 +13,9 @@ The [Underwater GPS G2](https://www.waterlinked.com/underwater-gps) is a robust !!! Tip 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! -The Underwater GPS G2 system is based upon Short Baseline (SBL) acoustic positioning. A locator ([U1](../locators/locator-u1), [A1](../locators/locator-a1), or [D1](../locators/locator-d1)) is attached to the device to be positioned. It functions as a beacon, sending out acoustic signals. Near the surface, either an [antenna](antenna) containing four receivers is lowered into the water, or four loose [receivers](../receiver-d1) are lowered into the water. These listen for the beacon signals. +The Underwater GPS G2 system is based upon Short Baseline (SBL) acoustic positioning. A locator ([U1](../underwater-gps/locators/locator-u1.md), [A1](../underwater-gps/locators/locator-a1.md), or [D1](../underwater-gps/locators/locator-d1.md)) is attached to the device to be positioned. It functions as a beacon, sending out acoustic signals. Near the surface, either an [antenna](antenna.md) containing four receivers is lowered into the water, or four loose [receivers](../underwater-gps/receiver-d1.md) are lowered into the water. These listen for the beacon signals. -Time-of-flight from the locator to each of the four receivers is used in an innovative algorithm to calculate the position of the locator relative to the UGPS G2 topside unit. We refer to as the _acoustic position_. The UGPS G2 system obtains a _global position_ by combining this acoustic position with the global GPS coordinates of the topside unit. This may be provided by the topside unit's in-built GPS antenna, or, for greater precision, passed in externally by means of the UGPS G2 [API](../integration/api). This API provides output of both the acoustic and global positions calculated by the UGPS G2 system, as well as comprehensive programmatic configuration of the system. +Time-of-flight from the locator to each of the four receivers is used in an innovative algorithm to calculate the position of the locator relative to the UGPS G2 topside unit. We refer to as the _acoustic position_. The UGPS G2 system obtains a _global position_ by combining this acoustic position with the global GPS coordinates of the topside unit. This may be provided by the topside unit's in-built GPS antenna, or, for greater precision, passed in externally by means of the UGPS G2 [API](../underwater-gps/integration/api.md). This API provides output of both the acoustic and global positions calculated by the UGPS G2 system, as well as comprehensive programmatic configuration of the system. Compared to USBL systems, the UGPS G2 system has the advantage of working well in challenging environments, for example shallow water, or reflective environments such as near ship hulls, in fish cages, near harbour installations, inside water tanks, etc. One of our [FAQs](https://support.waterlinked.com/en/knowledge/why-choose-ugps-g2-over-a-usbl-system) elaborates further on this. @@ -25,7 +25,7 @@ Compared to USBL systems, the UGPS G2 system has the advantage of working well i * Quick deployment using an [antenna](antenna.md) * WiFi connectivity * Integrated global GPS antenna -* Interface supporting [BlueROV2 hardware integration](../integration/bluerov-integration) +* Interface supporting [BlueROV2 hardware integration](../underwater-gps/integration/bluerov-integration.md) * Simple and quick updating of firmware/software ## Kit content diff --git a/docs/underwater-gps/quickstart.md b/docs/underwater-gps/quickstart.md index 9a464e14..ff053cea 100644 --- a/docs/underwater-gps/quickstart.md +++ b/docs/underwater-gps/quickstart.md @@ -46,7 +46,7 @@ For alternative ways to connect to the topside, see [Networking](../underwater-g ### Locator -Attach the locator ([U1](../locators/locator-u1), [A1](../locators/locator-a1), or [D1](../locators/locator-d1)) to your vehicle. The [BlueROV2 integration guide](../integration/bluerov-integration) may be helpful if integrating an A1 or D1 locator with a vehicle tether. +Attach the locator ([U1](../underwater-gps/locators/locator-u1.md), [A1](../underwater-gps/locators/locator-a1.md), or [D1](../underwater-gps/locators/locator-d1.md)) to your vehicle. The [BlueROV2 integration guide](../underwater-gps/integration/bluerov-integration.md) may be helpful if integrating an A1 or D1 locator with a vehicle tether. If using an A1 or D1 locator, connect it to the 'Locator' bulkhead on the UGPS G2 topside box. The U1 connector is wireless, which means that this step can be omitted. @@ -54,7 +54,7 @@ If using an A1 or D1 locator, connect it to the 'Locator' bulkhead on the UGPS G ### Antenna -Unfold the [antenna](../../antenna) and lock the mast straight using the latches on the folding joints. Avoid the cable being pinched at the joints. Secure the three arms in place using the thumb screw. Place the antenna in water at the desired location. Secure the Antenna using the RAM Mount components included with the antenna. +Unfold the [antenna](../underwater-gps/antenna.md) and lock the mast straight using the latches on the folding joints. Avoid the cable being pinched at the joints. Secure the three arms in place using the thumb screw. Place the antenna in water at the desired location. Secure the Antenna using the RAM Mount components included with the antenna. Connect the antenna to the bulkhead marked 'Receiver 1/Antenna' on the UGPS G2 topside box (see the above picture). @@ -63,21 +63,21 @@ Connect the antenna to the bulkhead marked 'Receiver 1/Antenna' on the UGPS G2 t ### Loose receivers -Before deploying the [receivers](../../receiver-d1) in the water, add a piece of tape to each receiver cable at the desired depth, to make [configuration](#configure-antennareceiver-placement-and-search-range) easier. Place the receivers in the water at the desired location, and connect one to each of the four bulkheads 'Receiver 1', 'Receiver 2', 'Receiver 3', and 'Receiver 4' of the UGPS G2 topside box (see the above picture). +Before deploying the [receivers](../underwater-gps/receiver-d1.md) in the water, add a piece of tape to each receiver cable at the desired depth, to make [configuration](#configure-antennareceiver-placement-and-search-range) easier. Place the receivers in the water at the desired location, and connect one to each of the four bulkheads 'Receiver 1', 'Receiver 2', 'Receiver 3', and 'Receiver 4' of the UGPS G2 topside box (see the above picture). !!! Tip Add a weight just above each receiver to improve stability in the water. ## Select locator and channel in the GUI -Select the correct locator type in the [GUI settings](../gui/settings/), and choose which channel to listen on. Channel 2 is the default. If using a [Locator-U1](../locators/locator-u1/), ensure that its channel (set by completely unscrewing the lid and turning the dial inside) is set to the same channel as you configure in the GUI. +Select the correct locator type in the [GUI settings](../underwater-gps/interface/ugps-gui.md#settings), and choose which channel to listen on. Channel 2 is the default. If using a [Locator-U1](../underwater-gps/locators/locator-u1.md), ensure that its channel (set by completely unscrewing the lid and turning the dial inside) is set to the same channel as you configure in the GUI. !!! Note - If you are using the Locator-A1, depth information needs to be provided to the topside unit by means of the UGPS [API](../integration/api). You can ignore this if following the [BlueROV2 integration guide](../integration/bluerov-integration). + If you are using the Locator-A1, depth information needs to be provided to the topside unit by means of the UGPS [API](../underwater-gps/integration/api.md). You can ignore this if following the [BlueROV2 integration guide](../underwater-gps/integration/bluerov-integration.md). ## Configure antenna/receiver placement and search range -Provide the correct placement of the antenna/receivers relative to the topside box in the [GUI settings](../gui/settings/), and, if using an antenna, specify if it has been rotated from the default indicated in the GUI. +Provide the correct placement of the antenna/receivers relative to the topside box in the [GUI settings](../underwater-gps/interface/ugps-gui.md#settings), and, if using an antenna, specify if it has been rotated from the default indicated in the GUI. Specifically, for the antenna, enter the position and optionally the rotational angle manually under **Advanced settings**. diff --git a/docs/underwater-gps/reference-frames.md b/docs/underwater-gps/reference-frames.md index 7e8bcde6..f29831b8 100644 --- a/docs/underwater-gps/reference-frames.md +++ b/docs/underwater-gps/reference-frames.md @@ -40,4 +40,4 @@ The z-coordinate of the acoustic frame is always depth relative to the sea surfa The default origin is a point on the topside housing, but can be taken to be anywhere: it is entirely defined by the positioning of the antenna/receivers with respect to it. If using an antenna, it may help intuitively to take the origin to be the base of the antenna, which can be achieved by setting both *Distance to topside housing* fields to 0 under *Baseline -> Antenna configuration -> Advanced settings*. !!! Note - The axes of the acoustic frame in the first version of UGPS, the [Explorer Kit](../../explorer-kit/quickstart), were slightly different: it was the y-axis which was aligned with the forward direction of the topside housing, and the x-axis which was to the 'east' of this. + The axes of the acoustic frame in the first version of UGPS, the [Explorer Kit](../explorer-kit/quickstart.md), were slightly different: it was the y-axis which was aligned with the forward direction of the topside housing, and the x-axis which was to the 'east' of this. diff --git a/docs/underwater-gps/sw-update.md b/docs/underwater-gps/sw-update.md index 7f30bbf2..35fee7e0 100644 --- a/docs/underwater-gps/sw-update.md +++ b/docs/underwater-gps/sw-update.md @@ -4,9 +4,9 @@ It is recommended to always run the latest UGPS G2 software where possible. The ## Automatic software update -The G2's [GUI](../gui/position) automatically checks and indicates if a new software version is available. +The G2's [GUI](./interface/ugps-gui.md) automatically checks and indicates if a new software version is available. -* [Connect](../network-settings) the G2 topside unit over ethernet or wifi to a network connected to the internet. If on a personal computer, it may be necessary to make a network bridge between a network interface which has access to the internet and the interface through which the G2 topside is connected. +* [Connect](./network-settings.md) the G2 topside unit over ethernet or wifi to a network connected to the internet. If on a personal computer, it may be necessary to make a network bridge between a network interface which has access to the internet and the interface through which the G2 topside is connected. * Go to http://[IP_ADDRESS_OF_THE_G2_TOPSIDE]:9000 in a web browser. * The GUI will automatically check if there is a new version available, and if so, initiate installation of it with a single click. @@ -14,7 +14,7 @@ The G2's [GUI](../gui/position) automatically checks and indicates if a new soft If it is not possible to connect the G2 topside to the internet, one can proceed as follows. -* Find the current version and chip ID of the G2 topside unit at *Menu -> About* in the [GUI](../gui/position). +* Find the current version and chip ID of the G2 topside unit at *Menu -> About* in the [GUI](./interface/ugps-gui.md). * Manually download an update package (`.wlup`) from the [update server](https://update.waterlinked.com/) using the chip ID. * Verify if the downloaded version is newer than the currently running version. * Navigate to http://[IP_ADDRESS_OF_THE_G2_TOPSIDE]:9000 in a web browser. diff --git a/docs/underwater-gps/ugps-sys-setup.md b/docs/underwater-gps/ugps-sys-setup.md index 52fb9818..bdc2916b 100644 --- a/docs/underwater-gps/ugps-sys-setup.md +++ b/docs/underwater-gps/ugps-sys-setup.md @@ -15,9 +15,9 @@ The antenna can be placed anywhere up to 10m from the topside housing (limited b | | | | ------------------- | :------------------- | -| **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. +| **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](../underwater-gps/reference-frames.md#global-frame) 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 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.md#acoustic-frame) and [global](../underwater-gps/reference-frames.md#global-frame) positions may be incorrect. | | **Antenna stability** | Secure the antenna tightly to the vessel using the provided Ram Mount. |
@@ -31,7 +31,7 @@ The antenna can be placed anywhere up to 10m from the topside housing (limited b ## 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. See[System Configuration](../underwater-gps/ugps-sysconfig.md#basline-settings) +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. See [System Configuration](../underwater-gps/ugps-sysconfig.md#basline-settings) | | | | ------------------- | :------------------- | @@ -52,7 +52,7 @@ The figure below indicates a typical loose receiver configuration when the topsi ## Locator setup -Select the type of locator ([U1](../underwater-gps/locators/locator-u1.md), [A1](../underwater-gps/locators/locator-a1), or [D1](../underwater-gps/locators/locator-d1)) which you are using, and which [channel](#channel-overview) you wish to use. +Select the type of locator ([U1](../underwater-gps/locators/locator-u1.md), [A1](../underwater-gps/locators/locator-a1.md), or [D1](../underwater-gps/locators/locator-d1.md)) which you are using, and which [channel](../underwater-gps/ugps-sysconfig.md#channel-overview) you wish to use. No matter what locator that is in use, it always need to be placed within line of sight from the receivers. This will in most cases be somewere on top of the unit that is to be tracked. @@ -65,12 +65,12 @@ As the U1 is a wireless locator it can easily be mounted on your vehicle with th ### Locator A1 The A1 needs to be physically connected to the G2 Topside, either directly or through a full system integration.
-For wiring details of the A1, se [locator-A1](../underwater-gps/locators/locator-a1.md). +For wiring details of the A1, se [locator-A1][A1](../underwater-gps/locators/locator-a1.md). If you are using the A1 on a Bluerov, see [Bluerov integration](./integration/bluerov-integration-a1.md) !!! 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). + If using the [A1](../underwater-gps/locators/locator-a1.md) locator, the depth of the locator must be inputted by means of the UGPS [API](../underwater-gps/integration/api.md). ### Locator D1 The D1 comes with 50m integrated cable that is coupled directly into the topside box. diff --git a/docs/underwater-gps/ugps-sysconfig.md b/docs/underwater-gps/ugps-sysconfig.md index 068d4afc..c49526f9 100644 --- a/docs/underwater-gps/ugps-sysconfig.md +++ b/docs/underwater-gps/ugps-sysconfig.md @@ -22,13 +22,13 @@ Cofigurations of the topside and locator settings is conducted in [Settings](../ ### Locator settings -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. +Select the type of locator ([U1](./locators/locator-u1.md), [A1](./locators/locator-a1.md), or [D1](./locators/locator-d1.md)) 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). + If using the [U1](./locators/locator-u1.md) 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). + If using the [A1](./locators/locator-a1.md) locator, the depth of the locator must be inputted by means of the UGPS [API](./integration/api.md). #### Channel overview @@ -46,18 +46,24 @@ The frequency bands of the available channels are as follows. Lower frequency ty ### Topside settings - The default source for the topside position and heading is *On-board*. This configuration should be chosen if the topside is located in any dynamic environment, like on a boat or similar. -!!! Note - 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 exteranl input of heading data (e.g. from a GPS compass) as well as global position data. An external device will likely be more accurate than the topside unit's built-in GPS receiver and IMU. For a thorough description on how to do this, see [External Compass](../underwater-gps/integration/external-gps.md) - 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) + +#### IMU calibration +The link "Onboard IMU calibration" takes you to a window where you can reset the gyros and set the heading manually. +![IMU calibration](../img/ugps-img/ugps-imu-calibration.png) +It is advisable to reset the gyros before every use. Place the topside on a static horisontal area and press "Reset gyros. + +The topsides heading has to be set manually. Use a decent compass and enter the heading in the heading filed, and press "set current heading". + +!!! Note + When you are using On-board positioning the heading has to be set periodically, as the IMU will drift over time. + +For best performance on boats or similar, with a moving topside unit, we recommend to use an exteranl input of heading data (e.g. from a GPS compass) as well as global position data. An external device will likely be more accurate than the topside unit's built-in GPS receiver and IMU. For a thorough description on how to do this, see [External Compass](../underwater-gps/integration/external-gps.md) #### 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/install-hooks.sh b/install-hooks.sh new file mode 100755 index 00000000..25887b78 --- /dev/null +++ b/install-hooks.sh @@ -0,0 +1,4 @@ +#!/bin/bash +mkdir -p .git/hooks +ln -sf check-links.sh .git/hooks/pre-push +echo "Pre-push hook installed!" \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index c9b4a423..7e17494b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ site_name: Documentation -site_url: "https://waterlinked.github.io" -repo_url: https://github.com/waterlinked/waterlinked.github.io +site_url: https://docs.waterlinked.com +repo_url: https://github.com/waterlinked/docs theme: name: material theme_dir: docstheme/material @@ -70,7 +70,7 @@ nav: - Baseline: - Antenna: underwater-gps/antenna.md - Receiver-D1: underwater-gps/receiver-d1.md - - Locator: + - Locators: - Locator-A1: underwater-gps/locators/locator-a1.md - Locator-D1: underwater-gps/locators/locator-d1.md - Locator-U1: underwater-gps/locators/locator-u1.md diff --git a/requirements.txt b/requirements.txt index b5917eb5..0342ff1a 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ mkdocs==1.2.3 mkdocs-material==7.2.0 jinja2<3.1.0 +LinkChecker==10.3.0