bluerobotics / ardusub-zola Goto Github PK

Would be useful if each ArduSub version specifies the MAVLink messages it supports. That should avoid confusing issues where someone tries to send a message in the normal MAVLink spec, but it doesn't exist, or the spec has new parameters that haven't yet been implemented.

Would likely be quite a bit of work to set up initially, but shouldn't be too bad to maintain beyond that, and would be helpful for people wanting to use MAVLink communication to know what is definitely supported.

Partially completed in #52:

• lists messages and links to firmware source code, but
• we don't yet have verification that the implementations are functional and/or complete
• it'd be nice if the code links were to a specific line/section, rather than just the file that declares/registers support

Other firmwares already have this, although for some reason they're not tied to the firmware versions.

• Should be based on the parsing script
• Likely need to create an emit_md.py, similar to the existing emit_rst.py
  • May need to add some exception handling if older versions don't have all the same files
  • May be worth linking to adding a new message dev docs, and UAV Log Viewer docs, although that may make more sense in a more general overview of logging / DataFlash logs
  • submit PR to ArduPilot repo
    • ArduPilot/ardupilot#23680
    • ArduPilot/ardupilot#23681

Relevant context in bluerobotics/BlueOS#1444.

It's already possible (so it'd be nice to document how), but the user experience will be significantly improved once BlueOS has

1. an active indicator of whether internet is connected (bluerobotics/BlueOS#1057), and
2. internet network testing built in (bluerobotics/BlueOS#448)

BlueOS 1.1 creates a hotspot that can be connected to if no other network connection is made on startup. This can be helpful for people connecting to BlueOS without an ethernet connection, like for use on a boat.

This is already documented in Advanced Usage, but should at least be mentioned in Getting Started as well. This will likely require re-ordering the Network Configuration section to only apply when connecting via ethernet, or if you want to pass through telemetry / connect to a GCS.

Should maybe be done together with #59, but not essential.

Ask Elisa for details

Versioned docs will likely be easiest to manage if the submodules for each version are automatically updated with the branch they're on.

Potentially possible with a github hook, or maybe even possible to make the submodule auto-track a branch instead of a commit.

We currently mention that joystick buttons can be assigned to Actions, but don't specify which actions are available or how they work / will be customisable in future.

• Forum thread for context
• Ideally we can also get MAVLink mode working for Sub >= 4.1, and document that :-)

https://discord.com/channels/1135646343776456765/1135646344569168027/1172117286497296515

• merged feature: bluerobotics/BlueOS#1440
• initial process docs (internal link)
• Should be linked to from extensions docs on theming, but is technically a user feature

Most of those links no longer work, because

1. A lot of the content is now in submodules, which GitHub doesn't use the folder names of for source file urls
2. The directory structure of https://blueos.cloud/docs is not the same as that for https://docs.bluerobotics.com/ardusub-zola, and currently those links are generated using the build directory structure rather than that of the source
   • Ideally we could link straight to the appropriate source branch for the version in question

As an alternative for the linked instructions, which are all GUI-oriented, we can add a command-line approach:

• Linux:

ip addr show  # To see the interface name
sudo ip a add 192.168.2.1/24 dev <interface>  # To set the interface ip

• Mac:

networksetup -listallnetworkservices
networksetup -setmanual <interface> 192.168.2.1 255.255.255.0 192.168.2.1

• Windows (cmd):

netsh interface ipv4 show config
netsh interface ipv4 set address name=<interface> static 192.168.2.1 255.255.255.0 192.168.2.1

I went looking for some docs for this, and apparently it's "self describing".

This forum comment was the best attempt at an explanation I could find, and pretty much everything else just recommended looking at implementations (like Pymavlink's DFReader.py).

The "adding a message" link that is already included in our docs describes the parameters for ArduPilot's AP::logger().Write method, which roughly describes what should end up in the file, but not how it's packed in as bits to the binary logs (which makes sense since AP::logger is generic to multiple logging backends).

It would be good if we could have a more cohesive place to link to that describes the file format, even if that means writing the relevant docs for ArduPilot and then linking to them.

• https://ceruleansonar.com/pages/omniscan-product-page
  • in an ROV context, the ForwardScan makes the most sense
  • Sidescan makes sense to cover if we want to also account for boats (although then we should also cover other sidescans)
• also correct "Companion Computer" to "Onboard Computer"

• Fill out the development process section
• Refine and properly integrate development-process.mermaid
• Include a section on optimisation approaches, mentioning
  • Docker's re-use of shared image bases (e.g. encourage developers to use the same bases as other extensions where possible)
  • Tools like dive (for image introspection)
• Complete the accessing and (persistently) modifying an installed extension section

Brought up by @Williangalvani as part of feedback for #100

• Versioned BlueOS docs will be hosted at blueos.cloud/docs (via BlueOS-deploy branch (WIP))
• Versioned ArduSub docs will be hosted at ardusub.com (via a new ArduSub-deploy branch perhaps?)
  • Requires completion of content transfer from the existing ardusub-gitbook repo, per
    • #32
    • #33
    • #34
    • #40
    • etc
• In future Cockpit docs will be hosted at blueos.cloud/cockpit/docs
• Docs for a specific version of BlueOS will be made available as a BlueOS extension (where the extension version corresponds to the version of BlueOS it documents)
• ArduSub docs will also be made available locally in BlueOS, likely via some form of extension
  • Not sure yet if it's best to provide all versions, or just a specific version per extension version like for BlueOS
  • Not sure yet how best to handle docs for other ArduPilot firmwares
    • Should they be bundled with the ArduSub ones on a per-version basis?
    • Should they be separated by vehicle type?
    • Should there be a single "ArduPilot Docs Manager" extension that allows selecting firmware types and versions to download / remove docs for?
      • This seems likely to be the best user experience, but is likely also extra development effort

• Some of the docs (e.g. hardware/integration) are shared amongst multiple targets, so should be refactored into their own branches and pulled in as appropriate via submodules (to avoid needing to maintain them separately)
• We may also want to refactor the zola templates into a submodule for the same reason

Existing documentation just mentions that the page exists and how to use it.

It should also include a list of available APIs and what kind of thing(s) they can be used for (e.g. commander API could be useful (internal link)).

Important for #1

• Ideally should have multiple search 'modes'/scopes:

1. full docs search
   • search the whole website, including across all versions of each software
   • preferable if the search index can be preferentially searched with later versions of software first
   • somehow need to avoid the same page coming up different times from multiple versions (possibly have a custom index for this search mode which just includes the latest version of each page name??)
2. search the docs of a specified version of a software (e.g. search only the QGC 4.1.4 docs)
   • can hopefully use just a subset of the default full index, branched out from just the relevant version folder of the specified software (not sure if that's how search indexes work, so may be required to create separate indexes for each version of each software)
3. [optional] search multiple versions of a specific software
   • could be all versions (likely easiest), or could be a (filtered?) subset (e.g. companion-1.0.*)
   • if we only want to support all, this is basically the same as 2. but from the parent/section folder of that software (if it's possible to search just a branch of an index then this is basically free, and would just need to be enabled)
   • kind of has the same issue as 1. for several (possibly identical) versions of the same page, but likely harder to deal with (maybe that's just a cost of using this mode)

• If modes are available, need the UI to use them (may need input/help from @rafaellehmkuhl)
  • we're thinking something like GitHub's search bar, which allows easily selecting which scope to use
    

Companion-docker pages don't have a page switcher at the moment. Possibly just because it's so nested, but would be good to figure out a switcher, especially once the other docs start being properly transferred over.

https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls

There is no clear way to identify the Getting Started is from 1.0 or 1.1

• video troubleshooting is a high priority
• would be good to walk through a general issue checking, log fetching, and support process

The correct may be to link to: https://docs.bluerobotics.com/ardusub-zola/software/onboard/BlueOS-1.1/advanced-usage/#wifi-hotspot-network-management

To have a single source of true.

• Currently versioned sections have the version number in the section display, but do not have an indication on the pages whether the documentation being looked at is for a current/outdated/beta version, or which version number is being looked at
  • The only current version indication is in the URL
• Somewhat related to #1

Important for #1

Traditionally there have been support issues caused by unclear/nonexistent documentation of which software versions are compatible with specific versions of other software (e.g. QGC with ArduSub)

• We need to document version compatibilities of our different softwares

  • should be stored in some sort of globally accessible form, so it can be used for auto-generated displays for each software without maintenance overhead from data duplication
  • zola may have some sort of global metadata construct built in, but if not it should be possible to use a markdown file in the static folder with the versioning info in the TOML metadata, or a json/TOML file if necessary

• Visualisation requires a meaningful and clear UI

  • may be relevant inspiration to consider Rust's dependencies list in their version selector
    

I couldn't manage to figure out how to get a custom favicon (e.g. the one from ardusub-gitbook) to work here.

We should update the documentation to say that the client should communicate with the server at least every 10 seconds to avoid loosing connection.

• Relevant PR: bluerobotics/BlueOS#1419
• Should be linked to from extensions docs on theming, but is technically a user feature (similar to #66)
• Custom stylesheet location: userdata/styles/theme_style.css
  • can access/modify via the File Browser
  • may need to create folders/files if they don't already exist
  • the colors update at the next page refresh after the file is saved
• Structure:

  :root {
      --v-primary-base: #c0ffee !important;
      --v-info-base: forestgreen !important;
  }

  • specified using css colors
    • colorhexa may be useful for palette creation / accessibility checking
  • the !important tag is required for a color to properly override its default
• Most relevant colors to change for a re-skin:
  • --v-primary-base
    • controls header bar, sidebar highlights, and submit button colors
    • best to set a color with lightness ~50%, for good compatibility with both light and dark viewing modes
  • --v-info-base
    • info boxes
    • generally set to the same as --v-primary-base
  • --v-error-base
    • notification bell and pirate mode icon colors
• Others that might be of interest:
  • --v-background-base
  • --v-surface-base
  • --v-secondary-base
  • --v-success-base
  • --v-warning-base

• macOS: Already has native mDNS support through Bonjour. No additional installation is required.
• Windows: Starting from Windows 10, native mDNS support is included in the operating system. For older Windows version, make sure to install Bonjour.
• Linux: Each OS flavor has different support for mDNS, the quickest way to check is running avahi-discover on the terminal to see if the avahi service is running. For reference: Debian, Arch.

why is that required, why that exist

Not sure if it's best always displayed or only on hover, but we should turn on automatic anchor link insertion and make the symbol either relevant to the project/software, or something generic that doesn't look terrible (like a #).

Use github api to provide link to latest beta and latest stable release

I did:
sudo pacman -S zola
git submodule update --init --recursive
zola serve -i 0.0.0.0 (testing from another computer)

But I apparently got no css. am I missing something?

all releases: https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#list-releases
latest: https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#get-the-latest-release

Bringing together bluerobotics/ardusub-gitbook#227 and bluerobotics/ardusub-gitbook#229, each software will be documented in its own set of branches (by semi-major version, e.g. ardusub-4.0), with tags used for minor versions (ardusub-4.0.3), and submodules used within the main branch site content to link to each version. A suitable switching mechanism will need to be made, which should be helped by Zola's ability to apply things to all pages in a given section.

• Electronic Switches should cover that non-5V supplies are possible for the switched side
• Add magnetic (reed) switches to the "electrical switch" section (brought up here)
• Split out pH sensors in the "other sensors" section
• Split out conductivity sensors in the "other sensors" section
• Link to relevant ArduSub sections (per here; reliant on #40)

Currently just links to the old ardusub.com page for it, which is unnecessarily external, and uses outdated operating system versions.

• SeaView - full system
• DWE - converter board

Would be useful if each ArduSub version specifies the parameters it actually uses. That should avoid confusing issues where someone tries to set a documented parameter, but it doesn't do anything because it exists but isn't used in the firmware.

Would likely be quite a bit of work to determine which existing parameters are unused, but shouldn't be too bad to maintain beyond that, and would be helpful for people wanting to use ArduSub vehicles to know what is definitely supported.

• Document specifications for parameters with some form of implementation in the source code (#52)
• Determine which parameters are unused
• Create more intuitive docs based on just the used parameters

Our docs and software are currently somewhat difficult to approach for developers who would like to help us improve. With a new docs system it's important to document how it's structured (see #1) and run, but simultaneously it's useful to provide information on how to contribute to the softwares that we're documenting.

Relevant Links

• https://github.com/bluerobotics/software-guidelines
• https://ardupilot.org/dev/docs/contributing.html
• https://github.com/ardupilot/ardupilot#top-contributors / https://github.com/ardupilot/ardupilot#how-to-get-involved
• https://dev.qgroundcontrol.com/master/en/contribute/
• https://github.com/mavlink/qgroundcontrol/blob/master/CONTRIBUTING.md
• https://mavlink.io/en/contributing/contributing.html