Control API

A ROS2 Library tested and working for multicopters by ADRG UI that simplifies interfacing with PX4 Firmware. This library deals with basic needs such as movement and servo control.

Table of Contents

• Architecture
• Setup and Installation
• Documentation

Architecture

Setup and Installation

On a standard ROS2 setup, make sure a workspace exists under ~/workspaces. If not create it and then clone the repository under a subfolder,

mkdir ~/workspaces/ros2_ws
cd ~/workspaces/ros2_ws
git clone https://github.com/rotary-auav-ui/control_api.git

Source the supported ROS2 distribution Humble Hawksbill,

source /opt/ros/humble/setup.bash

Then, build the library using colcon,

colcon build

Or selectively build the library,

colcon build --packages-select control_api

Documentation

class CopterAPI

Defined in: control_api.hpp

• Public Member Functions
  • Constructor & Destructor
    • CopterAPI()
    • ~CopterAPI()
  • Core Control
    • void arm()
    • void disarm()
    • void set_offboard_control_mode(...)
    • void land()
  • Motion Control
    • void set_setpoint(...)
    • void set_altitude(...)
    • void move_altitude(...)
    • void set_position(...)
    • void move_position(...)
    • void move_body(...)
    • void set_velocity(...)
    • void set_yaw(...)
    • void rotate_yaw(...)
  • Servo Control
    • bool initServo(...)
    • bool setServoAngle(...)
    • bool setServoAngleWithDelay(...)
    • bool isServoConnected() const
  • Initialization & Localization
    • void do_initialization()
    • bool isInitialized() const
    • rcl_time_point_value_t get_timestamp() const
    • void localize_setpoint()
    • void localize_altitude()
  • Internal Callbacks & Helpers
    • void publish_offboard_control_mode(...)
    • void publish_vehicle_command(...)
    • void vehicle_local_position_callback(...)
    • void vehicle_status_callback(...)
    • void get_parameters()
• Private Attributes

---

Public Member Functions

Constructor & Destructor

CopterAPI(const rclcpp::Node::SharedPtr& node, const std::chrono::milliseconds& rate_ms)

Description: Constructor. Initializes callback loops and parameters.

Parameter	Type	Description
node	rclcpp::Node::SharedPtr	Reference to active ROS2 node.
rate_ms	std::chrono::milliseconds	Loop update rate.

Returns: None.

~CopterAPI()

Description: Destructor. Calls land() as a safety fallback.

Returns: None.

---

Core Control

void arm()

Description: Arms the vehicle by sending a VehicleCommand::ARMING_ACTION_ARM message.

Returns: None.

void disarm()

Description: Disarms the vehicle by sending a VehicleCommand::ARMING_ACTION_DISARM message.

Returns: None.

void set_offboard_control_mode(const enum OFFBOARD_MODE mode)

Description: Sets the offboard control mode by publishing an OffboardControlMode message.

Parameter	Type	Description
mode	OFFBOARD_MODE	Sets mode to POSITION, VELOCITY, or ACCELERATION.

Returns: None.

void land()

Description: Commands the drone to land vertically below its current position.

Returns: None.

---

Motion Control

void set_setpoint(...)

Description: Sets position, velocity, acceleration, yaw, and yawspeed in one message.

Parameter	Type	Description
position	std::array<float, 2>&	XY-plane position (NED coordinates).
yaw	float&	Yaw in radians.
velocity	std::array<float,3>&	Body velocity (NED frame).
yawspeed	float&	Yaw speed in radians/s.
acceleration	std::array<float,3>&	Body acceleration (NED frame).

void set_altitude(const float& height = 0.0f)

Description: Sets the vehicle altitude relative to initialization.

Parameter	Type	Description
height	const float&	Target altitude in meters. Defaults to 0.0f.

void move_altitude(const float& height = 0.0f)

Description: Moves vehicle altitude relative to current height.

Parameter	Type	Description
height	const float&	Change in height (meters). Defaults to 0.0f.

void set_position(const std::array& position)

Description: Moves to an absolute position in the NED frame.

Parameter	Type	Description
position	std::array<float,3>&	Target XYZ position (NED coordinates).

void move_position(const std::array& delta)

Description: Moves relative to current position.

Parameter	Type	Description
delta	std::array<float,3>&	Relative XYZ offset (NED coordinates).

void move_body(const std::array& delta)

Description: Moves the drone in its local forward-right-down (body) frame.

Parameter	Type	Description
delta	std::array<float,3>&	Body-frame offset (forward, right, down).

void set_velocity(const std::array& vel)

Description: Sets the drone’s linear velocity in the body frame.

Parameter	Type	Description
vel	std::array<float,3>&	Velocity in body frame (m/s).

void set_yaw(const float& yaw, const float& yawspeed)

Description: Rotates the drone to an absolute yaw orientation.

Parameter	Type	Description
yaw	const float&	Target yaw angle in radians.
yawspeed	const float&	Rotation rate in radians/s.

void rotate_yaw(const float& yaw_delta, const float& yawspeed)

Description: Rotates drone by a relative yaw change.

Parameter	Type	Description
yaw_delta	const float&	Relative yaw change in radians.
yawspeed	const float&	Rotation rate in radians/s.

---

Servo Control

bool initServo(...)

Description: Initializes the servo controller.

Parameter	Type	Description
pin	int	PWM pin number.
frequency	int	PWM frequency in Hz.

Returns: true if initialization succeeded.

bool setServoAngle(int angle)

Description: Sets the servo to a specified angle.

Parameter	Type	Description
angle	int	Servo target angle in degrees.

Returns: true if command acknowledged.

bool setServoAngleWithDelay(int angle, int delay_ms)

Description: Sets the servo angle and waits for a specified delay.

Parameter	Type	Description
angle	int	Target angle in degrees.
delay_ms	int	Delay duration in milliseconds.

Returns: true if successful after delay.

bool isServoConnected() const

Description: Checks if servo communication is active.

Returns: true if the servo interface is connected and operational.

---

Initialization & Localization

void do_initialization()

Initializes offboard mode and local frames.

Returns: None.

bool isInitialized() const

Checks if the system has completed initialization.

Returns: true if fully initialized.

rcl_time_point_value_t get_timestamp() const

Returns current system timestamp in microseconds.

Returns: rcl_time_point_value_t — Current ROS2 time value.

void localize_setpoint()

Resets the trajectory setpoint to the current position.

void localize_altitude()

Resets the altitude setpoint to the current altitude.

---

Internal Callbacks & Helpers

void publish_offboard_control_mode(const OFFBOARD_MODE& mode)

Publishes OffboardControlMode messages to PX4.

Parameter	Type	Description
mode	const OFFBOARD_MODE&	Offboard control mode selection.

void publish_vehicle_command(...)

Publishes a generic VehicleCommand to PX4.

Parameter	Type	Description
command	uint16_t	Command ID.
param1–param7	float	Command parameters (optional).

void vehicle_local_position_callback(...)

Callback for live vehicle position updates.

void vehicle_status_callback(...)

Callback for PX4 vehicle status updates.

void get_parameters()

Fetches configuration and operational parameters from the ROS2 node or parameter server.

---

Private Attributes

Attribute	Type	Description
status	Status	Holds current vehicle state.
setpoint	Setpoint	Stores current trajectory targets.
TOLERANCE	struct	Defines motion error thresholds.
servo_control_	std::shared_ptr<ServoControl>	Servo handler instance.
node	rclcpp::Node::SharedPtr	ROS2 node reference.
initialized_	std::atomic<bool>	Initialization completion flag.