# OnboardDevSDK

**Repository Path**: wujin-alex/onboard-dev-sdk

## Basic Information

- **Project Name**: OnboardDevSDK
- **Description**: 无人机上层应用开发SDK，包含PX4飞控API，仿真（airsim）API接口，旋转变化、坐标转换相关的API
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2022-01-01
- **Last Updated**: 2024-12-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# onboardDevSDK说明

OnboardDevSDK是针对无人机应用开发推出的一个工具包，主要实现了无人机的飞控连接、通信、控制，并且提供了一些必要的计算工具如距离计算、坐标转换等。

使用该SDK，你可以连接PX4真机、gazebo的仿真、Airsim的仿真。

Onboard developing SDK based on PX4, It let's you focus on TOP-Level develop, it has finished the LOW-level part like drone link, basic fly control and supplies a lot APIs.

## 环境配置

开发环境为Ubuntu18.04/20.04，编程语言为python3.6+。

### 编译
如果需要安装、发布，那么需要首先编译出安装包，执行如下命令：
```shell
$ cd onboardDevSDK
# 编译生成二进制whl安装文件（推荐）
$python3 setup.py bdist_wheel
```
### 安装

我们编译后会在项目根目录下生成一个dist文件夹，并且可看到打包好的whl文件，可以直接安装，例如：

```shell
$ cd dist
$ sudo pip3 install onboardDevSDK-0.1.0-py3-none-any.whl
```

> 注意：
>
> 如果在开发阶段，需要调试和测试，那么可以使用如下命令：
>
> ```shell
> $ cd onboardDevSDK
> $ sudo python3 setup.py develop
> ```
>
> 这样进行代码改动后不需要编译即可实时生效。

### 示例

在项目根目录demos文件夹下提供了一些示例，请安装onboardDevSDK后再运行，各demo相关说明如下：

- demo.py

是多个demo的合并（demo_control_with_keyboard+demo_simple）。主要是通过键盘进行控制，并提供不同的飞行演示，按数字键1、2、3等选择不同的飞行演示！

- demo_test_api.py

演示了如何使用utils包下的函数；

- demo_control_with_keyboard.py

演示了如何使用键盘控制无人机基本飞行；

- demo_simple.py

演示了基本的无人机控制流程，如让无人机起飞后，控制无人机飞一个四边形；

## API说明

我们将帮助文档说明托管在了华为云，具体请参考：http://119.3.41.86/docs/onboard-dev-sdk/index.html

## 使用说明

我们提供了**DroneAPI**类用于无人机连接，故只需要实例化即可，如：

```python
drone = DroneAPI(params)
```

这里`param`是参数字典，如何设置请看下一节。

### 设置参数

`param`是参数字典的基本说明如下：

- sys_id: 指定onboardDevSDK应用程序的计算机system id；
- cmp_id: 指定onboardDevSDK应用程序的计算机component id；

- tgt_sys_id: 飞控system id参数，一定要与飞控的MAV_SYS_ID参数保持一致，具体可通过地面站连接飞控后去参数列表查看这个值是多少！很多时候无法控制飞行都是因为参数设置错误；
- tgt_cmp_id: 飞控component id参数，一定要与飞控的MAV_COMP_ID参数保持一致，具体可通过地面站连接飞控后去参数列表查看这个值是多少！
- fcu_url: 设置飞控地址，或者连接方式，目前支持串口、UDP；
- gcs_url: 设置转发地址/地面站，也就是onboardDevSDK可以作为中间桥梁，让地面站与飞控进行通信；
- fcu_type: 飞控类型，目前支持px4、airsim。

例如：

```python
dev_addr = "serial:///dev/ttyUSB0:921600"
gcs_addr = "udp://:14544@127.0.0.1:14550"
params = {'sys_id':1,                
          'cmp_id':200, 
          'tgt_sys_id':1, 
          'tgt_cmp_id':1,
          'fcu_url':dev_addr,
          'gcs_url':gcs_addr,
          'fcu_type':'px4'
          }
drone = DroneAPI(params)
```

### 飞控连接

onboardDevSDK旨在给开发者的应用程序提供一套飞控的连接、控制方式，故使用onboardDevSDK的第一步就是让你的应用程序与飞控建立连接。

连接飞控最重要的是设置`fcu_url`参数，根据实际几种情况，说明如下：

1. 通过串口连接飞控，这里连接飞控的USB口（固件烧写端口），仅仅用于地面调试，不能用于飞行测试

   如：

   ```python
   dev_addr = "serial:///dev/ttyACM0:115200"
   ```

2. 通过串口连接飞控，这里连接飞控的TELEM2，实际飞行时使用这个

   如：

   ```python
   dev_addr = "serial:///dev/ttyUSB0:921600"
   ```

3. 连接PX飞控，通过CUAV Serial转WiFi模块产生的热点连接飞控

   如：

   ```python
   dev_addr = "udp://:14550"
   ```

4. 连接PX4仿真器，如gazebo, jmavsim等

   ```python
   # 连接运行在主机192.168.43.59的仿真器
   dev_addr = "udp://:14540@192.168.43.59:14580"
   # 连接本机gazebo仿真中一号仿真机
   dev_addr = "udp://:14540@127.0.0.1:14580"
   # 连接本机gazebo仿真中二号仿真机
   dev_addr = "udp://:14541@127.0.0.1:14581"
   ```

## offboard正确使用

我们通过调用`offboard_enable()`函数获取无人机控制权，PX4无人机关于offboard模式的最关键说明是：

1. 必须获取无人机控制权才可以控制无人机！
2. 获取控制权后必须以大于10Hz频率发送控制指令，对于onboardDevSDK来说，类提供了很多控制指令发送函数，如`moveto_globalPosition_relAlt_yaw()`等非async函数！
3. 如果飞控检测出一定时间内没有接收到控制指令，那么就会退出offboard模式，如果需要控制无人机需要再次调用`offboard_enable()`函数获取无人机控制权并马上以10Hz频率发送控制指令；

在实际使用中，有时候即便按照上面流程也无法进入offboard模式，可能有的开发者就在循环中每次发送控制命令前调用一次`offboard_enable()`函数，这种方法非常不推荐！因为一旦有任何情况，遥控器无法接管飞机。

**我们可以在QGC地面站上，进入主菜单->Vehicle Setup->Flight Modes，给Offboard switch channel映射一个通道配置，例如遥控器7通道！这个通道的作用就是获取和释放无人机控制权（相当于调用`offboard_enable()`函数）。**

**使用流程为：**

1. offboard通道默认推到无效位置；
2. 启动应用程序，当确定有控制指令一直发给飞控时，拨动遥控器offboard通道开关至有效位置，使应用程序获取控制权限；
3. 当试验结束、或者有意外情况时，拨动遥控器offboard通道默认推到无效位置，通过摇杆进行接管无人机！

## 问题和解决

### 无法安装

由于onboardDevSDK会依赖一些第三方库，如numpy等，如果本地环境没有相应库就会进行下载安装，根据本地网络环境等因素，有些库的下载和安装可能不顺利，建议pip命令中使用国内镜像方式进行安装，如安装numpy库：

```shell
$ pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy
```

在实际过程中，注意看下终端提示哪些库安装有问题，根据上面方式对其进行安装即可。

### 无法控制飞机

- 首先检查参数设置是否正确；

- 检查波特率是否正确（串口连接情况下）；
- 是否进入offboard模式（可以通过地面站看到）；

### 串口无法打开

**问题描述：**
有时通过串口连接飞控，启动onboardDevSDK后，有如下错误：

```shell
onboardDevSDK/demos$ python3 demo.py 
ERROR: cannot initialize mavlink api, [Errno 16] could not open port /dev/ttyUSB0: [Errno 16] Device or resource busy: '/dev/ttyUSB0'
Exception ignored in: <bound method FcuPx4.__del__ of <onboardDevSDK.fcu_px4.FcuPx4 object at 0x7f86dd90de80>>
Traceback (most recent call last):
  File "/media/alex/Develop/无烬/onboardDevSDK/onboardDevSDK/fcu_px4.py", line 618, in __del__
```
**解决方法：**
这有可能是因为串口没有打开权限，请使用如下命令：

```shell
$ sudo chmod +777 /dev/ttyUSB0
```

## 版本

### v0.1

完成了基本架构设计，基本功能开发，主要实现了：

1. 实现了PX4飞控驱动接口（fcu_px4.py），通过mavlink2.0协议与飞控进行交互；
2. 实现了airsim驱动接口（fcu_airsim.py），参考airsim提供的API，与仿真器中无人机进行通信；
3. 为所有fcu统一提供了API接口（drone_api.py），使用户可以随意配置并连接不同的fcu机型！
4. 提供了坐标变换相关的一些功能函数（rotation_transform.py），例如欧拉角、四元素相关转换等；
5. 提供了一些距离测量、角度计算等功能函数（util.py）。

### v0.2
1. 增加说明文档docs

### v0.3
1. 增加加速度控制