From 9adf2a23ffacc5d7171b01095008158b5bb1ee4a Mon Sep 17 00:00:00 2001 From: Ryan Friedman <25047695+Ryanf55@users.noreply.github.com> Date: Sat, 19 Oct 2024 21:19:29 -0600 Subject: [PATCH] Dev: Document the ROS 2 interface Signed-off-by: Ryan Friedman <25047695+Ryanf55@users.noreply.github.com> --- dev/source/docs/ros.rst | 1 + dev/source/docs/ros2-interfaces.rst | 260 ++++++++++++++++++++++++++++ 2 files changed, 261 insertions(+) create mode 100644 dev/source/docs/ros2-interfaces.rst diff --git a/dev/source/docs/ros.rst b/dev/source/docs/ros.rst index 310852174c..5e963adee0 100644 --- a/dev/source/docs/ros.rst +++ b/dev/source/docs/ros.rst @@ -63,6 +63,7 @@ ROS 2 Install ROS 2 ROS 2 with SITL + ROS 2 Interfaces ROS 2 with SITL in Gazebo ROS 2 over Ethernet ROS 2 waypoint goal interface diff --git a/dev/source/docs/ros2-interfaces.rst b/dev/source/docs/ros2-interfaces.rst new file mode 100644 index 0000000000..fa1e163765 --- /dev/null +++ b/dev/source/docs/ros2-interfaces.rst @@ -0,0 +1,260 @@ +.. _ros2-interfaces: + +================= +ROS 2 Interfaces +================= + +The purpose of this page is to document all the ROS 2 interfaces available in ArduPilot. +Content is organized by functional area the data is used. + +Sensors +======= + +ArduPilot exposes "sensor" type data over DDS, that usually corresponds to a physical component, or some filterered version of it. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Topic NameTopic TypeDescription
ap/navsat/navsat0sensor_msgs/msg/NavSatFixThis is the reported GPS sensor position from the GPS subsystem. + TODO It will include a frame ID as instance number
ap/batterysensor_msgs/msg/BatteryStateThis sends the battery state for each enabled battery. + The battery instance is available in the frame ID. + Each enabled battery will be have data published. +
ap/imu/experimental/datasensor_msgs/msg/IMUThis is the high rate IMU data from the IMU that is currently used in the EKF.
ap/airspeedgeometry_msgs/msg/Vector3StampedThis is the 3D airspeed estimate of the vehicle in body frame.
+ +Pose, Rates, and Coordinates +============================ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Topic NameTopic TypeDescription
ap/gps_global_origin/filteredgeographic_msgs/msg/GeoPointStampedThis is the filtered AHRS's inertial navigation origin. This is NOT the same ask the HOME location. +
ap/twist/filteredgeometry_msgs/msg/TwistStampedThis is the filtered AHRS's velocity in the local ENU frame relative to home.
ap/pose/filteredgeometry_msgs/msg/PoseStampedThis is the filtered AHRS's pose in the local ENU frame relative to home.
ap/geopose/filteredgeographic_msgs/msg/GeoPoseStampedThis is the filtered AHRS's pose (position+orientation) in global coordinates
ap/tf_statictf2_msgs/msg/TFMessageAP broadcasts its known static transforms on this topic. + The transforms include the GPS sensor offsets relative to the vehicle origin.
+ +Time +==== + +.. raw:: html + + + + + + + + + + + + + + + + + + + +
Topic NameTopic TypeDescription
ap/timebuiltin_interface/msg/TimeThis sends time from AP's real time clock.
ap/clockrosgraph_msgs/msg/ClockThis sends time from AP's real time clock in a format suitable for aligning ROS time of a companion computer.
+ +Control +======= + +The control interfaces are how a companion computer can command the autopilot to move +either it's control surfaces, motors, or tell the autopilot to control to a setpoint position, velocity, acceleration. +Control includes the high level navigation objectives. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + +
Topic NameTopic TypeDescription
ap/joysensor_msgs/msg/JoyReceive joystick commands that override the RC input.
ap/cmd_velgeometry_msgs/msg/TwistStampedReceive REP-147 velocity commands. + Some vehicles support body frame while others support earth frame. +
ap/cmd_gps_poseardupilot_msgs/msg/GlobalPositionReceive REP-147 "High level goal". + This message is called "GlobalPosition" in REP-147. + Consult the source code to determine which fields are supported on which vehicles. +
+ +For more information on the high level goal interface, +see the :ref:`Waypoint Goal Interface` + +Commands +======== + +ArduPilot exposes service servers for the following purposes: + +* Pre-arm check +* Arming +* Changing modes +* Takeoff (copter only) + +Odometry +======== + +Ardupilot may not have a good estimate of where it is relative to where it started moving. +A companion computer can interface with sensors that provide odometry, which is the computation of the dynamic transform +from the ``odom`` frame to the ``base_link`` frame. This data is fed into ArduPilot's ``AP_VisualOdom`` library. +This data may come from visual sensors, however other technologies such as radar and lidar can +also provide odometry data. Regardless of the method of odometry, +ArduPilot has a single ROS interface to receive it. + +This data typically comes from a `TF2 Transfrom Tree `_. +For more information on the coordinate systems used, review `ROS REP-105 `_. + +.. raw:: html + + + + + + + + + + + + + + + +
Topic NameTopic TypeDescription
ap/tftf2_msgs/msg/TFMessageReceive the odometry dynamic transform on the normal tf2 dynamic transform topic.
+ +.. warning:: + Only the dynamic transformations on ``/ap/tf`` that have parent_frame ``odom`` and child_frame ``base_link`` are fed into ``AP_VisualOdom``. + Other frame configurations will be gracefully ignored, so feel free to populate this topic with other transforms if that's convenient. + +For more information on how to setup ArduPilot with an external odometry source, +see the :ref:`cartographer SLAM example. + +Configuring Interfaces at Compile Time +====================================== + +ArduPilot strives to only consume the resources it needs. +The DDS interface is no exception. + +Every topic and service can be individually enabled or disabled +at compile time. See +:ref:`common-oem-customizations`. + +Refer to the `AP_DDS_Config.h `_ +file on what is exposed. + +Additionally, publish rates form ArduPilot also all indivually configurable at compile time. + +When deploying ArduPilot on a resource constrained autopilot, developers +can disable interfaces they do not use and tune data rates to only +what their applications need. + +Adding New Interfaces +===================== + +ArduPilot's DDS interface is designed to be extensible. +Interfaces for pub/sub and services are easily added. + +If the interfaces are generic, consider contributing them to ArduPilot. +Custom application-specific interfaces are also easy to add and maintain +on private forks of ArduPilot. + +Interfaces that use custom messages that aren't already used commonly in +the ROS 2 ecosystem are typically added with an ``experimental`` designator. + + +ABI Stability Guarantees +======================== + +ArduPilot's DDS interface is intended to be ABI stable within an ArduPilot minor release. +Common interfaces such as ``NavSatFix`` are unlikely to change, however experimental interfaces +such as ``IMU`` may change, and are denoted with the ``experimental`` topic prefix. +In extenuating circumstances, non-experimental topics may require bugfixes that +change behavior, however message definitions will be kept compatible. + +Because the ROS way of updating messages is to not change messages +within a ROS release, many tools do not cope well with messages. +Different versions of the message between an autopilot and companion computer +can lead to receiving junk data without any errors, or cryptic serialization +errors. Thus, ArduPilot will do it's best to avoid changing messages. +If breaking changes are required, the ArduPilot release notes will make that clear. + +Developers should not expect ABI stability on ``exerimental`` interfaces. + +Because ArduPilot does not follow the same release timeline as ROS 2, and +the development team for the ROS interface is still in its early stages, +ArduPilot does not yet support a stable ABI across multiple ROS distributions. +The current ROS version supported is ``humble``.