.. _section_api:

Application Programming Interface (API)
=========================================

We provide open source API for development with the Kerloud VTOL series,
and the current supported language is C++. Details will be updated continuously in this part.

ROS API (C++)
------------------

The API in ROS (Robot Operating System) is implemented based on the official `MAVROS <http://wiki.ros.org/mavros>`_ package from the PX4 community.

Our maintained repositories are:

* mavros: https://github.com/cloudkernel-tech/mavros
* mavlink: https://github.com/cloudkernel-tech/mavlink-gdp-release

Note that users have to switch to the *dev_kerloudvtol* branch for above repositories.

We also provide an offboard control example for customers, and they will be invited to join our hosted repository in https://gitee.com/cloudkernel-tech/offboard_kerloudvtol.
We present here topics and services that are specifically related with the Kerloud VTOL case. More general information on the
mavros package can be referred in the official `link <http://wiki.ros.org/mavros>`_. Illustrations on how to utilize these APIs
can be found in the tutorial (:ref:`tutorial_offboard`)

Topics
^^^^^^^^^^

**(1) /mavros/extended_state**

This topic can be subscribed to obtain current vehicle state. The message type is `mavros_msgs/ExtendedState <https://github.com/cloudkernel-tech/mavros/blob/dev_kerloudvtol/mavros_msgs/msg/ExtendedState.msg>`_,
with details given below.

::

        # 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

        uint8 FLYINGROVER_STATE_UNDEFINED = 0
        uint8 FLYINGROVER_STATE_ROVER = 1
        uint8 FLYINGROVER_STATE_MC = 2
        uint8 FLYINGROVER_STATE_TRANSITION_TO_MC = 3
        uint8 FLYINGROVER_STATE_TRANSITION_TO_ROVER = 4

        std_msgs/Header header
        uint8 vtol_state
        uint8 landed_state
        uint8 flyingrover_state

For clarity, we illustrate the meanings here:

* vtol_state=0: VTOL state is not defined for this vehicle.
* vtol_state=1: The vehicle is in the forward transition phase to transit to the fixed-wing mode.
* vtol_state=2: The vehicle is in the backward transition phase to transit to the multicopter mode.
* vtol_state=3: The vehicle is in the multicopter mode.
* vtol_state=4: The vehicle is in the fixed-wing mode.

The field flyingrover_state is related with our `Kerloud flying rover series <https://kerloud-flyingrover.readthedocs.io/en/latest/>`_, hence not used here.

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

These two topic are used to publish the position setpoint in the local or global frame for both multicopter and fixed-wing modes.
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 <docs.ros.org/en/api/geometry_msgs/html/msg/PoseStamped.html>`_ or
`mavros_msgs/GlobalPositionTarget <docs.ros.org/en/api/mavros_msgs/html/msg/GlobalPositionTarget.html>`_ respectively.

**(3) mavros/setpoint_raw/local, /mavros/setpoint_raw/global**

These two topics can be utilized to construct more sophisticated position and velocity setpoints in the local or global frame for both multicopter
and fixed-wing modes. The Kerloud VTOL supports several guidance modes: (i) traditional position guidance mode: the UAV
will fly to the target position with a L1 guidance law, and then loiter around the position target afterwards.
(ii) fixed-vector position guidance mode: the UAV will fly to the target position with a L1 guidance law, and then fix its heading after reaching the position target.
(iii) velocity guidance mode: the UAV will follow the forward velocity and banking angle references, which is a low-level control interface for
application development.

Services
^^^^^^^^^^^^^^^

**mavros/cmd/command**

This service is utilized for mode switching between the multicopter and fixed-wing modes in the offboard operation. The message type is mavros_msgs/CommandLong.
It corresponds to a mavlink message (mavlink::common::MAV_CMD::DO_VTOL_TRANSITION) defined in the `link <https://github.com/cloudkernel-tech/mavlink-gdp-release/blob/dev_kerloudvtol/message_definitions/v1.0/common.xml>`_.

To illustrate, if we’d like to switch to the fixed-wing mode, then the service has to be called with settings below:

::

        mavros_msgs::CommandLong switch_to_fw_cmd;//command to switch to fixed-wing
        switch_to_fw_cmd.request.command = (uint16_t)mavlink::common::MAV_CMD::DO_VTOL_TRANSITION;
        switch_to_fw_cmd.request.confirmation = 0;
        switch_to_fw_cmd.request.param1 = (float)mavlink::common::MAV_VTOL_STATE::FW;

To switch to the multicopter mode reversely,

::

        mavros_msgs::CommandLong switch_to_mc_cmd;//command to switch to multicopter
        switch_to_mc_cmd.request.command = (uint16_t)mavlink::common::MAV_CMD::DO_VTOL_TRANSITION;
        switch_to_mc_cmd.request.confirmation = 0;
        switch_to_mc_cmd.request.param1 = (float)mavlink::common::MAV_VTOL_STATE::MC;