diff --git a/content/usage/advanced/custom-javascript-action.png b/content/usage/advanced/custom-javascript-action.png index b7bb3da..41fb890 100644 Binary files a/content/usage/advanced/custom-javascript-action.png and b/content/usage/advanced/custom-javascript-action.png differ diff --git a/content/usage/advanced/default-map-position.png b/content/usage/advanced/default-map-position.png new file mode 100644 index 0000000..e5df616 Binary files /dev/null and b/content/usage/advanced/default-map-position.png differ diff --git a/content/usage/advanced/depth-mini-widget.png b/content/usage/advanced/depth-mini-widget.png index f097220..1c7021b 100644 Binary files a/content/usage/advanced/depth-mini-widget.png and b/content/usage/advanced/depth-mini-widget.png differ diff --git a/content/usage/advanced/diy-widget-config.png b/content/usage/advanced/diy-widget-config.png new file mode 100644 index 0000000..8152abe Binary files /dev/null and b/content/usage/advanced/diy-widget-config.png differ diff --git a/content/usage/advanced/edit-mode.png b/content/usage/advanced/edit-mode.png index 4d9627a..e94ffdb 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/external-widget-example.png b/content/usage/advanced/external-widget-example.png new file mode 100644 index 0000000..43e7950 Binary files /dev/null and b/content/usage/advanced/external-widget-example.png differ diff --git a/content/usage/advanced/index.md b/content/usage/advanced/index.md index 64105ad..9305445 100644 --- a/content/usage/advanced/index.md +++ b/content/usage/advanced/index.md @@ -1,7 +1,7 @@ +++ title = "Advanced Usage" description = "Cockpit advanced usage documentation." -date = 2025-01-08T19:05:00+11:00 +date = 2025-01-22T01:00:00+11:00 template = "docs/page.html" sort_by = "weight" weight = 30 @@ -26,20 +26,22 @@ top = false 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. Mini-widget containers, including the top and bottom 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 +### Top Bar -The header bar is consistent across [Views](#views), and is usually used for displaying +The top bar is consistent across [Views](#views), and is usually used for displaying [mission information](#mission-information) mini-widgets and [connection statuses](#connection-statuses). -### Footer Bar +During operation, it can be toggled between hidden and shown using a [Cockpit Action](#cockpit-actions-1). + +### Bottom Bar -The footer bar is unique to each View, and is generally used to display [indicators](#very-generic-indicators) +The bottom 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). @@ -196,9 +198,9 @@ export the desired view(s) from one and import them into the other(s). {{ 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 + - Clicking on the cog settings icon allows renaming a view, and determining whether the bottom bar is shown or hidden/docked when Cockpit boots - - It is always possible to toggle the current footer bar visibility using + - It is always possible to toggle the current bottom bar visibility using [Cockpit Actions](#cockpit-actions) (e.g. via a joystick button) {{ easy_image(src="view-config", width=400, center=true) }} - The "Widgets in View" list allows @@ -211,9 +213,9 @@ export the desired view(s) from one and import them into the other(s). - New widgets can be added via the bottom section - 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 + - Mini widgets have fixed sizes, but can be dragged and dropped into the desired location in the top/bottom 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 top 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), @@ -226,9 +228,9 @@ There are several types of widgets available, including different displays of th - 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) + - They can be in the shared top bar, or in the View-specific bottom 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) + - They can be in the shared top bar, or in the View-specific bottom bar or a [container widget](#container-widgets)
{{ easy_image(src="widgets-variety", width=650) }} @@ -460,15 +462,15 @@ There are buttons [Mission Planning](#mission-planning) is documented in a dedicated section. {% end %} -Configuration allows showing or hiding a trail of the vehicle's path over time. +Configuration allows showing or hiding a trail of the vehicle's path over time: {{ 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). +and clicking the GoTo option), and setting the [default map position](#default-map-position): -{{ easy_image(src="goto", width=100, center=true) }} +{{ easy_image(src="map-click-options", width=200, 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. @@ -564,6 +566,48 @@ This is particularly useful for showing the interfaces and displays of IP camera 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) }} +###### Automatic External IFrames + +HTTP Servers that provide a `register_service` endpoint (e.g. +[BlueOS Extensions](https://blueos.cloud/docs/latest/development/extensions/#web-interface-http-server)) +can provide one or more URLs for Cockpit to automatically detect and present as External IFrame widgets: + +{{ easy_image(src="external-widget-example", width=200) }} + +The `register_service` endpoint should include a `"cockpit"` key in its `"extras"` dictionary, pointing to +an endpoint listing the available widgets: + +`/register_service` +```json +{ + ... + "extras":{ + "cockpit":"/cockpit_extras.json" + } +} +``` + +The Cockpit-focused endpoint should including a name, version, iframe URL, and an optional URL for +configuration of each widget: + +`cockpit_extras.json` +```json +{ + "target_system":"Cockpit", + "target_cockpit_api_version":"1.0.0", + "widgets":[ + { + "name":"ExternalWidgetName", + "config_iframe_url":null, + "iframe_url":"/path/to/widget/page", + "version":"1.3.8" + } + ] +} +``` + +If no configuration URL is provided, the standard [IFrame Widget](#iframe) configuration options apply. + ##### Image Viewer The image viewer widget shows an image that is accessible to the control station computer via its network. @@ -587,15 +631,27 @@ The plotter widget allows plotting data on a graph: Configuration options are provided for selecting the variables to plot, and modifying basic appearance characteristics: -{{ easy_image(src="plotter-config", width=400, center=true) }} +{{ easy_image(src="plotter-config", width=450, center=true) }} + +It is possible to change the decimal resolution of the displayed statistics, and the limit the number +of plotted samples to improve visibility and performance. {% 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). +The data lake which the widget gets its data from by default provides access to the Cockpit memory +usage, MAVLink message fields, and values added from [Custom Actions](#custom-actions). It will soon be +connected to the BlueOS-specific options available to +[Very Generic Indicators](#very-generic-indicators) as well. {% end %} +#### Do It Yourself Widget + +- Completely custom elements, code logic, and styling +{{ easy_image(src="diy-widget-config", width=550, center=true) }} +- Runs code automatically when Cockpit starts/refreshes + - Unlike [Custom Actions](#custom-actions), which need to be triggered to run +- Can listen to, create, and modify data lake variables, and register and/or execute Actions using the + Cockpit API (`window.cockpit.*`) + #### Container Widgets Regular widgets for storing [mini widgets](#widgets) and [input widgets](#input-widgets) in the main @@ -620,10 +676,10 @@ Input widgets should be placed in a [container widget](#container-widgets), and 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). +set variables for use as parameters in [Custom Actions](#custom-actions). ##### Action Buttons -Buttons can trigger a specified Action (currently only [Custom HTTP Actions](#custom-actions)) when pressed. +Buttons can trigger a specified Action when pressed. {{ easy_image(src="button-input", width=120, center=true) }} {{ easy_image(src="button-input-config", width=250, center=true) }} @@ -875,6 +931,25 @@ These features help with error tracking and troubleshooting, so in normal use ca - If system logs are disabled then messages are sent to the browser/application console instead, which may reduce performance +### MAVLink Inspection + +While it is possible to persistently monitor individual MAVLink message fields using +[Very Generic Indicators](#very-generic-indicators) or [data plotting widgets](#data-plotting), the MAVLink inspector +tab allows temporarily monitoring a small number of full MAVLink messages: + +{{ easy_image(src="mavlink-inspector", width=600) }} + +- Both incoming and outgoing message instances can be monitored +- Pressing "Reset" clears the currently monitored messages + +{% note() %} +It may be possible to access more detailed MAVLink inspection and tracking interfaces through the software that is +routing MAVLink messages to Cockpit. BlueOS includes a built in +[MAVLink Inspector](https://blueos.cloud/docs/latest/usage/advanced/#mavlink-inspector), and if [using MAVLink Server +as the router](https://blueos.cloud/docs/latest/usage/advanced/#mavlink-endpoints) there is a detailed debugging +interface provided. +{% end %} + ### Missions and Safety While autopilots often include built in failsafes and pre-arming checks, it can also be useful for the operator's @@ -900,6 +975,14 @@ If you want a similar feature for joystick button functions, consider assigning can be triggered. {% end %} +#### Default Map Position + +For convenience, it is possible to persistently set the default map position and zoom level: + +{{ easy_image(src="default-map-position", width=500) }} + +This can be useful before a specific mission, or just to get the map to start near typical operating regions. + ### Cockpit Actions Cockpit's Action system provides a set of functionalities that can be triggered from any of Cockpit's @@ -911,6 +994,7 @@ There are some predefined Actions built into Cockpit for convenience, including: - `go_to_next_view` - `go_to_previous_view` - `toggle_bottom_bar` +- `toggle_top_bar` - `toggle_full_screen` - `hold_to_confirm` - `start_recording_all_streams` @@ -975,11 +1059,11 @@ Using a hidden View allows configuring mini-widgets for any variables you want t display during operation. {% end %} -It is possible to configure which variables are logged and where they appear in the generated subtitle files -using the [telemetry settings](#telemetry). +It is possible to configure the logging frequency, as well as 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. +When a video recording completes, a corresponding subtitle file is generated by slicing the raw log from the +start to end timestamps of the video. {% note() %} Recorded video and subtitles are in separate files, so the browser will typically ask for permission to "download diff --git a/content/usage/advanced/interface-overview.png b/content/usage/advanced/interface-overview.png index 64cdfcb..6f961ea 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/map-click-options.png b/content/usage/advanced/map-click-options.png new file mode 100644 index 0000000..113fc24 Binary files /dev/null and b/content/usage/advanced/map-click-options.png differ diff --git a/content/usage/advanced/mavlink-inspector.png b/content/usage/advanced/mavlink-inspector.png new file mode 100644 index 0000000..15793f7 Binary files /dev/null and b/content/usage/advanced/mavlink-inspector.png differ diff --git a/content/usage/advanced/plotter-config.png b/content/usage/advanced/plotter-config.png index a4b5a67..ecff79f 100644 Binary files a/content/usage/advanced/plotter-config.png and b/content/usage/advanced/plotter-config.png differ diff --git a/content/usage/advanced/settings-menu.png b/content/usage/advanced/settings-menu.png index b2f0b51..95d026a 100644 Binary files a/content/usage/advanced/settings-menu.png and b/content/usage/advanced/settings-menu.png differ diff --git a/content/usage/getting-started/tutorial.png b/content/usage/getting-started/tutorial.png index f75f666..f60d8d5 100644 Binary files a/content/usage/getting-started/tutorial.png and b/content/usage/getting-started/tutorial.png differ diff --git a/content/usage/overview/index.md b/content/usage/overview/index.md index 81fba57..8960b35 100644 --- a/content/usage/overview/index.md +++ b/content/usage/overview/index.md @@ -1,7 +1,7 @@ +++ title = "Overview" description = "Cockpit overview." -date = 2025-01-08T21:30:00+11:00 +date = 2025-01-22T00:45:00+11:00 template = "docs/page.html" sort_by = "weight" weight = 0 @@ -52,6 +52,7 @@ It is currently available as: - Browser-based control station software, for vehicle control and monitoring from any web-capable device - [Widget](../advanced/#widgets)-based layout system, with freeform positioning and resizing - Widgets can display generic input, including custom MAVLink `NAMED_VALUE_FLOAT`/`_INT` messages + - [Externally provided widgets](../advanced/#automatic-external-iframes) can be detected and included automatically - 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) @@ -63,6 +64,9 @@ It is currently available as: - Provides position tracking and guiding - Allows [planning](../advanced/#mission-planning) (and saving/loading) autonomous missions - Allows mission control +- [Do It Yourself widget](../advanced/do-it-yourself-widget) + - Provides complete control over the widget contents, styling, and functionality + - Integrates with Cockpit's data lake, and Actions system - 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