[Docs] [Bug] OSD is not documented

[hamishwillee]

Describe the bug

Just saw #25233, which requests a full implementation.

Before we do that, it would be great to have any documentation on what is supported w.r.t. OSD.

All we have now is

• information on setting the OSD mavlink stream in https://docs.px4.io/main/en/peripherals/mavlink_peripherals.html
• OSD parameters https://docs.px4.io/main/en/advanced_config/parameter_reference.html#osd
• Module with no useful information https://docs.px4.io/main/en/modules/modules_driver.html#msp-osd
• Reptile dragon info https://docs.px4.io/main/en/frames_plane/reptile_dragon_2.html#msp-osd-module

What we need is a page on MSP OSD - what is it? How does it differ from other OSD? What modules support this "whatever it is"? How do you wire them into PX4?

Warning

"an undocumented feature does not exist".

Page URL

No response

Screenshot / Media

No response

[SolderSyntax]

Should we have a dedicated OSD page under docs.px4.io/main/peripherals?

I think most of the OSD parameters are clear enough, although I'm not completely sure all of them are being used.

The actual setup of OSD depends on the type. MSP OSD uses serial communication over any uart, so connection wise it's the same. Setting it up in PX4 is pretty straight forward with the module's parameters.

As for the MSP OSD module - I have to spend some time getting familiar with before I can add anything (code or documentation).

Mavlink OSD stream mode is not configurable - it's hard coded as seen here. If we'll have an OSD page for PX4 we can mention it over there, as an option. I also don't have any example for devices that implement OSD with Mavlink data.

[hamishwillee]

Thanks @SolderSyntax

Should we have a dedicated OSD page under docs.px4.io/main/peripherals?

Yes.

The structure would depend on what we document, but minimally it would be

• Hardware Hardware Selection & Setup
  • On Screen Display (OSD)

The OSD page describes what classes of OSD there are.

• If all hardware setup is common for different types it contains that too.
• If all PX4 configuration is the same for all types it contains that too.
• If there are no sub documents it contains lists of different devices

If there are different types of OSD with different setup then the the doc might grow to two levels, each with their own setup.

• Hardware Hardware Selection & Setup
  • On Screen Display (OSD)
    • MSP OSD
    • "Other OSD"

This then extends one more level to specific devices if needed. By way of example see https://docs.px4.io/main/en/sensor/optical_flow.html and https://docs.px4.io/main/en/sensor/pmw3901.html

The actual setup of OSD depends on the type. MSP OSD uses serial communication over any uart, so connection wise it's the same. Setting it up in PX4 is pretty straight forward with the module's parameters.

Awesome. Sounds like we might have the structure with OSD and MSP OSD as separate topics. But if the setup of MSP OSD is different it would all be int hat doc.

Mavlink OSD stream mode is not configurable - it's hard coded as seen here. If we'll have an OSD page for PX4 we can mention it over there, as an option. I also don't have any example for devices that implement OSD with Mavlink data.

So MSP just uses its own kind of data? IN that case we'd probably just have a thin "MAVLink OSD doc" or a section in the top level doc explaining the option.

Do you have an interest in kicking this off?

[SolderSyntax]

Yes, I can get something going.
I'd have to get myself familiar with how the Docs are written and built.

[hamishwillee]

@SolderSyntax There are some guidelines here https://docs.px4.io/main/en/contribute/docs.html but actually it is quite easy.

1. Docs are in the PX4 source tree - they are source code in markdown under /docs/en/<somefolder>
2. So you create files just like source. In this case you might copy the optical flow markdown file into /en/perhipherals as a starting point.
3. To make the doc appear in the sidebar you add a link in the pattern in docs/en/SUMMARY.md

You can test building by installing node - greater than version 22 (I use nvm to install node versions as needed). Then install yarn globally (node install yarn -g, then go to the /docs/ directory and enter yarn start`. That's it. Otherwise it is just code.