[Cockpit-devel] updates for first major release beta

advanced-usage/index.md

@@ -1,7 +1,7 @@
 +++
 title = "Advanced Usage"
 description = "Cockpit advanced usage documentation."
-date = 2023-11-23T20:15:00+11:00
+date = 2023-12-13T01:30:00+11:00
 template = "docs/page.html"
 sort_by = "weight"
 weight = 30
@@ -31,8 +31,13 @@ Clicking on the burger menu (in the top left of the screen) provides access to v
 
 #### Mission Name
 
-It is possible to set a display name for the current mission/operation from beside the burger menu. If the name
-is deleted it can be made available again by visiting the [Mission Planning](#mission-planning) page.
+It is possible to set a display name for the current mission/operation from beside the burger menu.
+
+A default mission name is randomly selected each time Cockpit is opened/restarted. The default names are not
+used for saving files/recordings, but modified names are. While modifying the mission name it is possible
+to restore the previous name (e.g. if you change you mind or make a mistake).
+
+{{ easy_image(src="mission-name-config", width=450, center=true) }}
 
 #### Alerts
 
@@ -57,10 +62,12 @@ The current time and date is displayed in the top right corner.
 Cockpit's interface consists of a configurable widget system, with
 1. [Profiles](#profiles)
     - for supporting different operators and/or vehicle types
-    - can be added/removed, saved and loaded, and switched between in edit mode
+    - can be added/removed/duplicated, saved and loaded (to/from both the vehicle and the display device),
+    and switched between in edit mode
 1. [Views](#views) (within each profile)
     - for handling different operation modes / targets within a mission
-    - can be added/removed, saved and loaded, and dynamically switched between
+    - can be added/removed/duplicated, saved and loaded to/from the display device, and
+    dynamically switched between during operation
 1. [Widgets](#widgets) (within each view)
     - for advanced information display and vehicle control
     - can be added/removed, placed in arbitrary locations, and resized
@@ -86,19 +93,23 @@ to connect a different control computer to a vehicle and load the familiar contr
 
 #### Default Profiles
 
-Cockpit includes default profiles for submarine and boat use-cases, which cannot be edited. These serve as
-a reference for a recommended base profile, and are useful for restoring to a known reasonable interface in
-case something goes wrong with custom interface options. The default profiles are not persistent, so they
-may change through different Cockpit versions.
+Cockpit includes default profiles for submarine and boat use-cases. It is possible to restore to these
+(as a known reasonable interface) in case something goes wrong with your custom profiles, but be aware
+that the defaults may change between different Cockpit versions, so may end up restoring to an interface
+you haven't seen before.
 
 #### Profile Configuration
 
 1. Open edit mode (via the [burger menu](#burger-menu)
 1. Select a custom/user profile to edit, and/or create, import, or remove profiles as desired
-    - Non-default profiles can be renamed by clicking on the settings cog icon
+    - Profiles can be renamed by clicking on the settings cog icon, or duplicated via the copy icon
+    - Additional profiles can be imported from the display device or the connected vehicle
+        - Opening Cockpit on a new device will automatically try to load profiles from the vehicle
+        - If the browser already has Cockpit profiles stored, it will not try to load any from the
+          vehicle unless the import from vehicle button is clicked
+    - The set of available profiles can be stored onto the vehicle, or reset/restored to the defaults
+        - Storing profiles onto the vehicle overwrites those that may already be there
     - The "Views" list shows the views that are available within the selected profile
-    - Selecting one of the [default profiles](#default-profiles) will restore the interface to a standard one,
-      but cannot be edited unless you download and upload it as a user profile
 
 ### Views
 
@@ -121,9 +132,12 @@ Multiple simultaneous tabs from the same browser instance will be supported in f
 
 - Open edit mode via the [burger menu](#burger-menu)
 - Select a view to edit, and/or create or remove views as desired
-    - Clicking on the cog settings icon allows renaming a view, and determining whether the bottom
-      bottom mini-widgets bar is shown or hidden/docked when Cockpit boots
     - Views can be imported from an external file, or exported to a file for sharing
+    - Clicking on the cog settings icon allows renaming a view, and determining whether the footer bar is
+      shown or hidden/docked when Cockpit boots
+        - It is always possible to toggle the current footer bar visibility using
+          [Cockpit Actions](#cockpit-actions) (e.g. via a joystick button)
+{{ easy_image(src="view-config", width=250, center=true) }}
 - The "Current widgets" list allows
     1. dragging the widgets in the current view to reorder which widget is on top
         - This helps for use-cases like overlaying a HUD element on a video display
@@ -251,9 +265,15 @@ adding transparent padding at the sides / above+below as necessary
 It is also possible to select the video source IP, which is recommended especially if there are multiple
 available connection routes (e.g. if there is a wired route through a tether, as well as a wireless connection,
 you should select the tether IP and remove the wireless one to avoid video stuttering from transmission over wifi).
+A warning is provided when multiple routes are available:
+
+{{ easy_image(src="video-multiple-ip-warning", width=400, center=true) }}
 
 Video recording is possible using a [mini widget](#mini-widgets), and directly records the incoming stream
-(not the scaled and cropped display of the widget).
+(not the scaled and cropped display of the widget). Cockpit can be configured to 
+[log some telemetry values](#logs), and record them as a subtitle file for convenient video playback:
+
+{{ easy_image(src="video-subtitles", width=450, center=true) }}
 
 ##### URL Video Player
 
@@ -306,10 +326,16 @@ The current options include
         - this is currently stored in memory and downloaded to the device when finished, which may limit
         maximum time for individual recordings
     - recordings are saved using the [mission name](#mission-name) and the starting timestamp
+    - a warning is displayed if Cockpit is closed while a video is recording, and a recovery popup
+    appears when Cockpit is next opened in that browser / on that device
+{{ easy_image(src="video-recording-config", width=250, center=true) }}
+{{ easy_image(src="video-recording-termination-warning", width=400, center=true) }}
+{{ easy_image(src="video-recording-recovery", width=400, center=true) }}
 - Joystick connection status indicator
 - Flight mode selector
 - GPS status indicator
 - [View](#views) selector
+- Takeoff/land button
 
 ## Configuration
 
@@ -326,26 +352,81 @@ addresses, and refresh the page to establish the desired connection.
 
 ### Joysticks
 
-Cockpit is intended to work with arbitrary joystick types, and allows mapping joystick buttons and axes
-to [`BTNn_FUNCTION`](https://docs.bluerobotics.com/ardusub-zola/software/autopilot/ArduSub-4.1/developers/parameters/#btnn-function-function-for-button)
-values for use in regularly sent [`MANUAL_CONTROL`](https://mavlink.io/en/messages/common.html#MANUAL_CONTROL)
-MAVLink messages, as well as to Cockpit Actions which can send commands to the vehicle or trigger interface
-events like like view switching or starting a video recording.
+Cockpit is intended to work with arbitrary joystick types, and allows mapping joystick buttons and axes to
+various [protocol functions](#joystick-protocols), which can send inputs and commands to the vehicle, or trigger
+interface events. Once a function mapping is configured it is possible to export it to the computer and/or the
+vehicle, which can then be imported later to new Cockpit instances/devices.
 
 {{ easy_image(src="../getting-started/joystick-config", width=600, center=true) }}
 
 Support is built in for simultaneous input from multiple sources, including multiple joysticks, and by
-default each joystick can provide up to 8 axis ranges and 32 buttons. As some caveats,
-
-- ArduSub only supports 16 independent buttons and 4 axis ranges in its `MANUAL_CONTROL` handling
-- When mapping the Z motion axis range, note that ArduSub uses 0 to +1000 for full reverse to full forwards,
-whereas other vehicle types use -1000 to +1000
-- Cockpit can assign a button to the "Shift" `BTNn_FUNCTION`, but is not currently capable of mapping
-a secondary "shifted" autopilot action to its other buttons
-    - This currently needs to be set up separately, either directly using vehicle parameters, or using
-    an alternative control station software like QGroundControl
-- Cockpit is currently only capable of mapping to `BTNn_FUNCTION` values that have already been assigned to
-a button, which may need to be done in advance using parameters or QGroundControl
+default each joystick can provide up to 8 axis ranges and 32 buttons.
+
+#### Joystick Protocols
+
+When mapping the functionality of a joystick button or axis, there are multiple protocols to choose from:
+
+{{ easy_image(src="joystick-button-mapping", width=500, center=true) }}
+
+##### MAVLink `MANUAL_CONTROL` Messages
+
+[`MANUAL_CONTROL`](https://mavlink.io/en/messages/common.html#MANUAL_CONTROL) MAVLink messages are 
+automatically sent to the vehicle at 25Hz, which is not currently configurable.
+
+Button functions are determined by the autopilot firmware - e.g. in ArduSub they correspond to
+[`BTNn_FUNCTION`](https://docs.bluerobotics.com/ardusub-zola/software/autopilot/ArduSub-4.1/developers/parameters/#btnn-function-function-for-button)
+parameter values.
+
+As a few caveats:
+- ArduSub <= 4.1.x only supports 16 independent buttons and 4 axis ranges in its `MANUAL_CONTROL` handling
+    - More recent versions support the extended protocol, with 32 buttons and 6 motion axis inputs
+- ArduRover does not support buttons via the `MANUAL_CONTROL` protocol
+- When mapping the Z (vertical) motion axis range, note that ArduSub uses 0 to +1000 for full reverse to full
+  forwards, whereas other vehicle types use -1000 to +1000
+
+The function mapping decision process is designed to minimise intrusiveness to existing setups. When mapping a
+`MANUAL_CONTROL` button function to a joystick button, Cockpit
+1. First tries to use already mapped functions
+    - e.g. if there is already a `BTNn_FUNCTION` configured to enable Stabilize mode, a Cockpit button being set
+      to enable Stabilize mode will map to that existing function bit
+1. Then overwrites available Disabled `BTNn_FUNCTION`s
+1. Then tries to overwrite any mapped function bits that Cockpit currently isn't using
+    - If you try to change a Cockpit function to a `MANUAL_CONTROL` function when there are no buttons left it
+      will display an error message about insufficient buttons
+
+It is permitted to map the joystick button functions without a vehicle connected, in which case any relevant
+autopilot parameters will be automatically remapped once the vehicle connects. If more `MANUAL_CONTROL` button
+functions have been assigned than are supported by the vehicle then the extra ones are removed, and a warning
+is raised to notify that the configured mapping is not fully as designed.
+
+##### Cockpit Actions
+
+Joystick buttons can also be configured to run more general functionalities, like modifying the interface or
+sending a single MAVLink message. The current supported Actions are:
+
+- `go_to_next_view`
+- `go_to_previous_view`
+- `toggle_bottom_bar`
+- `toggle_full_screen`
+- `mavlink_arm`
+- `mavlink_disarm`
+
+##### Modifier Keys
+
+Modifiers allow sacrificing one button in order to add an extra functionality slot for every non-modifier button.
+Pressing a button while a modifier is held runs the modified function instead of the regular button function.
+
+Currently only a single modifier is available (Shift). As a special case, when a shift functionality slot is
+configured as a MAVLink `MANUAL_CONTROL` protocol function, it will activate `BTNn_SFUNCTION`s rather than the
+regular `BTNn_FUNCTION`s, which allows additional `MANUAL_CONTROL` button functions to be configured. Functions
+from other joystick protocols are unaffected, and can be arbitrarily assigned to regular or modifier-based
+functionality slots.
+
+##### Other
+
+Currently only used for the "No Function" option.
+
+#### Custom Joysticks
 
 Adding support for a new joystick type requires providing an SVG file with particular element IDs
 (for function mapping, and so the elements can be dynamically filled when the corresponding button is pressed):
@@ -358,14 +439,38 @@ Adding support for a new joystick type requires providing an SVG file with parti
     - in future there will be support for arbitrary axes and sliders
 - New SVGs currently need to be added to the code, but in future will be possible to add/import dynamically
 
+Once Cockpit has a suitably registered SVG file for the desired joystick type, it is possible to perform the
+relevant "Joystick mapping", from the button IDs presented by the physical joystick to labels that match the
+corresponding buttons in the SVG file. This mapping can then be exported to the computer and/or the vehicle,
+and imported to new Cockpit instances/devices later.
+
+## Logs
+
+Cockpit can optionally record some of its received telemetry values, which can then be turned into subtitle
+files when recording videos. 
+
+Currently the possible variables for logging are pre-defined, and the output format is determined automatically.
+If left unconfigured, the variables that are recorded by default are those from active widgets in the selected 
+[Profile](#profiles). It is possible to override which variables are logged via the configuration page, but
+custom widgets like the `VeryGenericIndicator` cannot currently be logged.
+
+{{ easy_image(src="logging-config", width=600, center=true) }}
+
+Logging is at a fixed rate of 1Hz. When a video recording completes, a corresponding subtitle file is generated
+by slicing the raw log from the start to end timestamps of the video.
+
+{% note() %}
+Recorded video and subtitles are in separate files, so the browser will typically ask for permission to "download
+multiple files", which must be accepted to get access to the subtitles corresponding to a video recording.
+{% end %}
+
 ### Alerts
 
 It is possible to select the desired text-to-speech voice, as well as configure which alert severities
 are read out loud:
 
 {{ easy_image(src="alert-config", width=600, center=true) }}
 
-
 ## Mission Planning
 
 - Allows planning (and saving/loading) autonomous missions

getting-started/index.md

@@ -1,7 +1,7 @@
 +++
 title = "Getting Started"
 description = "Cockpit getting started instructions."
-date = 2023-08-25T13:00:00+11:00
+date = 2023-12-12T22:20:00+11:00
 template = "docs/page.html"
 sort_by = "weight"
 weight = 20
@@ -28,24 +28,27 @@ To access the configuration section, open the burger menu in the top left, and s
 ## Interface Setup
 
 ### Visual Display
-By default, the interface of Cockpit is set up with two [views](../advanced-usage/#display-views):
+By default, the interface of Cockpit is set up with three [views](../advanced-usage/#views):
 1. Video view
-    - Includes a video stream, vehicle telemetry, heads-up display (HUD) overlay elements, status updates, and flight mode selection
-    - Most useful for first-person control of a vehicle like an ROV, copter, or plane
+    - Includes a video stream, vehicle telemetry, compass and attitude instrument indicators, status updates, and flight mode selection
+    - Useful for first-person control of a vehicle like an ROV, copter, or plane, focused on what the vehicle can see
 
 {{ easy_image(src="video-view", width=600, center=true) }}
 
-2. Map view
+2. HUD view
+    - Includes a video stream, vehicle telemetry, heads-up display (HUD) overlay elements, status updates, and flight mode selection
+    - An alternative for first-person control of a vehicle like an ROV, copter, or plane, focused on precision maneuvering
+
+{{ easy_image(src="hud-view", width=600, center=true) }}
+
+3. Map view
     - Includes a map, vehicle telemetry, status updates, and flight mode selection
     - Most useful for mission planning and remote monitoring of vehicles with a positioning system and/or autonomous control
 
 {{ easy_image(src="map-view", width=600, center=true) }}
 
-Primary widgets that support configuration can be configured by clicking on the icon in their top right corner. Mini-widgets can be
-configured by clicking anywhere on the widget.
-
-The available views (including widget size and placement) can be configured as described in the
-[advanced usage documentation](../advanced-usage/#display-views).
+The available views and the widgets within them (including sizing and placement) can be configured as described in the
+[advanced usage documentation](../advanced-usage/#edit-mode).
 
 ### Joystick Configuration
 For vehicles controlled via a joystick, button and axis mappings can be set by clicking the burger menu (top left), then selecting