diff --git a/advanced-usage/edit-mode.png b/advanced-usage/edit-mode.png index b05a427..31be15b 100644 Binary files a/advanced-usage/edit-mode.png and b/advanced-usage/edit-mode.png differ diff --git a/advanced-usage/index.md b/advanced-usage/index.md index 82cdfa8..a822939 100644 --- a/advanced-usage/index.md +++ b/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,6 +439,31 @@ 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 @@ -365,7 +471,6 @@ are read out loud: {{ easy_image(src="alert-config", width=600, center=true) }} - ## Mission Planning - Allows planning (and saving/loading) autonomous missions diff --git a/advanced-usage/joystick-button-mapping.png b/advanced-usage/joystick-button-mapping.png new file mode 100644 index 0000000..116fdad Binary files /dev/null and b/advanced-usage/joystick-button-mapping.png differ diff --git a/advanced-usage/logging-config.png b/advanced-usage/logging-config.png new file mode 100644 index 0000000..5320c87 Binary files /dev/null and b/advanced-usage/logging-config.png differ diff --git a/advanced-usage/mission-name-config.png b/advanced-usage/mission-name-config.png new file mode 100644 index 0000000..e67a79e Binary files /dev/null and b/advanced-usage/mission-name-config.png differ diff --git a/advanced-usage/video-multiple-ip-warning.png b/advanced-usage/video-multiple-ip-warning.png new file mode 100644 index 0000000..772feac Binary files /dev/null and b/advanced-usage/video-multiple-ip-warning.png differ diff --git a/advanced-usage/video-recording-config.png b/advanced-usage/video-recording-config.png new file mode 100644 index 0000000..8adaf0a Binary files /dev/null and b/advanced-usage/video-recording-config.png differ diff --git a/advanced-usage/video-recording-recovery.png b/advanced-usage/video-recording-recovery.png new file mode 100644 index 0000000..04dbc91 Binary files /dev/null and b/advanced-usage/video-recording-recovery.png differ diff --git a/advanced-usage/video-recording-termination-warning.png b/advanced-usage/video-recording-termination-warning.png new file mode 100644 index 0000000..4bbd091 Binary files /dev/null and b/advanced-usage/video-recording-termination-warning.png differ diff --git a/advanced-usage/video-subtitles.png b/advanced-usage/video-subtitles.png new file mode 100644 index 0000000..311ceba Binary files /dev/null and b/advanced-usage/video-subtitles.png differ diff --git a/advanced-usage/view-config.png b/advanced-usage/view-config.png new file mode 100644 index 0000000..c1cfef2 Binary files /dev/null and b/advanced-usage/view-config.png differ diff --git a/getting-started/hud-view.png b/getting-started/hud-view.png new file mode 100644 index 0000000..a25aa16 Binary files /dev/null and b/getting-started/hud-view.png differ diff --git a/getting-started/index.md b/getting-started/index.md index 9c1f962..d9aae1e 100644 --- a/getting-started/index.md +++ b/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 diff --git a/getting-started/joystick-config.png b/getting-started/joystick-config.png index a06b372..6c17032 100644 Binary files a/getting-started/joystick-config.png and b/getting-started/joystick-config.png differ diff --git a/getting-started/map-view.png b/getting-started/map-view.png index da125e7..07cf281 100644 Binary files a/getting-started/map-view.png and b/getting-started/map-view.png differ diff --git a/getting-started/video-view.png b/getting-started/video-view.png index 1e55b29..98755e7 100644 Binary files a/getting-started/video-view.png and b/getting-started/video-view.png differ