应用程序接口 (API)

我们为Kerloud Autocar系列提供用于开发的开源API，并有C++、Python或其他语言的版本可选用，详细内容会在本章节持续更新。

1. ROS API (C++)

ROS（Robot Operating System）中的 API 基于PX4 社区的官方MAVROS 包实现。

我们在维护的库为：

mavros（dev_rover 分支）：https ://github.com/cloudkernel-tech/mavros
mavlink（dev_rover 分支）：https ://github.com/cloudkernel-tech/mavlink-gdp-release
使用 ROS C++ API（dev_rover 分支）的offboard 例程：https ://github.com/cloudkernel-tech/offboard_demo

1.1 Topics

(1)~mavros/setpoint_position/local, ~mavros/setpoint_position/global

本话题用于发布在本地或全局坐标系下的航点位置信息，陆地车、多旋翼模式下通用。需注意，ROS层使用的参考坐标系为ENU，而自驾仪使用的则是NED，消息类型分别为geometry_msgs/PoseStamped和mavros_msgs/GlobalPositionTarget。

(2)~mavros/setpoint_velocity/cmd_vel_unstamped, ~mavros/setpoint_velocity/cmd_vel

这两个话题用于发布飞车在本地坐标系中的速度设定值，陆地车、多旋翼模式下通用，两个话题的唯一区别是速度信息是否携带时间戳。消息类型为geometry_msgs/Twist。

(3)~mavros/setpoint_attitude/attitude, ~mavros/setpoint_attitude/thrust

这两个主题用于设置姿态和推力设定点。消息类型是geometry_msgs/PoseStamped 和mavros_msgs/Thrust。姿态推力直接输入车体的主推进油门控制，通过计算偏航角跟踪误差来生成转向伺服控制输入。

(4)~mavros/actuator_control

该话题可用于直接控制低级执行器，包括转向伺服和主电机。消息类型为mavros_msgs/ActuatorControl。转向伺服和主电机的通道编号分别为 2 和 3。

1.2 Services

(1)~mavros/cmd/command

本服务用于在offboard模式下控制车体在前进和后退之间进行模式切换，消息类型为mavros_msgs/CommandLong。它对应于https://github.com/cloudkernel-tech/mavlink-gdp-release/blob/dev_rover/message_definitions/v1.0/common.xml 中的自定义 mavlink 消息（mavlink::common::MAV_CMD::SET_ROVER_FORWARD_REVERSE_DRIVING）。

举例而言，如果我们想切换到前进，则必须使用以下设置来调用服务：

    mavros_msgs::CommandLong set_forward_driving_cmd;
    set_forward_driving_cmd.request.command 	(uint16_t)mavlink::common::MAV_CMD::SET_ROVER_FORWARD_REVERSE_DRIVING;
    set_forward_driving_cmd.request.confirmation = 0;
    set_forward_driving_cmd.request.param1 = 1.0f;

反过来实现后退：

    mavros_msgs::CommandLong set_backward_driving_cmd;
    set_backward_driving_cmd.request.command = (uint16_t)mavlink::common::MAV_CMD::SET_ROVER_FORWARD_REVERSE_DRIVING;
    set_backward_driving_cmd.request.confirmation = 0;
    set_backward_driving_cmd.request.param1 = 0.0f;

2.ROS API（python）

与 C++ 版的 ROS API 类似，ROS python API 也是基于我们维护的 mavros 和 mavlink 包实现的。仅有的区别是上文提到的所有话题和服务需通过python来使用。

我们在维护的库为：

mavros（dev_rover 分支）：https ://github.com/cloudkernel-tech/mavros
mavlink（dev_rover 分支）：https ://github.com/cloudkernel-tech/mavlink-gdp-release
使用 ROS python API（dev_rover 分支）的offboard控制示例：https ://github.com/cloudkernel-tech/offboard_demo_python

代码将在使用教程章节进行讲解。为简洁起见，底层消息通信在Px4Controller类中进行处理，而面向用户编程用的友好API接口封装于Commander类中，部分API列举如下：

move_position(x,y,z, BODY_FLU=False)：请求车辆移动到 FLU 坐标系或 ENU 坐标系下定义的指定位置，忽略 z 通道。
move_velocity(vx,vy,vz, BODY_FLU=False)：请求车辆在FLU 坐标系或 ENU 坐标系下以指定的速度移动，忽略 z 通道。
set_forward_driving()：请求车辆前进，仅适用于姿态和执行器控制命令模式。
set_backward_driving()：请求车辆向后移动，仅适用于姿态和执行器控制命令模式。
set_yaw_and_throttle()：为车辆设置所需的偏航角和油门。
set_steering_servo_and_throttle()：设置车辆的直接执行器控制，包括转向伺服和油门输入。
arm()：请求解锁车辆。
disarm()：请求锁定车辆。
return_home()：请求车辆返航，为ENU坐标系下的原点。