1.4 initial docs

content/development/core/index.md

@@ -64,10 +64,10 @@ The services built into BlueOS are as follows:
 
 | Service Name | Purpose | Webpage(s)? | Tool(s)? | Frontend? |
 | --- | --- | --- | --- | --- |
-| [ArduPilot Manager](https://github.com/bluerobotics/BlueOS/tree/master/core/services/ardupilot_manager) | Handles ArduPilot firmware connection, flashing, and MAVLink routing. | - [Autopilot Firmware](../../usage/advanced/#autopilot-firmware)<br> - [MAVLink Endpoints](../../usage/advanced/#mavlink-endpoints) | - [tools/ardupilot_tools](https://github.com/bluerobotics/BlueOS/tree/master/core/tools/ardupilot_tools) | - [views/Autopilot.vue](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/views/Autopilot.vue)<br> - [views/EndpointView.vue](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/views/EndpointView.vue)<br> - [components/autopilot](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/components/autopilot)<br> - [store/autopilot.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/store/autopilot.ts)<br> - [store/autopilot_manager.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/store/autopilot_manager.ts)<br> - [types/autopilot.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/types/autopilot.ts)<br> - [types/autopilot/parameter*.ts](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/types/autopilot) |
+| [ArduPilot Manager](https://github.com/bluerobotics/BlueOS/tree/master/core/services/ardupilot_manager) | Handles ArduPilot firmware connection, flashing, and MAVLink routing. | - [Autopilot Firmware](../../usage/advanced/#autopilot-firmware)<br> - [MAVLink Endpoints](../../usage/advanced/#mavlink-endpoints) | - [tools/ardupilot_tools](https://github.com/bluerobotics/BlueOS/tree/master/core/tools/ardupilot_tools)<br> - [tools/zenoh](https://github.com/bluerobotics/BlueOS/tree/master/core/tools/zenoh) | - [views/Autopilot.vue](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/views/Autopilot.vue)<br> - [views/EndpointView.vue](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/views/EndpointView.vue)<br> - [components/autopilot](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/components/autopilot)<br> - [store/autopilot.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/store/autopilot.ts)<br> - [store/autopilot_manager.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/store/autopilot_manager.ts)<br> - [types/autopilot.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/types/autopilot.ts)<br> - [types/autopilot/parameter*.ts](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/types/autopilot) |
 | Available Services | Finds and lists available HTTP servers and their API documentation. | - [Available Services](../../usage/advanced/#available-services) | -- | - [views/AvailableServicesView.vue](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/views/AvailableServicesView.vue)<br> - [components/scanner](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/components/scanner)<br> - [store/servicesScanner.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/store/servicesScanner.ts) |
 | [Bag of Holding](https://github.com/bluerobotics/BlueOS/tree/master/core/services/bag_of_holding) | A simple key-value storage API, used for storing and retrieving data as JSON objects through HTTP requests. | - [Bag Editor](../../usage/advanced/#bag-editor) | -- | - [views/BagEditorView.vue](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/views/BagEditorView.vue)<br> - [store/bag.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/store/bag.ts) |
-| [Beacon Service](https://github.com/bluerobotics/BlueOS/tree/master/core/services/beacon) | Handles mDNS domain advertisement and local network vehicle identification | -- | - [tools/dnsmasq](https://github.com/bluerobotics/BlueOS/tree/master/core/tools/dnsmasq) | - [components/beacon](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/components/beacon)<br> - [store/beacon.ts](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/store/beacon.ts)<br> - [types/beacon.ts](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/types/beacon.ts) |
+| [Beacon Service](https://github.com/bluerobotics/BlueOS/tree/master/core/services/beacon) | Handles mDNS domain advertisement and local network vehicle identification | -- | -- | - [components/beacon](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/components/beacon)<br> - [store/beacon.ts](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/store/beacon.ts)<br> - [types/beacon.ts](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/types/beacon.ts) |
 | BlueOS | The main BlueOS interface | - [Dashboard](../../usage/advanced/#dashboard) | - [tools/nginx](https://github.com/bluerobotics/BlueOS/tree/master/core/tools/nginx) | - [views/MainView.vue](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/views/MainView.vue)<br> - [components/app](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/components/app)<br> - [components/notifications](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/components/notifications)<br> - [store/frontend.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/store/frontend.ts)<br> - [store/settings.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/store/settings.ts)<br> - [types/notifications.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/types/notifications.ts) |
 | [Bridget](https://github.com/bluerobotics/BlueOS/tree/master/core/services/bridget) | Manages serial bridges. | - [Serial Bridges](../../usage/advanced/#serial-bridges) | - [tools/bridges](https://github.com/bluerobotics/BlueOS/tree/master/core/tools/bridges) | - [views/BridgesView.vue](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/views/BridgesView.vue)<br> - [components/bridges](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/components/bridges)<br> - [store/bridget.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/store/bridget.ts)<br> - [types/bridges.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/types/bridges.ts) |
 | [Cable-guy](https://github.com/bluerobotics/BlueOS/tree/master/core/services/cable_guy) | Manages ethernet IP(s) and DHCP server configuration | -- | -- | - [components/ethernet](https://github.com/bluerobotics/BlueOS/tree/master/core/frontend/src/components/ethernet)<br> - [store/ethernet.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/store/ethernet.ts)<br> - [types/ethernet.ts](https://github.com/bluerobotics/BlueOS/blob/master/core/frontend/src/types/ethernet.ts) |

content/development/extensions/index.md

@@ -267,10 +267,20 @@ To do so requires the Extension to run a HTTP server[^1], at which it must serve
    - The official URL for the extension
 - `"api"`
    - The official URL for the extension's API
+- `"extra_query"` (optional)
+   - A string of extra query parameters to include when the extension is accessed through the sidebar
 - `"avoid_iframes"` (optional)
    - Boolean (`true`/`false`) specifying whether to avoid embedding the extension interface in an iframe.
 - `"new_page"` (optional)
    - Boolean (`true`/`false`) specifying whether to open the extension in a new page instead of in a BlueOS frame
+- `"works_in_relative_paths"` (optional)
+   - Boolean (`true`/`false`) specifying whether the extension can be served at an arbitrary base URL
+     (i.e. it does not access its resources using absolute paths)
+   - This is required for extensions to be accessible remotely (e.g. via a cloud proxy), and is recommended for all extensions
+   - Makes the extension available at `/extensionv2/<sanitized_name>/`
+      - The sanitized name is the `name` field in lowercase, with all non alphanumeric characters removed
+- `"extras"` (optional)
+   - A dictionary of string keys and values, intended for convenience use (e.g. for simplifying integration with other extensions)
 
 As an example:
 ```json

content/usage/advanced/index.md

@@ -11,7 +11,7 @@ draft = false
 lead = ''
 toc = true
 top = false
-link_base = "https://github.com/bluerobotics/BlueOS/tree/1.3/core"
+link_base = "https://github.com/bluerobotics/BlueOS/tree/master/core"
 +++
 
 ## General Information
@@ -42,6 +42,14 @@ For clarity of this documentation, any pages that are extended by (or only avail
 in) Pirate Mode are shown in [dark mode](#display-mode-management), and described
 with grey text.
 
+### Safe Mode
+
+Operating a vehicle involves some risks to both the vehicle and the operator. When
+BlueOS detects that the vehicle is armed it engages safe mode, which requires explicit
+confirmation to access functionality like BlueOS and autopilot firmware updates.
+
+{{ easy_image(src="safe-mode", width="400") }} 
+
 ### Interface Overview
 {{ service(service="blueos-frontend", port=80) }}
 
@@ -55,9 +63,14 @@ right clicking and selecting the desired widgets to display. Widgets can be reor
 by clicking and dragging.
 
 There are currently widgets available for displaying the CPU and Disk (storage) usage
-as percentages, which are periodically updated during operation.
+as percentages, as well as local network usage, which are periodically updated during
+operation:
+
+{{ easy_image(src="widgets", width=350) }}
+
+There is also a prominent indicator when the vehicle is in [Safe Mode](#safe-mode):
 
-{{ easy_image(src="widgets", width=300) }}
+{{ easy_image(src="safe-mode-widget", width=100) }}
 
 ---
 
@@ -76,6 +89,7 @@ For each interface, choose between:
 - A static IP
 - A dynamic IP
 - A DHCP server
+   - Serves the lease range 101-200 `(New in 1.4)`
 
 It is possible to have multiple connections per interface type.
 
@@ -144,6 +158,9 @@ skull-and-crossbones icon
    - On click shows onboard computer temperature, voltage, and current usage
 - GPS icon displays the number of visible satellites if a GPS is detected
    - On click shows the current GPS position estimate, and some GPS health/status values
+   - Can show status for two connected GPS systems, and GPS-based yaw if both have valid position fixes `(New in 1.4)`
+{{ easy_image(src="gps-status", width=300, center=true) }}
+
 - Additional warning icons appear if a problem is detected on the onboard computer:
    - High disk usage
    - CPU overheating
@@ -205,6 +222,10 @@ Submit feedback about BlueOS via:
 - [Issues on the GitHub repository](https://github.com/bluerobotics/BlueOS/issues)
    - allows easily tracking changes, 
 and notification when complete/fixed
+- Report form submissions
+   - Can be submitted at any time, and get sent to the developers when the
+     [control station computer](@/integrations/hardware/required/control-computer/index.md)
+     next connects to the internet
 - Posts on [the Blue Robotics forum](https://discuss.bluerobotics.com)
    - allows easy discussion with the community
 
@@ -267,6 +288,10 @@ autopilot.
 The Autopilot Parameters page allows checking and changing the autopilot's configuration.
 
 - Includes fuzzy searching of names and descriptions, to help find relevant parameters
+- Parameter descriptions can be overridden by including a `metatdata_override.json` file
+in the `userdata` folder in the [File Browser](#file-browser) `(New in 1.4)`
+   - Parameter files can be generated from an ArduPilot firmware using 
+     [this tool](https://github.com/ArduPilot/ardupilot/blob/master/Tools/autotest/param_metadata/param_parse.py)
 - Allows loading parameters from a file, and saving the current parameters to a file
 
 {{ easy_image(src="parameters" width=600) }}
@@ -286,7 +311,7 @@ and where relevant
 - its API documentation (in a live-testable form)
 - the current API version
 
-The individual services are documented [in the development documentation](../development/core/#services).
+The individual services are documented [in the development documentation](@/development/core/index.md#services).
 {% end %}
 {{ easy_image(src="available-services", width=600, class="pirate") }}
 
@@ -371,8 +396,21 @@ endpoints for MAVLink-based services and programs to access.
 {% end %}
 {{ easy_image(src="mavlink-endpoints", width=600, class="pirate") }}
 {% pirate() %}
-- It is possible to switch from the default MAVLinkRouter to MAVP2P `(New in 1.2)`
-   - This may use more CPU, so is only recommended if your system is having frequent "GCS Heartbeat Lost" errors
+- The default MAVLinkRouter can be switched to instead use:
+   - [MAVP2P](https://github.com/bluenviron/mavp2p) `(New in 1.2)`
+      - This may use more CPU, so is only recommended if your system is having frequent "GCS Heartbeat Lost" errors
+      - Does not yet support generating telemetry log files
+   - [MAVLinkServer](https://github.com/bluerobotics/mavlink-server) `(New in 1.4)`
+      - All messages are forwarded to all clients (does not attempt to filter by component/target IDs)
+         - Endpoints do not have behavioural differences (e.g. UDP vs TCP, client vs server)
+      - Allows websocket and cross-websocket communication, with a 
+        [MAVLink2REST](https://github.com/mavlink/mavlink2rest?tab=readme-ov-file#api)-compatible API
+      - Logs all messages passed through, instead of just those from the vehicle
+         - Logs can be visualised and downloaded through the [Log Browser](#log-browser)
+      - Provides a detailed debugging interface (accessed via [Available Services](#available-services)):
+{% end %}
+{{ easy_image(src="mavlink-server", width=550, class="pirate") }}
+{% pirate() %}
 - Endpoints intended for internal BlueOS operations are configured to the
 loopback IP `127.0.0.1`
 - Server endpoints for external use are configured to the localhost IP
@@ -382,7 +420,7 @@ loopback IP `127.0.0.1`
    - e.g. `192.168.2.1` for connecting to a UDP server on the [Control Station Computer](@/integrations/hardware/required/control-computer/index.md)
 - Client endpoints seem to operate more stably than server ones
 - Unprotected endpoints can be removed or disabled
-- Modifying an endpoint is not possible - a new one must be created instead
+- New endpoints can be created, or existing unprotected ones can be modified
    - e.g. some users may wish to set up a UDP endpoint for connecting to with
    Pymavlink from the surface:
 {% end %}
@@ -391,7 +429,7 @@ loopback IP `127.0.0.1`
 {% pirate() %}
 ### MAVLink Inspector
 {% end %}
-{{ service(service="MAVLink2Rest", port=6040, link="https://github.com/patrickelectric/mavlink2rest") }}
+{{ service(service="MAVLink2Rest", port=6040, link="https://github.com/mavlink/mavlink2rest") }}
 {% pirate() %}
 
 The MAVLink Inspector provides real-time access to the MAVLink messages being
@@ -582,13 +620,16 @@ including failsafes, and reverting parameters to their defaults.
 
 {{ easy_image(src="vehicle-setup-configure-failsafes", width=600) }}
 
+`New in 1.4`
+{{ easy_image(src="vehicle-setup-configure-gimbal", width=600) }}
+
 ### Video Streams
 {{ service(service="MAVLink Camera Manager", link="https://github.com/bluerobotics/mavlink-camera-manager/", port=6020) }}
 
 - BlueOS automatically detects H264-encoded video streams
 {% pirate() %}
-   - MJPG and YUYV encoded streams are also detected in pirate mode,
-   but currently only work when configured as RTSP streams
+- MJPG and YUYV encoded streams are also detected in pirate mode, but currently only work when configured as RTSP streams
+- H265 encoded streams can be streamed, using RTSP or UDP265 `(New in 1.4)`
 {% end %}
 
 - The first time BlueOS starts up it will auto-configure any cameras that are 
@@ -747,15 +788,15 @@ together with the theme file that created it:
 
 {% end %}
 
-{{ easy_image(src="theme-style", width=600, class="pirate") }}
+{{ easy_image(src="theme-style-main", width=600, class="pirate") }}
 
 {% pirate() %}
 ```css
 :root {
   --v-primary-base: #CAB1E5 !important;  /* sidebar highlights, submit buttons */
   --v-info-base: #BA55E5 !important;     /* info boxes (often same as primary base) */
   --v-warning-base: #EDD1E5 !important;  /* warnings and skip buttons */
-  --v-error-base: #AC1D1C !important;    /* notifications, pirate icons, cancel/delete buttons */
+  --v-error-base: #AC1D1C !important;    /* notifications, pirate icons, negative buttons */
   --v-anchor-base: #5A11ED !important;   /* hyperlinks */
 }
 
@@ -787,6 +828,24 @@ header.dark-background-glass {
   -webkit-backdrop-filter: blur(10px) !important;
 }
 ```
+
+The explanatory diagram colours are also configurable `(New in 1.4)`:
+{% end %}
+
+{{ easy_image(src="theme-style-diagrams", width=600, class="pirate") }}
+
+{% pirate() %}
+```css
+:root {
+    --v-water-base: #AC2317 !important;
+    --v-negative-base: #891A10 !important;
+    --v-attention-base: #ECC19B !important;
+    --v-positive-base: #514A3B !important;
+    --v-neutral-base: #A15447 !important;
+    --v-detail-base: #370502 !important;
+    --v-outline-base: #FDF4C9 !important;
+}
+```
 {% end %}
 
 <script type="text/javascript">