Application Programming Interface (API)

We provide open source API for development with the Kerloud UAV series, and candidate API interfaces will support C++, python and other languages. Details will be updated continuously in this part. Note that we assume users are familiar with basic concepts about ROS, and those who don't meet the prerequisite are recommended to go through official tutorials in http://wiki.ros.org/ROS/Tutorials.

1. ROS API (C++)

The API in ROS (Robot Operating System) is implemented based on the official MAVROS package from the PX4 community.

Our maintained repositories are:

• mavros (dev_kerlouduav branch): https://github.com/cloudkernel-tech/mavros

• mavlink (dev_kerlouduav branch): https://github.com/cloudkernel-tech/mavlink-gdp-release

Note that the offboard control demo code is delivered only with Kerloud machines, hence is not open source. More programming details will be illustrated in the tutorial section here. We present here topics and services that are commonly used with our Kerloud UAV case.

1.1 Topics

(1) ~mavros/extended_state

This topic can be subscribed to obtain current UAV state. The message type is defined here. We can obtain the landed state accordingly, e.g. if the field landed_state equals LANDED_STATE_IN_AIR, then the uav is in air.

    # Extended autopilot state
    #
    # https://mavlink.io/en/messages/common.html#EXTENDED_SYS_STATE

    uint8 VTOL_STATE_UNDEFINED = 0
    uint8 VTOL_STATE_TRANSITION_TO_FW = 1
    uint8 VTOL_STATE_TRANSITION_TO_MC = 2
    uint8 VTOL_STATE_MC = 3
    uint8 VTOL_STATE_FW = 4

    uint8 LANDED_STATE_UNDEFINED = 0
    uint8 LANDED_STATE_ON_GROUND = 1
    uint8 LANDED_STATE_IN_AIR = 2
    uint8 LANDED_STATE_TAKEOFF = 3
    uint8 LANDED_STATE_LANDING = 4

    std_msgs/Header header
    uint8 vtol_state
    uint8 landed_state

(2) ~mavros/setpoint_position/local, ~mavros/setpoint_position/global

This topic is used to publish the position setpoint in the local or global frame, and then guide the uav to the desired position. Note that the reference frame in the ROS level is the ENU frame, while that for the autopilot is the NED frame. The message type is geometry_msgs/PoseStamped or mavros_msgs/GlobalPositionTarget respectively.

(3) ~mavros/setpoint_velocity/cmd_vel_unstamped, ~mavros/setpoint_velocity/cmd_vel

These two topics are used to publish the velocity setpoint in the local frame for both rover and multicopter modes. The only difference between them is whether the velocity information is with a timestamp or not. The message type is geometry_msgs/Twist.

1.2 Services

(1) ~mavros/cmd/command

This service is utilized to set various modes for the UAV, such as arm/disarm, set offboard mode, etc. The message type is mavros_msgs/CommandLong.

To illustrate, suppose we'd like to arm the vehicle, three steps are needed.

Step 1, we have to define the service client.

    //service for arm/disarm
    ros::ServiceClient arming_client = nh.serviceClient<mavros_msgs::CommandBool>
            ("mavros/cmd/arming");

Step 2, we define the arm command as follows:

    mavros_msgs::CommandBool arm_cmd;
    arm_cmd.request.value = true;

Step 3, we can call the service

    arming_client.call(arm_cmd)

2. ROS API (python)

Similar with the ROS API in C++, ROS python API is implemented on basis of our maintained mavros and mavlink packages as well. The only difference is that all those topics and services mentioned above should be utilized with python.

Our maintained repositories are:

• mavros (dev_kerlouduav branch): https://github.com/cloudkernel-tech/mavros

• mavlink (dev_kerlouduav branch): https://github.com/cloudkernel-tech/mavlink-gdp-release

The offboard control demo code is delivered with Kerloud machines as well, and it's explained in the tutorial section here. For brevity, the low level message communication is handled within the Px4Controller class, and the friendly API for user programming is wrapped within the Commander class, partially listed below:

• move(x,y,z, BODY_FLU=False): request the vehicle to move to a desired position defined in either FLU frame or ENU frame.

• turn(yaw_degree): request the vehicle to turn to a desired yaw angle during flight.

• land(): request the vehicle to land.

• hover(): request the vehicle to hover at current position.

• arm(): request to arm the vehicle.

• disarm(): request to disarm the vehicle on ground.

• return_home(height): request the vehicle to return home.