Add documentation for adding a widget icon by rutger-seascape · Pull Request #41 · bluerobotics/Cockpit-docs

rutger-seascape · 2026-04-29T13:55:24Z

🔎 PREVIEW 🔍

Documents:

Widgets: add support for Widget discovery from BlueOS cockpit#1499
- icon specification API for automatic external iframes was missed in the initial documentation

rafaellehmkuhl

Hey Rutger! Thanks a lot for this contribution!

And this API was actually broken recently (during the 1.18 beta phase), as we still didn't had anyone using it (only two internal extensions that were still in beta as well).

The standard changed from snake_case to camelCase, so the new fields are called iframeUrl and iframeIcon. You can find the whole schema in this file of the Cockpit repository.

You can find the discussion about those changes as well as the new features that were added here.

rutger-seascape · 2026-04-30T14:41:46Z

Hey @rafaellehmkuhl ,

Thanks for your answer :). Check, very cool pull request you added, did not know this was in the works. This gives some possibilities for my own extension. Should I also add documentation for the joystick mapping suggestions?

ES-Alexander · 2026-04-30T15:22:37Z

Should I also add documentation for the joystick mapping suggestions?

If you'd like to cover the surrounding feature set, you can document some or all of the undocumented aspects of the external integrations topic :-)

rafaellehmkuhl · 2026-04-30T17:27:10Z

Hey @rafaellehmkuhl ,

Thanks for your answer :). Check, very cool pull request you added, did not know this was in the works. This gives some possibilities for my own extension. Should I also add documentation for the joystick mapping suggestions?

Feel free to choose how to proceed. If you want to just finish this one with the instructions for the icon and url, which is the basic support, that's fine. If you want to document the whole API, even better!

rutger-seascape · 2026-05-01T15:43:31Z

Thanks for your replies. I will look into covering the whole cockpit_extras.json file.

…as endpoint

…s endpoint

…ps to your cockpit_extras endpoint

rutger-seascape · 2026-05-05T13:49:06Z

Hey @rafaellehmkuhl ,

Could you have a look at my recent changes? I have documented the new cockpit_extras API according to the schema you sent me and I used some other pieces of text/information I found in different Blue Robotics repositories. I think it would be nice to have some screenshots of the joystick mapping suggestions, do you have any at hand by chance?

rafaellehmkuhl · 2026-05-06T16:43:38Z

Hey @rafaellehmkuhl ,

Could you have a look at my recent changes? I have documented the new cockpit_extras API according to the schema you sent me and I used some other pieces of text/information I found in different Blue Robotics repositories. I think it would be nice to have some screenshots of the joystick mapping suggestions, do you have any at hand by chance?

Super cool @rutger-seascape! That's a really nice start! I took a look and I will try to wrote down the suggestions till friday. Sorry. for the delay. I usually try to do it in the same day but we are kind of in a rush right now with the stable release. And @ES-Alexander is the responsible for the docs, so I'm sure he will have some suggestions as well!

rafaellehmkuhl · 2026-05-06T16:46:45Z

And here are the images you requested:

.

rafaellehmkuhl · 2026-05-06T18:07:06Z

@rutger-seascape I got some spare time and was starting my review but unfortunately there is (again) a Github incident happening right now and I'm not being able to push the comments in the review. Will try again in the next hours.

ES-Alexander

Agreed that this is a great start - thanks!

I've given some comments on the high level structure and some missing contextualisation.

Given the "no relevant docs" state this is based over, the threshold for this getting approved is basically just "fit the style/intent of the docs, and don't mislead users", so I'm not planning to ask for exhaustive coverage of everything involved (though by the looks of things you've already largely achieved full coverage anyway!) :-)

ES-Alexander · 2026-05-07T02:09:32Z


-The Cockpit-focused endpoint should including a name, version, iframe URL, and an optional URL for
-configuration of each widget:
+#### Configuring cockpit_extras.json


This heading is several levels too high to be in this location, but I actually think the problem is the location. There are several examples here that go beyond what normal users would need to know or care about, so I suggest moving this whole section to its own file (e.g. /content/development/external-integrations/index.md, with the images in the same folder), which can then link back to relevant points in this file from each subsection.

This location can then be used to link out to that file, for developers who want to explore the detailed breakdown/examples, without it affecting the standard users.

ES-Alexander · 2026-05-07T02:12:59Z

+You can make your BlueOS Extension interact with different elements within the Blue Robotics software suite by configuring
+the `cockpit_extras.json` file. Keys are typed in `lowerCamelCase`. We recommend to type id values in `kebab-case`.


HTTP servers do not need to be from BlueOS Extensions - they could also be served by the computer running Cockpit, for example, or accessed via the internet (for operating conditions where that is viable).

If this gets introduced specifically as an example of making a BlueOS Extension integrate with Cockpit then that's potentially ok, but if it's intended just as a description of the functionality then it will need to be more general about the possible options.

ES-Alexander · 2026-05-07T02:15:57Z

+```
+
+##### Minimal configuration
+A minimal `cockpit_extras.json` file can be seen below. This file does not add any extra functionality yet.


It seems worthwhile describing the key functionalities (e.g. custom iframe widget integrations, custom Actions, and custom joystick button mapping suggestions) before providing an example like this, but that can potentially be at the top of the page.

ES-Alexander · 2026-05-07T02:17:18Z

+##### Widget configuration
+You can add widgets to Cockpit based on your BlueOS Extension by adding a widget configuration.
+
+| Attribute                   | Type      | Required | Note                           |


If the table has no notes, it shouldn't include a column for them.

ES-Alexander · 2026-05-07T02:19:20Z

+| `iconUrl`                   | `string`  | no[^1]   |                                |
+| `iframeIcon`                | `string`  | no[^1]   |                                |


ES-Alexander · 2026-05-07T02:25:11Z

+Each joystick profile tracks its own set of applied and ignored suggestions independently.
+
+###### Joystick Mapping Suggestion Group
+[Joystick Mapping Suggestions](#joystick-mapping-suggestion) must be contained in a Joystick Mapping Suggestion Group. This allows you to suggest multiple mappings based on what hardware is mounted for example.


Suggested change

[Joystick Mapping Suggestions](#joystick-mapping-suggestion) must be contained in a Joystick Mapping Suggestion Group. This allows you to suggest multiple mappings based on what hardware is mounted for example.

[Joystick Mapping Suggestions](#joystick-mapping-suggestion) must be contained in a Joystick Mapping Suggestion Group. This allows you to suggest multiple mappings based on what hardware is connected, for example.

Co-authored-by: ES-Alexander <sandman.esalexander@gmail.com>

rutger-seascape · 2026-05-07T15:07:45Z

Hey @rafaellehmkuhl and @ES-Alexander ,

Thanks for your response, feedback and images!

@rutger-seascape I got some spare time and was starting my review but unfortunately there is (again) a Github incident happening right now and I'm not being able to push the comments in the review. Will try again in the next hours.

No problem, it has been wild recently...

I suggest moving this whole section to its own file (e.g. /content/development/external-integrations/index.md, with the images in the same folder)

I did this and I also added an overview page to the development section but it feels a bit sparse right now, any suggestions?

I have tried to incorporate the other comments as well, can you let me know what you think?

ES-Alexander

Nice improvements, thanks!

it feels a bit sparse right now

Not too concerned about that - we've got to start somewhere, and extra content can always be filled in when there's time and motivation/resourcing to do so.

The development overview can likely take inspiration from the BlueOS-docs one, but I think that's better left for a later PR so we can get these docs in sooner :-)

I have tried to incorporate the other comments as well, can you let me know what you think?

Generally reasonable - nice work :-)

I've just added a few more comments around cohesion and trying to more logically differentiate what a user vs a developer would care about knowing.

ES-Alexander · 2026-05-08T22:09:22Z

@@ -643,27 +643,7 @@ an endpoint listing the available widgets:
 }
 ```



I think all of this can go in the new development section, with an explanation that "External services can automatically share web interface URLs for Cockpit to turn into IFrame widgets, along with other features."

ES-Alexander · 2026-05-08T22:26:05Z

+++
+
+## Configuring cockpit_extras.json
+You can make HTTP servers interact with different elements within the Blue Robotics software suite by creating  a `/register_service` endpoint, click [here](@/usage/advanced/index.md#automatic-external-iframes) to view it's documentation. This endpoint serves a `cockpit_extras.json` file that will be explained in this section. HTTP servers can be served by [BlueOS Extensions](https://blueos.cloud/docs/stable/development/extensions/), the Cockpit host computer or by the internet (for operating conditions where that is viable).


Suggested change

You can make HTTP servers interact with different elements within the Blue Robotics software suite by creating a `/register_service` endpoint, click [here](@/usage/advanced/index.md#automatic-external-iframes) to view it's documentation. This endpoint serves a `cockpit_extras.json` file that will be explained in this section. HTTP servers can be served by [BlueOS Extensions](https://blueos.cloud/docs/stable/development/extensions/), the Cockpit host computer or by the internet (for operating conditions where that is viable).

## Informing Cockpit of Features

External applications and services can share a variety of integration features with Cockpit using a HTTP server.

It should include a [`register_service`](https://blueos.cloud/docs/latest/development/extensions/#web-interface-http-server) JSON endpoint, with a path to a Cockpit-focused JSON endpoint, e.g.

`/register_service`

```json

{

...

"extras":{

"cockpit":"/cockpit_extras.json"

}

}

\``` <-- remove the "\", had to add it for the review suggestion to work

This is often relevant for [BlueOS Extensions](https://blueos.cloud/docs/stable/development/extensions/) that need active interaction while the vehicle is being operated, but can also be provided by programs on the Cockpit host computer, or via the internet (for operating conditions where that is viable).

ES-Alexander · 2026-05-08T22:31:06Z

+| Attribute       | Type     | Required | Note                                                                                      |
+|-----------------|----------|----------|-------------------------------------------------------------------------------------------|
+| `name`          | `string` | yes      |                                                                                           |
+| `messageType`   | `string` | yes      | Click  [here](https://github.com/patrickelectric/mavlink-json)  to view the allowed types |


I agree, I was not sure of how to do it naturally. Your way sounds good.

Co-authored-by: ES-Alexander <sandman.esalexander@gmail.com>

…ection and restructure the paragraph Co-authored-by: ES-Alexander <sandman.esalexander@gmail.com>

…that is now described there Co-authored-by: ES-Alexander <sandman.esalexander@gmail.com>

rutger-seascape · 2026-05-11T08:33:58Z

Not too concerned about that - we've got to start somewhere, and extra content can always be filled in when there's time and motivation/resourcing to do so.

The development overview can likely take inspiration from the BlueOS-docs one, but I think that's better left for a later PR so we can get these docs in sooner :-)

Ah okay, that sounds good.

Thanks again for the kind words and feedback. I have updated the pull request with the requested changes, can you let me know what you think?

rafaellehmkuhl self-requested a review April 29, 2026 18:06

rafaellehmkuhl requested changes Apr 29, 2026

View reviewed changes

rutger-seascape added 5 commits May 5, 2026 15:39

Add documentation for adding a widget icon

4aeb76e

Update the documentation for adding widgets based on the cockpit_extr…

a731666

…as endpoint

Add documentation on how to add Cockpit Actions to your cockpit_extra…

388e34c

…s endpoint

Add documentation on how to add Joystick Mapping Suggestions and grou…

9fa3329

…ps to your cockpit_extras endpoint

Add a full example of using the new cockpit_extras API

4624200

rutger-seascape force-pushed the feature/auto-iframe-docs branch from e0dbbd4 to 4624200 Compare May 5, 2026 13:42

ES-Alexander requested changes May 7, 2026

View reviewed changes

rutger-seascape and others added 10 commits May 7, 2026 10:00

Move documentation for the cockpit_extras endpoint to it's own section

9f52696

Add metadata (front matter)

c9b2292

Describe the joystick mapping process more clearly

f6348ca

Co-authored-by: ES-Alexander <sandman.esalexander@gmail.com>

Add images

43d53b0

Add section

0607f9b

Add overview page

fce46dd

Change weight

3dee8c1

Change header levels

bea9cf1

Link to different section

e905e05

Update the documentation to be more verbose

5f53712

ES-Alexander requested changes May 8, 2026

View reviewed changes

Make the description more concise

83c8371

Co-authored-by: ES-Alexander <sandman.esalexander@gmail.com>

rutger-seascape and others added 3 commits May 11, 2026 10:23

Put documentation on the register_service endpoint in the developer s…

1a3a04e

…ection and restructure the paragraph Co-authored-by: ES-Alexander <sandman.esalexander@gmail.com>

Link to the development documentation section and remove information …

65c4e3e

…that is now described there Co-authored-by: ES-Alexander <sandman.esalexander@gmail.com>

Remove unused image

1c95e72

		You can make your BlueOS Extension interact with different elements within the Blue Robotics software suite by configuring
		the `cockpit_extras.json` file. Keys are typed in `lowerCamelCase`. We recommend to type id values in `kebab-case`.

		\| `iconUrl` \| `string` \| no[^1] \| \|
		\| `iframeIcon` \| `string` \| no[^1] \| \|

	[Joystick Mapping Suggestions](#joystick-mapping-suggestion) must be contained in a Joystick Mapping Suggestion Group. This allows you to suggest multiple mappings based on what hardware is mounted for example.
	[Joystick Mapping Suggestions](#joystick-mapping-suggestion) must be contained in a Joystick Mapping Suggestion Group. This allows you to suggest multiple mappings based on what hardware is connected, for example.

		@@ -643,27 +643,7 @@ an endpoint listing the available widgets:
		}
		```

-You can make HTTP servers interact with different elements within the Blue Robotics software suite by creating  a `/register_service` endpoint, click [here](@/usage/advanced/index.md#automatic-external-iframes) to view it's documentation. This endpoint serves a `cockpit_extras.json` file that will be explained in this section. HTTP servers can be served by [BlueOS Extensions](https://blueos.cloud/docs/stable/development/extensions/), the Cockpit host computer or by the internet (for operating conditions where that is viable).
+## Informing Cockpit of Features
+External applications and services can share a variety of integration features with Cockpit using a HTTP server.
+It should include a [`register_service`](https://blueos.cloud/docs/latest/development/extensions/#web-interface-http-server) JSON endpoint, with a path to a Cockpit-focused JSON endpoint, e.g.
+`/register_service`
+```json
+{
+   ...
+   "extras":{
+      "cockpit":"/cockpit_extras.json"
+   }
+}
+\``` <-- remove the "\", had to add it for the review suggestion to work
+This is often relevant for [BlueOS Extensions](https://blueos.cloud/docs/stable/development/extensions/) that need active interaction while the vehicle is being operated, but can also be provided by programs on the Cockpit host computer, or via the internet (for operating conditions where that is viable).

	\| `messageType` \| `string` \| yes \| Click [here](https://github.com/patrickelectric/mavlink-json) to view the allowed types \|
	\| `messageType` \| `string` \| yes \| [Allowed types](https://github.com/patrickelectric/mavlink-json) \|

Conversation

rutger-seascape commented Apr 29, 2026 • edited by ES-Alexander Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔎 PREVIEW 🔍

Uh oh!

rafaellehmkuhl left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rutger-seascape commented Apr 30, 2026

Uh oh!

ES-Alexander commented Apr 30, 2026

Uh oh!

rafaellehmkuhl commented Apr 30, 2026

Uh oh!

rutger-seascape commented May 1, 2026

Uh oh!

rutger-seascape commented May 5, 2026

Uh oh!

rafaellehmkuhl commented May 6, 2026

Uh oh!

rafaellehmkuhl commented May 6, 2026

Uh oh!

rafaellehmkuhl commented May 6, 2026

Uh oh!

ES-Alexander left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rutger-seascape commented May 7, 2026

Uh oh!

ES-Alexander left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rutger-seascape commented May 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rutger-seascape commented Apr 29, 2026 •

edited by ES-Alexander

Loading

rafaellehmkuhl left a comment •

edited

Loading