add page for PX4 ROS library #2740

bkueng · 2023-09-20T13:48:05Z

Documentation for PX4/PX4-Autopilot#20707.

Some bits are still missing & it needs integration with the other pages.

@hamishwillee if you want you can already take a first pass. @tstastny will go through the steps to see if anything is missing.

hamishwillee · 2023-09-21T01:48:56Z

@bkueng Housekeeping

I've done some formatting changes on this to my taste.
- Ran prettier and did my own normal layout changes. FYI now using VSCode and prettier to format by default - makes things a little less arbitrary.
- Moved doc to a /ros2/ sub folder. I'm intending to separate/move ROS2 sources into own folder over time, but might as well start with this. It just makes things a little easier to manage.
- Images are shrunk using lossless compressor and all grouped in same ros2 folder. Again, easier to manage.
- Took the typo error (interpretted) into main and rebased
Ignore the git bot flaw checker - it thinks some of the output logging is a reference link (a bug). I'll fix that eventually.
@beniaminopozzan Should review this doc as well when it is done.
As an aside, can we also have a separate additions on PX4 modes outside of ROS2? I can probably do this if I know:
- What standard modes we support: https://mavlink.io/en/messages/development.html#MAV_STANDARD_MODE
- What old style modes these map to (though that should be blindingly obvious
- Confirm that the AVAILABLE_MODES and CURRENT_MODE etc are emitted as per the spec by PX4, and that https://mavlink.io/en/messages/development.html#MAV_CMD_DO_SET_STANDARD_MODE will change the mode.
- Are the names in QGC matching standard modes or PX4 modes? Is there a translation repo yet for the standard and custom modes?
- What I would like to do is get QGC to use the standard mode name as defined in MAVLink spec IF the standard mode is being used or the overloaded mode name/translation if not. Where I'm heading here is that if you're in Plane then you'd show Cruise rather than Position mode etc.

hamishwillee · 2023-09-21T02:13:08Z

Top level comments on this feature.

It's pretty amazing - but then you know that.
I hate the name: "PX4 SDK" - that's an SDK containing tools and libraries for developing PX4 modules. This is the "PX4 ROS SDK" or "PX4 ROS2 SDK" - a library for developing PX4 ROS2 applications.
My criteria for success on a doc is "Do I think I might be able to do this task". I don't think this is far off, though we could do a lot more.
It's quite monolithic. We might consider splitting it when the docs are complete.
The tutorial is not a tutorial - it's an overview. I think a tutorial might be very useful for this particular case as well - perhaps adding a custom smart shot a'la solo - but you could make it much simpler than that.
- Note we don't have that many tutorials in the docs because they create duplication and require additional maintenance. But inherently they serve a useful purpose in showing someone who doesn't know anything the things that we think are important to them. This is perhaps a case where an exception could be made.
There is some versioning here about QGC daily - is there a build we know that will have this coming up for PX4 v1.14. We need such a build anyway, so if we know what it will be, good to list it.
This suggests taking PX4 main. I believe that the ROS2 integration intends to version by PX4 release. Upshot:
- Good to mention the compatibility requirement for main is "right now" but when this is out in PX4 release you'll take the PX4 messages for that release.
- How will you manage compatibility for the SDK depending on ROS? Are there topics that can't be modified in PX4 because of this?
- How will you manage compatibility for users of the SDK? Are we saying that this is stable by PX4 release, or we'll maintain backwards compat?
This currently doesn't explain how you can set the name of your mode and translate it, and any text that might exist in QGC for it. This might be because at this point it is only the English key from the mode name?
Perhaps irrelevant, and perhaps already covered, but consider I have a bunch of different smart shot modes that I want to add to my drone, and I also want to hook in collision avoidance. Do we need to do anything special to bundle and install all of these together on the companion? I.e. is there any special registration stuff and auto startup stuff that we can/should link to for "the big picture"?

I'll add some other comments/suggestions in line.

hamishwillee · 2023-09-21T02:14:07Z

en/ros2/px4_sdk.md

@@ -0,0 +1,336 @@
+# PX4 SDK


The name :-(

en/ros2/px4_sdk.md

hamishwillee · 2023-09-21T03:04:11Z

en/ros2/px4_sdk.md

+
+#### Mode
+
+- A mode is a component that can send setpoints to the vehicle, which control its motion (such as velocity or direct actuator commands).


Good to list the setpoints somewhere below and link to them.

en/ros2/px4_sdk.md

hamishwillee · 2023-09-21T03:41:17Z

en/ros2/px4_sdk.md

+## Mode Tutorial
+
+This section steps through an example for a custom mode class.
+For a complete application, check out the [examples in the repository](https://github.com/PX4/px4_sdk/tree/main/examples/cpp).


Might be worth providing "such as" links https://github.com/PX4/px4_sdk/blob/main/examples/cpp/modes/rtl_replacement/include/mode.hpp

en/ros2/px4_sdk.md

hamishwillee · 2023-09-21T03:57:48Z

en/ros2/px4_sdk.md

+   To ensure compatibility, use the latest _main_ branches for PX4, _px4_msgs_ and the SDK.
+   See also [here](https://github.com/PX4/px4_sdk#compatibility-with-px4).


This makes me uncomfortable - it basically says we ensure compatibility of the SDK by forcing you to use an unstable version of PX4. The linked doc is better in that it says we might change this in future. We should come up with a plan now and let people know.

The linked doc mentions this, which should also appear in this doc (I haven't checked) but it is cool:

The SDK checks for message compatibility on startup when registering a mode. ALL_PX4_SDK_MESSAGES defines the set of checked messages. If you use other messages, you can check them using:

if (!px4_sdk::messageCompatibilityCheck(node, {{"/fmu/in/vehicle_rates_setpoint"}})) { throw std::runtime_error("Messages incompatible"); }

en/ros2/px4_sdk.md

hamishwillee · 2023-09-21T04:03:41Z

en/ros2/px4_sdk.md

+
+1. [Configure the output](../payloads/#generic-actuator-control-with-mavlink)
+2. Create an instance of [px4_sdk::OffboardActuatorControls](https://github.com/PX4/px4_sdk/blob/main/px4_sdk_cpp/include/px4_sdk/control/offboard_actuators.hpp) in the constructor of your mode
+3. Call the `set` method to control the actuator(s). This can be done independently of any active setpoints.


Code fragment or link to code showing last two points would be awesome.

en/ros2/px4_sdk.md

hamishwillee · 2023-11-22T04:33:38Z

en/ros2/px4_ros2_interface_lib.md

+};
+```
+
+- `[1]`: First we create a class that inherits from `px4_ros2::ModeBase`


Do you think we could create a "reference" of the public API - just names and a description for the main classes at the end. Starting from a reference tells you what documentation is available/missing.

Yes we could use doxygen

I am going to assume you have this on your list :-)

en/ros2/px4_ros2_interface_lib.md

hamishwillee · 2023-11-22T04:35:19Z

en/ros2/px4_ros2_interface_lib.md

+The following sections provide a list of commonly used setpoint types.
+You can also add your own type by adding a class that inherits from `px4_ros2::SetpointBase`, sets the configuration flags according to what the setpoint requires, and then publishes any topic containing a setpoint.
+
+<!--


hamishwillee · 2023-11-22T04:43:29Z

@bkueng I added some comments. I'm not sure how far this has to go before we decide it is "right". Some things I'd like considered before we merge:

Can you add a small section in https://docs.px4.io/main/en/releases/main.html for this. Essentially I'm trying to generate our release notes in advance of the final release. At least including the main features and autopilot PRs.
Can we add the video from the dev summit
This seems vehicle agnostic. Is it? I.e. can I expect this to work just as well on plane, and in similar ways? For example if my mode executor specifies takeoff will the system use the takeoff for plane on plane and mc on mc? Or to put it another way - can we have a section "Support for different vehicle types" that summarises what you have to think about. Ultimately we'd like examples for each.
It would be good to have API reference at top level for the public API - classes, topics, setpoint types etc. That way even if we don't document them all, people can infer their purpose and we can expand out over time.

You might not want to do any of this right now. That's OK if you think this is useful as is and have a cunning plan going forward?

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

bkueng · 2023-11-22T07:20:41Z

Can you add a small section in https://docs.px4.io/main/en/releases/main.html for this. Essentially I'm trying to generate our release notes in advance of the final release. At least including the main features and autopilot PRs.

Will do.

Can we add the video from the dev summit

Yes later. It's not up yet and I wanted to add the link to the docs to the video first.

This seems vehicle agnostic. Is it? I.e. can I expect this to work just as well on plane, and in similar ways? For example if my mode executor specifies takeoff will the system use the takeoff for plane on plane and mc on mc? Or to put it another way - can we have a section "Support for different vehicle types" that summarises what you have to think about. Ultimately we'd like examples for each.

Yes agnostic, but we'll have to see how much we can abstract a mode to be generic. I don't think they will be completely generic.

You might not want to do any of this right now. That's OK if you think this is useful as is and have a cunning plan going forward?

Cunning certainly goes too far, but yes, there's a lot of things to be done.

hamishwillee · 2023-11-23T00:15:06Z

en/releases/main.md

+- [Experimental] [PX4 ROS 2 Interface Library](../ros2/px4_ros2_interface_lib.md): A new C++ library that simplifies controlling PX4 from ROS 2.
+  Supports adding flight modes in ROS 2 that are peers of the PX4 modes running on the flight controller.
+  Added to PX4 in [PX4-Autopilot#20707](https://github.com/PX4/PX4-Autopilot/pull/20707) (initial support).


FYI the important thing here is to set expectation. So I have put a prefix experimental and added a link to the initial PR.
As you enhance this you can add new PR links.
If you consider significant parts of this stable, we can remove "Experimental".

hamishwillee · 2023-11-23T00:18:10Z

en/ros2/px4_ros2_interface_lib.md

+:::warning Experimental
+At time of writing parts of the PX4 ROS 2 Interface Library is experimental, and hence subject to change:
+
+- The architecture and core interfaces for defining modes in ROS 2 modes are largely stable.
+  The library offers significant benefits over using offboard mode in its current state.
+- Only a few setpoint types have settled (the others are still under development).
+  You may need to use internal PX4 topics which may not remain backwards-compatible over time.
+- The API is not fully documented.
+- Testing in CI is still limited.
+
+:::


FYI I added section "Experimental" up the top. What I'm trying to do here is explain that the mode stuff works now and already gives you a benefit over using offboard mode, but that many of the abstractions we provide for working with ROS 2 do not exist yet. So you can use it but likely things will change.

I've done it in bullets so you can extend easily if you want. I'm open to any text which sets the level of expectation appropriately (i.e. this is "for discussion").

en/ros2/px4_ros2_interface_lib.md

hamishwillee · 2023-11-23T00:50:25Z

en/ros2/px4_ros2_interface_lib.md

+Telemetry topics include:
+
+- [OdometryGlobalPosition](https://github.com/Auterion/px4-ros2-interface-lib/blob/main/px4_ros2_cpp/include/px4_ros2/odometry/global_position.hpp): Global position
+- [OdometryLocalPosition](https://github.com/Auterion/px4-ros2-interface-lib/blob/main/px4_ros2_cpp/include/px4_ros2/odometry/local_position.hpp): Local position, velocity and acceleration.
+
+:::note
+These topics provide a wrapper around the internal PX4 topics, allowing the library to maintain compatibility if the internal topics change.
+Check [px4_ros2/odometry](https://github.com/Auterion/px4-ros2-interface-lib/tree/main/px4_ros2_cpp/include/px4_ros2/odometry) for new topics, and of course you can use any ROS 2 topic published from PX4.
+:::


This needs checking. I wanted to add a little information on what we support now at this level, and a reason why we bother.

en/ros2/px4_ros2_interface_lib.md

hamishwillee · 2023-11-23T01:14:03Z

@bkueng I've addressed most of my own concerns with this - setting expectation - by adding an experimental header. Can you please check that is OK. Perhaps there is a better way of explaining the state of the SDK.

The only one thing missing that I think might block people from using this is this question on the mode executor: https://github.com/PX4/PX4-user_guide/pull/2740/files#r1402837201

I'll merge tomorrow if you think this is reasonable.

bkueng · 2023-11-23T07:20:19Z

en/ros2/px4_ros2_interface_lib.md

+- Only a few setpoint types have settled (the others are still under development).
+  You may need to use internal PX4 topics which may not remain backwards-compatible over time.
+- The API is not fully documented.
+- Testing in CI is still limited.


This is ok, but just fyi most of the things that are there are tested. Mostly the setpoint types (with their expected behavior) that are not.

Then let's say that :-)

bkueng · 2023-11-23T07:20:47Z

Thanks Hamish. Looks good to me.

en/ros2/px4_ros2_interface_lib.md

github-actions · 2023-11-23T20:45:11Z

TODO: Error duplicate reference to print
TODO: Error duplicate reference to print
TODO: Error duplicate reference to print
TODO: Error duplicate reference to print
TODO: Error duplicate reference to print
TODO: Error duplicate reference to print
TODO: Error duplicate reference to print

hamishwillee

OK @bkueng made a few minor changes to address your responses to my feedback. I'm going to merge. I wish we could do a lot more, but good to get this out there and visible.

hamishwillee force-pushed the px4_sdk branch from bcddb40 to 4a5c797 Compare September 21, 2023 00:51