diff --git a/.gitignore b/.gitignore index 592a6ea..1a30b91 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ .DS_Store public + +*.swp diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63204f0..d7dcf3e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,8 +5,10 @@ This file refers to the process of contributing to this documentation repository ## Repository Structure 1. Each branch covers some form of release of the software - - The `latest` and `beta` branches cover the unstable features in development / early testing - - The `X.Y` versioned branches track major and minor stable releases + - The `latest` branch covers the unstable features in development / early testing + - The `stable` and `X.Y` versioned branches track major and minor stable releases + - `stable` documents the current latest stable version + - It only branches into the corresponding numbered branch at the time of the next version number increment - Patch release (`X.Y.Z`) changes are documented (as relevant) in the corresponding minor release branch (`X.Y`) 1. Documentation content is in the `content` directory 1. The theme is included in the `themes` directory, as a git submodule @@ -18,9 +20,7 @@ This file refers to the process of contributing to this documentation repository - It is recommended that software pull requests that change an interface or part of the documented code structure be marked with a `docs-needed` [label](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels), and include a comment about which aspects need to be documented prior to the feature being merged (while the details are still front of mind for the developer) - If a software pull request is labelled as `docs-needed`, once a corresponding documentation pull request is merged the feature PR can be re-labelled with a completion status (e.g. `docs-minimal` or `docs-complete`) - Beta releases may require that no merged features are labelled with `docs-needed`, and stable releases may require that no included features are labelled with `docs-needed` or `docs-minimal` -1. When a new beta release of the software is made, the relevant changes in the `latest` branch get merged or cherry-picked over to the `beta` branch - - This is handled by the documentation maintainers -1. When a new major or minor stable release of the software is made, the `beta` branch gets duplicated into a new branch tracking that version, which then gets reconfigured with a fixed release number +1. When a new major or minor stable release of the software is made, the `stable` branch gets duplicated into a new branch tracking that version, which then gets reconfigured with a fixed release number, and the now-stable features in the `latest` branch get cherry-picked to the `stable` branch - This is handled by the documentation maintainers # Making a Contribution @@ -65,7 +65,7 @@ Specific processes are covered below, but the general process is: ### Improving/Adding Documentation for Released Features > ๐Ÿ’ก Relevant features can typically be found by looking through the public documentation for features with minimal information, and/or [searching this repository](https://github.com/bluerobotics/Cockpit-docs/issues?q=is%3Aissue+is%3Aopen+label%3Acontent) for issues with the `content` label, or [searching the software repository](https://github.com/bluerobotics/Cockpit/issues?q=is%3Apull+is%3Aclosed+label%3Adocs-minimal) for pull requests with the `docs-minimal` label. -Documentation for existing features should generally first be [added to the `latest` branch](#documenting-a-newupcoming-feature), before optionally being backported to the `beta` and/or any relevant version branches, usually via [`git cherry-pick`](https://git-scm.com/docs/git-cherry-pick). +Documentation for existing features should generally first be [added to the `latest` branch](#documenting-a-newupcoming-feature), before optionally being backported to the `stable` and/or any relevant version branches, usually via [`git cherry-pick`](https://git-scm.com/docs/git-cherry-pick). If your changes were requested in an Issue, make sure to include "Resolves #{ISSUE-NUMBER}" in the description of your pull request, to link to and automatically close the Issue when the pull request is merged. diff --git a/README.md b/README.md index f1419d2..fb4a21e 100644 --- a/README.md +++ b/README.md @@ -2,22 +2,23 @@ This repository documents the Blue Robotics' [Cockpit](https://blueos.cloud/cockpit/docs/usage/overview) software. -The documentation is generated using the [Zola](https://www.getzola.org/) static site generator. +The documentation is generated using the [Zola](https://www.getzola.org/) static site generator, together with [BlueTheme](https://github.com/bluerobotics/bluetheme). ## Structure - Each branch covers a minor release (`X.y`) of the software, including any patches (`X.Y.z`) of that release - - The `latest` branch covers the development state in the BlueOS `master` branch, but is not expected to be consistently up to date - - The `beta` branch covers the latest beta release, and is intended to at least minimally describe all included features + - The `latest` branch covers the development state in the Cockpit `master` branch, but is not expected to be consistently up to date + - It is intended to at least minimally describe all included features in the latest available beta release + - The `stable` branch covers the latest stable version, and is intended to sufficiently describe all included features - For ease of contribution, and to keep the search index independent between versions, each branch is built independently - Documentation content is in the `content` directory - The theme is provided as a submodule in the `themes` directory ## Contributing -New features should first be documented in `latest`, and subsequently branched into `beta` and a stable version toegther with the software release cycle. +New features should first be documented in `latest`, then cherry-picked into `stable` as part of the software release cycle. -Improved documentation for existing features should at least be added to `latest`, and ideally also cherry-picked into the existing `beta` and stable-versioned branches as relevant. +Improved documentation for existing features should at least be added to `latest`, and ideally also cherry-picked into the existing `stable` and numbered stable version branches as relevant. Detailed contribution information can be found in [CONTRIBUTING.md](CONTRIBUTING.md) diff --git a/content/usage/advanced/about.png b/content/usage/advanced/about.png new file mode 100644 index 0000000..0cd6c7a Binary files /dev/null and b/content/usage/advanced/about.png differ diff --git a/content/usage/advanced/alert-config.png b/content/usage/advanced/alert-config.png index e99dce8..d887da2 100644 Binary files a/content/usage/advanced/alert-config.png and b/content/usage/advanced/alert-config.png differ diff --git a/content/usage/advanced/alert-history.png b/content/usage/advanced/alert-history.png index c4bf5ba..93c9642 100644 Binary files a/content/usage/advanced/alert-history.png and b/content/usage/advanced/alert-history.png differ diff --git a/content/usage/advanced/alert-mini-widget.png b/content/usage/advanced/alert-mini-widget.png new file mode 100644 index 0000000..9e15ddc Binary files /dev/null and b/content/usage/advanced/alert-mini-widget.png differ diff --git a/content/usage/advanced/altitude-mini-widget.png b/content/usage/advanced/altitude-mini-widget.png new file mode 100644 index 0000000..6c88263 Binary files /dev/null and b/content/usage/advanced/altitude-mini-widget.png differ diff --git a/content/usage/advanced/arm-disarm-mini-widget.png b/content/usage/advanced/arm-disarm-mini-widget.png new file mode 100644 index 0000000..a6e9ce3 Binary files /dev/null and b/content/usage/advanced/arm-disarm-mini-widget.png differ diff --git a/content/usage/advanced/attitude-hud-config.png b/content/usage/advanced/attitude-hud-config.png index 9198f9f..5da0932 100644 Binary files a/content/usage/advanced/attitude-hud-config.png and b/content/usage/advanced/attitude-hud-config.png differ diff --git a/content/usage/advanced/boolean-input-config.png b/content/usage/advanced/boolean-input-config.png new file mode 100644 index 0000000..d933c42 Binary files /dev/null and b/content/usage/advanced/boolean-input-config.png differ diff --git a/content/usage/advanced/burger-menu.png b/content/usage/advanced/burger-menu.png deleted file mode 100644 index bf39978..0000000 Binary files a/content/usage/advanced/burger-menu.png and /dev/null differ diff --git a/content/usage/advanced/button-input-config.png b/content/usage/advanced/button-input-config.png new file mode 100644 index 0000000..9a4eba5 Binary files /dev/null and b/content/usage/advanced/button-input-config.png differ diff --git a/content/usage/advanced/button-input.png b/content/usage/advanced/button-input.png new file mode 100644 index 0000000..a047dc2 Binary files /dev/null and b/content/usage/advanced/button-input.png differ diff --git a/content/usage/advanced/change-altitude-mini-widget.png b/content/usage/advanced/change-altitude-mini-widget.png new file mode 100644 index 0000000..bcbe3a2 Binary files /dev/null and b/content/usage/advanced/change-altitude-mini-widget.png differ diff --git a/content/usage/advanced/change-altitude-slider.png b/content/usage/advanced/change-altitude-slider.png new file mode 100644 index 0000000..7c194c4 Binary files /dev/null and b/content/usage/advanced/change-altitude-slider.png differ diff --git a/content/usage/advanced/checkbox-input.png b/content/usage/advanced/checkbox-input.png new file mode 100644 index 0000000..6e75e37 Binary files /dev/null and b/content/usage/advanced/checkbox-input.png differ diff --git a/content/usage/advanced/clock-mini-widget.png b/content/usage/advanced/clock-mini-widget.png new file mode 100644 index 0000000..c05e953 Binary files /dev/null and b/content/usage/advanced/clock-mini-widget.png differ diff --git a/content/usage/advanced/compass-hud-config.png b/content/usage/advanced/compass-hud-config.png index 77e52b5..2abe8ae 100644 Binary files a/content/usage/advanced/compass-hud-config.png and b/content/usage/advanced/compass-hud-config.png differ diff --git a/content/usage/advanced/custom-actions-config.png b/content/usage/advanced/custom-actions-config.png new file mode 100644 index 0000000..25ab3d8 Binary files /dev/null and b/content/usage/advanced/custom-actions-config.png differ diff --git a/content/usage/advanced/custom-http-action.png b/content/usage/advanced/custom-http-action.png new file mode 100644 index 0000000..0d19094 Binary files /dev/null and b/content/usage/advanced/custom-http-action.png differ diff --git a/content/usage/advanced/custom-javascript-action.png b/content/usage/advanced/custom-javascript-action.png new file mode 100644 index 0000000..b7bb3da Binary files /dev/null and b/content/usage/advanced/custom-javascript-action.png differ diff --git a/content/usage/advanced/custom-mavlink-action.png b/content/usage/advanced/custom-mavlink-action.png new file mode 100644 index 0000000..2dc987e Binary files /dev/null and b/content/usage/advanced/custom-mavlink-action.png differ diff --git a/content/usage/advanced/custom-widget-base.png b/content/usage/advanced/custom-widget-base.png new file mode 100644 index 0000000..8ccc941 Binary files /dev/null and b/content/usage/advanced/custom-widget-base.png differ diff --git a/content/usage/advanced/custom-widget-config.png b/content/usage/advanced/custom-widget-config.png new file mode 100644 index 0000000..dd02402 Binary files /dev/null and b/content/usage/advanced/custom-widget-config.png differ diff --git a/content/usage/advanced/depth-hud-config.png b/content/usage/advanced/depth-hud-config.png index b16ec63..cabdcf7 100644 Binary files a/content/usage/advanced/depth-hud-config.png and b/content/usage/advanced/depth-hud-config.png differ diff --git a/content/usage/advanced/depth-mini-widget.png b/content/usage/advanced/depth-mini-widget.png new file mode 100644 index 0000000..f097220 Binary files /dev/null and b/content/usage/advanced/depth-mini-widget.png differ diff --git a/content/usage/advanced/dev-mode-config.png b/content/usage/advanced/dev-mode-config.png new file mode 100644 index 0000000..9131822 Binary files /dev/null and b/content/usage/advanced/dev-mode-config.png differ diff --git a/content/usage/advanced/dial-input-config.png b/content/usage/advanced/dial-input-config.png new file mode 100644 index 0000000..8f642f3 Binary files /dev/null and b/content/usage/advanced/dial-input-config.png differ diff --git a/content/usage/advanced/dial-input.png b/content/usage/advanced/dial-input.png new file mode 100644 index 0000000..5e5f859 Binary files /dev/null and b/content/usage/advanced/dial-input.png differ diff --git a/content/usage/advanced/dropdown-input-config.png b/content/usage/advanced/dropdown-input-config.png new file mode 100644 index 0000000..1137b04 Binary files /dev/null and b/content/usage/advanced/dropdown-input-config.png differ diff --git a/content/usage/advanced/dropdown-input.png b/content/usage/advanced/dropdown-input.png new file mode 100644 index 0000000..f8a837c Binary files /dev/null and b/content/usage/advanced/dropdown-input.png differ diff --git a/content/usage/advanced/edit-mode.png b/content/usage/advanced/edit-mode.png index 226a7e4..4d9627a 100644 Binary files a/content/usage/advanced/edit-mode.png and b/content/usage/advanced/edit-mode.png differ diff --git a/content/usage/advanced/exit-fullscreen.png b/content/usage/advanced/exit-fullscreen.png new file mode 100644 index 0000000..9588939 Binary files /dev/null and b/content/usage/advanced/exit-fullscreen.png differ diff --git a/content/usage/advanced/flight-mode-mini-widget.png b/content/usage/advanced/flight-mode-mini-widget.png new file mode 100644 index 0000000..7d74ce4 Binary files /dev/null and b/content/usage/advanced/flight-mode-mini-widget.png differ diff --git a/content/usage/advanced/general-config.png b/content/usage/advanced/general-config.png new file mode 100644 index 0000000..f43cf7c Binary files /dev/null and b/content/usage/advanced/general-config.png differ diff --git a/content/usage/advanced/goto.png b/content/usage/advanced/goto.png new file mode 100644 index 0000000..35a6226 Binary files /dev/null and b/content/usage/advanced/goto.png differ diff --git a/content/usage/advanced/gps-mini-widget.png b/content/usage/advanced/gps-mini-widget.png new file mode 100644 index 0000000..0e7485d Binary files /dev/null and b/content/usage/advanced/gps-mini-widget.png differ diff --git a/content/usage/advanced/iframe-config.png b/content/usage/advanced/iframe-config.png index d729915..84db3db 100644 Binary files a/content/usage/advanced/iframe-config.png and b/content/usage/advanced/iframe-config.png differ diff --git a/content/usage/advanced/image-viewer-config.png b/content/usage/advanced/image-viewer-config.png index 6ef7025..60bddde 100644 Binary files a/content/usage/advanced/image-viewer-config.png and b/content/usage/advanced/image-viewer-config.png differ diff --git a/content/usage/advanced/index.md b/content/usage/advanced/index.md index a822939..64105ad 100644 --- a/content/usage/advanced/index.md +++ b/content/usage/advanced/index.md @@ -1,12 +1,11 @@ +++ title = "Advanced Usage" description = "Cockpit advanced usage documentation." -date = 2023-12-13T01:30:00+11:00 +date = 2025-01-08T19:05:00+11:00 template = "docs/page.html" sort_by = "weight" weight = 30 draft = false -aliases = ['/software/control-station/Cockpit-latest/advanced-usage'] [extra] lead = '' @@ -14,149 +13,331 @@ toc = true top = false +++ +## Quick Links + +1. [**Widgets**](#widgets) +1. [**Joystick Configuration**](#joysticks) +1. [**Data Recording**](#status-and-recordings) +1. [**Mission Planning**](#mission-planning) + ## Display Breakdown {{ easy_image(src="interface-overview", width=650, center=true) }} +Cockpit's main interface consists of three main components: +1. A central region, for regular [widgets](#widgets) +1. Mini-widget containers, including the header and footer bars +1. A sidebar menu icon + - Normally a sidebar tab arrow on the left + - Can be configured as a burger menu in the top left corner + ### Header Bar -The header bar consists of the following main elements: +The header bar is consistent across [Views](#views), and is usually used for displaying +[mission information](#mission-information) mini-widgets and +[connection statuses](#connection-statuses). -#### Burger Menu +### Footer Bar -Clicking on the burger menu (in the top left of the screen) provides access to various -[configuration](#configuration) options: +The footer bar is unique to each View, and is generally used to display [indicators](#very-generic-indicators) +of various kinds, along with [vehicle status controllers](#vehicle-status-controllers) and +[interface controls](#interface-controls). -{{ easy_image(src="burger-menu", width=300, center=true) }} +During operation, it can be toggled between hidden and shown using a [Cockpit Action](#cockpit-actions-1). -#### Mission Name +### Sidebar Menu -It is possible to set a display name for the current mission/operation from beside the burger menu. +Clicking on the sidebar tab (on the left of the screen) provides access to various configuration options, +along with information about the application: -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="sidebar-menu", width=100) }} -{{ easy_image(src="mission-name-config", width=450, center=true) }} +#### About -#### Alerts +The "About" window displays a brief description of Cockpit itself, along with key information about the +version being run, and links to relevant resources and help/discussion/contribution channels: -Alerts received from the autopilot ([`STATUSTEXT`](https://mavlink.io/en/messages/common.html#STATUSTEXT)), as -well as application notifications (like loss of connection to the vehicle) are displayed in the central alerts -pane, which can be hovered over to access a scrollable history of alerts: +{{ easy_image(src="about", width=500) }} -{{ easy_image(src="alert-history", width=450, center=true) }} +#### Fullscreen Display -Some alerts can be read aloud on arrival using text to speech technology, which [can be configured](#alerts). +Cockpit can be run within the window it opens in, or as a full-screen application. + +Full-screening a browser window usually includes the tabs and search bar at the top, so there's a button +in the sidebar menu to make Cockpit itself full-screened instead, and to easily exit from full-screen to +resume access to the underlying browser / operating system interface. -#### Mini Widget Container +{{ easy_image(src="exit-fullscreen", width=100) }} -When space is available, [mini widgets](#mini-widgets) can be placed on the right side of the alerts display. +#### Settings -#### Date +Cockpit's settings control how the application behaves and communicates, including, what data sources it's +connected to, and how and where it processes and outputs commands and data (including recordings and logs): -The current time and date is displayed in the top right corner. +{{ easy_image(src="settings-menu", width=100) }} + +The available settings interfaces and options are [covered in a dedicated section](#behaviour-configuration) +below. ## Edit Mode +Cockpit is built around a configurable widget system, so you can design and modify custom interfaces for +different applications. + +{{ easy_image(src="edit-mode", width=650, center=true) }} + +### Organisation + +{{ easy_image(src="users-profiles-views", width=500, center=true) }} + Cockpit's interface consists of a configurable widget system, with + +0. [Users](#users) + - for supporting different operators + - can be added and switched between in [general configuration](#general) 1. [Profiles](#profiles) - - for supporting different operators and/or vehicle types + - for supporting different vehicle types and/or operating modes - 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/duplicated, saved and loaded to/from the display device, and + - can be added/hidden/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 -1. [Mini-widgets](#mini-widgets) (within mini-widget bar widgets) - - for basic information display and vehicle/interface control - - can be added/removed, reordered within widget bars, and moved between them + - for information display and vehicle control + - can be added/removed, moved around, and resized -{{ easy_image(src="edit-mode", width=650, center=true) }} +### Users + +Users are more abstract than the interface, and are mostly helpful for the following situations: +1. Multiple vehicle operators who share a single control station computer (e.g. within an + organisation), and don't want to use the same configurations + - This can alternatively be achieved with [Profiles](#profiles), but having separate users + provides a cleaner separation, and easier options to reset everything +1. Multiple operators who share a single BlueOS-based vehicle, and each want to synchronise their + own configuration with it + +For individuals with their own vehicles and control computers, it is generally fine to set a +username once and then ignoring that the "user" level exists. + +Switching users is done through [`Settings / General`](#general): +{{ easy_image(src="user-manager", width=500, center=true) }} + +Creating new users is possible by clicking the "Add New" button, and choosing a unique name. +The new user copies the Profiles of the currently selected user (if one exists - otherwise +it uses Cockpit's default profiles). + +It is [not currently possible to delete users](https://github.com/bluerobotics/cockpit/issues/1384). ### Profiles -A "profile" is a collection of [views](#views) that are relevant to a particular use-case or operator. +A "profile" is a collection of [views](#views) that are relevant to a particular use-case or vehicle. -If one control station computer is used by multiple operators (e.g. within the same organisation) -at different times then it could be useful for each operator to have their preferred interface saved on -that computer, and they can switch to their profile when they open up Cockpit. +If one control station computer is used for multiple complex use-cases (which each require multiple +separate Views), then they can be separated into Profiles and the most relevant one can be switched +to at the start of each mission. Alternatively, if the same control station computer is used to control different types of vehicles (e.g. a boat, an underwater ROV, and a drone) then the operator can load the appropriate vehicle control -interface when they connect to a different vehicle type. It will soon be possible to store and load -profiles from the vehicle itself, instead of only on the control station computer, which makes it easier -to connect a different control computer to a vehicle and load the familiar control profiles for that vehicle. +interface when they connect to a different vehicle type. Profiles are registered with the vehicle types +they're expected to be used for, so if there is only one profile that matches the connected vehicle +then Cockpit will load that automatically. + +For BlueOS-based vehicles, Cockpit can automatically store and load Users and their Profiles on/from the +vehicle, which can then be synchronised when Cockpit connects (including on separate control station +devices, or on a different network), which makes it convenient to quickly and easily load familiar +profiles. #### Default Profiles -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. +Cockpit includes default profiles for submarine, boat, and generic MAVLink aerial vehicle 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. + +{{ easy_image(src="profile-selector", width=250, center=true) }} #### 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 - - 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 +Profiles are managed via the top left corner region of edit mode, which can be accessed through the +[sidebar menu](#sidebar-menu). Clicking the three dots (โ‹ฎ) to the right of the current profile allows +renaming and configuring it: + +{{ easy_image(src="profile-config", width=500, center=true) }} + +It is also possible to duplicate, export, or delete it, as well as import or create a new profile, +reset this User's profiles to the default ones, and enable or disable the alignment grid for widget +placement and sizing: + +{{ easy_image(src="profile-manager", width=250, center=true) }} ### Views A "view" is like a page that [widgets](#widgets) can be displayed in. It is possible to configure multiple -separate views and switch between them during operation, which is useful if you have different interface -preferences for when you're performing different operations. +separate views and switch between them during operation (including [with a joystick](#cockpit-actions-1)), +which is useful if you have different interface preferences for when you're performing different operations. + +{{ easy_image(src="view-selector", width=120, center=true) }} As an example, you may have one view tailored to general navigation, and another that's designed around inspections. The first view could then be used while getting the vehicle to the inspection site, and then the second view can be switched to once it's time to actually perform the inspection. -It is possible for different devices or browser instances to access Cockpit at the same time (e.g. using -separate browser profiles, or one display in incognito mode, but currently **not** multiple tabs of the same -browser instance), with their views configured independently. To use the same component layouts across -instances you can export the desired view(s) from one and import into the other(s). - -Multiple simultaneous tabs from the same browser instance will be supported in future. +It is possible for different devices or browser instances to connect Cockpit to a vehicle (or load Cockpit +from a vehicle) at the same time (e.g. using separate browser profiles, or one display in incognito mode, +but currently **not** multiple tabs of the same browser instance), with their views configured independently. +To use the same component layouts across instances you can sync them through the vehicle, or manually +export the desired view(s) from one and import them into the other(s). -#### Configuration +#### Views Configuration -- Open edit mode via the [burger menu](#burger-menu) -- Select a view to edit, and/or create or remove views as desired +- Open edit mode via `Settings / Edit Interface` in the [sidebar menu](#sidebar-menu) +- Expand or hide the views manager via the arrow in the top left corner +{{ easy_image(src="view-manager", width=300, center=true) }} +- Select a view to edit, and/or create, hide/show, or remove views as desired - 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 +{{ easy_image(src="view-config", width=400, center=true) }} +- The "Widgets in View" list allows + - hovering over a widget name to highlight its display in the interface + - dragging the widgets in the main view area to reorder which widget is on top - This helps for use-cases like overlaying a HUD element on a video display - 1. removing an existing widget from the current view - 1. resizing a widget to fill the entire view + - removing an existing widget from the current view + - resizing a widget to fill the entire view +{{ easy_image(src="view-widgets", width=300, center=true) }} - New widgets can be added via the bottom section - - Clicking on a regular widget adds it to the view, after which it can be positioned and resized as desired + - Dragging a regular widget card into the main display area adds it to the View, after which it can be + positioned and resized as desired - Mini widgets have fixed sizes, but can be dragged and dropped into the desired location in the header/footer - bars or in a custom [mini widget bar](#mini-widget-bar) - - The selector in the bottom left can be used to choose between editing regular or mini widgets -- Some widgets can be configured, by clicking the cog settings icon in the "Current widgets" list + bars or in a custom [container widget](#container-widgets) + - The header bar is shared between Views, and the bottom bar is unique to each View + - The selector in the bottom left can be used to choose between editing regular, mini, or input widgets +- Some widgets can be configured, by clicking the cog settings icon in the "Widgets in View" list - [There are currently cog icons for all widgets](https://github.com/bluerobotics/cockpit/issues/541), so if you click a cog icon and nothing happens it means that widget is not configurable ### Widgets -There are several types of widgets available, and in future it will be possible to create, import, and use custom widgets as well. +There are several types of widgets available, including different displays of the same information for use in different contexts: +- **Regular Widgets** include detailed displays like videos, maps, instrument gauges, and overlays + - They can only be located in the main display area + - Their positions and sizes snap to the [Profile alignment grid](#profile-configuration), if it is enabled +- **Mini Widgets** are small (usually text-based) indicators and buttons + - They can be in the shared header bar, or in the View-specific footer bar or a [container widget](#container-widgets) +- [**Input Widgets**](#input-widgets) are like mini-widgets dedicated for custom user inputs / commands + - They can be in the shared header bar, or in the View-specific footer bar or a [container widget](#container-widgets) + +
+{{ easy_image(src="widgets-variety", width=650) }} + +#### Mission Information + +##### Mission Name +By default, a name is randomly generated for the current mission/operation each time Cockpit is opened/restarted, +and displayed in the mission name indicator: +{{ easy_image(src="mission-name-mini-widget", width=400, center=true) }} -#### Regular Widgets +Clicking on the widget allows setting a custom name, which is then used for saving files and video recordings: +{{ easy_image(src="mission-name-config", width=450, center=true) }} + +While modifying the mission name it is possible to restore the previous name, in case you change you mind or +make a mistake. + +##### Alerter +The alerter mini-widget allows displaying Cockpit's [alerts](#alerts-1), along with their severity: +{{ easy_image(src="alert-mini-widget", width=400, center=true) }} + +Hovering over the widget displays a scrollable history: +{{ easy_image(src="alert-history", width=450, center=true) }} + +##### Power/Battery Indicator +{{ easy_image(src="power-mini-widget", width=80, center=true) }} +Configuration allows choosing to display current or instantaneous power draw, or alternating between both +{{ easy_image(src="power-config", width=250, center=true) }} + +##### Date and Time +The current date and time can be displayed in a mini-widget: +{{ easy_image(src="clock-mini-widget", width=150, center=true) }} + +{% note() %} +If the time is needed in seconds, see the [Alerter](#alerter). +{% end %} + +#### Connection Statuses + +##### Vehicle Connection Indicator +When Cockpit gains or loses connection with the vehicle it displays a green/red border around the screen. +The vehicle connection mini-widget provides a continuous indication: +{{ easy_image(src="vehicle-connected-mini-widget", width=70, center=true) }} + +##### Joystick Connection Indicator +The joystick connection mini-widget indicates whether a joystick is disconnected, disabled, or connected: +{{ easy_image(src="joystick-mini-widget", width=120, center=true) }} + +Clicking on the widget allows manually disabling the connection: +{{ easy_image(src="joystick-config", width=300, center=true) }} + +which can be useful if multiple users are switching control of the vehicle between separate devices with +Cockpit open, or to prevent a faulty joystick from sending errant commands without needing to physically +disconnect or unpair it. + +##### GPS Connection Indicator +For vehicles that use satellite positioning, the GPS connection mini-widget indicates the number of +connected satellites, and the status of the position lock: +{{ easy_image(src="gps-mini-widget", width=100, center=true) }} + +#### Vehicle Status Controllers +Vehicle status and modes are controllable using [Cockpit Actions](#cockpit-actions) assigned to joystick +button functions, but these mini-widgets provide an on-screen interface for doing so, while also +presenting the current state. + +##### Arm / Disarm +{{ easy_image(src="arm-disarm-mini-widget", width=250, center=true) }} + +##### Flight Mode +{{ easy_image(src="flight-mode-mini-widget", width=150, center=true) }} + +#### Interface Controls +##### View Selector + +The actively displayed [View](#views) is specified and can be switched between using the View selector +mini-widget: +{{ easy_image(src="view-selector", width=120, center=true) }} + +{% note() %} +It is also possible to switch Views using [Cockpit Actions](#cockpit-actions) assigned to joystick +button functions. +{% end %} + +#### Very Generic Indicators +{{ easy_image(src="very-generic-widget", width=100, center=true) }} + +These are versatile mini-widgets that can be configured to track almost any information Cockpit receives +from the vehicle, including: +1. any variable that is inside a [MAVLink message](https://mavlink.io/en/messages/) + - messages with an ID field are separated into different instances per ID + - [`NAMED_VALUE_FLOAT/INT`](https://mavlink.io/en/messages/common.html#NAMED_VALUE_FLOAT) messages are + split by name, **including showing custom ones** (Cockpit does not need to know these names in advance) + - only messages from ArduPilot vehicles are currently known about / supported + - e.g. those from the [common](https://mavlink.io/en/messages/common.html) or + [ardupilotmega](https://mavlink.io/en/messages/ardupilotmega.html) message sets +1. select information from the onboard computer + - e.g. `blueos/cpu/tempC` for the BlueOS CPU temperature + +For configuration convenience, several pre-made presets are available for usage with common variables: +{{ easy_image(src="very-generic-widget-config-presets", width=300, center=true) }} + +For custom setups, it is also possible to specify a display unit, a value multiplier, an icon, the number of +digits after the decimal place, and a custom display name: +{{ easy_image(src="very-generic-widget-config-custom", width=500, center=true) }} + +Selecting a variable is done through a dropdown, which can also be typed into to perform a fuzzy search for +terms of interest. + +#### Attitude Indicators ##### Attitude HUD @@ -166,6 +347,10 @@ The attitude HUD widget displays the vehicle's pitch and roll as a heads-up disp It is possible to configure which components get displayed, as well as the line colour: {{ easy_image(src="attitude-hud-config", width=500, center=true) }} +For vehicles with a tilt-controlled camera mount, specifying the camera vertical FOV allows +the attitude HUD to account for the camera tilt angle in the displayed pitch lines and +center aim indicator. + ##### Virtual Horizon The virtual horizon widget displays the vehicle's pitch and roll as though on the gauge in a plane: @@ -173,6 +358,18 @@ The virtual horizon widget displays the vehicle's pitch and roll as though on th It is most useful for guided and/or autonomous control, where the main display is of the vehicle's position. +##### Attitude Values + +Roll, pitch, and yaw, and their rotation rates, can be accessed through the +[`ATTITUDE`](https://mavlink.io/en/messages/common.html#ATTITUDE) MAVLink message, which forms the +basis for the main attitude widgets. + +When operating in an attitude-stabilised flight mode, the _target_ attitude values are accessible +through the [`NAV_CONTROLLER_OUTPUT`](https://mavlink.io/en/messages/common.html#NAV_CONTROLLER_OUTPUT) +MAVLink messages, and can be displayed in Very Generic Indicator widgets if desired. + +#### Heading Indicators + ##### Compass The compass widget displays the vehicle's orientation as though looking at a compass in your hand: @@ -194,6 +391,14 @@ It is possible to configure whether the exact heading angle is shown, whether to (default is 0 to 360ยฐ), and the colour of the lines: {{ easy_image(src="compass-hud-config", width=500, center=true) }} +##### Heading Values + +Heading indicators typically use the yaw from the [attitude values](#attitude-values), but for vehicles +with relevant sensors and configuration, the raw heading form a GPS unit can be accessed through +[`GPS_RAW_INT`](https://mavlink.io/en/messages/common.html#GPS_RAW_INT) messages. + +#### Depth Indicators + ##### Depth HUD The depth HUD indicates the vehicle's current depth as determined by its external pressure sensor: @@ -204,77 +409,134 @@ This is primarily useful for underwater vehicles. Configuration determines whether the exact depth value is shown, and the colour of the lines: {{ easy_image(src="depth-hud-config", width=500, center=true) }} -##### IFrame +##### Depth Mini-Widget -The iframe widget provides an inline frame that can display another HTML page within the Cockpit interface. -This is particularly useful for showing the interfaces and displays of BlueOS Extensions (e.g. for a sonar viewer): -{{ easy_image(src="iframe-widget", width=400, center=true) }} +{{ easy_image(src="depth-mini-widget", width=150, center=true) }} -Configuration determines the URL to fetch the page from, as well as the overall transparency of the iframe: -{{ easy_image(src="iframe-config", width=400, center=true) }} +#### Altitude Indicators -##### Image Viewer +##### Altitude Indicator Mini-Widget -The image viewer widget shows an image that is accessible to the control station computer via its network. -{{ easy_image(src="image-viewer-config", width=400, center=true) }} +The Altitude mini-widget displays the vehicle's altitude estimate, relative to its barometer calibration point. -Images from the internet can be included (e.g. a logo for branding) as long as the computer has internet -access when Cockpit is started. +{{ easy_image(src="altitude-mini-widget", width=150, center=true) }} -This is most useful for images hosted on the local network, and was designed to display the output of a -self-replacing mjpeg like from an ESP32-Cam. It could also display images hosted by a -[BlueOS Extension](https://blueos.cloud/docs/blueos/latest/extensions). +It is intended for aerial vehicles, so positive is upwards. + +#### Altitude Modifiers + +When using a Takeoff/Land or Change Altitude Commander mini-widget, + +{{ easy_image(src="takeoff-mini-widget", width=120, center=true) }} +{{ easy_image(src="change-altitude-mini-widget", width=120, center=true) }} -##### Map +a slider is created to specify the desired altitude to fly to: + +{{ easy_image(src="change-altitude-slider", width=70, center=true) }} + +#### Map For vehicles with a positioning system, the map widget displays the [registered home location](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_SET_HOME) and the vehicle's [current position](https://mavlink.io/en/messages/common.html#GLOBAL_POSITION_INT), with an option to track the vehicle's path over time. -There are buttons to -1. move the map to follow the registered 'home' location - - this may move around if the control station computer is on a boat -1. move the map to follow the vehicle's current position -1. download the current mission from the vehicle, and display it on the map -1. execute the mission that is on the vehicle +There are buttons +- in the bottom left to + - move the map to follow the registered 'home' location + - this may move around if the control station computer is on a boat + - move the map to follow the vehicle's current position + - download the current mission from the vehicle, and display it on the map + - run the mission that is on the vehicle +- in the bottom right to zoom in and out, and +- in the top right to + - Switch between structured and satellite map views + - Include [sea marks](https://wiki.openstreetmap.org/wiki/Seamarks/Seamark_Objects) + - Include [water depths](https://openseamap.org/index.php?id=bathymetrie&L=1) + {{ easy_image(src="map-widget", width=350, center=true) }} -{{ easy_image(src="map-config", width=350, center=true) }} -In future it will be possible to set the current vehicle position, and click to guide the vehicle to new -positions. +{% note() %} +[Mission Planning](#mission-planning) is documented in a dedicated section. +{% end %} -##### Video Player +Configuration allows showing or hiding a trail of the vehicle's path over time. -The video player widget displays an available WebRTC video stream. BlueOS uses the -[MAVLink Camera Manager](https://github.com/mavlink/mavlink-camera-manager) to automatically create a WebRTC -stream for applicable video streams. -{{ easy_image(src="video-widget", width=400, center=true) }} +{{ easy_image(src="map-config", width=250, center=true) }} + +For vehicles with a supporting autopilot firmware and valid position estimate it is also possible to guide +the vehicle to a new position via GoTo commands (which can be sent by clicking a target location on the map, +and clicking the GoTo button). + +{{ easy_image(src="goto", width=100, center=true) }} + +It is [not currently possible](https://github.com/bluerobotics/cockpit/issues/1513) to manually specify the +vehicle's current position, GPS origin, or home location. -Multiple video widgets can be added to display different video streams. +#### Video Widgets + +Cockpit has a few different widgets for handling videos from different sources. + +Multiple video widgets can be added to display different video streams, with options for how the frames +should fit within the widget: -Configuration allows selecting which video stream to display, flipping the stream image, and choosing how -the frames should fit within the widget: - **cover**: maintains the video aspect ratio, but expands the frames to fully cover the widget, and crops off the sides or top+bottom if they extend beyond the widget boundaries - **fill**: stretches the frames so that all sides are against the corresponding widget boundary - **contain**: maintains the video aspect ratio, but shrinks the frames to fully fit inside the widget, adding transparent padding at the sides / above+below as necessary -{{ easy_image(src="video-config", width=600, center=true) }} -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: +##### WebRTC Video Player + +WebRTC Video Player widgets can display an available WebRTC video stream, as set up through the [Video Configuration +menu](#video-streams-configuration). BlueOS uses the +[MAVLink Camera Manager](https://github.com/mavlink/mavlink-camera-manager) to automatically create a WebRTC +stream for applicable video streams. +{{ easy_image(src="video-widget", width=400, center=true) }} + +Configuration allows selecting which video stream to display, flipping and rotating the stream image, and +choosing how the frames should fit within the widget (as described above): +{{ easy_image(src="video-widget-config", width=400, center=true) }} + +If your video stream is having some issues, the available stream performance statistics may help to determine +the cause of the problem: -{{ easy_image(src="video-multiple-ip-warning", width=400, center=true) }} +{{ easy_image(src="video-widget-stats", width=170, 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). Cockpit can be configured to -[log some telemetry values](#logs), and record them as a subtitle file for convenient video playback: +##### WebRTC Video Recorder +It is possible to directly record an incoming WebRTC video stream (not the scaled and cropped/flipped/rotated +display of the widget): + +{{ easy_image(src="video-recording-mini-widget", width=180, center=true) }} + +Clicking the red icon on the left allows quickly starting and stopping recording of the currently specified +stream. + +Clicking the stream name in the middle of the widget allows choosing which stream to record: +{{ easy_image(src="video-recording-config", width=250, center=true) }} + +Recordings are saved using the [mission name](#mission-name) and starting timestamp, and can be found in +the [Video Library](#video-library). When videos are available an indicator shows on the right side of the +recording widget, which can be clicked to open the library directly. + +{% note() %} +Recording occurs in the display device (not onboard the vehicle). +{% end %} +{% note() %} +When running Cockpit in a browser, downloading recordings currently temporarily stores them in memory, which +may limit the maximum duration of individual recordings. The standalone application records videos directly +to the filesystem, so does not have this issue. +{% end %} + +To make the recorded videos easier to analyse, Cockpit can be configured to +[log telemetry values](#telemetry-logs-subtitle-files), and record them as a subtitle file for +convenient video playback: {{ easy_image(src="video-subtitles", width=450, center=true) }} +If a recording is ongoing, Cockpit will try to prevent the tab/application from closing, with a warning: +{{ easy_image(src="video-recording-termination-warning", width=550, center=true) }} + ##### URL Video Player The URL video player widget displays a video from a URL. This is useful for testing IP cameras that are not @@ -284,94 +546,204 @@ being redirected via BlueOS, but can also be used to display online videos if th Configuration allows selecting which URL to stream a video from, as well as options for whether to play the video automatically, whether it should loop when complete, whether it should play sound or be muted, whether playback controls should be exposed, and choosing how the video frames should fit within the widget (as -described in [Video Player](#video-player). +described above). {{ easy_image(src="url-video-config", width=450, center=true) }} +{% note() %} +See also the [External Displays](#external-displays) section, for some alternatives with related functionality. +{% end %} + +#### External Displays + +##### IFrame + +The iframe widget provides an inline frame that can display another HTML page within the Cockpit interface. +This is particularly useful for showing the interfaces and displays of IP cameras and BlueOS Extensions: +{{ easy_image(src="iframe-widget", width=350, center=true) }} + +Configuration determines the URL to fetch the page from, as well as the overall transparency of the iframe: +{{ easy_image(src="iframe-config", width=450, center=true) }} + +##### Image Viewer + +The image viewer widget shows an image that is accessible to the control station computer via its network. +{{ easy_image(src="image-viewer-config", width=400, center=true) }} + +Images from the internet can be included (e.g. a logo for branding) as long as the computer has internet +access when Cockpit is started. + +{% note() %} +This is most useful for images hosted on the local network, and was designed to display the output of a +self-replacing mjpeg like from an ESP32-Cam. It could also display images hosted by a +[BlueOS Extension](https://blueos.cloud/docs/blueos/latest/extensions). +{% end %} + +#### Data Plotting + +##### Plotter Widget + +The plotter widget allows plotting data on a graph: +{{ easy_image(src="plotter-widget", width=300, center=true) }} + +Configuration options are provided for selecting the variables to plot, and modifying basic appearance +characteristics: +{{ easy_image(src="plotter-config", width=400, center=true) }} + +{% note() %} +The data lake which the widget gets its data from by default only provides access to the Cockpit memory +usage, and values added from [Custom Actions](#custom-actions). It will soon be connected to the +MAVLink message fields as well, and other options available to +[Very Generic Indicators](#very-generic-indicators). +{% end %} + +#### Container Widgets + +Regular widgets for storing [mini widgets](#widgets) and [input widgets](#input-widgets) in the main +View area. + ##### Mini Widget Bar -The mini widget bar widget is a rectangular container for storing [mini widgets](#mini-widgets). +A generic rectangular container widget, where list order determines internal positions. {{ easy_image(src="mini-widgets-bar-widget", width=500, center=true) }} -#### Mini Widgets - -Mini widgets are small, generally single-function widgets that can be drag-positioned in the -[header bar](#header-bar), footer bar, or any [mini widget bar](#mini-widget-bar). - -They are editable by selecting "Mini Widgets" in the bottom left corner of edit mode, then either -dragging a new mini-widget (from those available along the bottom of the screen) into a -[mini-widget bar](#mini-widget-bar), or configuring or removing one from the "current mini-widgets" -list in the bottom left corner. - -The current options include -- Arm/Disarm toggle switch -- Vehicle connection status indicator -- Power / battery indicator -- Depth indicator -- (Relative) altitude indicator -- Very generic indicator - - configuring this allows selecting which vehicle variable to track, out of - any that have been received so far (including custom ones) - - only variables coming from Ardupilot vehicles are currently supported - - available variables include those comming from `NAMED_VALUE_FLOAT/INT` messages as well - as any variable that is inside any MAVLink message - - several pre-made presets are available for usage with common variables - - it is also possible to specify a display unit, a value multiplier, an icon, the number of - digits after the decimal place and a custom display name -{{ easy_image(src="very-generic-widget-config-presets", width=300, center=true) }} -{{ easy_image(src="very-generic-widget-config-custom", width=300, center=true) }} -- Video recorder - - allows recording one of the available WebRTC streams, or the full Cockpit tab - - recording occurs in the browser of the display device (not onboard the vehicle) - - 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 +##### Custom Widget Base + +A collapsible, nameable, movable container widget, with a grid of internal position options. + +{{ easy_image(src="custom-widget-base", width=250, center=true) }} +{{ easy_image(src="custom-widget-config", width=350, center=true) }} + +#### Input Widgets + +Input widgets should be placed in a [container widget](#container-widgets), and can be configured by +clicking on them when in [Edit Mode](#edit-mode). + +While other widgets generally have predefined behaviour, these are specifically designed to trigger and +set variables for use as parameters in [Custom HTTP Actions](#custom-actions). + +##### Action Buttons +Buttons can trigger a specified Action (currently only [Custom HTTP Actions](#custom-actions)) when pressed. +{{ easy_image(src="button-input", width=120, center=true) }} +{{ easy_image(src="button-input-config", width=250, center=true) }} + +##### Boolean Inputs +For parameters that require True/False or 0/1 values, you can use a Switch or Checkbox Input widget: -## Configuration +{{ easy_image(src="switch-input", width=100, center=true) }} +{{ easy_image(src="checkbox-input", width=100, center=true) }} +{{ easy_image(src="boolean-input-config", width=250, center=true) }} -Cockpit's behaviour can be configured via the [burger menu](#burger-menu), with the following tabs: +##### Multi-value Inputs +If a parameter has a set of possible value options, that can be represented using a Dropdown Input widget: + +{{ easy_image(src="dropdown-input", width=180, center=true) }} +{{ easy_image(src="dropdown-input-config", width=250, center=true) }} + +##### Range Inputs +Parameters with an integer or decimal range of values can be set using Dial and Slider Input widgets. + +Dial Inputs allow configuring a value range, rounded to the nearest integer: +{{ easy_image(src="dial-input", width=100, center=true) }} +{{ easy_image(src="dial-input-config", width=250, center=true) }} + +Slider Inputs allow configuring a value range, rounded to the first decimal place (e.g. 0.1): +{{ easy_image(src="slider-input", width=200, center=true) }} +{{ easy_image(src="slider-input-config", width=250, center=true) }} + +##### Input Labels +If there are separate groups of Input widgets in a Custom Widget Base, it can be useful to give them headings +with Label widgets: +{{ easy_image(src="label-input", width=100, center=true) }} +{{ easy_image(src="label-input-config", width=250, center=true) }} + +## Behaviour Configuration + +Cockpit's behaviour can be configured via the [sidebar menu](#sidebar-menu), with the following tabs: ### General -Connection configuration allows specifying custom endpoint addresses for Cockpit to communicate with. -When Cockpit is hosted by a vehicle running BlueOS these are usually correct by default, but if using -it standalone or connecting to some external services it may be necessary to specify different -addresses, and refresh the page to establish the desired connection. +The general settings cover top level configuration of Cockpit, to set up who is using it and how it should +connect to a vehicle: + +{{ easy_image(src="general-config", width=400) }} -{{ easy_image(src="../getting-started/general-config", width=600, center=true) }} +- Create and switch the active [User](#users) +- Specify the primary network address to connect to the vehicle +- Optionally override the autopilot / MAVLink router telemetry connection address +- Optionally override the WebRTC media connection address, for video streaming +- Optionally customise the WebRTC connection configuration values + +### Interface + +The interface settings cover high-level configuration options about Cockpit's appearance and data displays: + +{{ easy_image(src="interface-config", width=500) }} + +It is also possible to rearrange and modify the components and widgets displayed during operation, which +there's a dedicated interface for managing in [Edit Mode](#edit-mode). ### Joysticks 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. +various [protocol functions](#joystick-protocols), which can send inputs and commands to the vehicle, or +trigger interface events. + +{% note() %} +The default function mapping is selected based on the connected vehicle type, and Cockpit automatically +synchronises function mappings to/from the [User](#users), but it is also possible to manually export +them as a file, and import them into another User or a different Cockpit instance/device. +{% end %} + +Known joystick types have an interactive diagram for mapping button and axis functions visually: +{{ easy_image(src="joystick-button-mapping", width=600, center=true) }} -{{ easy_image(src="../getting-started/joystick-config", width=600, center=true) }} +Button presses and axis movements should be mirrored on the diagram, and clicking on a button +element in the diagram allows remapping its mapped function. +{% note() %} +Axes currently must have unique functions, so mapping an axis to an Action that is already in +use will result in that Action being unmapped from whichever axis was using it previously. +{% end %} + +There is also a table view, which is available for both known and new joystick types: +{{ easy_image(src="joystick-table", width=600, center=true) }} + +Buttons can be remapped to different Actions using the edit pencil at the far right of the corresponding row. + +{% note() %} 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. +default each joystick can provide up to 32 axis ranges and 32 buttons. +{% end %} #### 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) }} +{{ easy_image(src="joystick-protocols", width=500, center=true) }} +{{ easy_image(src="joystick-axis-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. +automatically transmitted at 25Hz, which is not currently configurable. + +{% note() %} +While it is generally expected for there to be a vehicle connected, Cockpit is capable of sending +MAVLink Messages to a MAVLink system more generally, even without a vehicle included. +{% end %} + +{% warning() %} +If the browser tab is changed away from Cockpit, or the Cockpit application window is minimised, +Cockpit loses access to the joystick inputs, and normally stops sending `MANUAL_CONTROL` messages +to reflect the loss of input. This can trigger an autopilot failsafe, which may not be desirable, +so an option is provided in the top right of the joystick page to tell Cockpit to repeatedly send +the last joystick input it received before losing access to the joystick. +> +>It is important to **always be conscious of where your vehicle is**, and what kind of hazards it +is operating near. +{% end %} 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) @@ -402,14 +774,8 @@ 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` +sending a single MAVLink message. These options can be provided (or defined) using +[Cockpit's Action system](#cockpit-actions-1). ##### Modifier Keys @@ -424,7 +790,7 @@ functionality slots. ##### Other -Currently only used for the "No Function" option. +Currently only used for the "No Function" option, which is used when a button or axis input is unmapped. #### Custom Joysticks @@ -444,17 +810,173 @@ relevant "Joystick mapping", from the button IDs presented by the physical joyst 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 +### Video Streams Configuration + +Available video streams and connection settings can be viewed and configured: + +{{ easy_image(src="video-streams-config", width=400) }} + +- Set a custom name for each recognised video stream + - Edit by double clicking the existing name, or clicking the pencil icon +- Limit which IP address(es) are allowed to be used for video streaming + - This is particularly recommended 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). + - By default wired connection pathways (e.g. an ethernet tether or USB cable) are assigned as the + preferred pathway, if they are detected +- Limit which network protocol(s) are allowed for video streaming + - UDP can be lower latency but may drop frames, while TCP enforces frame ordering at the cost of some + increased latency and jitter +- Customise the stream pipeline's jitter buffer duration + - Higher values increase stream latency, but can compensate for network jitter and display the stream + with a smoother / more consistent duration between frames +- Configure [Video Library](#video-library) behaviours + - Recorded video chunks can be combined automatically at the end of the recording session (which may + take a while on low end hardware), or can be left for the user to trigger manually when they want to + download a specific video + - Videos and subtitle files can be zipped together to download them as a single compressed archive, but + the zipping process can take a while if the files are large, which may be inconvenient + - Access the Video Library from here, or from any video recorder mini-widget + +### Telemetry + +Telemetry values received by Cockpit can be displayed live, but also [recorded into video subtitle files]( +#telemetry-logs-subtitle-files). + +Available variables can be dragged and dropped into the relevant screen region to specify where they show +up in the generated subtitle file, or removed from recording by pressing the X beside the variable name in +the grid. It is also possible to style the subtitle file using the Overlay Options expandable section, and +specify the subtitle update rate in the Settings section. + +{{ easy_image(src="telemetry-config", width=600, center=true) }} + +### Alerts + +Cockpit includes a variety of [alerts](#alerts-1) during operation, and provides settings for which ones +(if any) should be read using text to speech technology: + +{{ easy_image(src="alert-config", width=500, center=true) }} + +### Development / Troubleshooting + +These features help with error tracking and troubleshooting, so in normal use can generally be left alone: + +{{ easy_image(src="dev-mode-config", width=600) }} + +- **Development mode** turns on a debugging overlay that displays relevant information about the visible widgets + - Dev info blur level determines how much the underlying interface is blurred when in dev mode +- **BlueOS settings sync** allows synchronising Cockpit's settings to the connected vehicle (if it is running BlueOS) + - This helps with keeping the same settings and profiles if that vehicle is then later controlled using + a different device running Cockpit +- **Usage statistics telemetry** can be automatically sent to the Cockpit development team to help identify and + track common errors and performance issues across global Cockpit usage +- **System logging** creates [application logs](#system-application-logs) that can be checked or shared with + developers to help debug issues + - If system logs are disabled then messages are sent to the browser/application console instead, which may + reduce performance + +### Missions and Safety + +While autopilots often include built in failsafes and pre-arming checks, it can also be useful for the operator's +interface to require explict confirmation before a safety-related or mission critical action is even sent to the +vehicle. + +Depending on the interface configuration, some interfaces may make it easy to accidentally press a button or +slider on the screen that has an undesirable outcome, so it is possible to require these actions to be have an +extra confirmation step: + +{{ easy_image(src="mission-config", width=500) }} + +A confirmation slider is shown, which can either be dragged to completion in the interface, or confirmation can +be provided by pressing and holding a joystick button that is configured to the `hold_to_confirm` Action: + +{{ easy_image(src="slide-to-confirm", width=250, center=true) }} + +{% note() %} +Actions that are *triggered* by joystick button presses (instead of interface elements) do not require extra +confirmation - it is assumed that the press of a dedicated button is enough confirmation.

+If you want a similar feature for joystick button functions, consider assigning them to a +[modifier-based slot](#modifier-keys), to require a modifier key to be held down before the function +can be triggered. +{% end %} + +### Cockpit Actions + +Cockpit's Action system provides a set of functionalities that can be triggered from any of Cockpit's +supported input sources (e.g. joystick buttons, interface elements, other Actions, etc). + +#### Default Actions +There are some predefined Actions built into Cockpit for convenience, including: + +- `go_to_next_view` +- `go_to_previous_view` +- `toggle_bottom_bar` +- `toggle_full_screen` +- `hold_to_confirm` +- `start_recording_all_streams` +- `stop_recording_all_streams` +- `mavlink_arm` +- `mavlink_disarm` + +#### Custom Actions +It is also possible to define (and export or import) your own custom Actions, with a few different approaches: + +{{ easy_image(src="custom-actions-config", width=500) }} + +- **MAVLink Message Actions** are the most confined, and allow sending arbitrary + [MAVLink messages](https://mavlink.io/en/messages/common.html) and + [commands](https://mavlink.io/en/messages/common.html#mav_commands) to the vehicle and any other + components in your MAVLink system +{{ easy_image(src="custom-mavlink-action", width=400) }} +- **HTTP Request Actions** can send arbitrary HTTP requests, including custom URL parameters, headers, + and a JSON body + - These are best for basic communication with arbitrary APIs + - Parameters that are defined using [Input Widgets](#input-widgets) can be easily modified during + operation +{{ easy_image(src="custom-http-action", width=400, center=true) }} +- **JavaScript Actions** are a blank canvas, with all the possibilities (but also the complexities) of + programming your own functionalities +{{ easy_image(src="custom-javascript-action", width=500, center=true) }} + +Existing custom Actions can be edited, run manually (to test them), exported, or deleted. + +{% note() %} +More detailed breakdowns and examples will be coming in future. +{% end %} + +## Status and Recordings + +### Video Library +- Allows processing and previewing video recordings, and downloading them with corresponding subtitle files +- It is possible to select and act on multiple recordings at once, including downloading or deleting as a batch + - Selecting multiple files requires either switching to the relevant mode, or doing a long press on the + first file in the batch, or selecting a set of individual files using `CTRL+Click` or `CMD+Click` (for macOS). +{{ easy_image(src="video-recording-library", width=500, center=true) }} + +### Telemetry Logs / Subtitle Files 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. +{% note() %} +For lower level and more detailed communication/telemetry logs, consider checking the logs and debugging +interfaces of your MAVLink router. Relevant information can be found in the +[MAVLink Endpoints documentation](https://blueos.cloud/docs/latest/usage/advanced/#mavlink-endpoints) for +BlueOS users. +{% end %} + +Available variables for logging are determined using the [mini-widgets](#widgets) included in a +[View](#views) in the active [Profile](#profiles), including Very Generic Indicator widgets, which can display +almost anything Cockpit receives from the vehicle. It is also possible to add custom text values, to include +extra metadata like a company name or vehicle operator. + +{% note() %} +Using a hidden View allows configuring mini-widgets for any variables you want to record but do not want to +display during operation. +{% end %} -{{ easy_image(src="logging-config", width=600, center=true) }} +It is possible to configure which variables are logged and where they appear in the generated subtitle files +using the [telemetry settings](#telemetry). 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. @@ -464,16 +986,45 @@ Recorded video and subtitles are in separate files, so the browser will typicall multiple files", which must be accepted to get access to the subtitles corresponding to a video recording. {% end %} +### System/Application Logs + +For debugging purposes, Cockpit keeps track of its internal state changes and errors in JSON-based log files, +which can be downloaded or deleted from the dev page: +{{ easy_image(src="system-logs", width=600, center=true) }} + +The top right button allows deleting all the old log files as a group. + +Downloaded logs can be opened in a standard text editor, and include a sequence of events recorded with a +[UNIX-style epoch timestamp](https://www.unixtimestamp.com/), together with the event severity level +(e.g. debug, log, error, etc), and some kind of related message. + ### Alerts -It is possible to select the desired text-to-speech voice, as well as configure which alert severities -are read out loud: +Alerts received from the autopilot ([`STATUSTEXT`](https://mavlink.io/en/messages/common.html#STATUSTEXT)), as +well as application notifications (like loss of connection to the vehicle) are displayed in the +[alerter mini-widget](#alerter). -{{ easy_image(src="alert-config", width=600, center=true) }} +Some alerts can be read aloud on arrival using text to speech technology, which [can be configured](#alerts). ## Mission Planning -- Allows planning (and saving/loading) autonomous missions -- Allows mission control +For vehicles with a position estimate, `Mission Planning` mode (in the sidebar) can be used to create basic +autonomous missions, and load a mission from a file. +Planning can involve placing individual waypoints and generating basic surveys, +including multiple survey regions with manually placed waypoints between them: + +{{ easy_image(src="mission-creation", width=200, center=true) }} {{ easy_image(src="mission-planning", width=600, center=true) }} + +{% note() %} +Waypoints are currently limited to basic motion targets, but will soon be able to trigger custom +MAVLink commands and other actions. +{% end %} + +Once the mission is ready it can be uploaded to the vehicle, or saved to a file for later, before exiting +mission planning via the `Flight` button in the sidebar: + +{{ easy_image(src="mission-sidebar", width=150, center=true) }} + +Starting the mission is done using the play button in the bottom left corner of a [Map widget](#map). diff --git a/content/usage/advanced/interface-config.png b/content/usage/advanced/interface-config.png new file mode 100644 index 0000000..48acf32 Binary files /dev/null and b/content/usage/advanced/interface-config.png differ diff --git a/content/usage/advanced/interface-overview.png b/content/usage/advanced/interface-overview.png index 378643e..64cdfcb 100644 Binary files a/content/usage/advanced/interface-overview.png and b/content/usage/advanced/interface-overview.png differ diff --git a/content/usage/advanced/joystick-axis-mapping.png b/content/usage/advanced/joystick-axis-mapping.png new file mode 100644 index 0000000..220e771 Binary files /dev/null and b/content/usage/advanced/joystick-axis-mapping.png differ diff --git a/content/usage/advanced/joystick-button-mapping.png b/content/usage/advanced/joystick-button-mapping.png index 116fdad..90ecac6 100644 Binary files a/content/usage/advanced/joystick-button-mapping.png and b/content/usage/advanced/joystick-button-mapping.png differ diff --git a/content/usage/advanced/joystick-config.png b/content/usage/advanced/joystick-config.png new file mode 100644 index 0000000..610e9d0 Binary files /dev/null and b/content/usage/advanced/joystick-config.png differ diff --git a/content/usage/advanced/joystick-mini-widget.png b/content/usage/advanced/joystick-mini-widget.png new file mode 100644 index 0000000..073fb8f Binary files /dev/null and b/content/usage/advanced/joystick-mini-widget.png differ diff --git a/content/usage/advanced/joystick-protocols.png b/content/usage/advanced/joystick-protocols.png new file mode 100644 index 0000000..b571cb5 Binary files /dev/null and b/content/usage/advanced/joystick-protocols.png differ diff --git a/content/usage/advanced/joystick-table.png b/content/usage/advanced/joystick-table.png new file mode 100644 index 0000000..46ac488 Binary files /dev/null and b/content/usage/advanced/joystick-table.png differ diff --git a/content/usage/advanced/label-input-config.png b/content/usage/advanced/label-input-config.png new file mode 100644 index 0000000..90e8c31 Binary files /dev/null and b/content/usage/advanced/label-input-config.png differ diff --git a/content/usage/advanced/label-input.png b/content/usage/advanced/label-input.png new file mode 100644 index 0000000..0cc5b6e Binary files /dev/null and b/content/usage/advanced/label-input.png differ diff --git a/content/usage/advanced/logging-config.png b/content/usage/advanced/logging-config.png deleted file mode 100644 index 5320c87..0000000 Binary files a/content/usage/advanced/logging-config.png and /dev/null differ diff --git a/content/usage/advanced/map-config.png b/content/usage/advanced/map-config.png index bf17f9f..b680df4 100644 Binary files a/content/usage/advanced/map-config.png and b/content/usage/advanced/map-config.png differ diff --git a/content/usage/advanced/map-widget.png b/content/usage/advanced/map-widget.png index c4e2daf..edb341f 100644 Binary files a/content/usage/advanced/map-widget.png and b/content/usage/advanced/map-widget.png differ diff --git a/content/usage/advanced/mission-config.png b/content/usage/advanced/mission-config.png new file mode 100644 index 0000000..91d999a Binary files /dev/null and b/content/usage/advanced/mission-config.png differ diff --git a/content/usage/advanced/mission-creation.png b/content/usage/advanced/mission-creation.png new file mode 100644 index 0000000..c9100a4 Binary files /dev/null and b/content/usage/advanced/mission-creation.png differ diff --git a/content/usage/advanced/mission-name-config.png b/content/usage/advanced/mission-name-config.png index e67a79e..bd8a450 100644 Binary files a/content/usage/advanced/mission-name-config.png and b/content/usage/advanced/mission-name-config.png differ diff --git a/content/usage/advanced/mission-name-mini-widget.png b/content/usage/advanced/mission-name-mini-widget.png new file mode 100644 index 0000000..c088016 Binary files /dev/null and b/content/usage/advanced/mission-name-mini-widget.png differ diff --git a/content/usage/advanced/mission-planning.png b/content/usage/advanced/mission-planning.png index feb6559..eac0671 100644 Binary files a/content/usage/advanced/mission-planning.png and b/content/usage/advanced/mission-planning.png differ diff --git a/content/usage/advanced/mission-sidebar.png b/content/usage/advanced/mission-sidebar.png new file mode 100644 index 0000000..603e149 Binary files /dev/null and b/content/usage/advanced/mission-sidebar.png differ diff --git a/content/usage/advanced/plotter-config.png b/content/usage/advanced/plotter-config.png new file mode 100644 index 0000000..a4b5a67 Binary files /dev/null and b/content/usage/advanced/plotter-config.png differ diff --git a/content/usage/advanced/plotter-widget.png b/content/usage/advanced/plotter-widget.png new file mode 100644 index 0000000..b485d42 Binary files /dev/null and b/content/usage/advanced/plotter-widget.png differ diff --git a/content/usage/advanced/power-config.png b/content/usage/advanced/power-config.png new file mode 100644 index 0000000..2e07d93 Binary files /dev/null and b/content/usage/advanced/power-config.png differ diff --git a/content/usage/advanced/power-mini-widget.png b/content/usage/advanced/power-mini-widget.png new file mode 100644 index 0000000..eee0803 Binary files /dev/null and b/content/usage/advanced/power-mini-widget.png differ diff --git a/content/usage/advanced/profile-config.png b/content/usage/advanced/profile-config.png new file mode 100644 index 0000000..441ce78 Binary files /dev/null and b/content/usage/advanced/profile-config.png differ diff --git a/content/usage/advanced/profile-manager.png b/content/usage/advanced/profile-manager.png new file mode 100644 index 0000000..61e7355 Binary files /dev/null and b/content/usage/advanced/profile-manager.png differ diff --git a/content/usage/advanced/profile-selector.png b/content/usage/advanced/profile-selector.png new file mode 100644 index 0000000..e2eaf1c Binary files /dev/null and b/content/usage/advanced/profile-selector.png differ diff --git a/content/usage/advanced/settings-menu.png b/content/usage/advanced/settings-menu.png new file mode 100644 index 0000000..b2f0b51 Binary files /dev/null and b/content/usage/advanced/settings-menu.png differ diff --git a/content/usage/advanced/sidebar-menu.png b/content/usage/advanced/sidebar-menu.png new file mode 100644 index 0000000..93d9635 Binary files /dev/null and b/content/usage/advanced/sidebar-menu.png differ diff --git a/content/usage/advanced/slide-to-confirm.png b/content/usage/advanced/slide-to-confirm.png new file mode 100644 index 0000000..14d4c35 Binary files /dev/null and b/content/usage/advanced/slide-to-confirm.png differ diff --git a/content/usage/advanced/slider-input-config.png b/content/usage/advanced/slider-input-config.png new file mode 100644 index 0000000..0daf262 Binary files /dev/null and b/content/usage/advanced/slider-input-config.png differ diff --git a/content/usage/advanced/slider-input.png b/content/usage/advanced/slider-input.png new file mode 100644 index 0000000..171f5bf Binary files /dev/null and b/content/usage/advanced/slider-input.png differ diff --git a/content/usage/advanced/switch-input.png b/content/usage/advanced/switch-input.png new file mode 100644 index 0000000..27ba672 Binary files /dev/null and b/content/usage/advanced/switch-input.png differ diff --git a/content/usage/advanced/system-logs.png b/content/usage/advanced/system-logs.png new file mode 100644 index 0000000..7101a5b Binary files /dev/null and b/content/usage/advanced/system-logs.png differ diff --git a/content/usage/advanced/takeoff-mini-widget.png b/content/usage/advanced/takeoff-mini-widget.png new file mode 100644 index 0000000..d6e1126 Binary files /dev/null and b/content/usage/advanced/takeoff-mini-widget.png differ diff --git a/content/usage/advanced/telemetry-config.png b/content/usage/advanced/telemetry-config.png new file mode 100644 index 0000000..d0cddc6 Binary files /dev/null and b/content/usage/advanced/telemetry-config.png differ diff --git a/content/usage/advanced/url-video-config.png b/content/usage/advanced/url-video-config.png index a049089..911296a 100644 Binary files a/content/usage/advanced/url-video-config.png and b/content/usage/advanced/url-video-config.png differ diff --git a/content/usage/advanced/user-manager.png b/content/usage/advanced/user-manager.png new file mode 100644 index 0000000..03a8b7e Binary files /dev/null and b/content/usage/advanced/user-manager.png differ diff --git a/content/usage/advanced/users-profiles-views.png b/content/usage/advanced/users-profiles-views.png new file mode 100644 index 0000000..943107b Binary files /dev/null and b/content/usage/advanced/users-profiles-views.png differ diff --git a/content/usage/advanced/vehicle-connected-mini-widget.png b/content/usage/advanced/vehicle-connected-mini-widget.png new file mode 100644 index 0000000..86eba47 Binary files /dev/null and b/content/usage/advanced/vehicle-connected-mini-widget.png differ diff --git a/content/usage/advanced/very-generic-widget-config-custom.png b/content/usage/advanced/very-generic-widget-config-custom.png index 8e73743..caab50f 100644 Binary files a/content/usage/advanced/very-generic-widget-config-custom.png and b/content/usage/advanced/very-generic-widget-config-custom.png differ diff --git a/content/usage/advanced/very-generic-widget-config-presets.png b/content/usage/advanced/very-generic-widget-config-presets.png index 7b6bd91..905c32c 100644 Binary files a/content/usage/advanced/very-generic-widget-config-presets.png and b/content/usage/advanced/very-generic-widget-config-presets.png differ diff --git a/content/usage/advanced/very-generic-widget.png b/content/usage/advanced/very-generic-widget.png new file mode 100644 index 0000000..d93ec87 Binary files /dev/null and b/content/usage/advanced/very-generic-widget.png differ diff --git a/content/usage/advanced/video-config.png b/content/usage/advanced/video-config.png deleted file mode 100644 index f64380e..0000000 Binary files a/content/usage/advanced/video-config.png and /dev/null differ diff --git a/content/usage/advanced/video-multiple-ip-warning.png b/content/usage/advanced/video-multiple-ip-warning.png deleted file mode 100644 index 772feac..0000000 Binary files a/content/usage/advanced/video-multiple-ip-warning.png and /dev/null differ diff --git a/content/usage/advanced/video-recording-config.png b/content/usage/advanced/video-recording-config.png index 8adaf0a..ccb27e3 100644 Binary files a/content/usage/advanced/video-recording-config.png and b/content/usage/advanced/video-recording-config.png differ diff --git a/content/usage/advanced/video-recording-library.png b/content/usage/advanced/video-recording-library.png new file mode 100644 index 0000000..375e410 Binary files /dev/null and b/content/usage/advanced/video-recording-library.png differ diff --git a/content/usage/advanced/video-recording-mini-widget.png b/content/usage/advanced/video-recording-mini-widget.png new file mode 100644 index 0000000..52f9ecd Binary files /dev/null and b/content/usage/advanced/video-recording-mini-widget.png differ diff --git a/content/usage/advanced/video-recording-recovery.png b/content/usage/advanced/video-recording-recovery.png deleted file mode 100644 index 04dbc91..0000000 Binary files a/content/usage/advanced/video-recording-recovery.png and /dev/null differ diff --git a/content/usage/advanced/video-recording-termination-warning.png b/content/usage/advanced/video-recording-termination-warning.png index 4bbd091..865d0f7 100644 Binary files a/content/usage/advanced/video-recording-termination-warning.png and b/content/usage/advanced/video-recording-termination-warning.png differ diff --git a/content/usage/advanced/video-streams-config.png b/content/usage/advanced/video-streams-config.png new file mode 100644 index 0000000..dbcf6fc Binary files /dev/null and b/content/usage/advanced/video-streams-config.png differ diff --git a/content/usage/advanced/video-subtitles.png b/content/usage/advanced/video-subtitles.png index 311ceba..d81ef1e 100644 Binary files a/content/usage/advanced/video-subtitles.png and b/content/usage/advanced/video-subtitles.png differ diff --git a/content/usage/advanced/video-widget-config.png b/content/usage/advanced/video-widget-config.png new file mode 100644 index 0000000..d949592 Binary files /dev/null and b/content/usage/advanced/video-widget-config.png differ diff --git a/content/usage/advanced/video-widget-stats.png b/content/usage/advanced/video-widget-stats.png new file mode 100644 index 0000000..5d9ced9 Binary files /dev/null and b/content/usage/advanced/video-widget-stats.png differ diff --git a/content/usage/advanced/view-config.png b/content/usage/advanced/view-config.png index c1cfef2..6216211 100644 Binary files a/content/usage/advanced/view-config.png and b/content/usage/advanced/view-config.png differ diff --git a/content/usage/advanced/view-manager.png b/content/usage/advanced/view-manager.png new file mode 100644 index 0000000..1ca8689 Binary files /dev/null and b/content/usage/advanced/view-manager.png differ diff --git a/content/usage/advanced/view-selector.png b/content/usage/advanced/view-selector.png new file mode 100644 index 0000000..14b16d1 Binary files /dev/null and b/content/usage/advanced/view-selector.png differ diff --git a/content/usage/advanced/view-widgets.png b/content/usage/advanced/view-widgets.png new file mode 100644 index 0000000..9996293 Binary files /dev/null and b/content/usage/advanced/view-widgets.png differ diff --git a/content/usage/advanced/widgets-variety.png b/content/usage/advanced/widgets-variety.png new file mode 100644 index 0000000..db5832e Binary files /dev/null and b/content/usage/advanced/widgets-variety.png differ diff --git a/content/usage/getting-started/boat-map-view.png b/content/usage/getting-started/boat-map-view.png new file mode 100644 index 0000000..5740b44 Binary files /dev/null and b/content/usage/getting-started/boat-map-view.png differ diff --git a/content/usage/getting-started/general-config.png b/content/usage/getting-started/general-config.png index cad3637..ef3a988 100644 Binary files a/content/usage/getting-started/general-config.png and b/content/usage/getting-started/general-config.png differ diff --git a/content/usage/getting-started/hud-view.png b/content/usage/getting-started/hud-view.png deleted file mode 100644 index a25aa16..0000000 Binary files a/content/usage/getting-started/hud-view.png and /dev/null differ diff --git a/content/usage/getting-started/index.md b/content/usage/getting-started/index.md index f1e4164..1013caa 100644 --- a/content/usage/getting-started/index.md +++ b/content/usage/getting-started/index.md @@ -1,7 +1,7 @@ +++ title = "Getting Started" description = "Cockpit getting started instructions." -date = 2023-12-12T22:20:00+11:00 +date = 2025-01-08T21:05:00+11:00 template = "docs/page.html" sort_by = "weight" weight = 20 @@ -12,52 +12,90 @@ lead = '' toc = true top = false +++ +## Welcome to Cockpit! + +When you're first starting out, it's good to find out what there is and where you can find it. +On the first boot, Cockpit opens a tutorial window that walks you through the main parts of the interface: + +{{ easy_image(src="tutorial", width=500, center=true) }} + ## General Configuration -When run as a BlueOS Extension, Cockpit will automatically be configured to connect using the IP address of the connection to BlueOS. +Cockpit generally automatically finds and/or connects to your vehicle: +- When run as a BlueOS Extension, Cockpit will automatically be configured to connect using the IP address of the connection to BlueOS. +- When run as a standalone application, there is a vehicle discovery process for detecting BlueOS vehicles on your network: +{{ easy_image(src="vehicle-discovery", width=400, center=true) }} -If that address changes during operating (or if Cockpit is run as a standalone application) it may be necessary to configure the -global vehicle address, MAVLink2REST address, and WebRTC signalling server address so that Cockpit knows the correct connection -points for the vehicle. After address configuration it is necessary to refresh the page. +If that address changes while operating, or your vehicle is not running BlueOS, it may be necessary to configure the global vehicle +address, and potentially also the more specific backend server addresses to connect to MAVLink2REST and the WebRTC video signalling +server (e.g. from MAVLink Camera Manager), so that Cockpit knows the correct connection points for the vehicle. -To access the configuration section, open the burger menu in the top left, and select "Configuration". +To access the configuration section, open the left sidebar, and select `Settings / General`: {{ easy_image(src="general-config", width=500, center=true) }} +If necessary, there are some additional details [in the advanced usage documentation](../advanced/#general). + ## Interface Setup ### Visual Display -By default, the interface of Cockpit is set up with three [views](../advanced/#views): + +Once connected to a vehicle, Cockpit loads a [profile](../advanced/#profiles) with a default set of interface +[views](../advanced/#views) that are relevant for the vehicle type. These should serve as a reasonable starting +point, which you can then [customise](../advanced/#edit-mode) to suit your specific use-cases and preferences. + +#### MAVs / QuadCopters + +Micro-aerial vehicles start out with an interface similar to other control station softwares, with +- a map +- basic tracking of the connection details and notifications +- on-screen control options to arm, take off, and change flight modes, and +- some telemetry widgets to track the vehicle altitude and attitude + +{{ easy_image(src="mav-map-view", width=600, center=true) }} + +#### Rovers / Boats + +The default interface for rovers and boats is similar to the MAV one, but with the bottom bar altitude tracking +swapped for a GPS speed widget: + +{{ easy_image(src="boat-map-view", width=600, center=true) }} + +#### ROVs / Submarines + +Cockpit was first developed for ROVs, and there are three starting views built in: + 1. Video view - 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 + - Useful for first-person control, focused on what the vehicle can see -{{ easy_image(src="video-view", width=600, center=true) }} +{{ easy_image(src="sub-video-view", width=600, center=true) }} 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 + - An alternative for first-person control of a vehicle, focused on precision maneuvering -{{ easy_image(src="hud-view", width=600, center=true) }} +{{ easy_image(src="sub-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) }} - -The available views and the widgets within them (including sizing and placement) can be configured as described in the -[advanced usage documentation](../advanced/#edit-mode). +{{ easy_image(src="sub-map-view", width=600, center=true) }} ### Joystick Configuration -For vehicles controlled via a joystick, button and axis mappings can be set by clicking the burger menu (top left), then selecting -"Configuration" and navigating to the Joystick tab. +For vehicles controlled via a joystick, [button and axis function mappings](../advanced/#joysticks) can be set through the +`Settings / Joystick` section of the left sidebar: {{ easy_image(src="joystick-config", width=500, center=true) }} ## Vehicle Setup Cockpit does not currently contain vehicle configuration or calibration functionalities. It is recommended to perform these in advance, -using either the BlueOS web interface and/or an alternative control station software like QGroundControl. +using either [the BlueOS web interface](https://blueos.cloud/docs/latest/usage/advanced/#vehicle-setup) and/or an alternative control +station software like QGroundControl. + +## Operation -It is possible to switch between Mission Planning and Flight displays via the burger menu in the top left. +Once you're ready to operate your vehicle, you can get started with remote control, or switch between the +[Mission Planning](../advanced/#mission-planning) and Flight displays via the left sidebar. diff --git a/content/usage/getting-started/joystick-config.png b/content/usage/getting-started/joystick-config.png index 6c17032..7a5c60a 100644 Binary files a/content/usage/getting-started/joystick-config.png and b/content/usage/getting-started/joystick-config.png differ diff --git a/content/usage/getting-started/map-view.png b/content/usage/getting-started/map-view.png deleted file mode 100644 index 07cf281..0000000 Binary files a/content/usage/getting-started/map-view.png and /dev/null differ diff --git a/content/usage/getting-started/mav-map-view.png b/content/usage/getting-started/mav-map-view.png new file mode 100644 index 0000000..a5532b8 Binary files /dev/null and b/content/usage/getting-started/mav-map-view.png differ diff --git a/content/usage/getting-started/sub-hud-view.png b/content/usage/getting-started/sub-hud-view.png new file mode 100644 index 0000000..54a8d0b Binary files /dev/null and b/content/usage/getting-started/sub-hud-view.png differ diff --git a/content/usage/getting-started/sub-map-view.png b/content/usage/getting-started/sub-map-view.png new file mode 100644 index 0000000..8cca206 Binary files /dev/null and b/content/usage/getting-started/sub-map-view.png differ diff --git a/content/usage/getting-started/sub-video-view.png b/content/usage/getting-started/sub-video-view.png new file mode 100644 index 0000000..13c508c Binary files /dev/null and b/content/usage/getting-started/sub-video-view.png differ diff --git a/content/usage/getting-started/tutorial.png b/content/usage/getting-started/tutorial.png new file mode 100644 index 0000000..f75f666 Binary files /dev/null and b/content/usage/getting-started/tutorial.png differ diff --git a/content/usage/getting-started/vehicle-discovery.png b/content/usage/getting-started/vehicle-discovery.png new file mode 100644 index 0000000..29d463a Binary files /dev/null and b/content/usage/getting-started/vehicle-discovery.png differ diff --git a/content/usage/getting-started/video-view.png b/content/usage/getting-started/video-view.png deleted file mode 100644 index 98755e7..0000000 Binary files a/content/usage/getting-started/video-view.png and /dev/null differ diff --git a/content/usage/installation.md b/content/usage/installation.md index 19bfe28..0cefacc 100644 --- a/content/usage/installation.md +++ b/content/usage/installation.md @@ -1,7 +1,7 @@ +++ title = "Installation" description = "Cockpit installation instructions." -date = 2023-08-25T12:00:00+11:00 +date = 2024-12-30T04:30:00+11:00 template = "docs/page.html" sort_by = "weight" weight = 10 @@ -19,7 +19,7 @@ and an IP-based (wifi / ethernet tether) connection to the [Control Station Comp Cockpit [is available](https://docs.bluerobotics.com/BlueOS-Extensions-Repository/#:~:text=Cockpit,-Maintainer) as a [BlueOS Extension](https://blueos.cloud/docs/blueos/latest/extensions). -### Updates +### Extension Updates Once installed, updating to a new Cockpit version can be done via the "Installed" tab of the BlueOS [Extensions Manager](https://blueos.cloud/docs/blueos/latest/advanced-usage/#extensions-manager). @@ -27,5 +27,94 @@ Once installed, updating to a new Cockpit version can be done via the "Installed ## Self-Contained Application -In future, Cockpit will also be available as a self-contained Electron application, which can be stored on a Control Station +Cockpit is also available as a self-contained Electron application, which can be stored on a Control Station Computer and started up for connection to a vehicle. + +The latest available release is + +[![Latest Stable](https://img.shields.io/github/v/release/bluerobotics/cockpit.svg?label=Cockpit) ![Date](https://img.shields.io/github/release-date/bluerobotics/cockpit?label=Date)](https://github.com/bluerobotics/cockpit/releases/latest) + +Download the latest version for your operating system here: + +{% horizontal_scroll(width="750px") %} +| Operating System | x86_64 | arm64 | +| --- | --- | --- | +| Windows | Cockpit.exe | Not available | +| macOS[ยน](#1) | Cockpit-Intel.dmg | Not yet available, use x86_64 version | +| iOS / iPadOS | N/A | use the BlueOS Extension in a browser | +| Linux | Cockpit-x86_64.AppImage
Cockpit-x86_64.flatpak | Cockpit-arm64.AppImage
Cockpit-arm64.flatpak | +| Android | N/A | use the BlueOS Extension in a browser | +{% end %} + +or check the [releases](https://github.com/bluerobotics/cockpit/releases), for a list of all available versions, and the main changes between them. + +[^1]: Cockpit is not yet registered with Apple, so may get flagged as a potential security threat. For now, the first open on macOS may require + right-clicking Cockpit in your Applications folder, selecting "Open", then choosing to "Open anyway" if prompted, or opening the security + preferences and scrolling down to "Allow" opening if there is no prompt. + + +### Application Updates + +The Cockpit application checks for new versions each time it opens, and if the latest available version +is newer than the installed one, it provides some information about the new release, and a button for if +you want to download and install it. + + diff --git a/content/usage/overview/index.md b/content/usage/overview/index.md index f7e6843..81fba57 100644 --- a/content/usage/overview/index.md +++ b/content/usage/overview/index.md @@ -1,7 +1,7 @@ +++ title = "Overview" description = "Cockpit overview." -date = 2024-09-03T04:30:00+10:00 +date = 2025-01-08T21:30:00+11:00 template = "docs/page.html" sort_by = "weight" weight = 0 @@ -21,31 +21,51 @@ top = false The existing market for control station software is missing an option that's readily available, easy to use, versatile, easy to customise and develop for, and cross-platform. In response to this need, and fueled by years of inspirations for what a truly great control station could be, Cockpit is Blue Robotics' next-generation control interface, for thrusting your vehicle control experience into the future. -## Availability +## Availability and Limitations -Cockpit is currently publicly available [as a BlueOS Extension](https://docs.bluerobotics.com/BlueOS-Extensions-Repository#:~:text=Cockpit,-Maintainer) (requires BlueOS >= 1.1). It is still in an initial development phase, and will not be actively supported until it is officially released. +[Cockpit is open source](https://github.com/bluerobotics/cockpit), and is free to install and use. -The source code is available [on GitHub](https://github.com/bluerobotics/cockpit), -under [two possible licenses](https://github.com/bluerobotics/cockpit/tree/master/LICENSE.md). +It is currently available as: +1. [a BlueOS Extension](https://docs.bluerobotics.com/BlueOS-Extensions-Repository#:~:text=Cockpit,-Maintainer) (requires BlueOS >= 1.1) + - with an interface that runs in a web browser, on almost any web-capable device (including mobiles and VR headsets) +1. [a standalone application](../installation#self-contained-application) + - built for Windows, macOS, and Linux (including SteamOS) + - we are looking into also making it available on iOS and android + - includes some additional features, and may run more reliably + - if connected to a non-BlueOS vehicle, requires external server software to communicate in the formats it expects + - e.g. [MAVLink Server](https://github.com/bluerobotics/mavlink-server) + and [MAVLink Camera Manager](https://github.com/mavlink/mavlink-camera-manager) + +### Try it! + +0. โฏ๏ธ [Watch the usage introduction video](#usage-introduction-video) +1. ๐ŸŒ [Run a browser-served version](https://docs.bluerobotics.com/cockpit), to play with the latest state of the interface + - Opens instantly + - Has no vehicle connected, so widgets don't display meaningful data +1. ๐ŸŽฎ [Run a full vehicle simulation with BlueOS](https://blueos.cloud/bluesim), to test the control process and effectiveness of different views + - Can take several minutes to start and connect to the virtual machine + - Can get behind on updates, so may not be running the latest Cockpit and/or BlueOS version +1. ๐Ÿš€ [Install your own copy](../installation) ## Primary Feature List - Browser-based control station software, for vehicle control and monitoring from any web-capable device -- Widget-based layout system, with freeform positioning and resizing +- [Widget](../advanced/#widgets)-based layout system, with freeform positioning and resizing + - Widgets can display generic input, including custom MAVLink `NAMED_VALUE_FLOAT`/`_INT` messages - Custom display [Views](../advanced/#views), for interface pages/profiles that can be switched between - Different browser windows/screens/devices can independently select which view to display - Views are downloadable and can be shared (json contains name and list of components and widget settings) -- MAVLink `NAMED_VALUE_FLOAT`/`_INT` messages are self-registering for use in [mini-widgets](../advanced/#mini-widgets) (including custom ones!) -- WebRTC-based [video widget](../advanced/#video) +- WebRTC-based [video widget](../advanced/#video-widgets) - Multiple widgets can be added to support arbitrary numbers of video streams - - Includes video recording support, on the display device + - Includes video recording support on the display device, with + [subtitle files of telemetry](../advanced/#telemetry-logs-subtitle-files) - [Map widget](../advanced/#map) - - Provides position tracking - - Allows planning (and saving/loading) autonomous missions + - Provides position tracking and guiding + - Allows [planning](../advanced/#mission-planning) (and saving/loading) autonomous missions - Allows mission control - - In future will allow setting the current vehicle position, and clicking to guide the vehicle to new positions -- Customisable Actions mappable to user inputs (e.g. joysticks, and key presses / screen clicks in future) - - Actions can send commands to the vehicle, or can trigger local events like view switching and starting video recording +- Versatile [Actions system](../advanced/#cockpit-actions-1), mappable to user inputs through joystick actions and + on-screen elements + - Actions can send commands to the vehicle, or trigger local events like view switching and starting video recording - Includes support for simultaneous input from multiple sources (including multiple joysticks) - [Joysticks](../advanced/#joysticks) of _any_ type can be configured - Buttons and axes can be mapped to arbitrary Actions @@ -53,3 +73,25 @@ under [two possible licenses](https://github.com/bluerobotics/cockpit/tree/maste - Displays autopilot (MAVLink `STATUSTEXT`) and application alerts - Includes text to speech announcements - [Mission naming](../advanced/#mission-name) used on the interface and video save filenames + +## Quick Links + +1. [Documentation](@/_index.md) +2. [Source code](https://github.com/bluerobotics/cockpit) +3. [Releases, changelogs, files](https://github.com/bluerobotics/cockpit/releases) + +## Community + +### Discussions and Support + +- [Discussion Forum](https://discuss.bluerobotics.com/c/bluerobotics-software/cockpit/91) +- [Issues and Feature Requests](https://github.com/bluerobotics/cockpit/issues) +- [Chat (Discord)](https://discord.gg/mFgvxhCDrv) + +### Usage Introduction Video +`Phil Parisi (October 2024) - Supported by Blue Robotics` + + +### Developer Presentations +`ArduPilot Developers Conference (October 2024)` +