_images/robomaster.jpg

欢迎来到 RoboMaster 开发者页面

开篇介绍

EP套装介绍

RoboMaster EP 教育拓展套装在 RoboMaster S1 教育机器人的基础上延展出丰富的拓展性，配有完善的课程内容及全新 RoboMaster 青少年专属赛事；各类编程模块均围绕教学需求精心设计，带来焕然一新的教学与学习体验，拓展未来教育的全新边界。

EP机器人形态

RoboMaster EP 教育套装可以组装出步兵机器人或工程机器人。其中步兵机器人在外观上与常规版本的 S1 较为接近，并在软硬件上进行了升级，增加了许多新部件， 极大地提升了拓展能力，升级后的机器人能够通过传感器转接模块接入第三方传感器，拥有更多的可编程空间。

alternate text

步兵机器人

工程机器人在外观上基于 S1 做了较大的改动：采用一个并联机械臂代替安装在底盘正中央的云台结构，保留了图传系统，并且在机械臂末端装配一个机械夹爪，从而可以执行更加复杂的任务。在底盘的行动能力和整机的拓展能力方面，则与步兵机器人水准相当。

alternate text

工程机器人

网站内容

RoboMaster EP 作为一款教育机器人，具有强大的扩展性和可编程性。为了方便用户编程使用，官方 App 集成了 Scratch 编程和 Python 编程的功能，并提供了Python SDK，明文 SDK 多种编程方式。

本网站为 RoboMaster 系列产品的技术开发网站，面向对象为使用 RoboMaster 系列的学生、教师和科技爱好者，为用户提供技术上的指引，方便对 RoboMaster EP 进行二次开发，扩展更加丰富的功能，解锁更多乐趣。

本网站分为四部分，主要内容介绍如下：

  • 快速开始
    本章将简要概述 RoboMaster EP 教育套装和本网站内容，提供编程环境的安装方法，介绍 RoboMaster EP 如何跟第三方平台进行通信，以帮助用户扩展更加丰富的功能。
  • Python SDK
    RoboMaster SDK 是基于Python语言实现的，适用于RoboMater 机甲大师系列的 Python SDK 软件库。 目前适用于RoboMaster EP 和 Tello Edu 等系列产品，提供了丰富的API接口，包括: 运动控制，飞行控制，智能识别，灯效设置，数据推送，视频流和音频流等API。 并且设计上遵循尽量简单的原则，能够快速上手使用，便于学习和教学使用。
  • 扩展模块/扩展接口说明
    RoboMaster EP 相比 S1 具有更加丰富的扩展模块与拓展接口，本章将简要说明拓展模块以及拓展接口的配置和使用方法。
  • 明文 SDK 说明
    用户使用第三方平台跟 RoboMaster EP 建立连接后，可通过明文 SDK 对 EP 机器人进行更复杂、更有趣的操作。本章将详细说明明文 SDK 的功能、用法和相关协议。
  • Python 编程说明
    本章将指导用户通过 RoboMaster EP 官方 App 内置的 python 编程环境对 EP 上新增的功能和模块进行编程，解锁更多玩法。
  • 版本说明
    本章主要描述文档与机器人之间相互匹配的版本信息。

联系我们

如果您对该文档任何的建议和意见，欢迎在 RoboMaster-SDK Github 上联系我们。

编程环境安装

介绍

用户在 PC 上通过 WIFI、 USB 和 UART 跟 EP 建立连接后，可以使用明文 SDK 跟 EP 进行通信，进行更复杂的二次开发。用户可以在 PC 上使用 C++、 C#、 Python 或是其他语言进行编程，用户可根据自身开发能力选择开发语言。

为了让用户尽快熟悉 EP 的各个模块和功能，并方便使用本网站中的 Python 示例代码，我们介绍一下 Python 在 PC 上的安装步骤。

在 Windows 上安装 Python

环境： Windows 10 64 位

  1. 从python官网 python 官网链接 找到可以下载的安装包，以Python3.7.8 为例，选择安装文件进行下载。

警告

请确保下载的 python.exe 是64位的，python sdk适配3.6.6以上至3.8.9版本python版本，否则会影响python sdk的使用，切记。

_images/win_python_setup1.png

  1. 步骤（1）：确认安装包版本是 64-bit, 否则会影响Python sdk使用。

    步骤（2）：勾选 Add Python 3.7 to Path。

    步骤（3）：选择 Install Now 进行安装，如下图所示。

_images/win_python_setup2.png
  1. 安装完成后按 win+r，在弹出窗口中输入 cmd 打开命令提示符界面，在命令行里面输入 python, 确认 Python 3.7.8 安装成功。
_images/python_version.png

注解

cmd窗口会显示对应的版本信息，否则，请从第一步重新安装

在 Ubuntu 上安装 Python

环境： ubuntu 16.04 64 位，Python 3.7.8

  1. Ubuntu16.04 默认安装了Python2.7和3.5，输入命令 python，可以查看 Python 默认版本。请注意，系统自带的python千万不能卸载。
  2. 输入如下命令安装 python 3.7 软件包：
sudo add-apt-repository ppa:jonathonf/python-3.7
sudo apt-get update
sudo apt-get install python3.7
  1. 输入如下命令，调整 Python3 的优先级，使得 Python 3.7 优先级较高。
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.6 1
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.7 2
sudo update-alternatives --install /usr/bin/python python /usr/bin/python2 100
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 150
  1. 此时再输入命令 python ，确认 Python 3.7 安装成功。

第三方平台通信

介绍

用户使用第三方平台跟 RoboMaster EP 建立连接后，通过明文 SDK 和 EP 机器人进行通信，可以控制各个内置模块和拓展模块，并获取 EP 机器人的视频流、音频流，极大地丰富了 EP 的扩展性，解锁更多玩法。

第三方平台类型

用户使用的第三方平台为有自主计算能力，具有 WIFI 、 USB 和 UART 接口的计算平台，包括但不限于 DJI 妙算、Arduino 开发板、Micro:bit、树莓派、Jetson Nano 和 PC。

_images/third_part.png

通信方式

第三方平台和 RoboMaster EP 的通信方式包括三种： WIFI、 USB 和 UART。下面介绍这三种通信方式的连接方法。

WIFI 连接

WIFI 连接包括直连模式和路由器模式，具体参考如下说明。

直连模式
条件:

第三方平台具有 WIFI 连接功能。
用途:

第三方平台使用 WIFI 连接到 EP 后，通过明文 SDK 和 EP 进行通信。
步骤:
  1. 启动 EP，切换智能中控的连接模式开关至 直连模式。
  2. 打开第三方平台的无线网络，扫描 EP 的热点，进行连接。
  3. 通过明文 SDK 和 EP 进行通信。（详细步骤参考 WIFI 直连模式)
应用举例:

DJI 妙算、Jetson Nano 或 PC 使用 WIFI 连接到 EP 后，通过明文 SDK 和 EP 进行通信，并获取 EP 的视频流、音频流。
示意图:
_images/wifi_direct1.png

DJI 妙算、Jetson Nano 或 PC 通过 WIFI 直连模式连接到 EP

路由器模式
条件:

第三方平台具有 WIFI 或有线网络连接功能。
用途:

第三方平台和 EP 连接到同一个局域网中，通过明文 SDK 和 EP 进行通信。
步骤:
  1. 启动 EP，切换智能中控的连接模式开关 路由器模式。
  2. 通过官方 App 的扫码连接方式将 EP 连接到路由器。
  3. 第三方平台通过 WIFI 或有线网络连接到同一路由器。
  4. 通过官方 App 的设置页面或是编写脚本等方式获取到 EP 的 IP 地址。
  5. 通过明文 SDK 和 EP 进行通信。（详细步骤参考 WIFI 路由器模式)
应用举例:

DJI 妙算、Jetson Nano 或 PC 和 EP 连接到同一个局域网后，通过明文 SDK 和 EP 进行通信，并获取 EP 的视频流、音频流。
示意图:
_images/wifi_sta1.png

DJI 妙算、Jetson Nano 或 PC 通过 WIFI 路由器模式连接到 EP

USB 连接

条件:

第三方平台具有 TypeA USB 接口，并支持 RNDIS 功能。
用途:

第三方平台通过 USB 线连接到 EP 的智能中控的 Micro USB 端口，使用明文 SDK 和 EP 进行通信。
步骤:
  1. 启动 EP，无需关心智能中控的连接模式开关位置。
  2. 第三方平台通过 USB 线连接到 EP 的智能中控。
  3. 通过明文 SDK 和 EP 进行通信。（详细步骤参考 USB 连接)
应用举例:

树莓派或 Jetson Nano 固定在 EP 小车上，并由 EP 的电源转接模块供电，通过 USB 连接到 EP，使用明文 SDK 和 EP 进行通信，并获取 EP 的视频流、音频流。
示意图:
_images/raspberry1.png

树莓派连接示意图

_images/nano.png

Jetson Nano连接示意图

UART 连接

条件:

第三方平台具有 UART 接口或有串口转 USB 功能。
用途:

第三方平台通过 UART 连接到 EP 运动控制器的 UART 接口，使用明文 SDK 和 EP 进行通信。
步骤:
  1. 启动 EP，无需关心智能中控的连接模式开关位置。
  2. 第三方平台 UART 的 TX/RX 和 GND 分别连接到 EP 运动控制器 UART 的 RX/TX 和 GND。（参考 引脚说明)
  3. 通过明文 SDK 和 EP 进行通信。（详细步骤参考 UART 连接)
应用举例:

Arduino 或 Micro:bit 固定在 EP 小车上，并由 EP 的电源转接模块供电，通过 UART 连接到 EP 运动控制器，使用明文 SDK 和 EP 进行通信。
示意图:
_images/arduino.jpg

Arduino连接示意图

_images/microbit.png

Micro:bit连接示意图

RoboMaster SDK 安装

安装 SDK 到 Windows平台

开发环境准备

小技巧

在使用python sdk前，需要确保编程平台端安装对应的python环境，建议参考以下链接进行安装或重新安装： python编程环境安装

安装VC库环境（可选）

下载（下载地址：GitHub RoboMaster SDK repository , 备用地址：Gitee RoboMaster SDK repository）安装VC库的exe可执行文件：

_images/vc_exe.png

警告

如果使用SDK，出现以下问题，请执行此安装:

_images/libmedia_err.png

安装VC build tools

下载（下载地址：GitHub RoboMaster SDK repository , 备用地址：Gitee RoboMaster SDK repository）安装VC build tools的exe可执行文件：

_images/vs_build_tool.png

警告

不安装VC build tools，安装SDK,会报以下错误：

_images/neti_err.jpg

安装robomaster python sdk

安装RoboMaster SDK，点开开始菜单，在搜索框中输入 cmd ，在搜索结果中，对着命令提示符程序，单击鼠标右键，菜单中点击选择 以管理员身份运行 ,并输入以下指令:

pip install robomaster

如果网络较差，多次都安装失败，可以尝试:

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple robomaster

小技巧

如果出现下列情况，请参考以下链接进行python环境安装：python编程环境安装

_images/pip_install_error.jpg

升级 RoboMaster SDK

当需要升级 RoboMaster SDK时，可在命令行中输入以下指令:

pip install --upgrade robomaster

安装 SDK 到 Linux平台

Ubuntu 16.04

Python 环境安装

介绍 Ubuntu 16.04 的Python环境安装。

安装 RoboMaster SDK

安装 RoboMaster SDK，可输入以下指令:

pip install robomaster

升级 RoboMaster SDK

当需要升级 RoboMaster SDK时，可在命令行中输入以下指令:

pip install --upgrade robomaster

小技巧

树莓派下的python sdk安装教程可参考 sdk install on Raspberry Pi.7z

安装 SDK 到 macOS X平台

安装 RoboMaster SDK

安装RoboMaster SDK，可输入以下指令:

pip install robomaster

升级 RoboMaster SDK

当需要升级 RoboMaster SDK时，可在命令行中输入以下指令:

pip install --upgrade robomaster

RoboMaster SDK 下载源码

可以在官方GitHub上下载SDK的示例代码。

Clone, fork, or report issues on the GitHub RoboMaster SDK repository.

也可以从的Gitee（国内源，下载更快）上下载SDK的示例代码。

Clone, fork, or report issues on the Gitee RoboMaster SDK repository.

RoboMaster SDK 和机器人建立连接

EP固件升级

请通过RoboMaster App查看EP固件，确保EP固件版本在01.01.0500及其以上版本，如果不是请通过RoboMaster APP进行升级，不然会影响到RoboMaster SDK的使用。

EP连接方式

Robomaster SDK 支持3种与EP的连接方式：WiFi 直连模式，WiFi 组网模式和 USB(RNDIS) 连接模式。

  1. WIFI直连 ：

Wi-Fi 直连 ：通过将机器人设置为直连模式，并连接机器人的 Wi-Fi 热点进行接入，Wi-Fi 直连模式下，机器人默认 IP 为 192.168.2.1

  • 开启机器人电源，切换智能中控的连接模式开关至 直连模式，如下图所示：

    _images/direct_connection_change.png

  • 准备具有WIFI连接功能的设备，例如：DJI 妙算、Jetson Nano 或 PC：

    _images/wifi_direct.png

    DJI 妙算、Jetson Nano 或 PC 通过 WIFI 直连 到 EP

  • 参考sdk代码 /examples/01_robot/04_ap_conn.py 目录下的例程（GitHub RoboMaster SDK repository）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import robomaster
from robomaster import robot


if __name__ == '__main__':
    # 如果本地IP 自动获取不正确，手动指定本地IP地址
    # robomaster.config.LOCAL_IP_STR = "192.168.2.20"
    ep_robot = robot.Robot()

    # 指定连接方式为AP 直连模式
    ep_robot.initialize(conn_type='ap')

    version = ep_robot.get_version()
    print("Robot version: {0}".format(version))
    ep_robot.close()

  • 运行结果:

    Robot Version: xx.xx.xx.xx
  1. USB连接

USB 连接 ：通过机器人的智能中控上的 USB 端口接入，机器人默认 IP 为 192.168.42.2

USB 连接模式，实质上是使用 RNDIS 协议，将机器人上的 USB 设备虚拟为一张网卡设备， 通过 USB 发起 TCP/IP 连接更多 RNDIS 内容请参见 RNDIS Wikipedia。

  • 选择具有 TypeA USB 接口，并支持 RNDIS 功能的第三方平台，这边列举树莓派的连接，图中蓝线即为USB连接，红线为供电线：

    _images/raspberry.png

    树莓派连接示意图

  • 参考sdk代码 /examples/01_robot/06_rndis_conn.py 目录下的例程（GitHub RoboMaster SDK repository）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import robomaster
from robomaster import robot


if __name__ == '__main__':
    ep_robot = robot.Robot()

    # 指定连接方式为USB RNDIS模式
    ep_robot.initialize(conn_type='rndis')

    version = ep_robot.get_version()
    print("Robot version: {0}".format(version))
    ep_robot.close()

  • 运行结果:

    Robot Version: xx.xx.xx.xx
  1. 组网连接 ：

Wi-Fi 组网 ：通过将机器人设置为组网模式，并将计算设备与机器人加入到同一个局域网内，实现组网连接

  • 开启机器人电源，切换智能中控的连接模式开关至 组网模式

    _images/networking_connection_change.png

  • DJI 妙算、Jetson Nano 或 PC 和 EP 连接到同一个局域网后和 EP 进行通信。

    _images/wifi_sta.png

    DJI 妙算、Jetson Nano 或 PC 路由连接至 EP

  • 安装myqr库生成二维码，按 win+r，在弹出窗口中输入 cmd 打开命令提示符界面，在命令行里面输入:

    pip install myqr

  • 参考sdk代码 /examples/01_robot/05_sta_conn_helper.py 目录下的例程（GitHub RoboMaster SDK repository）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import time
import robomaster
from robomaster import conn
from MyQR import myqr
from PIL import Image


QRCODE_NAME = "qrcode.png"

if __name__ == '__main__':

    helper = conn.ConnectionHelper()
    info = helper.build_qrcode_string(ssid="RoboMaster_SDK_WIFI", password="12341234")
    myqr.run(words=info)
    time.sleep(1)
    img = Image.open(QRCODE_NAME)
    img.show()
    if helper.wait_for_connection():
        print("Connected!")
    else:
        print("Connect failed!")

警告

示例代码13行中的，ssid （路由器名称）和 password (路由器密码)，需要根据实际的路由器信息进行填写

  • 运行示例代码，会出现二维码图片，按下机器人智能中控上的扫码连接按键，扫描二维码进行组网连接。

    _images/networking_connection_key.png

  • 运行结果:

    Connected!

同时机器人的灯效变为白色呼吸变为青绿色常亮。

小技巧

支持在组网模式下通过SN连接指定的机器人，用户通过在初始化时给 sn 参数赋值完成对机器人 sn 的输入， 参考例程 /examples/01_robot/05_sta_conn_sn.py （GitHub RoboMaster SDK repository）。在不指定 sn 时，SDK默认与搜索到的第一台机器人建立连接。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
from robomaster import robot
from robomaster import config


if __name__ == '__main__':
    ep_robot = robot.Robot()
    # 指定机器人的 SN 号
    ep_robot.initialize(conn_type="sta", sn="3JKDH2T001ULTD")

    ep_version = ep_robot.get_version()
    print("Robot Version: {0}".format(ep_version))

    ep_robot.close()

教育无人机系列连接方式

教育无人机目前主要包括 Tello EDU 以及 Tello Talent，Robomaster SDK支持通过WIFI直连模式与这两款产品建立连接。

  1. WIFI直连 ：

Wi-Fi 直连 ：通过将机器人设置为直连模式，并连接机器人的 WIFI 热点进行接入，WIFI 直连模式下，机器人默认 IP 为 192.168.10.1

  • 首先将机器人设置为 WIFI 直连模式

    • Tello EDU : 短按图中红色剪头所示电源按键，等待黄灯快闪开机完成，机器人出厂默认即为 WIFI 直连模式，如果开机时为组网模式， 可以通过电源按键重置 WIFI：在开机状态下，长按电源键 5s，期间状态指示灯将熄灭后再闪烁黄灯。 状态指示灯显示黄灯快闪后， WIFI 的 SSI 和密码将重置为出厂设置，默认无密码

      _images/tello_power.png

    • Tello Talent :: 开启机器人电源，切换扩展模块的模式开关至 直连模式，如下图所示：

      _images/direct_connection_change.png

  • 准备具有WIFI连接功能的设备连接教育无人机的 WIFI，例如：DJI 妙算、Jetson Nano 或 PC：

  • 参考sdk代码 /examples/12_drone/01_ap_conn.py 目录下的例程（GitHub RoboMaster SDK repository）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
from robomaster import robot


if __name__ == '__main__':
    # 如果本地IP 自动获取不正确，手动指定本地IP地址
    # robomaster.config.LOCAL_IP_STR = "192.168.10.22"
    tl_drone = robot.Drone()
    # 初始化
    tl_drone.initialize()

    # 获取飞机SDK版本信息
    version = tl_drone.get_sdk_version()
    print("Drone SDK Version: {0}".format(version))

    tl_drone.close()

  • 运行结果:

    Drone SDK Version: xx.xx.xx.xx
  1. 组网模式 ：

组网模式 ：将机器人设置为组网模式，并连接SDK运行设备所在的局域网进行接入，

  • 首先将飞机设置为 直连模式，并且与运行SDK的设备连接，具体操作参考上一小节
  • 运行提供的示例程序 /examples/12_drone/23_set_sta.py （GitHub RoboMaster SDK repository）， 将程序中的 ssis 与 password 参数改为当前使用的路由器的账号与密码
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import robomaster
from robomaster import robot


if __name__ == '__main__':
    tl_drone = robot.Drone()
    tl_drone.initialize()

    # 切换飞行器WiFi模式为组网模式，指定路由器SSID和密码
    tl_drone.config_sta(ssid="RoboMaster_SDK_WiFi", password="12341234")

    tl_drone.close()
  • 切换扩展模块的模式开关至组网模式，之后机器会自动连接到指定的路由器所在的局域网内
  • 将运行SDK的设备也连接至该局域网内，此时SDK与机器即在同一网络内

通讯方式

EP通讯方式

Robomaster SDK 与EP的3种连接方式在通讯协议上支持 TCP 和 UDP 通讯。

参数 TCP UDP
可靠性 可靠 不可靠
连接性 面向连接 无连接
效率 低 高
场景 对数据准确性要求高 对数据传输的实时性要求高

小技巧

机器人要实时的控制运动的可以选用 UDP, 机器人进行事件型控制可以选用 TCP

用户可以根据自己的运用场景去设置对应的通讯方式 更多TCP通讯内容可以参考：TCP Wikipedia ，UDP通讯可以参考：UDP Wikipedia。

  1. TCP通讯
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import robomaster
from robomaster import robot


if __name__ == '__main__':
    ep_robot = robot.Robot()

    # 指定连接方式为STA 组网模式, 网络通讯方式 tcp
    ep_robot.initialize(conn_type='sta', proto_type='tcp')

    version = ep_robot.get_version()
    print("Robot Version: {0}".format(version))
    ep_robot.close()
  • 组网连接

这边可以根据代码第8行中的 connect_type 参数进行修改 sta 对应组网连接，ap 对应WIFI直连，rndis 对应USB连接。

  • 运行程序，并得到结果返回:

    Robot Version: xx.xx.xx.xx
  1. UDP 通讯
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import robomaster
from robomaster import robot


if __name__ == '__main__':
    ep_robot = robot.Robot()
    # 指定连接方式为AP 直连模式, 网络通讯方式 udp
    ep_robot.initialize(conn_type='ap', proto_type='udp')

    version = ep_robot.get_version()
    print("Robot Version: {0}".format(version))
    ep_robot.close()
  • 进行组网连接

这边可以根据代码第8行中的 connect_type 参数进行修改 sta 对应组网连接，ap 对应WIFI直连，rndis 对应USB连接

小技巧

不同的通讯方式，实际是根据代码第8行中的对 robot.initialize() 函数的 proto_type 传递的参数来变更的，tcp 对应TCP通讯， udp 对应UDP通讯

  • 运行程序，并得到结果返回:

    Robot Version: xx.xx.xx.xx

教育无人机 通讯方式

目前 Tello EDU 与 Tello Talent 只支持UDP通信方式，因此不需要额外的配置

RoboMaster SDK 新手入门 - 基础篇

SDK 能做什么?

RoboMaster SDK （以下简称 SDK）是一套面向大疆 RoboMaster 系列产品的开发工具包， 目前支持的产品包括 RoboMaster EP, RoboMaster EP Core, Tello EDU, Tello Talent 等。 通过 SDK， 用户可以实现在PC上控制机器人运动以及获取机器人传感器的相关信息 （待补充？？？）

第一个SDK程序

接下来本文档将从如何获取 RoboMaster SDK（以下简称 SDK）的版本号来编写第一个 SDK 程序

  • 首先从安装的的 robomaster 包中导入自己需要的模块，这里我们导入包含获取SDK版本信息的 version 模块:

    from robomaster import version

  • 接下来通过 version 模块中的 __version__ 属性可以获得 SDK 的版本号，并将其打印:

    sdk_version = version.__version__
print("sdk version:", sdk_version)

  • 运行程序，可以看到打印的结果:

    sdk version: 0.1.1.29

示例文档中提供了获取 SDK 版本号的例程 /examples/00_general/01_sdk_version.py

1
2
3
4
5
from robomaster import version

if __name__ == "__main__":
    sdk_version = version.__version__
    print("sdk version:", sdk_version)

RoboMaster SDK 新手入门 - EP 篇

初始化机器人

在进行与机器人相关的操作之前，需要根据指定的配置初始化机器人对象

  • 首先从安装的 robomaster 包中导入 robot 模块:

    from robomaster import robot

  • 指定 RoboMaster SDK 的本地ip地址（如需手动指定），在本示例中，查询得到本地的ip地址为 192.168.2.20 （比如在Windows操作系统下，通过 快捷键 Win + R 调出的窗口中输入 cmd， 然后在 CMD窗口中输入 ipconfig ， 即可以查看设备ip的信息）， 如需指定ip使用以下语句:

    robomaster.config.LOCAL_IP_STR = "192.168.2.20"

小技巧

大部分情况下SDK能够自动获取正确的本地ip，无需手动指定这一步骤，但是当SDK运行在多网卡同时使用的设备时， 自动获取的ip可能不是与机器人进行连接的ip，此时需要手动指定ip

  • 创建 Robot 类的实例对象 ep_robot， ep_robot 即一个机器人的对象:

    ep_robot = robot.Robot()

  • 初始化机器人，如果调用初始化方法时不传入任何参数，则使用config.py中配置的默认连接方式（WIFI直连模式） 以及默认的通讯方式（udp通讯）对机器人进行初始化，在本示例中我们手动指定机器人的连接方式为组网模式, 不指定通讯方式使用默认配置:

    ep_robot.initialize(conn_type="sta")

可以通过以下语句设置默认的连接方式与通讯方式，本例中将默认的连接方式设置为 sta 模式， 默认的通讯方式设置为 tcp 方式:

config.DEFAULT_CONN_TYPE = "sta"
config.DEFAULT_PROTO_TYPE = "tcp"

至此，机器人的初始化工作就完成了，接下来可以通过相关接口对机器人进行信息查询、动作控制、多媒体使用等操作， 本文档将在后面的部分对几类接口的使用分别进行介绍

获取模块对象

部分 SDK 接口属于 Robot 对象本身，因此可以通过 Robot 对象直接调用， 但是一些接口属于 Robot 对象包含的其他模块，比如装甲灯的设置接口在 led 模块对象中， 底盘的控制接口在 chassis 模块对象中，等等。如果想使用这些接口需要首先获得相应的对象， 这里以获取 led 模块对象举例，介绍如何获取这些对象

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 可以使用两种方法获取 led 对象

    • 方法一：直接使用 . 运算符从 Robot() 对象中获取 led 对象:

      ep_led = ep_robot.led

    • 方法二：利用 Robot 对象的 get_module() 方法获得指定的对象:

      ep_led = ep_robot.get_module("led")

获取了相关对象，便可以通过该对象调用其所包含的 SDK 接口

释放机器人资源

在程序的最后，应该手动释放机器人对象相关的资源，包括释放网络地址、结束相应后台线程、释放相应地址空间等， 在 Robot 对象中，提供了用来释放相关资源的方法 close()，使用方法如下:

ep_robot.close()

小技巧

为了避免一些意外错误，记得在程序的最后调用 close() 方法哦！

查询类接口的使用

查询类接口即数据获取类接口，用户可以通过该类接口获取机器人自身的状态信息以及传感器状态等信息， 接下来将从查询机器人版本信息与查询机器人SN号两个例子来帮助用户掌握该类型接口的用法

示例一：查询机器人版本

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 使用`Robot` 对象的 get_version() 方法，方法的返回值即为代表机器人版本号的字符串， 并且将获取到的版本号打印出来:

    ep_version = ep_robot.get_version()
print("Robot Version: {0}".format(ep_version))

  • 利用 释放机器人资源 章节的介绍释放相关资源

完整的程序参考示例文件 /examples/01_robot/01_get_version.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from robomaster import robot


if __name__ == '__main__':
    ep_robot = robot.Robot()
    ep_robot.initialize(conn_type="ap")

    ep_version = ep_robot.get_version()
    print("Robot Version: {0}".format(ep_version))

    ep_robot.close()

示例二：获取机器人SN号

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 利用 Robot 对象使用 get_sn() 方法，方法的返回值即为代表机器人SN号的字符串， 并且将获取到的SN号打印出来:

    SN = ep_robot.get_sn()
print("Robot SN:", SN)

  • 利用 释放机器人资源 章节的介绍释放相关资源

完整的程序参考示例文件 /examples/01_robot/02_get_sn.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from robomaster import robot


if __name__ == '__main__':
    ep_robot = robot.Robot()
    ep_robot.initialize(conn_type="sta")

    SN = ep_robot.get_sn()
    print("Robot SN:", SN)

    ep_robot.close()

设置类接口的使用

设置类接口可以完成对机器人的相关模块的设置，本文档接下来将通过设置机器人整机运动模式与设置机器人装甲灯两个例子讲解设置类接口的使用

示例一：设置机器人整机运动模式

机器人的运动模式有三种：自由模式（FREE）、云台跟随底盘（CHASSIS_LEAD）、底盘跟随云台（GIMBAL_LEAD）， 本文档以设置机器人的运动模式为底盘跟随云台（CHASSIS_LEAD）为例带大家熟悉如何使用设置类接口

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 使用`Robot` 对象中的 set_robot_mode() 方法设置机器人的整机运动模式， 机器人的模式定义在 /examples/01_robot/02_get_sn.py 中， FREE ， GIMBAL_LEAD , CHASSIS_LEAD 是可选的三个参数， 本示例中设置机器人的整机运动模式为底盘跟随云台模式（GIMBAL_LEAD）:

    ep_robot.set_robot_mode(mode=robot.GIMBAL_LEAD)

  • 利用 释放机器人资源 章节的介绍释放相关资源

完整的程序参考示例文件 /examples/01_robot/09_set_mode.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from robomaster import robot


if __name__ == '__main__':
    ep_robot = robot.Robot()
    ep_robot.initialize(conn_type="ap")

    ep_robot.set_robot_mode(mode=robot.GIMBAL_LEAD)

    ep_robot.close()

示例二：设置机器人装甲灯

下面介绍如何通过 SDK 实现设置机器人装甲灯的操作

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作, 另外由于设置灯效时要使用 led 模块中关于装甲灯的一些定义，因此需要额外导入 led 模块:

    from robomaster import led

  • 机器人的装甲灯设置接口属于 Robot`对象包含的 `led 模块，因此首先需要获取 led 对象， 按照 获取模块对象 章节的介绍获取 led 对象, 本示例中使用方法一获取模块对象:

    ep_led = ep_robot.led

  • 使用 led 对象中的 set_led() 方法设置机器人的装甲灯效果， 在使用 led 方法时，通过 comp 参数选定要控制的装甲灯， 通过 r g b 参数指定灯的颜色， 通过 effect 参数指定led灯的显示效果。 在本例中，控制的装甲灯对象通过 comp 选定为所有装甲灯， r g b 颜色指定为红色， effect 选定的灯效为常亮灯效:

    ep_led.set_led(comp=led.COMP_ALL, r=255, g=0, b=0, effect=led.EFFECT_ON)

  • 利用 释放机器人资源 章节的介绍释放相关资源

示例程序中提供了一个完整的设置装甲灯的例程 /examples/01_robot/07_led.py， 例程中利用了for循环，实现了led灯的8次颜色变换，每次维持1秒钟

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import time
from robomaster import robot
from robomaster import led


if __name__ == '__main__':
    ep_robot = robot.Robot()
    ep_robot.initialize(conn_type="sta")

    ep_led = ep_robot.led

    # 设置灯效为常亮，亮度递增
    bright = 1
    for i in range(0, 8):
        ep_led.set_led(comp=led.COMP_ALL, r=bright << i, g=bright << i, b=bright << i, effect=led.EFFECT_ON)
        time.sleep(1)
        print("brightness: {0}".format(bright << i))

    ep_robot.close()

动作类接口的使用

动作类接口是用来控制机器人执行某些指定动作的接口，根据动作本身特性的不同， SDK中包含 即时动作控制 与 任务动作控制 两类动作接口

即时动作控制

即时控制类动作是指设置后马上生效的动作，特指宏观上是“瞬时”执行的动作， 接下来本文档将通过控制发射器射击与控制底盘速度两个例子带大家熟悉此类动作接口

示例一：控制发射器射击

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作, 另外由于使用发射器接口时要使用 blaster 模块中关于发射器的一些定义，因此需要额外导入 blaster 模块:

    from robomaster import blaster

  • 发射器的控制接口属于 blaster 模块，首先按照 获取模块对象 章节的介绍获取 blaster 对象, 本示例中使用方法一获取模块对象:

    ep_blaster = ep_robot.blaster

  • 使用 blaster 对象中的 fire() 方法控制发射器射击， 方法的参数 fire_type 可以指定发射的类型， 可选水弹、红外弹，在本示例中我们使用水弹， 参数 times 设置发射的次数，本示例中指定发射的次数为1:

    ep_balseter.fire(fire_type=balseter.WATER_FIRE, times=1)

  • 利用 释放机器人资源 章节的介绍释放相关资源

示例程序中提供了一个完整的控制发射器射击的例程 examples/06_blaster/01_fire.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import time
from robomaster import robot
from robomaster import blaster


if __name__ == '__main__':
    ep_robot = robot.Robot()
    ep_robot.initialize(conn_type="sta")

    ep_blaster = ep_robot.blaster

    # 发射1颗水弹
    ep_blaster.fire(times=1)
    time.sleep(2)

    # 发射3颗水弹
    ep_blaster.fire(fire_type=blaster.WATER_FIRE, times=3)
    time.sleep(2)

    # 发射1颗红外子弹
    ep_blaster.fire(fire_type=blaster.INFRARED_FIRE)
    time.sleep(2)

    # 发射3颗红外子弹
    ep_blaster.fire(fire_type=blaster.INFRARED_FIRE, times=3)
    time.sleep(2)

    ep_robot.close()
示例二：控制底盘速度

控制底盘速度是一种典型的即时控制，发出控制指令后机器人将会立即按照指定速度运动

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 底盘控制接口属于 chassis 模块，首先按照 获取模块对象 章节的介绍获取 chassis 对象, 本示例中使用方法一获取模块对象:

    ep_chassis= ep_robot.chassis

  • 使用 chassis 对象中的 dirve_speed() 方法控制底盘的速度， 方法的参数 x y z 分别代表前进、横移、旋转速度， 本示例中指定 x 前进速度点为 0.5 m/s, timeout 参数可以指定一个时间，超过该时间未接收到控制速度指令，SDK 将会主动控制机器人停止， 本示例中指定 timeout 为 5s, 在机器人按照指定速度运行3s后，将速度设置为 0

    ep_chassis.drive_speed(x=0.5, y=0, z=0, timeout=5)
time.sleep(3)
ep_chassis.drive_speed(x=0, y=0, z=0, timeout=5)

  • 利用 释放机器人资源 章节的介绍释放相关资源

示例程序中提供了一个完整的控制底盘速度的例程 examples/02_chassis/03_speed.py， 例程中每次令机器人按照指定速度运动三秒钟，然后改变速度

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
import time
from robomaster import robot


if __name__ == '__main__':
    ep_robot = robot.Robot()
    ep_robot.initialize(conn_type="sta")

    ep_chassis = ep_robot.chassis

    x_val = 0.5
    y_val = 0.3
    z_val = 30

    # 前进 3秒
    ep_chassis.drive_speed(x=x_val, y=0, z=0, timeout=5)
    time.sleep(3)

    # 后退 3秒
    ep_chassis.drive_speed(x=-x_val, y=0, z=0, timeout=5)
    time.sleep(3)

    # 左移 3秒
    ep_chassis.drive_speed(x=0, y=-y_val, z=0, timeout=5)
    time.sleep(3)

    # 右移 3秒
    ep_chassis.drive_speed(x=0, y=y_val, z=0, timeout=5)
    time.sleep(3)

    # 左转 3秒
    ep_chassis.drive_speed(x=0, y=0, z=-z_val, timeout=5)
    time.sleep(3)

    # 右转 3秒
    ep_chassis.drive_speed(x=0, y=0, z=z_val, timeout=5)
    time.sleep(3)

    # 停止麦轮运动
    ep_chassis.drive_speed(x=0, y=0, z=0, timeout=5)

    ep_robot.close()

任务动作控制

任务动作是指需要持续一段时间才能完成的动作，比如控制底盘向前运动一米， 底盘对于该动作需要执行一段时间才能到达指定地点。通过 SDK 控制任务动作时， SDK 将对应的任务发送给机器人，机器人收到任务后会选择执行/拒绝执行（存在机器人当前时刻无法执行对应任务的情况）并通知 SDK， 如果选择执行任务，会在任务完成时再次告知 SDK。在使用任务动作控制接口时，用户需要注意以下两点：

  • 任务动作接口的返回值为 action 对象，action 对象提供 wait_for_completed(timeout) 方法， 用户可以通过 timeout 参数指定动作的超时时长。当调用 wait_for_completed(timeout) 方法时， 程序会阻塞在该语句，直至动作执行完毕或执行超时
  • 同一模块同一时间只能执行一个动作， 因此同一模块的任务之间互斥；不同模块之间的相互独立，动作可以同时执行。 比如在使用任务动作控制接口后不立即调用 wait_for_completed() 方法时，用户在控制云台移动到指定角度的同时可以控制底盘移动到指定位置， 但是不支持在上次控制云台的任务动作还未完成时再次发送其他的控制云台的任务动作

小技巧

如果在使用任务动作控制接口时不马上调用 wait_for_completed() 方法，切记程序中要控制好逻辑， 避免在该任务执行完毕前发送与其互斥的其他任务动作命令！

接下来本文档会通过控制底盘移动指定距离来帮助大家熟悉该类接口的使用

示例一：控制底盘移动指定距离

控制底盘移动指定距离是一种任务动作控制

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 底盘控制接口属于 chassis 模块，首先按照 获取模块对象 章节的介绍获取 chassis 对象, 由于本示例中同时也会控制装甲灯，因此也需要获取 led 模块， 本示例中使用方法一获取模块对象:

    ep_chassis = ep_robot.chassis
ep_led = ep_robot.led

  • 在本示例中为了说明任务类动作的特点，在控制底盘运动后会设置装甲灯灯效。 使用 chassis 对象中的 move() 方法控制底盘的相对位置移动， 方法的参数 x y 代表 x 轴 y 轴的运动距离， 参数 z 代表 z 轴的旋转速度， 本示例中指定 x 轴的运动距离为 0.5 m, y z 两参数为 0， xy_speed 参数可以指定 xy 两轴的运动速度， z_speed 参数用来指定 z 轴的旋转速度， 本示例中指定 xy 轴的运动速度为 0.7 m/s, z 轴的旋转速度设置为 0。 设置装甲灯灯效可以参考 示例二：设置机器人装甲灯 。接下来本文档会使用三种方法控制底盘移动的任务动作：

    • 方法一：执行任务动作后，立即调用 wait_for_completed() 方法:

      ep_chassis.move(x=x_val, y=0, z=0, xy_speed=0.7).wait_for_completed()
ep_led.set_led(comp=led.COMP_ALL, r=255, g=0, b=0, effect=led.EFFECT_ON)

    • 方法二：在执行其他命令后再调用 wait_for_completed() 方法:

      chassis_action = ep_chassis.move(x=x_val, y=0, z=0, xy_speed=0.7)
ep_led.set_led(comp=led.COMP_ALL, r=255, g=0, b=0, effect=led.EFFECT_ON)
chassis_action.wait_for_completed()

    • 方法三：不使用 wait_for_completed() 方法，利用延时来保证动作执行结束:

      ep_chassis.move(x=x_val, y=0, z=0, xy_speed=0.7)
ep_led.set_led(comp=led.COMP_ALL, r=255, g=0, b=0, effect=led.EFFECT_ON)
time.sleep(10)

    三种任务动作接口的调用形式对应机器人的行为不同，方法一 机器人会先移动到指定位置之后装甲灯再全亮红色， 而 方法二 与 方法三 则会在移动的过程中装甲灯全亮红色。

小技巧

建议使用 方法一 以及 方法二 ，在合适的时机调用 wait_for_completed() 是比较安全的做法

示例程序中提供了一个完整的控制底盘移动指定距离的例程 examples/02_chassis/01_move.py，

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
from robomaster import robot


if __name__ == '__main__':
    ep_robot = robot.Robot()
    ep_robot.initialize(conn_type="sta")

    ep_chassis = ep_robot.chassis

    x_val = 0.5
    y_val = 0.6
    z_val = 90

    # 前进 0.5米
    ep_chassis.move(x=x_val, y=0, z=0, xy_speed=0.7).wait_for_completed()

    # 后退 0.5米
    ep_chassis.move(x=-x_val, y=0, z=0, xy_speed=0.7).wait_for_completed()

    # 左移 0.6米
    ep_chassis.move(x=0, y=-y_val, z=0, xy_speed=0.7).wait_for_completed()

    # 右移 0.6米
    ep_chassis.move(x=0, y=y_val, z=0, xy_speed=0.7).wait_for_completed()

    # 左转 90度
    ep_chassis.move(x=0, y=0, z=z_val, z_speed=45).wait_for_completed()

    # 右转 90度
    ep_chassis.move(x=0, y=0, z=-z_val, z_speed=45).wait_for_completed()

    ep_robot.close()

多媒体接口的使用

多媒体接口主要包括视频流与音频流两部分，接下来将通过两个示例介绍该类型接口的使用

示例一：获取视频流

获取机器人采集到的视频流有助于实现一些非常实用的案例，下面本文档将介绍如何通过 SDK 获取视频流

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作， 由于示例中会用到 camera 模块的相关定义，因此还需要导入 camera 模块:

    from robomaster import camera

  • 获取视频流相关的接口属于属于 camera 模块，首先按照 获取模块对象 章节的介绍获取 camera 对象, 本示例中使用`获取模块对象`_ 章节介绍的方法一获取模块对象:

    ep_camera= ep_robot.camera

  • camera 模块的 start_video_stream 方法有两个参数， display 参数指定是否显示获取到的视频流， resolution 参数指定视频的尺寸大小。在本示例中，向大家介绍两种获取视频流的方法，

    • 方法一：获取视频流并直接播放显示十秒:

      ep_camera.start_video_stream(display=True, resolution=camera.STREAM_360P)
time.sleep(10)
ep_camera.stop_video_stream()

    • 方法二：获取视频流，通过cv2提供的方法显示200帧图像:

      ep_camera.start_video_stream(display=False)
for i in range(0, 200):
    img = ep_camera.read_cv2_image()
    cv2.imshow("Robot", img)
    cv2.waitKey(1)
cv2.destroyAllWindows()
ep_camera.stop_video_stream()

    第一种方法直接通过 camera 对象的 start_video_tream() 方法将机器人些采集到的视频流通过SDK获取并播放； 第二种方法通过 camera 对象的 start_video_stream 方法获取到视频流，之后通过 cv2.inshow() 播放获取到的视频流

  • 利用 释放机器人资源 章节的介绍释放相关资源

示例程序中提供了一个完整的获取并直接显示视频流的例程 examples/04_camera/01_video_with_display.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import time
from robomaster import robot
from robomaster import camera


if __name__ == '__main__':
    ep_robot = robot.Robot()
    ep_robot.initialize(conn_type="sta")

    ep_camera = ep_robot.camera

    # 显示十秒图传
    ep_camera.start_video_stream(display=True, resolution=camera.STREAM_360P)
    time.sleep(10)
    ep_camera.stop_video_stream()

    ep_robot.close()

示例程序中同时提供了一个完整的获取视频流之后利用cv2提供的方法显示图像的例程 examples/04_camera/03_video_without_display.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import cv2
from robomaster import robot


if __name__ == '__main__':
    ep_robot = robot.Robot()
    ep_robot.initialize(conn_type="sta")

    ep_camera = ep_robot.camera

    # 显示200帧图传
    ep_camera.start_video_stream(display=False)
    for i in range(0, 200):
        img = ep_camera.read_cv2_image()
        cv2.imshow("Robot", img)
        cv2.waitKey(1)
    cv2.destroyAllWindows()
    ep_camera.stop_video_stream()

    ep_robot.close()

示例二：获取音频流

本示例将会通过 SDK 获取机器人采集到的音频流， 并将获取到的音频信息以 wav 文件的形式保存在本地

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 获取视频流相关的接口属于属于 camera 模块，首先按照 获取模块对象 章节的介绍获取 camera 对象, 本示例中使用`获取模块对象`_ 章节介绍的方法一获取模块对象:

    ep_camera= ep_robot.camera

  • 通过调用 camera 模块的 record_audio() 方法，将获取到的音频流保存在本地， 方法的 save_file 参数可以指定保存文件的名称， seconds 参数可以指定采集的音频时长， sample_rate 参数指定采集频率:

    ep_camera.record_audio(save_file="output.wav", seconds=5, sample_rate=16000)

  • 利用 释放机器人资源 章节的介绍释放相关资源

示例程序中提供了一个完整的获取音频流并保存在本地的例程 examples/04_camera/05_record_audio.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from robomaster import robot


if __name__ == '__main__':
    ep_robot = robot.Robot()
    ep_robot.initialize(conn_type="rndis")

    ep_camera = ep_robot.camera

    ep_camera.record_audio(save_file="output.wav", seconds=5, sample_rate=16000)
    ep_robot.close()

RoboMaster SDK 新手入门 - 教育系列无人机篇

初始化机器人

在进行与机器人相关的操作之前，需要根据指定的配置初始化机器人对象

  • 首先从安装的 robomaster 包中导入 robot 模块:

    from robomaster import robot

  • 指定 RoboMaster SDK 的本地ip地址（如需手动指定），在本示例中，查询得到本地的ip地址为 192.168.2.20 （比如在Windows操作系统下，通过 快捷键 Win + R 调出的窗口中输入 cmd， 然后在 CMD窗口中输入 ipconfig ， 即可以查看设备ip的信息）， 如需指定ip使用以下语句:

    robomaster.config.LOCAL_IP_STR = "192.168.2.20"

小技巧

大部分情况下SDK能够自动获取正确的本地ip，无需手动指定这一步骤，但是当SDK运行在多网卡同时使用的设备时， 自动获取的ip可能不是与机器人进行连接的ip，此时需要手动指定ip

  • 创建 Drone 类的实例对象 tl_drone， tl_drone 即一个机器人的对象:

    tl_drone = robot.Drone()

  • 初始化机器人，目前教育系列无人机的初始化不需要传入任何参数:

    tl_drone.initialize()

至此，机器人的初始化工作就完成了，接下来可以通过相关接口对机器人进行信息查询、动作控制、多媒体使用等操作， 本文档将在后面的部分对几类接口的使用分别进行介绍

获取模块对象

部分 SDK 接口属于 Drone 对象本身，因此可以通过 Drone 对象直接调用， 但是一些接口属于 Drone 对象包含的其他模块，比如飞机电池的信息获取接口在 led 模块对象中， 飞行器的控制接口在 flight 模块对象中，等等。如果想使用这些接口需要首先获得相应的对象， 这里以获取 flight 模块对象举例，介绍如何获取这些对象

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 可以使用两种方法获取 flight 对象

    • 方法一：直接使用 . 运算符从 Drone() 对象中获取 flight 对象:

      tl_flight = tl_drone.flight

    • 方法二：利用 Drone 对象的 get_module() 方法获得指定的对象:

      tl_flight = tl_drone.get_module("flight")

获取了相关对象，便可以通过该对象调用其所包含的 SDK 接口

释放机器人资源

在程序的最后，应该手动释放机器人对象相关的资源，包括释放网络地址、结束相应后台线程、释放相应地址空间等， 在 Drone 对象中，提供了用来释放相关资源的方法 close()，使用方法如下:

tl_drone.close()

小技巧

为了避免一些意外错误，记得在程序的最后调用 close() 方法哦！

查询类接口的使用

查询类接口即数据获取类接口，用户可以通过该类接口获取机器人自身的状态信息以及传感器状态等信息， 接下来将从查询机器人SDK固件版本信息与查询机器人SN号两个例子来帮助用户掌握该类型接口的用法

示例一：查询机器人固件SDK版本

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 使用 Drone 对象的 get_sdk_version() 方法，方法的返回值即为代表机器人SDK固件版本号的字符串， 并且将获取到的版本号打印出来:

    drone_version = tl_drone.get_sdk_version()
print("Drone sdk version: {0}".format(drone_version))

  • 利用 释放机器人资源 章节的介绍释放相关资源

完整的程序参考示例文件 /examples/12_drone/02_get_version.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import robomaster
from robomaster import robot


if __name__ == '__main__':
    tl_drone = robot.Drone()
    tl_drone.initialize()

    # 获取飞机版本信息
    drone_version = tl_drone.get_sdk_version()
    print("Drone sdk version: {0}".format(drone_version))

    tl_drone.close()

示例二：获取机器人SN号

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 利用 Drone 对象使用 get_sn() 方法，方法的返回值即为代表机器人SN号的字符串， 并且将获取到的SN号打印出来:

    SN = tl_drone.get_sn()
print("drone sn: {0}".format(SN))

  • 利用 释放机器人资源 章节的介绍释放相关资源

完整的程序参考示例文件 /examples/12_drone/03_get_sn.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import robomaster
from robomaster import robot


if __name__ == '__main__':
    tl_drone = robot.Drone()
    tl_drone.initialize()

    # 获取飞机SN信息
    SN = tl_drone.get_sn()
    print("drone sn: {0}".format(SN))

    tl_drone.close()

设置类接口的使用

设置类接口可以完成对机器人的相关模块的设置，本文档接下来将通过设置扩展led模块讲解设置类接口的使用

小技巧

设置扩展led灯目前只有 Tello Talent 机器支持！

示例一：设置机器人扩展led模块

下面介绍如何通过 SDK 实现设置机器人机器人扩展led模块的操作

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作,

  • 机器人的装甲灯设置接口属于 Drone`对象包含的 `led 模块，因此首先需要获取 led 对象， 按照 获取模块对象 章节的介绍获取 led 对象, 本示例中使用方法一获取模块对象:

    tl_led = tl_robot.led

  • 使用 led 对象中的 set_led() 方法设置机器人的扩展led灯效， 在使用 led 方法时，通过 r g b 参数可以指定led的颜色，这了将其指定为红色:

    tl_led.set_led(r=255, g=0, b=0)

  • 利用 释放机器人资源 章节的介绍释放相关资源

示例程序中提供了一个完整的设置装甲灯的例程 /examples/12_drone/20_led.py， 例程中利用了for循环，实现了led灯的8次颜色变换，每次维持0.5秒钟

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import time
import robomaster
from robomaster import robot


if __name__ == '__main__':
    tl_drone = robot.Drone()
    tl_drone.initialize()

    tl_led = tl_drone.led

    tl_led.set_led(r=0, g=0, b=0)

    rgb_list = [(100, 100, 100), (255, 255, 255), (255, 0, 0), (0, 0, 255),
                (0, 255, 0), (255, 255, 0), (255, 0, 255), (0, 255, 255)]

    for rgb_info in rgb_list:
        tl_led.set_led(r=rgb_info[0], g=rgb_info[1], b=rgb_info[2])
        time.sleep(0.5)

    tl_drone.close()

动作类接口的使用

动作类接口是用来控制机器人执行某些指定动作的接口，根据动作本身特性的不同， SDK中包含 即时动作控制 与 任务动作控制 两类动作接口。 由于飞机类机器人本身的特性决定必须要起飞后才能进行控制， 因此本文档将首先会介绍 任务动作控制，带领大家熟悉了飞行类动作之后会再介绍 即时动作控制 类的接口使用

任务动作控制

任务动作是指需要持续一段时间才能完成的动作，比如控制底盘向前运动一米， 底盘对于该动作需要执行一段时间才能到达指定地点。通过 SDK 控制任务动作时， SDK 将对应的任务发送给机器人，机器人收到任务后会选择执行/拒绝执行（存在机器人当前时刻无法执行对应任务的情况）并通知 SDK， 如果选择执行任务，会在任务完成时再次告知 SDK。在使用任务动作控制接口时，用户需要注意以下两点：

  • 任务动作接口的返回值为 action 对象，action 对象提供 wait_for_completed(timeout) 方法， 用户可以通过 timeout 参数指定动作的超时时长。当调用 wait_for_completed(timeout) 方法时， 程序会阻塞在该语句，直至动作执行完毕或执行超时
  • 同一模块同一时间只能执行一个动作， 因此同一模块的任务之间互斥；不同模块之间的相互独立，动作可以同时执行。 比如在使用任务动作控制接口后不立即调用 wait_for_completed() 方法时，用户在控制云台移动到指定角度的同时可以控制底盘移动到指定位置， 但是不支持在上次控制云台的任务动作还未完成时再次发送其他的控制云台的任务动作

小技巧

如果在使用任务动作控制接口时不马上调用 wait_for_completed() 方法，切记程序中要控制好逻辑， 避免在该任务执行完毕前发送与其互斥的其他任务动作命令！

接下来本文档会通过控制底盘移动指定距离来帮助大家熟悉该类接口的使用

示例一：控制飞机起飞并前后飞行

在本例程中，首先需要控制飞机起飞，之后控制飞机起飞并向前飞行50cm

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 飞行控制接口属于 flight 模块，首先按照 获取模块对象 章节的介绍获取 flight 对象, 由于本示例中同时也会控制扩展led模块，因此也需要获取 led 模块， 本示例中使用方法一获取模块对象:

    tl_flight = tl_drone.flight
tl_led = tl_drone.led

  • 之后控制飞机起飞升空，控制起飞时通过调用任务动作接口返回的 action 中的 wait_for_completed() 方法阻塞程序直至起飞完成:

    tl_flight.takeoff().wait_for_completed()

  • 接下来会控制飞机向前飞行50cm，本示例为了说明任务类动作的特点，在控制飞机飞行后会设置扩展led灯效。 使用 flight 对象中的 forward() 方法控制底盘向前飞行，该方法都只有一个参数 distance ， 用来指定飞行距离。 设置扩展led模块可以参考 示例一：设置机器人扩展led模块 。接下来本文档会使用三种方法使用任务动作接口

    • 方法一：执行任务动作后，立即调用 wait_for_completed() 方法:

      tl_flight.forward(distance=50).wait_for_completed()
tl_led.set_led(r=255, g=0, b=0)

    • 方法二：在执行其他命令后再调用 wait_for_completed() 方法:

      flight_action = tl_flight.forward(distance=50)
tl_led.set_led(r=255, g=0, b=0)
flight_action.wait_for_completed()

    • 方法三：不使用 wait_for_completed() 方法，利用延时来保证动作执行结束:

      flight_action = tl_flight.forward(distance=50)
tl_led.set_led(r=255, g=0, b=0)
time.sleep(8)

    三种任务动作接口的调用形式对应机器人的行为不同，方法一 机器人会向前飞行到达指定地点后再将扩展led模块设置为红色， 而 方法二 与 方法三 向前飞行的过程中将扩展led模块设置为红色。

注解

方法二 与 方法三 中，要注意不能在飞行过程使用其他 ack 为 ok/error 的接口！机器人的 ack 参考 《 Tello SDK 使用说明》

小技巧

建议使用 方法一 以及 方法二 ，在合适的时机调用 wait_for_completed() 是比较安全的做法

  • 飞机降落:

    tl_flight.land().wait_for_completed()

  • 利用 释放机器人资源 章节的介绍释放相关资源

示例程序中提供了一个完整的控制底盘前后各飞行50cm的例程 examples/12_drone/07_forward_backward.py，

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import robomaster
from robomaster import robot


if __name__ == '__main__':
    tl_drone = robot.Drone()
    tl_drone.initialize()

    tl_flight = tl_drone.flight

    # 起飞
    tl_flight.takeoff().wait_for_completed()

    # 向前飞50厘米，向后飞50厘米
    tl_flight.forward(distance=50).wait_for_completed()
    tl_flight.backward(distance=50).wait_for_completed()

    # 降落
    tl_flight.land().wait_for_completed()

    tl_drone.close()

即时动作控制

即时控制类动作是指设置后马上生效的动作，特指宏观上是“瞬时”执行的动作， 接下来本文档将通过控制遥控器杆量带大家熟悉此类动作接口

示例一：控制遥控器杆量

控制遥控器杆量是一种典型的即时控制，发出控制指令后机器人将会立即按照指定速度与方向飞行

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作

  • 飞行控制接口属于 flight 模块，首先按照 获取模块对象 章节的介绍获取 flight 对象, 本示例中使用方法一获取模块对象:

    tl_flight = tl_drone.flight

  • 之后控制飞机起飞升空，控制起飞时通过调用任务动作接口返回的 action 中的 wait_for_completed() 方法阻塞程序直至起飞完成:

    tl_flight.takeoff().wait_for_completed()

  • 接下来会控制飞机以指定的速度向左飞行三秒钟然后停止。 使用 flight 对象中的 rc() 方法控制底盘向前飞行，方法有控制横滚、俯仰、油门、偏航四个速度的参数，可以通过api文档中的介绍详细了解， 本示例中令横滚的控制参数 a 的值为 20， 来达到飞机左飞的目的, 在三秒后将飞机的所有速度全设为0，达到停止飞行的目的:

    tl_flight.rc(a=20, b=0, c=0, d=0)
time.sleep(4)

  • 飞机降落:

    tl_flight.land().wait_for_completed()

  • 利用 释放机器人资源 章节的介绍释放相关资源

示例程序中提供了一个完整的通过遥控器杆量控制飞机飞行的例程 examples/12_drone/13_rc.py，

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import time
import robomaster
from robomaster import robot

if __name__ == '__main__':
    tl_drone = robot.Drone()
    tl_drone.initialize()

    tl_flight = tl_drone.flight

    # 起飞
    tl_flight.takeoff().wait_for_completed()

    # 左移
    tl_flight.rc(a=20, b=0, c=0, d=0)
    time.sleep(4)

    # 右移
    tl_flight.rc(a=-20, b=0, c=0, d=0)
    time.sleep(3)

    # 停止
    tl_flight.rc(a=0, b=0, c=0, d=0)

    # 降落
    tl_flight.land().wait_for_completed()

    tl_drone.close()

多媒体接口的使用

教育系列无人机的多媒体部分主要指获取视频流

示例一：获取视频流

获取机器人采集到的视频流有助于实现一些非常实用的案例，下面本文档将介绍如何通过 SDK 获取视频流

  • 首先按照 初始化机器人 章节的介绍完成机器人对象的初始化操作， 由于示例中会用到 camera 模块的相关定义，因此还需要导入 camera 模块:

    from robomaster import camera

  • 获取视频流相关的接口属于属于 camera 模块，首先按照 获取模块对象 章节的介绍获取 camera 对象, 本示例中使用`获取模块对象`_ 章节介绍的方法一获取模块对象:

    tl_camera= tl_robot.camera

  • camera 模块的 start_video_stream 方法有两个参数， display 参数指定是否显示获取到的视频流，在本示例中，向大家介绍两种获取视频流的方法，

    • 方法一：获取视频流并直接播放显示十秒:

      tl_camera.start_video_stream(display=True)
time.sleep(10)
tl_camera.stop_video_stream()

    • 方法二：获取视频流，通过cv2提供的方法显示200帧图像:

      tl_camera.start_video_stream(display=False)
for i in range(0, 200):
    img = tl_camera.read_cv2_image()
    cv2.imshow("Drone", img)
    cv2.waitKey(1)
cv2.destroyAllWindows()
tl_camera.stop_video_stream()

    第一种方法直接通过 camera 对象的 start_video_tream() 方法将机器人些采集到的视频流通过SDK获取并播放； 第二种方法通过 camera 对象的 start_video_stream 方法获取到视频流，之后通过 cv2.inshow() 播放获取到的视频流

  • 利用 释放机器人资源 章节的介绍释放相关资源

示例程序中同时提供了一个完整的获取视频流之后利用cv2提供的方法显示图像的例程 examples/04_camera/01_video_with_display.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
from robomaster import robot


if __name__ == '__main__':
    tl_drone = robot.Drone()
    tl_drone.initialize()

    tl_camera = tl_drone.camera
    # 显示302帧图传
    tl_camera.start_video_stream(display=False)
    tl_camera.set_fps("high")
    tl_camera.set_resolution("high")
    tl_camera.set_bitrate(6)
    for i in range(0, 302):
        img = tl_camera.read_cv2_image()
        cv2.imshow("Drone", img)
        cv2.waitKey(1)
    cv2.destroyAllWindows()
    tl_camera.stop_video_stream()

    tl_drone.close()

RoboMaster SDK 新手入门 - 多机控制篇

多机控制简介

RobomasterSDK 支持多机控制，用户可以调用相应的多机接口，轻松控制多台机器，实现复杂的多机编队等任务

多机控制流程

多机控制主要分为以下方面：

  • 多机初始化 ，与局域网内的多台机器建立连接，并初始化相关机器人
  • 多机编号 ，通过飞机的SN号对飞机进行编号，便于后面进行多机的选中控制
  • 多机分组 & 群组控制 ，通过将多台机器进行分组，实现多机选中的效果
  • 任务控制 ，通过任务控制的方式可以同时控制不同组执行不同的动作

接下来本文档将对这几部分别进行介绍。

多机初始化

环境准备安装netifaces包:

pip install netifaces

小技巧

如果出现以下问题，请下载安装visualcppbuildtools_full.exe(下载地址：GitHub RoboMaster SDK repository)

_images/neti_err.jpg

1. 首先将机器人设置为路由器组网模式，并将所有机器人与运行 RobomasterSDK 的设备连接至同一个局域网内。 关于本部分如何操作，RobomasterEP参考 EP连接方式 ，教育飞机参考 教育无人机系列连接方式

  1. 导入多机控制相关的包:

    from multi_robomaster import multi_robot

  2. 生成多机对象

  • 示例一：生成EP机器人多机对象:

    multi_robot = multi_robot.MultiEP()

  • 示例二：生成教育机器人多机对象:

    multi_drones = multi_robot.MultiDrone()

4. 调用多机初始化函数，完成对多机器的扫描以及初始化步骤，EP多机的初始化函数不需要输入参数， 教育飞机的多机初始化函数需要指明需要扫描的飞机数量

  • 示例一：初始化EP机器人多机对象:

    multi_robots.initialize()

  • 示例二：初始化教育无人机对象，飞机的数量为2:

    multi_drones.initialize(2)

注解

注意EP机器人与教育机器人在多机初始化时的区别！

多机编号

通过将机器人编号，可以方便用户进行多机控制。 目前支持的编号策略为根据输入的SN进行机器人与编号的绑定,多机对象包含以下编号方法:

number_id_by_sn([id1, SN1], [id2, SN2], [id2, SN3] ...)

方法的参数为一系列包含机器人编号信息的列表，每一个列表包含两个元素:[id, SN]， 第一个元素为期望的编号数字，第二个元素为包含机器人SN信息的字符串, 列表的个数为用户需要编号的机器台数， 且该方法的返回值为成功编号的机器数目

本文档接下来会通过一个EP多机编号的例子带领大家熟悉如何使用该功能，教育无人机的多机编号与EP类似：

  • 示例一：假设我们有两台EP机器人需要编号，且经过之前的步骤创建了并初始化了多机对象 multi_robots， 希望将SN号为 3JKDH2T001ULTD 的机器人编号为 0 号机器人， 希望将SN号为 3JKDH3B001NN0E 的机器人编号为 1 号机器人，则可以使用如下代码完成该编号操作:

    multi_robots.number_id_by_sn([0, '3JKDH2T001ULTD'], [1, '3JKDH3B001NN0E'])

多机分组 & 群组控制

通过将机器人分为不同组，可以更加简单的进行多机控制。在进行控制时， 组对象 的控制接口调用形式与单机类似，在大多数控制情况下，用户可以将一个 组对象 想象成一个单机对象使用

生成 组对象

用户可以利用包含不同机器人编号（多机编号参考上一小节）的列表，生成包含多个机器人的 组对象 ， 在之后对该 组对象 的操作将作用于组内每个单体机器人上，多机对象支持一下创建 组对象 的接口:

build_group(robot_id_list)

方法的输入参数为包含需要分组的机器人的id信息的列表，方法的返回值为创建的 组对象 ，接下来本文档会以EP的分组操作举例， 教育机器人的分组方法与其类似：

  • 示例一：假设我们有三台EP机器人，且前面几步骤的操作都已经完成，三台机器人的编号分别为 0 1 2 号，接下来想将 0 号机器人与 1 号机器人放到一组中，将 2 号机器人放到一组中，三台机器人同时又属于另一组，则:

    robot_group1 = multi_robots.build_group([0, 1])
robot_group2 = multi_robots.build_group([2])
robot_group_all = multi_robots.build_group([0, 1, 2])

    通过以上代码，创建的 robot_group1 对象是包含 0 号与 1 号机器人的 组对象 ， 创建的 robot_group2 对象是包含 2 号机器人的 组对象 ， 创建的 robot_group_all 对象是包含全部三台机器人的 组对象 ，我们可以通过这些 组对象 控制组内机器人执行同样的命令

组对象 的相关操作

更新成员

组对象 提供支持增添/删除指定成员的功能，对应的对象方法分别是:

append(self, robots_id_list)
remove(self, robots_id_list)

方法的输入参数为包含需要添加/删除的机器人的编号的列表，返回值为操作结果，接下来以EP举例，教育飞机类似：

  • 示例一：通过前面的步骤，我们得到了 组对象 robot_group_all ，现在需要将其中的 1 号机器人 与 2 号机器人从群组中移除:

    robot_group_all.remove([1, 2])

  • 示例二： 经过思考后，我们认为删除的 1 号机器人与 2 号机器人还是需要被添加回来:

    robot_group_all.append([1, 2])
群组控制

在大多数情况下，群组控制的 动作类接口 形式与单机控制的接口形式一致，因此用户基本上可以将前面生成的 组对象 当成单机对象使用, 一下分别举例EP与教育机器人的两个控制示例：

  • 示例一：假设前面的操作都已经完成，生成的EP 组对象 为 robot_group ，本示例利用该 组对象 控制所有EP机器人进行 底盘与机器人的移动:

    # 组内所有机器人前进1米，程序阻塞至所有机器人动作完成
robot_group.chassis.move(1, 0, 0, 2, 180).wait_for_completed()

# 组内所有机器人云台向向左旋转90度，程序阻塞至所有机器人动作完成
robot_group.gimbal.move(0, 90).wait_for_completed()

目前群组控制支持的api接口列表参考 多机API列表 ， 列表中的接口参数类别以及取值范围与单机部分相同，使用形式也相同

单机控制

在某些多机控制的场景下，用户可能需要单独控制群组中的某一台机器，RobomasterSDK也支持从群组中获取单机对象，从而进行单机控制。

用户可以通过 组对象 的 get_robot(robot_id) 方法获取到单机对象，从而进行单机控制，该方法的输入参数为相应机器的编号数字， 返回值为该单机对象。另外用户可以通过”组对象”的 robot_id_list 属性获取组内所有机器人的编号列表， 下面本文档将会以教育飞机举例说明，EP机器人使用方法类似：

  • 示例一：假设前面的准备工作都已经完成，drone_group 为获取到的“组对象”，可以通过以下代码实现组内的教育飞机依次起飞:

    for drone_id in drone_group.robots_id_list:
    drone_obj = drone_group.get_robot(drone_id)
    drone_obj.flight.takeoff().wait_for_completed()

任务控制

上一节有介绍如何通过 组对象 进行简单的群组控制，但是如何同时让不同组同时做不同的动作？如何在实现不同组同时执行任务的时候保证同步？ 本节课来介绍多机对象的 任务控制 方法的使用，接口如下:

run([robot_group1, action_task1], [robot_group2, action_task2], [robot_group3, action_task3]...)

通过该接口，用户可以实现不同的组同时执行不同的动作，并且 run 方法会保证该语句执行结束时，方法输入的所有动作任务都执行完毕。 run 接口的输入参数为储存任务信息的列表，列表包含两个元素，第一个元素是期望执行任务的 组对象 ，第二个元素为用户自己编写的的任务函数。 用户定义的任务函数必须满足固定的接口形式 ，函数应只有一个参数，参数为执行函数内动作的 组对象 ，下面本文将会以EP机器人举例任务控制接口 的使用，教育飞机的使用方法类似：

  • 示例一：根据前面的教程现在已经获得了三个机器人 组对象 ，分别为包含 0 号机器人与 1 号机器人的 robot_group1, 包含 2 号 机器人的 robot_group2 ，以及包含 1 2 3 号三台机器人的 robot_group_all ，我们现在想控制 robot_group1 中 的两台机器人底盘向前移动1m，控制 robot_group2 中的 一台机器人向后移动1m， 在这两个任务动作执行完毕后，控制三台机器人全部向左 移动1m，可以利用如下方法实现

    • 首先定义上述三套动作的任务函数:

      def move_forward_task(robot_group):
    robot_group.chassis.move(x=1, y=0, z=0, xy_speed=0.7).wait_for_completed()


def move_backward_task(robot_group):
    robot_group.chassis.move(x=-1, y=0, z=0, xy_speed=0.7).wait_for_completed()


def move_left_task(robot_group):
    robot_group.chassis.move(x=0, y=-1, z=0, xy_speed=0.7).wait_for_completed()

    • 之后在利用多机对象 multi_robots 的 run() 方法指定 组对象 执行上述任务:

      # `0` 号与 `1` 号机器的底盘前进1m, `2` 号机器后退1m
multi_robots.run([robot_group1, move_forward_task], [robot_group2, move_backward_task])

# 三台机器的底盘同时左移1m
multi_robots.run([robot_group_all, move_left_task])

注解

用户自定义的动作任务函数需要满足固定的接口形式！

RoboMaster SDK 如何记录日志

配置日志等级

RoboMaster SDK 的日志等级默认为ERROR，用户可根据自己的需要进行修改。

  • 设置日志等级的语句为 /examples/01_robot/00_logger.py 中该行代码:

    logger.setLevel(logging.ERROR)

  • 用户可根据自己的需要将其修改为:

    logger.setLevel(logging.WARNING)

    或者:

    logger.setLevel(logging.INFO)

日志文件的使用

如果用户是使用过程中遇到问题，需要将日志写入文件中，并将日志文件提供给技术支持人员。

生成日志文件方法

  • 用户需要在程序最开始添加语句:

    robomaster.enable_logging_to_file()

  • 运行程序

  • SDK会自动生成对应的系统日志文件，存放路径为该程序同级目录中，日志文件命名格式为:

    RoboMasterSDK_YYYYMMDDHHMMSS_log.txt

  • 将生成的系统日志文件发送到邮箱 developer@dji.com，邮件模板如下:

    xxxxxxxx
xxxxxxxx
xxxxxxxx

示例代码

  • 参考sdk代码 /examples/01_robot/00_logger.py 目录下的例程
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

import robomaster
from robomaster import robot


if __name__ == '__main__':
    robomaster.enable_logging_to_file()

    # 如果本地IP 自动获取不正确，手动指定本地IP地址
    # robomaster.config.LOCAL_IP_STR = "192.168.2.20"

    ep_robot = robot.Robot()

    # 指定连接方式为AP 直连模式
    ep_robot.initialize(conn_type='rndis')

    version = ep_robot.get_version()
    print("Robot version: {0}".format(version))
    ep_robot.close()

  • 运行程序后SDK会在在程序的同级目录下会自动生成系统日志文件,如下图所示

    _images/log_file.png

RoboMaster SDK APIs

API接口列表。

RoboMaster SDK API 详细介绍

robomaster package

robomaster.action

class robomaster.action.Action(**kw)

基类：object

wait_for_completed(timeout=None)

等待任务动作直到完成

参数:timeout – 超时，在timeout前未完成任务动作，直接返回
返回:bool: 动作在指定时间内完成，返回True; 动作超时返回False
class robomaster.action.TextAction(**kw)

基类：robomaster.action.Action

Blocking action in plaintext protocol

wait_for_completed(timeout=None)

等待任务动作直到完成

参数:timeout – 超时，在timeout前未完成任务动作，直接返回
返回:bool: 动作在指定时间内完成，返回True; 动作超时返回False

robomaster.armor

class robomaster.armor.Armor(robot)

基类：robomaster.module.Module

static comp2id(comp)

装甲部位转换为装甲ID

参数:comp – enum (“bottom_back”, “bottom_front”, “bottom_left”, “bottom_right”, “top_left”, “top_right”) 装甲部位
返回:int: [1, 6] 装甲ID
get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

static id2comp(armor_id)

装甲ID转换为装甲部位

参数:armor_id – int [1, 6]，装甲ID
Return comp:enum: (“bottom_back”, “bottom_front”, “bottom_left”, “bottom_right”, “top_left”, “top_right”)， 装甲部位
set_hit_sensitivity(comp='all', sensitivity=5)

设置装甲灵敏度

参数:
  • comp – enum:(“all”, “top_all”, “bottom_all”, “top_left”, “top_right”, “bottom_left”, “bottom_right”, “bottom_front”, “bottom_back”)：要设置的装甲部位
  • sensitivity – int:[0, 10] 灵敏度系数，系数越大灵敏度越低
返回:

bool:返回调用结果
sub_hit_event(callback=None, *args, **kw)

打击事件订阅

参数:
  • callback –

    回调函数, 返回数据 (armor_id, hit_type)：

    param armor_id:int:[1, 6]打击装甲的编号，1 底盘后；2 底盘前；3 底盘左；4 底盘右；5 云台左；6 云台右
    param hit_type:enum:(“water”, “ir”)，被打击类型，water:水弹，ir:红外
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 事件订阅结果
sub_ir_event(callback=None, *args, **kw)

红外打击事件订阅

参数:
  • callback – 回调函数, 返回数据 (hit_cnt)
  • hit_cnt – 受到红外击打的次数
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 事件订阅结果
unsub_hit_event()

取消打击事件订阅

返回:bool: 取消事件订阅结果
unsub_ir_event()

取消红外打击事件订阅

返回:bool: 取消事件订阅结果

robomaster.battery

class robomaster.battery.Battery(robot)

基类：robomaster.module.Module

EP 电池模块

get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

sub_battery_info(freq=5, callback=None, *args, **kw)

订阅电池信息

参数:
  • freq – enum:(1,5,10,20,50) 设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 percent:

    percent:电池电量百分比
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
unsub_battery_info()

取消电池订阅

返回:bool: 取消订阅结果
class robomaster.battery.TelloBattery(robot)

基类：object

教育无人机 电池模块

get_battery()

获取电池电量信息

返回:int: 电池的剩余电量百分比
sub_battery_info(freq=5, callback=None, *args, **kw)

订阅电池信息

参数:
  • freq – enum:(1,5,10) 设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 percent:

    percent:电池电量百分比
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
unsub_battery_info()

取消订阅飞机电池信息

返回:返回取消订阅结果

robomaster.blaster

class robomaster.blaster.Blaster(robot)

基类：robomaster.module.Module

EP 发射器模块

fire(fire_type='water', times=1)

发射器发射

参数:
  • fire_type – enum: (“water”, “ir”)， 发射器发射类型，水弹、红外弹
  • times – 发射次数
返回:

bool: 调用结果
get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

set_led(brightness=255, effect='on')

设置发射器灯效

参数:
  • brightness – int:[0,255]，亮度
  • effect – enum:(“on”, “off”)，on 表示常亮，off 表示常灭
返回:

bool:调用结果

robomaster.camera

class robomaster.camera.EPCamera(robot)

基类：robomaster.module.Module, robomaster.camera.Camera

EP 摄像机模块

audio_stream_addr

机器人音频流地址

返回:tuple:(ip, port)，机器人音频流地址
conf

相机参数配置

get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

read_audio_frame(timeout=1)

读取一段音频流信息

参数:timeout – float: (0, inf)，超时时间，超过指定timeout时间后函数返回
返回:data, 已解码的音频流帧字节流
read_cv2_image(timeout=3, strategy='pipeline')

读取一帧视频流帧

参数:
  • timeout – float: (0, inf)，超时参数，在timeout时间内未获取到视频流帧，函数返回
  • strategy – enum: (“pipeline”, “newest”)，读取帧策略：pipeline 依次读取缓存的帧信息，newest 获取最新的一帧 数据，会清空旧的数据帧
返回:

image
read_video_frame(timeout=3, strategy='pipeline')

读取一帧视频流帧

参数:
  • timeout – float: (0, inf)，超时时间，超过指定timeout时间后函数返回
  • strategy – enum: (“pipeline”, “newest”) 读取帧策略：pipeline 流水线依次读取，newest 获取最新的一帧数据， 注意会清空老的数据帧队列
返回:

frame, 已解码的视频流帧字节流
record_audio(save_file='output.wav', seconds=5, sample_rate=48000)

录制音频，保存到本地，支持wav格式，单通道

参数:
  • save_file – 本地文件路径，目前仅支持wav格式
  • seconds – 录制时间
  • sample_rate – 采样率
返回:

bool: 调用结果
start_audio_stream()

开启音频流

start_video_stream(display=True, resolution='720p')

开启视频流

参数:
  • display – bool，是否显示视频流
  • resolution – enum: (“360p”, “540p”, “720p”)，设置图传分辨率尺寸
返回:

bool：调用结果
stop()

停止

stop_audio_stream()

停止音频流

Return：bool:调用结果
stop_video_stream()

停止视频流

返回:bool: 调用结果
take_photo()

拍照

返回:bool: 调用结果
video_stream_addr

机器人视频流地址

返回:tuple:(ip, port)：机器人视频流地址
class robomaster.camera.TelloCamera(robot)

基类：robomaster.camera.Camera

教育无人机 摄像机模块

read_cv2_image(timeout=3, strategy='pipeline')

读取一帧视频流帧

参数:
  • timeout – float: (0, inf)，超时参数，在timeout时间内未获取到视频流帧，函数返回
  • strategy – enum: (“pipeline”, “newest”)，读取帧策略：pipeline 依次读取缓存的帧信息，newest 获取最新的一帧 数据，会清空旧的数据帧
返回:

image
read_video_frame(timeout=3, strategy='pipeline')

读取一帧视频流帧

参数:
  • timeout – float: (0, inf)，超时时间，超过指定timeout时间后函数返回
  • strategy – enum: (“pipeline”, “newest”) 读取帧策略：pipeline 流水线依次读取，newest 获取最新的一帧数据， 注意会清空老的数据帧队列
返回:

frame, 已解码的视频流帧字节流
set_bitrate(bitrate)

设置飞机传输码率

参数:bitrate – 需要设置的传输码率，[0, 6]
返回:bool: 设置结果
set_down_vision(setting)

设置飞机图像源

参数:direction – 需要设置的图像源，[1, 0]
返回:设置结果
set_fps(fps)

设置飞机视频帧率

参数:fps – 需要设置的帧率，[high, middle, low]
返回:bool: 设置结果
set_resolution(resolution)

设置飞机视频分辨率

参数:resolution – 需要设置的视频分辨率，[high, low]
返回:bool: 设置结果
start_video_stream(display=True)

开启视频流

参数:display – bool, 是否显示视频流
返回:bool: 调用结果

robomaster.chassis

class robomaster.chassis.Chassis(robot)

基类：robomaster.module.Module

EP 底盘模块，可以控制底盘的速度、位置、订阅底盘的数据，控制麦克纳姆轮等操作

drive_speed(x=0.0, y=0.0, z=0.0, timeout=None)

设置底盘速度，立即生效

参数:
  • x – float:[-3.5,3.5]，x 轴向运动速度即前进速度，单位 m/s
  • y – float:[-3.5,3.5]，y 轴向运动速度即横移速度，单位 m/s
  • z – float:[-600,600]，z 轴向运动速度即旋转速度，单位 °/s
  • timeout – float:(0,inf)，超过指定时间内未收到麦轮转速指令，主动控制机器人停止，单位 s
drive_wheels(w1=0, w2=0, w3=0, w4=0, timeout=None)

设置麦轮转速

参数:
  • w1 – int:[-1000,1000]，右前麦轮速度，以车头方向前进旋转为正方向，单位 rpm
  • w2 – int:[-1000,1000]，左前麦轮速度，以车头方向前进旋转为正方向，单位 rpm
  • w3 – int:[-1000,1000]，左后麦轮速度，以车头方向前进旋转为正方向，单位 rpm
  • w4 – int:[-1000,1000]，右后麦轮速度，以车头方向前进旋转为正方向，单位 rpm
  • timeout – float:(0,inf)，超过指定时间内未收到麦轮转速指令，主动控制机器人停止，单位 s
get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

move(x=0, y=0, z=0, xy_speed=0.5, z_speed=30)

控制底盘运动当指定位置，坐标轴原点为当前位置

参数:
  • x – float: [-5,5]，x轴向运动距离，单位 m
  • y – float: [-5,5]，y轴向运动距离，单位 m
  • z – float: [-1800,1800]，z轴向旋转角度，单位 °
  • xy_speed – float: [0.5,2]，xy轴向运动速度，单位 m/s
  • z_speed – float: [10,540]，z轴向旋转速度，单位 °/s
返回:

返回action对象
set_pwm_freq(pwm1=None, pwm2=None, pwm3=None, pwm4=None, pwm5=None, pwm6=None)

设置PWM输出频率

参数:pwm1~6 – int:[0,50000]，pwm输出频率，单位Hz
set_pwm_value(pwm1=None, pwm2=None, pwm3=None, pwm4=None, pwm5=None, pwm6=None)

设置PWM输出占空比

参数:
  • pwm1 – int:[0,100]，pwm输出占空比，单位%
  • pwm2 – int:[0,100]，pwm输出占空比，单位%
  • pwm3 – int:[0,100]，pwm输出占空比，单位%
  • pwm4 – int:[0,100]，pwm输出占空比，单位%
  • pwm5 – int:[0,100]，pwm输出占空比，单位%
  • pwm6 – int:[0,100]，pwm输出占空比，单位%
stick_overlay(fusion_mode=0)

设置底盘的杆量叠加模式 :param fusion_mode: int:[0,1,2] 0 = 关闭SDK的杆量叠加, 1 = 使能杆量叠加,速度正方向为车身坐标系, 2 = 使能SDK模式,速度正方向为云台朝向 :return: bool:调用结果

sub_attitude(freq=5, callback=None, *args, **kw)

订阅底盘姿态信息

参数:
  • freq – enum: (1, 5, 10, 20, 50) 设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 (yaw, pitch, roll)：

    yaw:yaw轴姿态角
    pitch:pitch轴姿态角
    roll:roll轴姿态角
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
sub_esc(freq=5, callback=None, *args, **kw)

订阅底盘电调信息

参数:
  • freq – enum: (1, 5, 10, 20, 50)，设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 (speed[4], angle[4], timestamp, state):

    speed[4]:4个电机的速度值，单位rpm,范围：-8192~8191
    angle[4]:4个电机的角度值，数值范围：0~32767映射0~360
    timestamp:4个电机的包序号
    state:4个电调的状态
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
sub_imu(freq=5, callback=None, *args, **kw)

订阅底盘IMU陀螺仪信息

参数:
  • freq – enum: (1, 5, 10, 20, 50)，设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 (acc_x, acc_y, acc_z, gyro_x, gyro_y, gyro_z):

    acc_x:x轴加速度
    acc_y:y轴加速度
    acc_z:z轴加速度
    gyro_x:x轴角速度
    gyro_y:y轴角速度
    gyro_z:z轴角速度
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
sub_mode(freq=5, callback=None, *args, **kw)

订阅底盘模式信息

参数:
  • freq – enum: (1, 5, 10, 20, 50)，设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 mode:

    mode:底盘模式
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
sub_position(cs=0, freq=5, callback=None, *args, **kw)

订阅底盘位置信息

参数:
  • cs – int: [0,1] 设置底盘位置的坐标系，0 机器人当前位置，1 机器人上电位置
  • freq – enum: (1, 5, 10, 20, 50) 设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 (x, y, z):

    x:x轴方向距离，单位 m
    y:y轴方向距离，单位 m
    z:z轴方向距离，单位 m
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
sub_status(freq=5, callback=None, *args, **kw)

订阅底盘状态信息

参数:
  • freq – enum: (1, 5, 10, 20, 50)，设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 (static_flag, up_hill, down_hill, on_slope, is_pickup, slip_flag, impact_x, impact_y, impact_z, roll_over, hill_static):

    static_flag:状态标准位
    up_hill:处于上坡状态
    down_hill:处于下坡状态
    on_slope:处于倾斜状态
    is_pickup:处于抱起状态
    slip_flag:车身打滑
    impact_x:x轴发生撞击
    impact_y:y轴发生撞击
    impact_z:z轴发生撞击
    roll_over:车身翻转
    hill_static:处于斜坡状态
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
sub_velocity(freq=5, callback=None, *args, **kw)

订阅底盘加速度信息

参数:
  • freq – enum:(1, 5, 10, 20, 50) 设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据（vgx, vgy, vgz, vbx, vby, vbz)：

    vgx:上电时刻下的世界坐标系下x方向速度
    vgy:上电时刻下的世界坐标系下y方向速度
    vgz:上电时刻下的世界坐标系下z方向速度
    vbx:当前时刻的车身坐标系下x方向速度
    vby:当前时刻的车身坐标系下y方向速度
    vbz:当前时刻的车身坐标系下z方向速度
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
unsub_attitude()

取消订阅底盘姿态信息

返回:bool: 取消数据订阅的结果
unsub_esc()

取消订阅电调信息

返回:bool: 取消数据订阅的结果
unsub_imu()

取消订阅底盘IMU陀螺仪信息

返回:bool: 取消数据订阅的结果
unsub_mode()

取消订阅底盘模式信息

返回:bool: 取消数据订阅的结果
unsub_position()

取消订阅底盘位置信息

返回:bool: 取消数据订阅的结果
unsub_status()

取消订阅底盘状态信息

返回:bool: 取消数据订阅的结果
unsub_velocity()

取消订阅底盘加速度信息

返回:bool: 取消数据订阅的结果

robomaster.exceptions

exception robomaster.exceptions.TimeOutError

基类：robomaster.exceptions.SDKException

Remote Call Timeout.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

robomaster.flight

class robomaster.flight.Flight(robot)

基类：object

教育无人机 飞行器模块

backward(distance=0, retry=True)

向后飞行distance厘米， 指相对距离

Param:distance: float:[20, 500]向后飞行的相对距离，单位 cm
Param:retry: bool:是否重发命令
返回:action对象
curve(x1=0, y1=0, z1=0, x2=0, y2=0, z2=0, speed=20, mid=None, retry=True)

以设置速度飞弧线，经过对应坐标系中的(x1, y1, z1)点到（x2, y2, z2）点

如果选用mid参数，则对应坐标系为指定挑战卡的坐标系。不使用挑战卡时，飞机的前方为x轴正方向，飞机的左方为y轴的正方向 如果mid参数为默认值None,则为飞机自身坐标系

Param:x1: float:[-500, 500] x轴坐标
Param:y1: float:[-500, 500] y轴坐标
Param:z1: float:如果使用挑战卡（mid不为None），取值范围为 [0, 500]; 如果不使用挑战卡（mid为None），取值范围为[-500, 500]
Param:x2: float:[-500, 500] x轴坐标
Param:y2: float:[-500, 500] y轴坐标
Param:z2: float:如果使用挑战卡（mid不为None），取值范围为 [0, 500]; 如果不使用挑战卡（mid为None），取值范围为[-500, 500]
Param:speed: float:[10, 60] 飞行的速度
Param:mid: string: 不使用挑战卡时mid为None，运动坐标系为飞机自身坐标系；当使用挑战卡时mid为对应挑战卡编号，运动坐标系为对应挑战卡 坐标系。挑战卡编号参考挑战卡使用说明
Param:retry: bool:是否重发命令
返回:action对象
down(distance=0, retry=True)

向下飞distance厘米，指相对距离

Param:distance: float:[20, 500]向下飞行的相对距离，单位 cm
Param:retry: bool:是否重发命令
返回:action对象
flip(direction='f', retry=True)

控制飞机向指定方向翻滚

当电量低于50%时无法完成翻滚 :param direction: string: 飞机翻转的方向， ’l‘ 向左翻滚，’r‘ 向右翻滚，’f‘ 向前翻滚， ’b‘ 向后翻滚 :param: retry: bool:是否重发命令 :return: action对象

flip_backward(retry=True)

控制飞机向后翻滚

当电量低于50%时无法完成翻滚 :param: retry: bool:是否重发命令 :return: action对象

flip_forward(retry=True)

控制飞机向前翻滚

当电量低于50%时无法完成翻滚 :param: retry: bool:是否重发命令 :return: action对象

flip_left(retry=True)

控制飞机向左翻滚

当电量低于50%时无法完成翻滚 :param: retry: bool:是否重发命令 :return: action对象

flip_right(retry=True)

控制飞机向右翻滚

当电量低于50%时无法完成翻滚 :param: retry: bool:是否重发命令 :return: action对象

fly(direction='forward', distance=0, retry=True)

控制飞机向指定方向飞行指定距离。

Param:direction: string: 飞行的方向，”forward” 向上飞行， “back” 向下飞行， “up” 向上飞行， “down” 向下飞行， “left” 向左飞行， “right” 向右飞行
Param:distance: float:[20, 500]，飞行的距离，单位 cm
Param:retry: bool:是否重发命令
返回:action对象
forward(distance=0, retry=True)

向前飞行distance厘米，指相对距离

Param:distance: float:[20, 500]向前飞行的相对距离，单位 cm
Param:retry: bool:是否重发命令
返回:action对象
get_speed()

获取当前设置速度

返回:float: 当前速度值，单位 cm/s
go(x, y, z, speed=10, mid=None, retry=True)

控制飞机以设置速度飞向指定坐标位置

注意， x,y,z 同时在-20~20时，飞机不会运动。当不使用挑战卡时，飞机所在位置为坐标系原点，飞机的前方为x轴正方向，飞机的左方为y轴的正方向

Param:x: float: [-500, 500] x轴的坐标，单位 cm
Param:y: float: [-500, 500] y轴的坐标，单位 cm
Param:z: float: [-500, 500] z轴的坐标，单位 cm
Param:speed: float: [10, 100] 运动速度， 单位 cm/s
Param:mid: string: 不使用挑战卡时mid为None，运动坐标系为飞机自身坐标系；当使用挑战卡时mid为对应挑战卡编号， 运动坐标系为指定挑战卡的坐标系。支持编号可参考挑战卡使用说明。
Param:retry: bool:是否重发命令
返回:action对象
jump(x=0, y=0, z=0, speed=20, yaw=0, mid1='m-1', mid2='m-1', retry=True)

飞行器飞往mid1坐标系的(x, y, z)点后悬停，识别mid2的挑战卡，飞到mid2坐标系下(0, 0, z)的位置并且旋转到设定的yaw值

Param:x: float: [-500, 500]，x轴的坐标，单位 cm
Param:y: float: [-500, 500]，y轴的坐标，单位 cm
Param:z: float: [0, 500]，z轴的坐标，单位 cm
Param:speed: float:[10, 60]，飞行的速度, 单位 cm/s
Param:yaw: [-360, 360] 最终悬停的yaw轴角度, 单位 °
Param:mid1: string: 第一个挑战卡的id, 挑战卡id的介绍参考挑战卡使用说明
Param:mid2: string: 第一个挑战卡的id, 挑战卡id的介绍参考挑战卡使用说明
Param:retry: bool:是否重发命令
返回:action对象
land(retry=True)

自动降落

Param:retry: bool:是否重发命令
返回:action对象
left(distance=0, retry=True)

向左飞行distance厘米， 指相对距离

Param:distance: float:[20, 500]向左飞行的相对距离，单位 cm
Param:retry: bool:是否重发命令
返回:action对象
mission_pad_off()

关闭挑战卡探测

返回:bool:控制结果
mission_pad_on()

打开挑战卡探测

默认同时打开前视和下视探测 :return: bool: 控制结果

motor_off()

控制飞机停桨

返回:action对象
motor_on()

控制飞机转桨

返回:action对象
move(x=0, y=0, z=0, speed=10, mid=None, retry=True)

飞机相对位置的控制

x/y/z值不能同时在-20~20之间，适用该接口时应当先打开挑战卡检测功能

Param:x: float:[-500, 500]，目标位置在挑战卡坐标系中的x坐标，实际取值范围要根据挑战卡大小调整，单位 cm
Param:y: float:[-500, 500]，目标位置在挑战卡坐标系中的y坐标，实际取值范围要根据挑战卡大小调整，单位 cm
Param:z: float:[-500, 500]，目标位置在挑战卡坐标系中的z坐标，实际取值范围要根据挑战卡大小调整，单位 cm
Param:speed: int:[10, 100]，运动速度，单位 cm/s
Param:mid: string: 挑战卡的编号，支持编号可参考挑战卡使用说明
Param:retry: bool:是否重发命令
返回:action对象
moveto(yaw=0, retry=True)

控制飞机旋转到挑战卡坐标系中指定的绝对角度

Param:yaw: float:[-180, 180]，飞机在挑战卡上的的角度，俯视时，顺时针为正角度，逆时针为负角度
Param:retry: bool:是否重发命令
返回:action 对象
rc(a=0, b=0, c=0, d=0)

控制飞机遥控器的四个杆量

参数:
  • a – float:[-100, 100] 横滚
  • b – float:[-100, 100] 俯仰
  • c – float:[-100, 100] 油门
  • d – float:[-100, 100] 偏航
right(distance=0, retry=True)

向右飞行distance厘米， 指相对距离

Param:distance: float:[20, 500]向右飞行的相对距离，单位 cm
Param:retry: bool:是否重发命令
返回:action对象
rotate(angle=0, retry=True)

控制飞机旋转指定角度

Param:angle: float:[-360, 360] 旋转的角度，俯视飞机时，顺时针为正角度，逆时针为负角度
Param:retry: bool:是否重发命令
返回:action对象
set_speed(speed=0)

设置当前飞行速度

参数:speed – float:[10, 100]，飞行速度，单位 cm/s
返回:bool: 设置结果
stop(retry=True)

停止rc运动并悬停，任何时候都可以

Param:retry: bool:是否重发命令
返回:bool: 控制结果
sub_attitude(freq=5, callback=None, *args, **kw)

订阅飞机姿态信息

参数:
  • freq – enum:(1, 5, 10)，订阅数据的频率
  • callback – 传入数据处理的回掉函数
  • args – 回调函数参数
  • kw – 回调函数参数
返回:

bool: 数据订阅结果
sub_imu(freq=5, callback=None, *args, **kw)

订阅飞机陀螺仪信息

参数:
  • freq – enum:(1, 5, 10)，订阅数据的频率
  • callback – 传入数据处理的回掉函数
  • args – 回调函数参数
  • kw – 回调函数参数
返回:

bool: 数据订阅结果
takeoff(retry=True)

自动起飞

Param:retry: bool:是否重发命令
返回:action对象
throw_fly()

控制飞机抛飞

返回:action对象
unsub_attitude()

取消订阅飞机姿态信息

返回:bool: 取消数据订阅结果
unsub_imu()

取消订阅飞机陀螺仪信息

返回:bool: 取消数据订阅结果
up(distance=0, retry=True)

向上飞distance厘米，指相对距离

Param:distance: float:[20, 500]向上飞行的相对距离，单位 cm
Param:retry: bool:是否重发命令
返回:action对象

robomaster.gimbal

class robomaster.gimbal.Gimbal(robot)

基类：robomaster.module.Module

EP 云台模块

drive_speed(pitch_speed=30.0, yaw_speed=30.0)

控制以一定速度转动

参数:
  • pitch_speed – float: [-360, 360]，pitch轴速度，单位 °/s
  • yaw_speed – float: [-360, 360]，yaw 轴速度，单位 °/s
返回:

bool:调用结果
get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

move(pitch=0, yaw=0, pitch_speed=30, yaw_speed=30)

控制云台运动到指定位置，坐标轴原点为当前位置

参数:
  • pitch – float: [-55, 55]，pitch 轴角度，单位 °
  • yaw – float: [-55, 55]，yaw 轴角度，单位 °
  • pitch_speed – float: [0, 540]，pitch 轴运动速速，单位 °/s
  • yaw_speed – float: [0, 540]，yaw 轴运动速度，单位 °/s
返回:

返回action对象
moveto(pitch=0, yaw=0, pitch_speed=30, yaw_speed=30)

控制云台运动到指定位置，坐标轴原点为上电位置

参数:
  • pitch – int: [-25, 30]，pitch 轴角度，单位 °
  • yaw – int: [-250, 250]，yaw 轴角度，单位 °
  • pitch_speed – int: [0, 540]，pitch 轴运动速度，单位 °
  • yaw_speed – int: [0, 540]，yaw 轴运动速度，单位 °
返回:

返回action对象
recenter(pitch_speed=60, yaw_speed=60)

控制云台回中

参数:
  • pitch_speed – float: [-360, 360]，pitch轴速度，单位 °/s
  • yaw_speed – float: [-360, 360]，yaw 轴速度，单位 °/s
返回:

返回action对象
resume()

控制云台从休眠状态中恢复

返回:bool:调用结果
sub_angle(freq=5, callback=None, *args, **kw)

订阅云台姿态角信息

参数:
  • freq – enum: (1, 5, 10, 20, 50) 设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 (pitch_angle, yaw_angle, pitch_ground_angle, yaw_ground_angle):

    pitch_angle:相对底盘的pitch轴角度
    yaw_angle:相对底盘的yaw轴角度
    pitch_ground_angle:
     上电时刻pitch轴角度
    yaw_ground_angle:
     上电时刻yaw轴角度
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
suspend()

控制云台进入休眠状态

返回:bool:调用结果
unsub_angle()

取消云台姿态角订阅

返回:bool: 取消数据订阅的结果

robomaster.gripper

class robomaster.gripper.Gripper(robot)

基类：robomaster.module.Module

EP 机械爪模块

close(power=50)

控制机械爪关闭

参数:power – int: [1, 100]，控制出力
返回:bool: 调用结果
get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

open(power=50)

控制机械爪张开

参数:power – int: [1, 100]，控制出力
返回:bool: 调用结果
pause()

控制机械爪停止

返回:bool: 调用结果
sub_status(freq=5, callback=None, *args, **kw)

订阅夹爪的状态信息

参数:
  • freq – enum: (1, 5, 10, 20, 50)，设置数据订阅数据的推送频率，单位 Hz
  • callback –

    传入数据处理的回调函数,回调函数参数为：

    gripper_status:opened:夹爪打开 closed:夹爪闭合。
  • callback –

    回调函数，返回数据 (status):

    status:opened 夹爪完全打开，closed 夹爪完全闭合，normal 处在中间正常状态
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
unsub_status()

取消夹爪状态信息订阅

返回:取消订阅结果

robomaster.led

class robomaster.led.Led(robot)

基类：robomaster.module.Module

EP 装甲灯模块

get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

set_gimbal_led(comp='top_all', r=255, g=255, b=255, led_list=[0, 1, 2, 3], effect='on')

设置云台灯效

参数:
  • comp – enum: (“top_all”, “top_left”, “top_right”)，云台部位
  • r – int: [0, 255]，RGB红色分量值
  • g – int: [0, 255]，RGB绿色分量值
  • b – int: [0, 255]，RGB蓝色分量值
  • led_list – list [idx0, idx1, …]，idx：int[0,7] 云台灯序号列表.
  • effect – enum: (“on”, “off”)，灯效类型
返回:

bool: 调用结果
set_led(comp='all', r=0, g=0, b=0, effect='on', freq=1)

设置整机装甲灯效

参数:
  • comp – enum: (“all”, “top_all”, “top_right”, “top_left”, “bottom_all”, “bottom_front”, “bottom_back”, “bottom_left”, “bottom_right”) 灯效部位，all: 所有装甲灯；top_all:云台所有装甲灯； top_right: 云台右侧装甲灯；top_left: 云台左侧装甲灯; bottom_all: 底盘所有装甲灯；bottom_front: 前装甲灯； bottom_back: 后装甲灯；bottom_left: 左装甲灯；bottom_right: 右装甲灯
  • r – int: [0~255]，RGB红色分量值
  • g – int: [0~255]，RGB绿色分量值
  • b – int: [0~255]，RGB蓝色分量值
  • effect – enum: (“on”, “off”, “flash”, “breath”, “scrolling”) 灯效类型，on:常亮；off:常灭；flash:闪烁； breath:呼吸；scrolling:跑马灯（仅对云台灯有效）
  • freq – int: [1, 10]，闪烁频率，仅对闪烁灯效有效
返回:

bool:调用结果

robomaster.robot

class robomaster.robot.Robot(cli=None)

基类：robomaster.robot.RobotBase

RoboMaster EP 机甲大师 机器人

battery

获取电池模块对象

blaster

获取水弹枪模块对象

camera

获取相机模块对象

chassis

获取底盘模块对象

get_module(name)

获取模块对象

参数:name – 模块名称，字符串，如：chassis, gimbal, led, blaster, camera, battery, vision, etc.
返回:模块对象
get_robot_mode()

获取机器人工作模式

返回:自由模式返回free; 底盘跟随云台模式返回gimbal_lead；云台跟随底盘模式返回chassis_lead
get_sn()

获取机器人硬件SN信息

返回:硬件SN字符串，如：”3JKDH2T0011000”
get_version()

获取机器人固件版本号信息

返回:版本字符串，如：”01.01.0305”
gimbal

获取云台模块对象

initialize(conn_type='ap', proto_type='udp', sn=None)

初始化机器人

参数:
  • conn_type – 连接建立类型: ap表示使用热点直连；sta表示使用组网连接，rndis表示使用USB连接
  • proto_type – 通讯方式: tcp, udp

注意：如需修改默认连接方式，可在conf.py中指定DEFAULT_CONN_TYPE

led

获取灯效控制模块对象

play_audio(filename)

播放本地音频文件

参数:filename – 播放音效的文件名，目前仅支持单通道，48KHz采样的wav格式文件
返回:action对象
play_sound(sound_id, times=1)

播放系统音效

参数:
  • sound_id – 系统音效ID值
  • times – 播放次数
返回:

action对象
reset()

重置机器人到初始默认状态

robotic_arm

获取机械臂模块对象

set_robot_mode(mode='gimbal_lead')

设置机器人工作模式

参数:mode – 机器人工作模式: free表示自由模式；chassis_lead表示云台跟随底盘模式；gimbal_lead表示底盘跟随云台模式
返回:bool: 调用结果
vision

获取智能识别模块对象

class robomaster.robot.Drone(cli=None)

基类：robomaster.robot.RobotBase

教育系列无人机

close()

停止drone对象

config_sta(ssid, password)

设置飞机的连接模式为组网模式

参数:
  • ssid – 路由器的账号
  • password – 路由器的密码
返回:

bool: 设置结果
get_acceleration()

获取飞机三轴加速度值

返回:dict: 飞机三轴加速度值
get_attitude()

获取飞机三轴姿态信息

返回:dict: 飞机三轴姿态信息
get_baro()

获取电机气压计高度

返回:float: 电机气压计高度
get_drone_version()

获取飞机固件版本号

返回:string: 版本号
get_esp32_version()

获取esp32版本号

返回:string: 版本号
get_hardware()

获取飞机硬件信息 本命令仅支持SDK版本号>=30 可通过hardware?指令查询是否有接WIFI拓展模块，没接拓展模块返回TELLO，接了拓展模块返回RMTT。

返回:string: 硬件信息
get_height()

获取飞机相对高度

返回:string: 飞机相对高度
get_motor_time()

获取电机运行时间

返回:string: 电机的运行时间
get_sdk_version()

获取SDK版本号

返回:string: 版本号
get_sn()

获取飞机sn号

返回:string: 飞机的SN号
get_ssid()

获取SSID名称

返回:string: ssid名称
get_status(name)

获取飞机指定的状态

参数:name – string:需要获取的状态名，可列表[“MID”, “x”, “y”, “z”, “mpry”, “pitch”, “roll”, “yaw”, “vgx”, “vgy”, “vgz”, “templ”, “temph”, “tof”, “h”, “bat”, “baro”, “time”, “agx”, “agy”, “agz”]，详细介绍 参考SDK使用文档
返回:name对应状态的数据值，DDS_PAD_MPRY_FLAG 对应状态的返回值为长度为3的list，分别代表的在飞机相对挑战卡的pitch、yaw、row值， 其他状态返回的都是float数据
get_subnets()

Look through the machine’s internet connection and returns subnet addresses and server ip :return: list[str]: subnets

list[str]: addr_list
get_temp()

获取飞机机身温度

返回:dict: 飞机机身温度
get_wifi()

获取wifi信噪比

返回:float: wifi的信噪比数值
get_wifi_version()

获取WIFI版本号

返回:string: 版本号
scan_drone_robot()

Automatic scanning of robots in the network

参数:num –
返回:
set_wifichannel(channel)

设置飞机WIFI信道

参数:channel – 需要设置的信道
返回:bool: 设置结果
sub_drone_info(freq=5, callback=None, *args, **kw)

订阅飞机高度、气压计、电机运行时间信息

参数:
  • freq – 订阅数据的频率, 1HZ, 5HZ, 10HZ
  • callback – 传入数据处理的回掉函数
  • args – 回调函数参数
  • kw – 回调函数参数
返回:

返回订阅结果
sub_temp(freq=5, callback=None, *args, **kw)

订阅飞机温度信息

参数:
  • freq – 订阅数据的频率, 1HZ, 5HZ, 10HZ
  • callback – 传入数据处理的回掉函数
  • args – 回调函数参数
  • kw – 回调函数参数
返回:

返回订阅结果
sub_tof(freq=5, callback=None, *args, **kw)

订阅飞机tof信息

参数:
  • freq – 订阅数据的频率, 1HZ, 5HZ, 10HZ
  • callback – 传入数据处理的回掉函数
  • args – 回调函数参数
  • kw – 回调函数参数
返回:

返回订阅结果
unsub_drone_info()

取消订阅飞机高度、气压计、电机运行时间信息

返回:返回取消订阅结果
unsub_temp()

取消订阅温度信息。

返回:返回取消订阅结果。
unsub_tof()

取消订阅tof信息

返回:返回取消订阅结果

robomaster.robotic_arm

class robomaster.robotic_arm.RoboticArm(robot)

基类：robomaster.module.Module

EP 机械臂 模块

get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

move(x=0, y=0)

机械臂相对位置移动

参数:
  • x – float, x轴运动距离，向前移动为正方向，单位 mm
  • y – float, y轴运动距离，向上移动为正方向，单位 mm
返回:

action对象
moveto(x=0, y=0)

机械臂绝对位置移动

参数:
  • x – float, x轴运动距离，向前移动为正方向，单位 mm
  • y – float, y轴运动距离，向上移动为正方向，单位 mm
返回:

action对象
recenter()

控制机械臂回中

返回:action对象
sub_position(freq=5, callback=None, *args, **kw)

订阅机械臂的位置信息

参数:
  • freq – enum:(1,5,10,20,50) 设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 (pos_x, pos_y)：

    pos_x:机械臂x轴位置信息
    pos_y:机械臂y轴位置信息
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
unsub_position()

取消机械臂位置信息订阅

返回:bool: 取消订阅结果

robomaster.sensor

class robomaster.sensor.DistanceSensor(robot)

基类：robomaster.module.Module

EP 距离传感器模块

get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

sub_distance(freq=5, callback=None, *args, **kw)

订阅距离传感器测量的距离信息

参数:
  • freq – 订阅数据的频率，支持的订阅频率为1、5、10、20、50hz
  • callback –

    传入数据处理的回调函数，回调函数的参数为：

    distance[4]:4个tof的距离信息
  • args – 传入参数。
返回:

返回订阅结果。
unsub_distance()

取消距离传感器的信息订阅。

class robomaster.sensor.SensorAdaptor(robot)

基类：robomaster.module.Module

EP 传感器板模块

get_adc(id=1, port=1)

传感器板adc值获取

参数:
  • id – int[1,8]，传感器板编号
  • port – int:[1,2]，传感器板端口号
返回:

adc值
get_io(id=1, port=1)

传感器板io电平值获取

参数:
  • id – int[1,8], 传感器板编号
  • port – int:[1,2], 传感器板端口号
返回:

io电平值
get_pulse_period(id=1, port=1)

传感器板电平持续时间获取

参数:
  • id – int[1,8], 传感器板编号
  • port – int:[1,2], 传感器板端口号
返回:

电平持续时间,单位ms
get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

sub_adapter(freq=5, callback=None, *args, **kw)

订阅传感器转接板信息

参数:
  • freq – 订阅数据的频率，支持的订阅频率为1、5、10、20、50hz
  • callback –

    传入数据处理的回调函数，回调函数的参数为：

    adapter[6]:6个adapter的io/ad信息
  • args – 传入参数。
返回:

返回订阅结果。
unsub_adapter()

取消传感器转接板的信息订阅。

robomaster.servo

class robomaster.servo.Servo(robot)

基类：robomaster.module.Module

EP 舵机模块

get_angle(index=1)

获取舵机角度值

参数:index – int: [1，3]，舵机编号
返回:int 舵机角度
get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

moveto(index=0, angle=0)

舵机绝对位置移动

参数:
  • index – int [1, 3]，舵机编号
  • angle – int: [-180, 180]，舵机旋转角度，单位（°）
返回:

action对象
pause(index=0)

停止

参数:index – int: [1, 3]，舵机编号
Return bool:调用结果
sub_servo_info(freq=5, callback=None, *args, **kw)

订阅舵机角度信息

参数:
  • freq – enum: (1, 5, 10, 20, 50) 设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 (valid[4], speed[4], angle[4]):

    valid[4]:4个舵机在线状态
    speed[4]:4个舵机的速度值
    angle[4]:4个舵机的角度值
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
unsub_servo_info()

取消订阅舵机的角度信息 :return: bool: 调用结果

robomaster.uart

class robomaster.uart.Uart(robot)

基类：robomaster.module.Module

EP 串口模块

get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

serial_param_set(baud_rate=0, data_bit=1, odd_even=0, stop_bit=0, rx_en=1, tx_en=1, rx_size=50, tx_size=50)

底盘串口参数设置

默认设置：’9600’, ‘bit8’, ‘none’, ‘1’

参数:
  • baud_rate – 串口波特率，设置范围：0~4映射‘9600’，‘19200’，‘38400’，‘57600’，‘115200’
  • data_bit – 数据位设置，设置范围：0~3映射‘bit7’, ‘bit8’, ‘bit9’, ‘bit10’
  • odd_even – 数据校验位，设置范围：0~3映射‘none’, ‘odd’, ‘even’
  • stop_bit – 停止位，设置范围：1~2
  • rx_en – 接收使能
  • tx_en – 发送使能
  • rx_size – 接收buff大小
  • tx_size – 发送buff大小
返回:

返回串口设置结果
serial_send_msg(msg_buf)

底盘串口数据数据发送

参数:
  • msg_buf – 发送的数据
  • msg_len – 发送的数据长度
返回:

返回串口数据发送结果

robomaster.version

robomaster.vision

class robomaster.vision.Vision(robot)

基类：robomaster.module.Module

EP 视觉识别模块

get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

sub_detect_info(name, color=None, callback=None, *args, **kw)

订阅智能识别消息

参数:
  • name – enum: (“person”, “gesture”, “line”, “marker”, “robot”)，person 行人，gesture 手势，line 线识别， marker 标签识别，robot 机器人识别
  • color – enum:(“red”, “green”, “blue”): 指定识别颜色，仅线识别和标签识别时生效
  • callback –

    回调函数，返回数据 (list(rect_info)):

    rect_info:包含的信息如下： person 行人识别：(x, y, w, h), x 中心点x轴坐标，y 中心点y轴坐标，w 宽度，h 高度 gesture 手势识别：(x, y, w, h), x 中心点x轴坐标，y 中心点y轴坐标，w 宽度，h 高度 line 线识别：(x, y, theta, C)，x点x轴坐标，y点y轴坐标，theta切线角，C 曲率 marker 识别：(x, y, w, h, marker), x 中心点x轴坐标，y 中心点y轴坐标，w 宽度，h 高度，marker 识别到的标签 robot 机器人识别：(x, y, w, h)，x 中心点x轴坐标，y 中心点y轴坐标，w 宽度，h 高度
unsub_detect_info(name)

取消智能订阅消息

参数:name – enum: (“person”, “gesture”, “line”, “marker”, “robot”)，取消的智能识别功能
返回:bool: 调用结果

robomaster.ai_module

class robomaster.ai_module.AiModule(robot)

基类：robomaster.module.Module

EP AI模块

get_version()

获取模块版本号

:return：字符串，格式为：AA.BB.CC.DD

sub_ai_event(callback=None, *args, **kw)

订阅AI信息

参数:
  • freq – enum:(1,5,10) 设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 明文字符串:

    id:目标对象ID
    x:目标图像的坐标x
    y:目标图像的坐标y
    w:目标图像的宽度
    h:目标图像的高度
    C:目标的置信度
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
unsub_ai_event()

取消AI数据订阅

返回:bool: 取消数据订阅结果
class robomaster.ai_module.TelloAI(robot)

基类：object

教育无人机 AI模块

get_ai()

获取AI模块信息

返回:int: AI模块明文字符串
sub_ai_info(freq=5, callback=None, *args, **kw)

订阅AI信息

参数:
  • freq – enum:(1,5,10) 设置数据订阅数据的推送频率，单位 Hz
  • callback –

    回调函数，返回数据 明文字符串:

    id:目标对象ID
    x:目标图像的坐标x
    y:目标图像的坐标y
    w:目标图像的宽度
    h:目标图像的高度
    C:目标的置信度
  • args – 可变参数
  • kw – 关键字参数
返回:

bool: 数据订阅结果
unsub_ai_info()

取消订阅AI模块信息

返回:返回取消订阅结果

Module contents

RoboMaster SDK 多机api汇总

目前多机支持的api的使用大部分都与单机相同，因此本文档主要对多机目前支持的api做一个汇总。本文档单独介绍了多机中与单机用法不同的接口， 其余api的具体参数类型、取值范围以及返回值等详细介绍参考单机部分。

多机api汇总

EP 机器人部分

module api
chassis drive_wheels(w1, w2, w3, w4, timeout)
drive_speed(x, y, z, timeout)
move(x, y, z, xy_speed, z_speed)
gimbal recenter(pitch_speed, yaw_speed)
suspend()
resume()
move(pitch, yaw, pitch_speed, yaw_speed)
moveto(pitch, yaw, pitch_speed, yaw_speed)
blaser fire(fire_type, times)
set_led(brightness, effect)
led set_led(comp, r, g, b, effect, freq)
robotic_arm recenter()
move(x, y)
moveto(x, y)
gripper open(power)
close(power)
pause()
  play_sound(sound_id, times)

教育机器人部分

module api
flight takeoff()
land()
up(distance)
down(distance)
forward(distance)
backword(distance)
left(distance)
right(distance)
rotate(angle)
flip_forward()
flip_backward()
flip_left()
flip_right()
go(distance)
mission_pad_on()
mission_pad_off()
motor_on()
mortor_off()
led set_led(r, g, b)
set_led_blink(freq, r1, g1, b1, r2, g2, b2)
set_led_breath(freq, r, g, b)
set_mled_bright(bright)
set_mled_boot(display_graph)
set_mled_sc()
set_mled_graph(display_graph)
set_mled_char(color, display_char)
set_mled_char_scroll(direction, color, freq, display_str)
set_mled_char_scroll(direction, color, freq, display_graph)
battery get_battery()

以下两个接口在多机中的使用与单机不同：

  1. flight 模块的 go() 指令:

    go(go_dict)

参数： go_dict: {robot_id1: [x1, y1, z1, speed1, mid1], robot_id2: [x2, y2, z2, speed2, mid2], ... }
      其中 robot_id 是飞机的编号， x y z 分别对应单机 go 指令的坐标 x y z， speed 对应单机 go 指令的移动速度 speed，mid 对应单机 go 指令的挑战卡号码 mid

返回值： multi_action 对象

  2. led 模块的指令:

    新增command_dict参数，通过使用command_dict实现对单个飞机led的控制，功能与go类似

参数： command_dict: {robot_id1: [*args], robot_id2: [*args], ... }
      其中 robot_id 是飞机的编号， *args为各led模块的参数

返回值： multi_action 对象

  3. battery 模块的 get_battery() 指令:

    get_battery()

参数： 无

会将飞机id和对应的电量打印至控制台

RoboMaster SDK 多机编队TT

初始化无人机

在进行与无人机相关的操作之前，需要根据指定的配置初始化无人机对象

  • 首先从安装的 multi_robomaster 包中导入 multi_robot 模块:

    from multi_robomaster import multi_robot

  • 创建 MultiDrone 类的实例对象 multi_drone， multi_drone 即一个多机控制器的对象:

    multi_drone = multi_robot.MultiDrone()

  • 初始化无人机，目前教育系列无人机的初始化需要传入想要控制的飞机数量:

    multi_drone.initialize(drone_num)

至此，无人机的初始化工作就完成了。

对无人机进行编号编组

在进行多机控制时我们希望能够简化对飞机控制的流程，需要对飞机进行组队操作，由于SN码是唯一识别一架飞机的信息， 所以在多机编队时需要根据sn码来对飞机进行编队，为了简化编队时的复杂度，SDK要求用户使用自定义的id来对飞机SN码 进行映射

  • 在初始化后，使用已经实例化后的 multi_drone 对SN进行编号:

    multi_drone.number_id_by_sn([1, "0TQZH79ED00H56"], [2, "0TQZH79ED00H89"])

用户对飞机同一SN进行多个id的映射是被允许的，但是一个id只允许映射一个SN

  • 使用已经实例化后的 multi_drone 对飞机进行编组:

    multi_drone_group1 = multi_drone.build_group([1, 2])

编组后的结果为 multi_group 对象为 multi_drone_group1 ，用户可以对同一架飞机进行多次编组，如:

multi_drone_group1 = multi_drone.build_group([1])
multi_drone_group2 = multi_drone.build_group([1, 2])

  • 若用户不期望对飞机进行编号，则可使用 number_id_to_all_drone API隐式的对飞机进行0~drone_num的随机编号:

    multi_drone.number_id_to_all_drone()

至此，无人机的编组工作就完成了，接下来可以通过相关接口对无人机进行信息查询、动作控制等操作

控制无人机执行命令

  • 在完成动作编组后，使用已经实例化后的 multi_drone 执行动作:

    multi_drone.run([multi_drone_group1, base_action_1])

其中 multi_drone_group1 为编组后的 multi_group 对象， base_action_1 为用户自定义的命令函数，格式为:

def base_action_1(robot_group):
    robot_group.get_sn()
    robot_group.get_battery()

若想多group同时执行多组动作，可通过如下方式进行，以两个group为例:

multi_drone.run([multi_drone_group1, base_action_1],
                [multi_drone_group2, base_action_2])

至此，无人机的执行命令就完成了

释放无人机资源

在程序的最后，应该手动释放无人机对象相关的资源，包括释放网络地址、结束相应后台线程、释放相应地址空间等， 在 multi_drone.close 对象中，提供了用来释放相关资源的方法 close()，使用方法如下:

multi_drone.close()

小技巧

为了避免一些意外错误，记得在程序的最后调用 close() 方法哦！

查询类接口的使用

查询类接口即数据获取类接口，用户可以通过该类接口获取无人机自身的状态信息以及传感器状态等信息， 接下来将从查询无人机SN信息与查询无人机电量两个例子来帮助用户掌握该类型接口的用法

示例一：查询机器人SN信息和电量

  • 首先按照 控制无人机执行命令 章节的介绍完成无人机对象的各项操作
  • 对 base_action_1 (此例中为 base_task )进行编写如下:
1
2
3
def basic_task(robot_group):
    robot_group.get_sn()
    robot_group.get_battery()

飞机的SN号和电量会在控制台打印出来，打印格式为： “DRONE id: {}, reply: {}”

完整的程序参考示例文件 /examples/15_multi_robot/multi_drone/02_basic.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
from multi_robomaster import multi_robot


def basic_task(robot_group):
    robot_group.get_sn()
    robot_group.get_battery()


if __name__ == '__main__':
    # get drone sn by run the expamles of /15_multi_robot/multi_drone/01_scan_ip.py

    robot_sn_list = ["0TQZH79ED00H56", "0TQZH79ED00H89"]
    sn_list = []
    battery_list = []
    drone_num = 2
    multi_drone = multi_robot.MultiDrone()
    multi_drone.initialize(robot_num=2)
    multi_drone.number_id_by_sn([0, robot_sn_list[0]], [1, robot_sn_list[1]])
    tello_group = multi_drone.build_group([0, 1])
    multi_drone.run([tello_group, basic_task])
    multi_drone.close()

设置类接口的使用

设置类接口可以完成对无人机的相关模块的设置，本文档接下来将通过设置扩展led模块讲解设置类接口的使用

小技巧

设置扩展led灯目前只有 Tello Talent 机器支持！

示例一：设置无人机扩展led模块

下面介绍如何通过 SDK 实现设置无人机扩展led模块的操作

1
2
3
4
def base_action_1(robot_group):
    robot_group.set_led(255, 255, 255)
    time.sleep(2)
    robot_group.set_led(command_dict={1: [255, 0, 0], 2: [255, 255, 0]})

使用 set_led(255, 255, 255) 接口可以令当前group中所有飞机亮白灯，若想实现不同飞机分别亮不同颜色的灯， 可以使用 command_dict 关键字，当使用了 command_dict 且其参数类型为dict时，将实现当前group下 不同飞机分别亮灯，如上例所示，1号飞机亮红灯，2号飞机亮绿灯。

值得注意的是，当使用了 command_dict 关键字且其参数类型为dict时以后，其他参数将被自动忽略，字典中的飞机数 必须等于当前group中的飞机数，不支持默认设置。

完整的程序参考示例文件 /examples/15_multi_robot/multi_drone/06_led.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import time
from multi_robomaster import multi_robot


def base_action_1(robot_group):
    robot_group.set_led(255, 255, 255)
    time.sleep(2)
    robot_group.set_led(command_dict={1: [255, 0, 0], 2: [255, 255, 0]})


if __name__ == '__main__':
    # get drone sn by run the expamles of /15_multi_robot/multi_drone/01_scan_ip.py

    robot_sn_list = ["0TQZH79ED00H56", "0TQZH79ED00H89"]
    multi_drone = multi_robot.MultiDrone()
    multi_drone.initialize(robot_num=2)
    multi_drone.number_id_by_sn([1, robot_sn_list[0]], [2, robot_sn_list[1]])
    multi_drone_group1 = multi_drone.build_group([1, 2])
    multi_drone.run([multi_drone_group1, base_action_1])
    multi_drone.close()

动作类接口的使用

动作类接口是用来控制无人机执行飞行动作的接口，本文档接下来将讲解飞行类接口的使用

警告

飞机固件版本v2.5.1.4 和 wifi模块版本v1.0.0.33 以下的用户，请升级后再使用动作类接口，否则会导致执行飞行动作异常，查询方式请参考单机接口文档

示例一：控制飞机起飞并前后飞行

在本例程中，首先需要控制两组共两架飞机起飞，之后控制飞机起飞并向前向后各飞行100cm

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

from multi_robomaster import multi_robot


def takeoff_land_task1(robot_group):
    robot_group.takeoff().wait_for_completed()
    robot_group.forward(100).wait_for_completed()
    robot_group.land().wait_for_completed()


def takeoff_land_task2(robot_group):
    robot_group.takeoff().wait_for_completed()
    robot_group.backward(100).wait_for_completed()
    robot_group.land().wait_for_completed()


if __name__ == '__main__':
    # get drone sn by run the expamles of /15_multi_robot/multi_drone/01_scan_ip.py

    robot_sn_list = ["0TQZH79ED00H56", "0TQZH79ED00H89"]
    multi_drone = multi_robot.MultiDrone()
    multi_drone.initialize(robot_num=2)
    multi_drone.number_id_by_sn([0, robot_sn_list[0]], [1, robot_sn_list[1]])
    multi_drone_group1 = multi_drone.build_group([0])
    multi_drone_group2 = multi_drone.build_group([1])
    multi_drone.run([multi_drone_group1, takeoff_land_task1],
                    [multi_drone_group2, takeoff_land_task2])
    multi_drone.close()

警告

不同于单机，多机执行飞行动作时，wait_for_completed()接口为必写项，如忘记书写则可能导致当前动作的下一动作无法运行，在等待一段时间后会执行当前动作之后的第二个动作

示例二：控制飞机移动到目标坐标点

在本例程中，首先需要控制两架飞机起飞，之后控制飞机起飞并以大地毯中点为圆心， 以50cm为边长，在100cm高度上以100cm/s的速度按正方形轨迹运动

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
def base_action_1(robot_group):
    robot_group.mission_pad_on()
    robot_group.takeoff().wait_for_completed()
    robot_group.go({1: [-50, -50, 100, 100, "m12"], 2: [50, 50, 100, 100, "m12"]}).wait_for_completed()
    robot_group.set_mled_char("r", "heart")
    robot_group.go({1: [-50, 50, 100, 100, "m12"], 2: [50, -50, 100, 100, "m12"]}).wait_for_completed()
    robot_group.set_mled_char("p", "heart")
    robot_group.go({1: [50, 50, 100, 100, "m12"], 2: [-50, -50, 100, 100, "m12"]}).wait_for_completed()
    robot_group.go({1: [50, -50, 100, 100, "m12"], 2: [-50, 50, 100, 100, "m12"]}).wait_for_completed()
    robot_group.land().wait_for_completed()
    robot_group.mission_pad_off()

值得注意的是，多机编队的go指令强制用户使用地毯坐标进行运动，为了编程安全不支持飞机自身坐标系移动， 字典中的飞机数必须等于当前group中的飞机数，不支持默认设置。

完整的程序参考示例文件 /examples/15_multi_robot/multi_drone/05_go.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
from multi_robomaster import multi_robot


def base_action_1(robot_group):
    robot_group.mission_pad_on()
    robot_group.takeoff().wait_for_completed()
    robot_group.go({1: [-50, -50, 100, 100, "m12"], 2: [50, 50, 100, 100, "m12"]}).wait_for_completed()
    robot_group.set_mled_char("r", "heart")
    robot_group.go({1: [-50, 50, 100, 100, "m12"], 2: [50, -50, 100, 100, "m12"]}).wait_for_completed()
    robot_group.set_mled_char("p", "heart")
    robot_group.go({1: [50, 50, 100, 100, "m12"], 2: [-50, -50, 100, 100, "m12"]}).wait_for_completed()
    robot_group.go({1: [50, -50, 100, 100, "m12"], 2: [-50, 50, 100, 100, "m12"]}).wait_for_completed()
    robot_group.land().wait_for_completed()
    robot_group.mission_pad_off()


if __name__ == '__main__':
    # get drone sn by run the expamles of /15_multi_robot/multi_drone/01_scan_ip.py

    robot_sn_list = ["0TQZH79ED00H56", "0TQZH79ED00H89"]
    multi_drone = multi_robot.MultiDrone()
    multi_drone.initialize(robot_num=2)
    multi_drone.number_id_by_sn([1, robot_sn_list[0]], [2, robot_sn_list[1]])
    multi_drone_group1 = multi_drone.build_group([1, 2])
    multi_drone.run([multi_drone_group1, base_action_1])
    multi_drone.close()

RoboMaster SDK 多机编队EP

这里以window 64位为例，介绍robomaster SDK的EP编队教程：

Demo的环境要求及物料清单

  1. 编程环境

（1）下载RoboMaster-SDK压缩包，Github下载链接：RoboMaster-SDK压缩包 (备用Gitee下载链接：RoboMaster-SDK压缩包)，下载步骤：

  • 点击 Code ,点击 Download ZIP 下载压缩包。
_images/download_sdk.png
  • 解压下载完的RoboMaster-SDK-master.zip压缩包：
_images/zip.png

  • 压缩文件包含：

    1.VS相关运行库： VisualCppRedist_AIO_20200707.exe

    2.VS build tool: visualcppbuildtools_full.exe

    3.RoboMaster SDK示例代码: examples

    4.第三方库安装脚本： lib_install.bat

（2）安装必要的VC库：

运行RoboMaster-SDK压缩包中的 VisualCppRedist_AIO_20200707.exe ，并完成安装：

_images/vc_exe.png

警告

不安装VC库，使用SDK，会引起以下问题:

_images/libmedia_err.png

（3）安装VS Build Tool：

运行RoboMaster-SDK压缩包中的 visualcppbuildtools_full.exe ，并完成安装：

_images/vs_build_tool.png

（4）python环境安装：

  1. 从 python 官网上 找到可以下载的安装包，以Python3.7.8 为例，选择安装文件进行下载。

警告

请确保下载的 python.exe 是64位的，python sdk适配3.6.6以上python版本，否则会影响python sdk的使用，如果电脑上已经安装了python环境，建议卸载重新安装。

_images/win_python_setup11.png

  1. 步骤（1）：确认安装包版本是 64-bit, 否则会影响Python sdk使用。

    步骤（2）：勾选 Add Python 3.7 to Path。

    步骤（3）：选择 Install Now 进行安装，如下图所示。

_images/win_python_setup21.png
  1. 安装完成后按 win+r，在弹出窗口中输入 cmd 打开命令提示符界面，在命令行里面输入 python, 确认 Python 3.7.8 安装成功。
_images/python_version1.png

（5）python第三方依赖库安装：

方法一：在下载的RoboMaster-SDK压缩包目录(RoboMaster-SDK-master/lib_install.bat )中找到lib_install.bat文件，鼠标右键单击该文件，选择以管理员身份运行即可。

方法二：安装RoboMaster SDK，点击电脑开始菜单，在搜索框中输入 cmd ，在搜索结果中，对着命令提示符程序，单击鼠标右键，菜单中点击选择 以管理员身份运行 ,并依次输入以下指令:

pip install robomaster
pip install netaddr
pip install netifaces
pip install myqr
  1. EP小车
  • 数量：6台EP步兵车

小技巧

如果没有6台EP小车，2台EP小车也可以，后面的示例代码请更换参考 /examples/15_muti_robot/multi_ep/02_two_ep_demo.py

  • 固件版本：01.01.0500

小技巧

固件版本升级可以通过Robomaster App进行，确保固件版本号在01.01.0500及以上版本。

EP组网连接

步骤1：首先将每台EP机器人设置为路由器组网模式并将电脑与机器人加入到同一个局域网内，实现组网连接

如下图所示：

_images/networking_connection_change.png

步骤2：生成二维码

  • 参考下载的RoboMaster-SDK压缩包目录下的示例代码 /examples/01_robot/05_sta_conn_helper.py 目录下的例程
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import time
import robomaster
from robomaster import conn
from MyQR import myqr
from PIL import Image


QRCODE_NAME = "qrcode.png"

if __name__ == '__main__':

    helper = conn.ConnectionHelper()
    info = helper.build_qrcode_string(ssid="RoboMaster_SDK_WIFI", password="12341234")
    myqr.run(words=info)
    time.sleep(1)
    img = Image.open(QRCODE_NAME)
    img.show()
    if helper.wait_for_connection():
        print("Connected!")
    else:
        print("Connect failed!")

警告

示例代码13行中的：

info = helper.build_qrcode_string(ssid=”RoboMaster_SDK_WIFI”, password=”12341234”)

ssid （路由器名称）和 password (路由器密码)，需要根据实际的路由器信息进行填写

  • 运行示例代码，会出现二维码图片，按下机器人智能中控上的扫码连接按键，扫描二维码进行组网连接。

    _images/networking_connection_key.png

  • 运行结果:

    Connected!

同时机器人的灯效变为白色呼吸变为青绿色常亮。

注解

一共6台EP小车需要连接WiFi，首次逐个连接6台EP小车时，连接每台小车都要重复运行示例代码，连接完成后，下次重启小车时会自动连接。

运行多机编队示例代码

  • 参考下载的RoboMaster-SDK压缩包目录下的示例代码 /examples/15_muti_robot/multi_ep/03_six_ep_demo.py 目录下的例程
  1. 待每台机器人连接同一个路由器成功后，需手动修改示例代码中的机器人SN编号，每台机器人的SN编号位于智能中控的标签中，如下图所示：
_images/sn_num.jpg

2.编辑示例代码，找到示例代码的203行：

1
2
                      '3JKDH3B001M8MW', '3JKDH3B001PQ53', '3JKDH3B001470C']

根据机器人的SN依次修改示例代码里的SN。

  1. 根据6个SN的顺序，依次按照下图摆放6台机器人，箭头方向为机器人朝向。
_images/6EPlocate.png

运行修改后的示例程序

  • 打开 /examples/15_muti_robot/multi_ep/ 目录，按住键盘shift，然后再目录任意空白处单击鼠标右键，单击选择 “在此处打开Powershell窗口” ，或 “在此处打开命令窗口”

  • 运行代码,命令窗口输入:

    python 03_six_ep_demo.py

机械臂与机械爪

介绍

机械臂支持 FPV 精准遥控，机械爪配合机械臂使用，支持夹力控制，用户可在 App 中通过第一人称视角操控机械臂和机械爪完成任务。

_images/arm&gripper.png

使用说明

用户可以控制机械臂的移动范围、机械爪的开合距离。其中，机械臂的水平移动范围为 0-0.22 米，垂直移动范围为 0-0.15 米；机械爪的开合距离约为 10 厘米。

警告

1.当机械臂或机械爪处于工作状态时，请尽量避免对其施加外力。

2.请勿碰撞或损伤机械臂或机械爪，避免导致性能下降或舵机运行异常。

3.避免因用身体部位接触机械臂或机械爪旋转或尖锐部分而导致受伤。

4.及时清理水滴、水晶弹残渣等异物，避免腐蚀结构表面。

机械爪PWM 接口说明:

机械爪支持力矩控制模式

_images/arm_pwm.png
序号 引脚
1 485A/PWM
2 485B
3 VCC-12V
4 GND

PWM 信号为50Hz，占空比为2.5%~12.5%。

  1. 2.5%~7.5% 占空比对应闭合力度[ 最大，0];
  2. 7.5%~12.5% 占空比对应开合力度[0，最大]。

Python API

请参考 机械臂 和 机械爪

舵机

介绍

舵机的油门控制方式除了支持 485 控制，还可以进行 PWM 控制，控制模式包含：速度模式和角度模式。

注解

舵机的控制模式

舵机的控制模式需要通过官方的编程接口（ Scratch / Python ）进行切换，并且会记录在舵机内部，不会随着舵机掉电而重置。使用 PWM 控制前请确认舵机当前的控制模式。

引脚说明

舵机上的 485 管脚和 PWM 管脚复用，如下图所示

_images/arm_pwm.png
序号 引脚
1 485A/PWM
2 485B
3 VCC-12V
4 GND

控制说明

在 PWM 控制方式下，舵机对应的输入输出

控制模式 脉冲周期 油门范围 舵机输出
角度模式 50Hz 2.5%~12.5% 0°~360°
速度模式 50hz 2.5%~7.5% 49rpm~0rpm,顺时针
7.5%~12.5% 0rpm~—49rpm,逆时针

Python API

请参考 舵机

红外深度传感器

介绍

红外深度传感器的设计是基于飞行时间 TOF (Time of Flight) 原理，即传感器发出经调制的近红外光，遇物体后反射，传感器通过计算光线发射和反射时间差或相位差，来计算距离物体的距离。

产品特性

红外深度传感器的探测面积见下图：

_images/tof.png

其发出的是一个角度为 20° 的圆锥光，这个光斑 D 与距离 Dist 的关系：

D=2×Dist×tan⁡(10)

要实现最佳测试效果，应保证目标物的尺寸要至少等于 TOF 光斑的尺寸。

小技巧

如果目标物小于光斑大小，那么应保证目标物尽量在光斑的中心位置，因为光斑内的光强分布并不是均匀的，而是呈一个类高斯分布，中间光强大，四周光强小，为了保证返回光能量足够，应尽量保证目标物在光斑中心。

引脚说明

_images/tof_module.png

这里介绍红外深度传感器的UART口：

编号 引脚 功能 对应连接项
1 VCC 供电 电源正极
2 GND 供电 电源地
3 TX 发送 RX
4 RX 接收 TX

通讯协议和数据格式

通讯接口 波特率 数据位 停止位 奇偶校验
UART 115200 8 1 none

控制命令输入:

ir_distance_sensor_measure_on
描述:打开红外深度传感器数据输出，输出频率为20 Hz
ir_distance_sensor_measure_off
描述:关闭红外深度传感器数据输出

数据输出:

ir distance:xxx
描述:红外深度传感器数据格式

小技巧

命令格式都以字符串形式输入和输出

Python API

请参考 红外深度传感器

传感器转接模块

介绍

传感器转接模块是为了方便用户将温度、压力、测距等传感器接入 RoboMaster EP而设计的，可在Scratch 编程环境中获取传感器数据信息，每个模块均有两个传感器接口，两个接口功能相同。

_images/pinboard.png

引脚说明

端口 引脚 功能
port1 VCC 电源正极，输出电压3.3V
GND 电源地
I/O 电平输入，输入范围0~3.3V
AD 模拟电压输入，输入范围0~3.3V
port2 同Port1 同port1

Python API

请参考 传感器转接模块

UART 接口

介绍

UART 是第三方平台跟 EP 连接的一种方式。用户通过 UART 可以很方便地将搭载在 EP 上的单片机跟 EP 建立连接，并在单片机上实现交互逻辑，使用明文 SDK 和 EP 机器人进行通信，实现对 EP 的自动化控制。

引脚说明

EP 的 UART 接口设置在运动控制器上，引脚说明如下：

_images/uart.png

串口配置

通讯接口 波特率 数据位 停止位 奇偶校验
UART 115200 8 1 none

第三方平台连接方式

请参考 UART 连接

Python 编程示例

  1. PC 通过串口转 USB 连接到 EP 运动控制器的 UART 接口上。

  2. PC 端开启串口调试助手，选择打开串口对应 COM 口。

  3. 打开已跟 EP 建立连接设备的官方 App，进入 Python 编程模式。

  4. 在 Python 编程界面下，写一个简单的程序，使用 read_string() 读取串口数据，打印出来后再通过 write_string() 进行转发，并点击 “开始” 按钮运行程序。

  5. 在串口调试助手上发送一个字符串，看是否能正确收到发出去的字符串。并查看 App 上是否正确打印了收到的字符串。

    _images/uart_serial.png

    串口调试助手发送并回显字符串

    _images/uart_pc.png

    App 打印收到的字符串并进行转发

明文 SDK 示例

  1. PC 通过串口转 USB 连接到 EP 运动控制器的 UART 接口上。

  2. PC 端开启串口调试助手，选择打开串口对应 COM 口。

  3. 在串口调试助手上发送字符串 command;，若能收到 EP 发回来的 ok 表示明文 SDK 解析成功。

    _images/uart_serial_sdk.png

    串口调试助手发送 SDK 字符串收到回应

警告

在通过 UART 发送明文 SDK 指令时，一定要记得在命令后面加 ; 分号，否则会解析失败。

Python API

请参考 UART

明文 SDK 介绍

RoboMaster EP 最重要的一个功能是支持明文 SDK，包含各个内置模块和拓展模块的控制接口，以及视频流、音频流的输出接口。 EP 支持 USB、 WIFI、 UART 等多种接入方式，用户可根据平台接口选择任意方式接入。

明文 SDK 极大的丰富了 EP 的扩展性，使其能够方便地与 第三方平台通信，提供了二次开发的可能性。下面将使用 Wi-Fi 直接连接 方式（其他连接模式请参考 建立连接），以完成 控制发射器发射 功能为例，介绍SDK中明文协议的使用。

开发前的准备

  1. 准备一台 PC 电脑，需具备 Wi-Fi 功能
  2. PC 上搭建 Python 3.x 环境，安装方式请参考 Python Getting Started

建立连接

  1. 开启电源

    开启机器人电源，切换智能中控的连接模式开关至 直连模式，如下图所示：

    _images/direct_connection_change1.png

  2. 建立Wi-Fi连接

    打开电脑的无线网络访问列表，选择位于机身贴纸上对应的 Wi-Fi 名称，输入 8 位密码，选择连接

  3. 准备连接脚本

    在完成 Wi-Fi 后，我们还需要编程与机器人建立 TPC/IP 连接，并在对应的端口上传输特定的 明文协议，就可以实现相应的控制，更多 明文协议 请参考 协议内容。

    这里我们以 Python 编程语言为例，编写脚本来完成 建立控制连接，接收用户指令，传输明文协议 的过程，达到控制机器人的目的。

    参考代码如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# -*- encoding: utf-8 -*-
# 测试环境: Python 3.6 版本

import socket
import sys

# 直连模式下，机器人默认 IP 地址为 192.168.2.1, 控制命令端口号为 40923
host = "192.168.2.1"
port = 40923

def main():

        address = (host, int(port))

        # 与机器人控制命令端口建立 TCP 连接
        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

        print("Connecting...")

        s.connect(address)

        print("Connected!")

        while True:

                # 等待用户输入控制指令
                msg = input(">>> please input SDK cmd: ")

                # 当用户输入 Q 或 q 时，退出当前程序
                if msg.upper() == 'Q':
                        break

                # 添加结束符
                msg += ';'

                # 发送控制命令给机器人
                s.send(msg.encode('utf-8'))

                try:
                        # 等待机器人返回执行结果
                        buf = s.recv(1024)

                        print(buf.decode('utf-8'))
                except socket.error as e:
                        print("Error receiving :", e)
                        sys.exit(1)
                if not len(buf):
                        break

        # 关闭端口连接
        s.shutdown(socket.SHUT_WR)
        s.close()

if __name__ == '__main__':
        main()

  1. 将上述代码保存为 rm_sdk.py

  2. 运行脚本

    运行 rm_sdk.py 文件 (Windows系统在安装完成Python环境后可直接双击 *.py 文件运行，若无法运行，请按键 win+r 并输入 cmd，按回车后打开命令运行, 键入 python rm_sdk.py 运行；Linux系统请按键 ctrl+alt+t 打开命令行键入 python rm_sdk.py)

  3. 建立 TCP/IP 控制连接

    当运行窗口输出 Connecting... 时，代表正在尝试与机器人建立连接，当运行窗口输出 Connected!; 时，表示已经成功建立控制连接。

使能 SDK 模式

要进行 SDK 控制，我们需要控制机器人进入 SDK 模式。 在上述 Python 运行窗口输入 command 命令，按回车键，程序将会发送该命令至机器人，返回 ok 即机器人成功进入 SDK 模式:

>>> please input SDK cmd: command
ok

成功进入 SDK 模式后，我们就可以输入控制命令来控制机器人了。

发送控制命令

继续输入 blaster fire ，返回 ok ，同时，发射器会发射一次:

>>> please input SDK cmd: blaster fire
ok

此时，您可以输入其他控制指令来进行机器人控制，更多控制指令请参考 明文协议。

退出 SDK 模式

在完成所有控制指令之后，我们需要退出 SDK 模式，这样机器人的其他功能才可以正常使用。

输入 quit, 退出 SDK 模式，退出 SDK 模式后无法继续使用 SDK 功能，若要使用，请重新输入 command 进入 SDK 模式:

>>> please input SDK cmd: quit
ok

小结

上面我们通过与机器人建立物理连接，与机器人建立 TCP/IP 控制连接，控制机器人进入 SDK 模式，发送控制指令，退出 SDK 模式等几个步骤，实现了通过 SDK 对机器人进行相关的控制功能。您可以通过增加其中 发送控制指令 部分的内容，来实现更为复杂的逻辑，完成更为有趣的功能。

其中 Python 编程控制部分，如果您更熟悉其他语言的使用，也可以使用其他语言完成整个控制流程。

如果您手边的设备不支持 Wi-Fi ，无法使用 Wi-Fi 直接连接，可以参考 连接 使用其他连接模式。

以上就是 SDK 快速入门内容，更多使用细节请参见 SDK文档，更多示例代码请参见 RoboMaster Sample Code。

接入方式

连接方式

机器人支持多种连接方式，可通过任意一种连接方式接入使用 SDK 功能

  • 直接连接 ：

    1. Wi-Fi 直连 ：通过将机器人设置为直连模式，并连接机器人的 Wi-Fi 热点进行接入
    2. USB 连接 ：通过机器人的智能中控上的 USB 端口接入（需支持 RNDIS 功能）
    3. UART 连接 ：通过机器人的运动控制器上的 UART 接口接入

  • 组网连接 ：

    Wi-Fi 组网 ：通过将机器人设置为组网模式，并将计算设备与机器人加入到同一个局域网内，实现组网连接

连接参数

Wi-Fi 直连/Wi-Fi 组网/USB 连接方式请参考以下参数配置：

  • IP 地址说明：

    • Wi-Fi 直连模式下，机器人默认 IP 为 192.168.2.1
    • Wi-Fi 组网模式下，机器人 IP 由路由器动态分配，可通过监听 IP 广播 数据端口来获取当前局域网内机器人 IP 地址来进行连接
    • USB 连接模式下，需要计算设备支持 RNDIS 功能，机器人默认 IP 为 192.168.42.2

  • 端口及连接方式说明：

数据 端口号 连接方式 说明
视频流 40921 TCP 需执行开启视频流推送命令，才有数据输出
音频流 40922 TCP 需执行开启音频流推送命令，才有数据输出
控制命令 40923 TCP 可通过当前通道使能 SDK 模式，参见 SDK 模式控制
消息推送 40924 UDP 需执行开启消息推送命令，才有数据输出
事件上报 40925 TCP 需执行开启事件上报命令，才有数据输出
IP 广播 40926 UDP 当机器人未与任何设备建立连接时，会有数据输出
  1. UART 连接方式请参考以下 UART 参数配置
波特率 数据位 停止位 校验位
115200 8 1 None

警告

UART 连接方式下的数据说明：

UART 连接方式下，仅提供 控制命令/消息推送/事件上报 数据，如需 视频流/音频流 数据，请使用 Wi-Fi/USB 连接模式

连接示例

下面我们将以 Python 编程语言为基础，介绍多种连接方式的使用范例。以下所有示例中，默认 PC 上需要集成 Python 3.x 环境（安装方式请参考 Python Getting Started），后面不再赘述。

WIFI 直连模式

  • 环境准备
  1. 准备一台 PC 电脑，需具备 Wi-Fi 功能。
  • 建立连接

  1. 开启电源

    开启机器人电源，切换智能中控的连接模式开关至 直连模式，如下图所示：

    _images/direct_connection_change1.png

  2. 建立 Wi-Fi 连接

    打开电脑的无线网络访问列表，选择位于机身贴纸上对应的 Wi-Fi 名称，输入 8 位密码，选择连接

  3. 准备连接脚本

    建立 Wi-Fi 连接后，我们还需要编程与机器人建立 TPC/IP 连接 机器人开放多个连接端口可供连接，我们首先应完成 控制命令端口 的连接（直连模式下机器人 IP 地址为 192.168.2.1, 控制命令端口号: 40923），以使能机器人 SDK 模式。

    这里我们以 Python 编程语言为例，编写脚本来完成 建立控制连接，使能 SDK 模式 功能

    参考代码如下

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
    # -*- encoding: utf-8 -*-
# 测试环境: Python 3.6 版本

import socket
import sys

# 直连模式下，机器人默认 IP 地址为 192.168.2.1, 控制命令端口号为 40923
host = "192.168.2.1"
port = 40923

def main():

        address = (host, int(port))

        # 与机器人控制命令端口建立 TCP 连接
        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

        print("Connecting...")

        s.connect(address)

        print("Connected!")

        while True:

                # 等待用户输入控制指令
                msg = input(">>> please input SDK cmd: ")

                # 当用户输入 Q 或 q 时，退出当前程序
                if msg.upper() == 'Q':
                        break

                # 添加结束符
                msg += ';'

                # 发送控制命令给机器人
                s.send(msg.encode('utf-8'))

                try:
                        # 等待机器人返回执行结果
                        buf = s.recv(1024)

                        print(buf.decode('utf-8'))
                except socket.error as e:
                        print("Error receiving :", e)
                        sys.exit(1)
                if not len(buf):
                        break

        # 关闭端口连接
        s.shutdown(socket.SHUT_WR)
        s.close()

if __name__ == '__main__':
        main()

  4. 将上述代码保存为 rm_direct_connection_sdk.py

  5. 运行脚本

    Windows 系统 在安装完成 Python 环境后可直接双击*.py 文件运行，若无法运行，请按 win+r 并输入 cmd，按回车后打开命令运行, 键入 python rm_direct_connection_sdk.py 运行；

    Linux 系统 请按 ctrl+alt+t 打开命令行键入 python rm_direct_connection_sdk.py 运行

  6. 建立 TCP/IP 控制连接

    当运行窗口输出 Connecting... 时，代表正在尝试与机器人建立连接，当运行窗口输出 Connected!; 时，表示已经成功建立控制连接。

  • 验证

在成功建立控制连接后，在命令行里输入 command, 机器人返回 ok;，则表示已经完成连接，并且机器人进入 SDK 模式成功，之后您就可以输入任意控制指令控制机器人了。

  • 其他

UART物理链路连接示例请参考：UART

WIFI 路由器模式

  • 环境准备
  1. 准备一台 PC 电脑，具备网络功能（Wi-Fi 或者有线网络皆可）
  2. 准备一台家用路由器
  • 建立连接

  1. 开启电源

    开启机器人电源，切换智能中控的连接模式开关至 组网模式

    _images/networking_connection_change1.png

  2. 建立组网连接

    Wi-Fi：

    若使用 Wi-Fi 连接，请将 PC 电脑通过 Wi-Fi 连接至路由器上

    有线网络：

    若使用有线网络连接，请将 PC 电脑通过网线连接至路由器的 LAN 口

    确保 PC 已经接入路由器后，打开 RoboMaster App，进入组网连接页面，按下机器人智能中控上的扫码连接按键，扫描二维码进行组网连接，直到连接成功。

    _images/networking_connection_key1.png

  3. 获取机器人在局域网内的 IP 地址

    在完成组网连接后，我们的 PC 机已经和机器人处于同一个局域网内，接下来需要编程与机器人建立 TPC/IP 连接，并连接到 控制命令端口 端口，以使能机器人 SDK 模式。

    若您使用的路由器开启了 DHCP 服务，则机器人的 IP 地址为路由器动态分配，我们需要进一步获取机器人在局域网内的 IP 地址。这里提供两种办法获取：

    1. 若您通过 RoboMaster App 进行的组网连接，则进入 RoboMaster App的 设置->连接 页面，机器人在局域网内的 IP 地址会在此处显示。
    2. 若您通过其他方式进行的组网连接，则需要通过 监听机器人地址广播 来获取机器人在局域网内的 IP 地址，更多细节请参考 广播 部分。

    参考代码如下

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    # -*- encoding: utf-8 -*-
import socket

ip_sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# 绑定 IP 广播端口
ip_sock.bind(('0.0.0.0', 40926))

# 等待接收数据
ip_str = ip_sock.recvfrom(1024)

# 输出数据
print(ip_str)

    将上述代码保存为 rm_get_robot_ip.py, 运行上述代码，命令行输出:

    robot ip 192.168.0.115

    我们可以看到，通过 监听机器人地址广播 可以获取到机器人在局域网内的 IP 地址为 192.168.0.115

  1. 准备连接脚本

    我们已经获取到机器人的 IP 地址，这里我们仍以 Python 编程语言为例，编写脚本来完成 建立控制连接，使能 SDK 模式 功能

    参考代码如下

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
    # -*- encoding: utf-8 -*-
# 测试环境：Python 3.6 版本

import socket
import sys

# 组网模式下，机器人当前 IP 地址为 192.168.0.115, 控制命令端口号为 40923
# 机器人 IP 地址根据实际 IP 进行修改
host = "192.168.0.115"
port = 40923

def main():

        address = (host, int(port))

        # 与机器人控制命令端口建立 TCP 连接
        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

        print("Connecting...")

        s.connect(address)

        print("Connected!")

        while True:

                # 等待用户输入控制指令
                msg = input(">>> please input SDK cmd: ")

                # 当用户输入 Q 或 q 时，退出当前程序
                if msg.upper() == 'Q':
                        break

                # 添加结束符
                msg += ';'

                # 发送控制命令给机器人
                s.send(msg.encode('utf-8'))

                try:
                        # 等待机器人返回执行结果
                        buf = s.recv(1024)

                        print(buf.decode('utf-8'))
                except socket.error as e:
                        print("Error receiving :", e)
                        sys.exit(1)
                if not len(buf):
                        break

        # 关闭端口连接
        s.shutdown(socket.SHUT_WR)
        s.close()

if __name__ == '__main__':
        main()

  2. 将上述代码保存为 rm_networking_connection_sdk.py

  3. 运行脚本

    Windows 系统：在安装完成 Python 环境后可直接双击*.py 文件运行，若无法运行，请按 win+r 并输入 cmd，按回车后打开命令运行, 键入 python rm_networking_connection_sdk.py 运行；

    Linux 系统 请按：ctrl+alt+t 打开命令行键入 python rm_networking_connection_sdk.py 运行

  4. 建立 TCP/IP 控制连接

    当运行窗口输出 Connecting... 时，代表正在尝试与机器人建立连接，当运行窗口输出 Connected!; 时，表示已经成功建立控制连接。

  • 验证

在成功建立控制连接后，在命令行里输入 command, 机器人返回 ok;，则表示已经完成连接，并且机器人进入 SDK 模式成功，之后你就可以输入任意控制指令进行机器人控制了。

USB 连接

USB 连接模式，实质上是使用 RNDIS 协议，将机器人上的 USB 设备虚拟为一张网卡设备，通过 USB 发起 TCP/IP 连接。更多 RNDIS 内容请参见 RNDIS Wikipedia。

  • 环境准备
  1. 准备一台具备 RNDIS 功能的 PC 电脑（请确认 PC 电脑上已经配置好 RNDIS 功能）
  2. 准备一根 Micro-USB 数据线
  • 建立连接

  1. 开启电源

    开启机器人电源，无需关心连接模式开关位置

  2. 建立 USB 连接

    将 USB 数据线接入到机器人智能中控上的 USB 口，另一端与电脑相连

  3. 测试连接

    打开命令行窗口，运行:

    ping 192.168.42.2

    若命令行输出通信成功，则表示链路正常，可以进行下一步，如:

    PING 192.168.42.2 (192.168.42.2) 56(84) bytes of data.
64 bytes from 192.168.42.2: icmp_seq=1 ttl=64 time=0.618 ms
64 bytes from 192.168.42.2: icmp_seq=2 ttl=64 time=1.21 ms
64 bytes from 192.168.42.2: icmp_seq=3 ttl=64 time=1.09 ms
64 bytes from 192.168.42.2: icmp_seq=4 ttl=64 time=0.348 ms
64 bytes from 192.168.42.2: icmp_seq=5 ttl=64 time=0.342 ms

--- 192.168.42.2 ping statistics ---
5 packets transmitted, 5 received, 0% packet loss, time 4037ms
rtt min/avg/max/mdev = 0.342/0.723/1.216/0.368 ms

    若命令行输出 无法访问… 或者显示超时，则需要检查 PC 上 RNDIS 服务是否配置正常，并重启小车重试，如:

    PING 192.168.42.2 (192.168.42.2) 56(84) bytes of data.

--- 192.168.42.2 ping statistics ---

4 packets transmitted, 0 received, 100% packet loss, time 3071ms

  1. 准备连接

    连接过程与 WIFI 直连模式 -> 准备连接脚本 类似，需要将机器人 IP 地址替换为 USB 模式下的 IP 地址，其余代码与步骤保持不变即可，这里不再赘述。

    参考代码变更如下

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    # -*- encoding: utf-8 -*-
# 测试环境: Python 3.6 版本

import socket
import sys

# USB 模式下，机器人默认 IP 地址为 192.168.42.2, 控制命令端口号为 40923
host = "192.168.42.2"
port = 40923

# other code
  • 验证

在成功建立控制连接后，在命令行里输入 command, 机器人返回 ok;，则表示已经完成连接，并且机器人进入 SDK 模式成功，之后你就可以输入任意控制指令进行机器人控制了。

UART 连接

  • 环境准备
  1. 一台 PC 电脑，并确定已安装 USB 转串口模块驱动
  2. USB 转串口模块
  3. 三根杜邦线
  • 建立连接

  1. 开启电源

    开启机器人电源，无需关心连接模式开关位置

  2. 连接 UART

    将杜邦线插在机器人底盘主控上的 UART 接口上，分别插在 GND, RX, TX 引脚上，另一端对应插在 USB 转串口模块的 GND, TX, RX 引脚

  3. 配置 UART，建立通信连接

    这里，我们仍以 Python 编程为例，进行 Windows 系统下 UART 相关配置。

    1. 确认 PC 已识别 USB 转串口模块，并在 电脑设备管理器 中的 端口 里确认对应的串口号，如 COM3。

    2. 安装 serial 模块:

      pip install pyserial

    3. 编写代码进行 UART 控制，参考代码如下：

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
    # -*- encoding: utf-8 -*-
# 测试环境：Python 3.6 版本
import serial

ser = serial.Serial()

# 配置串口 波特率 115200，数据位 8 位，1 个停止位，无校验位，超时时间 0.2 秒
ser.port = 'COM3'
ser.baudrate = 115200
ser.bytesize = serial.EIGHTBITS
ser.stopbits = serial.STOPBITS_ONE
ser.parity = serial.PARITY_NONE
ser.timeout = 0.2

# 打开串口
ser.open()

while True:

        # 等待用户输入控制指令
        msg = input(">>> please input SDK cmd: ")

        # 当用户输入 Q 或 q 时，退出当前程序
        if msg.upper() == 'Q':
                break

        # 添加结束符
        msg += ';'

        ser.write(msg.encode('utf-8'))

        recv = ser.readall()

        print(recv.decode('utf-8'))

# 关闭串口
ser.close()
    1. 将上述程序保存为 rm_uart.py, 并运行
  • 验证

在成功建立控制连接后，在命令行里输入 command;, 机器人返回 ok;，则表示已经完成连接，并且机器人进入 SDK 模式成功，之后您就可以输入任意控制指令进行机器人控制了。

小技巧

示例代码

更多连接相关示例代码请参考 RoboMaster Sample Code

明文协议

协议格式

控制命令

IN：<obj> <command> <params> [<seq>];

  • 描述
    • 控制命令协议格式，一般用来与机器人做控制上的交互
    • 以 ; 作为结束符
  • 参数
    • obj (str): 控制对象字符串
    • command (str): 控制命令字符串
    • params (str): 命令参数字符串，一般为 <key> <value> 形式
    • seq (str): 命令序号字符串，一般为 seq <seq_value> 形式，可选参数

OUT：<result> [<seq>];

  • 描述
    • 控制命令响应结果协议格式，一般用来确认控制命令执行结果
    • 不做特殊说明的情况下，所有控制命令均有响应结果
    • 以 ; 作为结束符
  • 参数
    • result (exec_result_enum): 执行结果字符串
    • seq (str): 执行结果序号字符串，一般为 seq <seq_value> 形式

注解

<seq>

<seq> 可用来标识当前消息的唯一性，当控制命令中带有 <seq> 参数时， 对应命令的响应结果结果中即包含对应的序号

消息推送

OUT: <obj> push <attr> <value>;

  • 描述
    • 消息推送协议格式，通过控制命令打开某消息推送后即可接收到
    • 消息推送将会以固定的频率进行的推送，推送频率取决于使能当前消息推送时的频率设置
    • 以 ; 作为结束符
  • 参数
    • obj (str): 推送对象
    • attr (str): 推送数据属性
    • value (str): 推送数据数值

事件上报

OUT: <obj> event <attr> <value>;

  • 描述
    • 事件上报协议格式，通过控制命令打开某事件上报开关后即可接收到
    • 以 ; 作为结束符
  • 参数
    • obj (str): 发生事件的对象
    • attr (str): 事件数据属性
    • value (str) 事件数据数值

注解

触发机制

当成功使能对应 事件上报 功能后，若发生事件，则会进行一次事件上报

IP 广播

OUT: robot ip <addr>;

  • 参数
    • addr (str): 当前连接模式下的机器人的 IPv4 地址

注解

广播生命周期

当处于 Wi-Fi 组网 模式下，机器人会不断在对应端口上广播自己的 IPv4 地址，您可通过该 IP 地址连接到机器人，当成功连接后，广播停止

视频流

OUT: H.264 编码实时视频流数据，分辨率为 1280*720，刷新率为 30 FPS，需要对视频流数据进行正确的解码操作才能实时显示视频画面。

音频流

OUT: Opus 编码实时音频流数据，采样率为 48000 bps，帧大小为 960 bit，单通道，需要对音频流数据进行正确的解码操作才能实时播放音频。

小技巧

Decoder

接收端音视频解码示例代码请参见 Stream Decoder

注解

IN/OUT

该文档中，控制指令中出现的前缀 IN 或者 OUT 在控制指令中无实际意义，仅为标识以机器人为主体的情况下，当前指令的数据流向：

IN：标识当前数据为从外部设备发送至机器人

OUT：标识当前数据为从机器人发送至外部设备

实际使用中，请忽略该标识，仅发送和接收实际的控制命令即可

协议内容

SDK 模式控制

进入 SDK 模式

IN：command;

  • 描述
    • 控制机器人进入 SDK 模式
    • 当机器人成功进入 SDK 模式后，才可以响应其余控制命令
退出 SDK 模式

IN: quit;

  • 描述
    • 控制机器人退出 SDK 模式，重置所有设置项
    • Wi-Fi/USB 连接模式下，当连接断开时，机器人会自动退出 SDK 模式

机器人控制

机器人运动模式控制

IN：robot mode <mode>

  • 描述
    • 设置机器人运动模式
  • 参数
  • 示例
    • robot mode chassis_lead; : 将机器人的运动模式设置为“云台跟随底盘模式”

注解

机器人运动模式

机器人运动模式描述了云台与底盘之前相互作用与相互运动的关系，每种机器人模式都对应了特定的作用关系。

机器人运动模式分为三种模式：

  1. 云台跟随底盘模式：该模式下，云台的 YAW 轴会进入持续跟随底盘 YAW 轴的运动的状态，云台将不响应所有控制指令中 YAW 轴控制的部分，影响指令有 云台运动速度控制 云台相对位置控制 云台绝对位置控制
  2. 底盘跟随云台模式：该模式下，底盘的 YAW 轴会进入持续跟随云台 YAW 轴的运动的状态，底盘将不响应所有控制指令中 YAW 轴控制的部分，影响指令有 底盘运动速度控制 底盘轮子速度控制 底盘相对位置控制
  3. 自由模式：该模式下，云台的 YAW 轴与底盘的 YAW 轴运动互不影响
机器人运动模式获取

IN: robot mode ?

  • 描述
    • 查询当前机器人运动模式
  • 返回值
  • 示例
    • IN：robot mode ?; : 查询当前的机器人运动模式
    • OUT: chassis_lead; : 机器人返回当前的运动模式为 云台跟随底盘模式

警告

获取指令中的 ?

注意：查询指令中的 ? 与前面命令部分中间存在一个空格

机器人剩余电量获取

IN: robot battery ?

  • 描述
    • 查询当前机器人剩余电量
  • 返回值
    • battery_percentage (int:[1-100]): 机器人剩余电量，满电量为100
  • 示例
    • IN：robot battery ?; : 查询当前的机器人剩余电量
    • OUT: 20; : 机器人返回当前的剩余电量为 20

底盘控制

底盘运动速度控制

IN: chassis speed x <speed_x> y <speed_y> z <speed_z>

  • 描述
    • 控制底盘运动速度
  • 参数
    • speed_x (float:[-3.5,3.5]): x 轴向运动速度，单位 m/s
    • speed_y (float:[-3.5,3.5]): y 轴向运动速度，单位 m/s
    • speed_z (float:[-600,600]): z 轴向旋转速度，单位 °/s
  • 示例
    • chassis speed x 0.1 y 0.1 z 1; : 底盘 x 轴速度为 0.1 m/s，y 轴速度为 0.1 m/s，z 轴旋转速度为 1°/s
底盘轮子速度控制

IN: chassis wheel w1 <speed_w1> w2 <speed_w2> w3 <speed_w3> w4 <speed_w4>

  • 描述
    • 控制四个轮子的速度
  • 参数
    • speed_w1 (int:[-1000, 1000]): 右前麦轮速度，单位 rpm
    • speed_w2 (int:[-1000, 1000]): 左前麦轮速度，单位 rpm
    • speed_w3 (int:[-1000, 1000]): 右后麦轮速度，单位 rpm
    • speed_w4 (int:[-1000, 1000]): 左后麦轮速度，单位 rpm
  • 示例
    • chassis wheel w2 100 w1 12 w3 20 w4 11; : 底盘左前麦轮的速度为 100 rpm，右前麦轮速度为 12 rpm，右后麦轮速度为 20 rpm，左后麦轮速度为 11 rpm
底盘相对位置控制

IN: chassis move { [x <distance_x>] | [y <distance_y>] | [z <degree_z>] } [vxy <speed_xy>] [vz <speed_z>]

  • 描述
    • 控制底盘运动当指定位置，坐标轴原点为当前位置
  • 参数
    • distance_x (float:[-5, 5]): x 轴向运动距离，单位 m
    • distance_y (float:[-5, 5]): y 轴向运动距离，单位 m
    • degree_z (int:[-1800, 1800]): z 轴向旋转角度，单位 °
    • speed_xy (float:(0, 3.5]): xy 轴向运动速度，单位 m/s
    • speed_z (float:(0, 600]): z 轴向旋转速度， 单位 °/s
  • 示例
    • chassis move x 0.1 y 0.2; ：以当前位置为坐标原点，向 x 轴运动 0.1 m，向 y 轴运动 0.2 m
底盘速度获取

IN: chassis speed ?

  • 描述
    • 获取底盘速度信息
  • 返回值
    • <x> <y> <z> <w1> <w2> <w3> <w4> ：x 轴向运动速度(m/s)，y 轴向运动速度(m/s)，z 轴向旋转速度(°/s)，w1 右前麦轮速度(rpm)，w2 左前麦轮速速(rpm)，w3 右后麦轮速度(rpm)，w4 左后麦轮速度(rpm)
  • 示例
    • IN: chassis speed ?; : 获取底盘的运动速度信息
    • OUT: 1 2 30 100 150 200 250; : 底盘当前的 x 轴向运动速度为 1 m/s，y 轴向运动速度 2 m/s，z 轴向旋转速度为 20°/s，1 号轮子转速为 100 rpm，2 号轮子转速为 100 rpm，3 号轮子转速为 100 rpm，4 号轮子转速为 100 rpm
底盘位置获取

IN: chassis position ?

  • 描述
    • 获取底盘位置信息
  • 返回值
    • <x> <y> <z> ：x 轴位置(m)，y 轴位置(m)，偏航角度(°)
  • 示例
    • IN: chassis position ?; ：获取底盘的位置信息
    • OUT: 1 1.5 20; ：底盘当前的位置距离上电时刻位置，沿 x 轴运动了 1 m，沿 y 轴运动了 1.5 m，旋转了 20°
底盘姿态获取

IN: chassis attitude ?

  • 描述
    • 获取底盘姿态信息
  • 返回值
    • <pitch> <roll> <yaw> ：pitch 轴角度(°)，roll 轴角度(°)，yaw 轴角度(°)
  • 示例
    • chassis attitude ?; ：查询底盘的姿态信息
底盘状态获取

IN: chassis status ?

  • 描述
    • 获取底盘状态信息
  • 返回值
    • <static> <uphill> <downhill> <on_slope> <pick_up> <slip> <impact_x> <impact_y> <impact_z> <roll_over> <hill_static>
      • static：是否静止
      • uphill：是否上坡
      • downhill：是否下坡
      • on_slope：是否溜坡
      • pick_up：是否被拿起
      • slip：是否滑行
      • impact_x：x 轴是否感应到撞击
      • impact_y：y 轴是否感应到撞击
      • impact_z：z 轴是否感应到撞击
      • roll_over：是否翻车
      • hill_static：是否在坡上静止
  • 示例
    • IN: chassis status ?; ：查询底盘的状态
    • OUT: 0 1 0 0 0 0 0 0 0 0 0; : 底盘当前处于上坡状态
底盘信息推送控制

IN：chassis push {[position <switch> pfreq <freq>][attitude <switch> afreq <freq>] | [status <switch> sfreq <switch>] [freq <freq_all>]}

  • 描述
    • 打开/关闭底盘中相应属性的信息推送
    • 频率设置
      • 各单独的功能支持单独的频率设置，如：
        • chassis push position on pfreq 1 attitude on; : 打开位置和姿势推送，位置推送频率为 1 Hz，姿势推送频率使用默认设置 5 Hz
      • 支持当前模块所有功能频率统一设置，如：
        • chassis push freq 10; #chassis 推送统一为 10 Hz
        • chassis push position pfreq 1 freq 5; #此时有 freq 参数，将会忽略 pfreq
      • 支持的频率 1, 5, 10, 20, 30, 50
    • 推送数据格式参见 底盘推送信息数据
  • 参数
    • switch (switch_enum) ：当此处参数使用 on 时，表示打开对应属性的推送；当此处参数使用 off 时，表示关闭对应属性的推送
    • freq (int:(1,5,10,20,30,50)) ：对应的属性推送的推送频率
    • freq_all (int:(1,5,10,20,30,50)) : 整个底盘所有相关推送信息的推送频率
  • 示例
    • chassis push attitude on; : 打开底盘姿态信息推送
    • chassis push attitude on status on; ：打开底盘姿态、状态信息推送
    • chassis push attitude on afreq 1 status on sfreq 5; ：打开底盘的姿态信息推送，推送频率为每秒一次，同时打开底盘的状态信息推送，推送频率为每秒五次
    • chassis push freq 10; ：底盘所有信息推送的频率为每秒十次
底盘推送信息数据

OUT: chassis push <attr> <data>

  • 描述
    • 当用户使能底盘信息推送后，机器人会以设置的频率向用户推送相应信息
  • 参数
    • attr (chassis_push_attr_enum) : 订阅的属性名称
    • data : 订阅的属性数据
      • 当 attr 为 position 时，data 内容为 <x> <y>
      • 当 attr 为 attitude 时，data 内容为 <pitch> <roll> <yaw>
      • 当 attr 为 status 时，data 内容为 <static> <uphill> <downhill> <on_slope> <pick_up> <slip> <impact_x> <impact_y> <impact_z> <roll_over> <hill_static>
  • 示例
    • chassis push attitude 0.1 1 3; ：当前底盘的 pitch、roll、yaw 姿态信息分别为 0.1、1、3

云台控制

云台运动速度控制

IN: gimbal speed p <speed> y <speed>

  • 描述
    • 控制云台运动速度
  • 参数
    • p (float:[-450, 450]) ：pitch 轴速度，单位 °/s
    • y (float:[-450, 450]) ：yaw 轴速度，单位 °/s
  • 示例
    • gimbal speed p 1 y 1; ：云台的 pitch 轴速度为 1°/s，yaw 轴速度为 1°/s
云台相对位置控制

IN: gimbal move { [p <degree>] [y <degree>] } [vp <speed>] [vy <speed>]

  • 描述
    • 控制云台运动到指定位置，坐标轴原点为当前位置
  • 参数
    • p (float:[-55, 55]) ：pitch 轴角度， 单位 °
    • y (float:[-55, 55]) ：yaw 轴角度，单位 °
    • vp (float:[0, 540]) ：pitch 轴运动速速，单位 °/s
    • vy (float:[0, 540]) ：yaw 轴运动速度，单位 °/s
  • 示例
    • gimbal move p 10; ：以当前位置为坐标基准，控制云台运动到 pitch 轴角度为 10° 的状态
云台绝对位置控制

IN: gimbal moveto { [p <degree>] [y <degree>] } [vp <speed>] [vy <speed>]

  • 描述
    • 控制云台运动到指定位置，坐标轴原点为上电位置
  • 参数
    • p (int:[-25, 30]) ：pitch 轴角度(°)
    • y (int:[-250, 250]) ：yaw 轴角度(°)
    • vp (int:[0, 540]) ：pitch 轴运动速度(°)
    • vy (int:[0, 540]) ：yaw 轴运动速度(°)
  • 示例
    • gimbal moveto p 10 y -20 vp 0.1; ：以机器人上电位置为坐标基准，控制云台运动到 pitch 轴角度为 10°，yaw 轴角度为 -20° 的状态，运动时指定 pitch 轴的运动速度为 0.1°/s
云台休眠控制

IN: gimbal suspend

  • 描述
    • 控制云台进入休眠状态
  • 示例
    • gimbal suspend; ：使云台进入休眠状态
云台恢复控制

IN: gimbal resume

  • 描述
    • 控制云台从休眠状态中恢复
  • 参数
    • None
  • 示例
    • gimbal resume; ：使云台退出休眠状态

警告

休眠状态 当云台进入休眠状态时，云台两轴电机将会释放控制力，云台整体不响应任何控制指令。

要解除云台休眠状态，请参见 云台恢复控制

云台回中控制

IN: gimbal recenter

  • 描述
    • 云台回中
  • 示例
    • gimbal recenter; ：控制云台回中
云台姿态获取

IN: gimbal attitude ?

  • 描述
    • 获取云台姿态信息
  • 返回值
    • <pitch> <yaw> ：pitch 轴角度(°)，yaw 轴角度(°)
  • 示例
    • IN：gimbal attitude ?; ：查询云台的角度信息
    • OUT: -10 20; ：云台当前 pitch 轴角度 -10°，yaw 轴角度 20°
云台信息推送控制

IN: gimbal push <attr> <switch> [afreq <freq_all>]

  • 描述
  • 参数
    • attr (gimbal_push_attr_enum) : 订阅的属性名称
    • switch (switch_enum) ：当此处参数使用 on 时，表示打开对应属性的推送；当此处参数使用 off 时，表示关闭对应属性的推送
    • freq_all : 云台所有相关推送信息的推送频率
  • 示例
    • gimbal push attitude on; ：打开云台的信息推送
云台推送信息数据

OUT: gimabal push <attr> <data>

  • 描述
    • 当用户使能云台信息推送后，机器人会以设置的频率向用户推送相应信息
  • 参数
    • attr (gimbal_push_attr_enum) : 订阅的属性名称
    • data: 订阅的属性数据
      • 当 attr 为 attitude 时，data 内容为 <pitch> <yaw>
  • 示例
    • gimbal push attitude 20 10; ：当前云台的 pitch 角度为 20°，yaw 角度为 10°

发射器控制

发射器单次发射量控制

IN：blaster bead <num>

  • 描述
    • 设置发射器单次发射量
  • 参数
    • num (int:[1,5]) ：发射量
  • 示例
    • blaster bead 2; ：控制发射器单次发射两发
发射器发射控制

IN: blaster fire

  • 描述
    • 控制水弹枪发射一次
  • 示例
    • blaster fire; ：控制水弹枪发射一次
发射器单次发射量获取

IN: blaster bead ?

  • 描述
    • 获取水弹枪单次发射的水弹数
  • 返回值
    • <num> ：水弹枪单次发射的水弹数
  • 示例
    • IN: blaster bead ?; ：查询水弹枪单次发射的水弹数
    • OUT: 3; ：当前水弹枪单次发射水弹数量为 3

装甲板控制

装甲板灵敏度控制

IN: armor sensitivity <value>

  • 描述
    • 设置装甲板打击检测灵敏度
  • 参数
    • value (int:[1,10]) ：装甲板灵敏度，数值越大，越容易检测到打击。默认灵敏度值为 5
  • 示例
    • armor sensitivity 1; ：设置装甲板打击检测灵敏度为 1
装甲板灵敏度获取

IN: armor sensitivity ?

  • 描述
    • 获取装甲板打击检测灵敏度
  • 参数
    • <value> ：装甲板灵敏度
  • 示例
    • IN: armor sensitivity ?; ：查询装甲板打击检测灵敏度
    • OUT: 5; ：查询装甲板打击检测灵敏度
装甲板事件上报控制

IN: armor event <attr> <switch>

装甲板事件上报数据

OUT: armor event hit <index> <type>

  • 描述
    • 当发生装甲板敲击事件时，可以从事件推送端口接收到此消息
  • 参数
    • index (int:[1, 6]) ：当前发生敲击事件的装甲板 ID
      • 1 底盘后
      • 2 底盘前
      • 3 底盘左
      • 4 底盘右
      • 5 云台左
      • 6 云台右
    • type (int:[0, 2]) ：当前敲击事件的种类
      • 0 水弹攻击
      • 1 撞击
      • 2 手敲击
  • 示例
    • armor event hit 1 0; ：1 号装甲板检测到水弹枪攻击

声音识别控制

声音识别事件上报控制

IN: sound event <attr> <switch>

  • 描述
  • 参数
  • 示例
    • sound event applause on; ：打开声音（掌声）识别
声音识别事件上报数据

OUT: sound event <attr> <data>

  • 描述
  • 参数
    • attr (sound_event_attr_enum): 事件属性名称
    • data ：事件属性数据
      • 当 attr 为 applause 时， data 为 <count>，表示短时间内击掌的次数
  • 示例
    • sound event applause 2; ：识别到短时间内有 2 次拍掌

PWM 控制

PWM 输出占空比控制

IN: pwm value <port_mask> <value>

  • 描述
    • PWM 输出占空比设置
  • 参数
    • port_mask (hex:0-0xffff) ：PWM 拓展口掩码组合, 编号为 X 的输出口对应掩码为 1 << (X-1)
    • value (float:0-100) ：PWM 输出占空比，默认输出为 12.5
  • 示例
    • pwm value 1 50; : 控制 1 号 PWM 口的占空比为 50%
PWM 输出频率控制

IN: pwm freq <port_mask> <value>

  • 描述
    • PWM 输出频率设置
  • 参数
    • port_mask (hex:0-0xffff) ：PWM 拓展口掩码组合, 编号为 X 的输出口对应掩码为 1 << (X-1)
    • value (int:XXX) ：PWM 输出频率值
  • 示例
    • pwm freq 1 1000; : 控制 1 号 PWM 口的频率为 1000 Hz

LED 控制

LED 灯效控制

IN：led control comp <comp_str> r <r_value> g <g_value> b <value> effect <effect_str>

  • 描述
    • 机器人 LED 灯效控制接口，可设置多种效果
    • 跑马灯效果仅可作用于云台两侧 LED
  • 参数
    • comp_str (led_comp_enum) ：LED 编号
    • r_value (int:[0, 255]) ：RGB 红色分量值
    • g_value (int:[0, 255]) ：RGB 绿色分量值
    • b_value (int:[0, 255]) ：RGB 蓝色分量值
    • effect_str (led_effect_enum) ：LED 灯效类型
  • 示例
    • led control comp all r 255 g 0 b 0 effect solid; : 机器人所有 LED 常亮为红色

传感器转接板控制

传感器转接板 ADC 值获取

IN: sensor_adapter adc id <adapter_id> port <port_num> ?

  • 描述
    • 获取传感器转接板的 ADC 数值
  • 参数
    • adapter_id (int:[1, 6]) ：转接板的 ID 号
    • port_num (int:[1, 2]) ：port 的编号
  • 返回值
    • adc_value ：测量得到相应转接板上指定端口的电压值，电压取值范围[0V, 3,3V]
  • 示例
    • IN: sensor_adapter adc id 1 port 1 ?; : 查询 1 号转接板上 1 号端口的 ADC 数值
    • OUT: 1.1; ：当前查询端口 ADC 值为 1.1
传感器转接板 IO 值获取

IN: sensor_adapter io_level id <adapter_id> port <port_num> ?

  • 描述
    • 获取传感器转接板 IO 口的逻辑电平
  • 参数
    • adapter_id (int:[1, 6]) ：转接板的 ID 号
    • port_num (int:[1, 2]) ：port 的编号
  • 返回值
    • io_level_value ：测量得到相应转接板上指定端口的逻辑电平值，0 或 1
  • 示例
    • IN: sensor_adapter io_level id 1 port 1 ?; ：查询 1 号转接板上 1 号端口的 IO 逻辑电平
    • OUT: 1; ：当前查询端口的 IO 值为 1
传感器转接板 IO 引脚电平跳变时间值获取

IN: sensor_adapter pulse_period id <adapter_id> port <port_num>

  • 描述
    • 获取传感器转接板 IO 口电平跳变持续时间
  • 参数
    • adapter_id (int:[1, 6])：转接板的 ID 号
    • port_num (int:[1, 2])：port 的编号
  • 返回值
    • pulse_period_value: 测量得到相应转接板上指定端口的电平跳变持续时间值，单位 ms
  • 示例
    • sensor_adapter pulse_period id 1 port 1; ：查询 1 号转接板上 1 号端口的电平跳变持续时间
传感器转接板事件上报控制

IN: sensor_adapter event io_level <switch>

  • 描述
    • 打开/关闭传感器转接板电平跳变事件推送，打开后当 IO 上电平跳变时推送消息，见下一章中[传感器转接板电平跳变事件推送](#传感器转接板电平跳变推送)的介绍
  • 参数
    • switch (switch_enum)：电平跳变事件上报的控制开关
  • 示例
    • sensor_adapter event io_level on; ：打开传感器转接板的电平跳变事件推送、
传感器转接板事件上报数据

OUT: sensor_adapter event io_level (<id>, <port_num>, <io_level>)

  • 描述
    • 当传感器转接板发生电平跳变时推送，可以从事件推送端口接收到此消息
    • 需要打开传感器转接板电平跳变推送，参见 传感器转接板事件上报数据
  • 参数
    • id：传感器转接板的 ID
    • port_num：IO 的 ID
    • io_level：当前的逻辑电平值
  • 示例
    • sensor_adapter event io_level (1, 1, 0); ：当前 1 号转接板的 1 号 IO 的逻辑电平跳变为 0

红外深度传感器控制

红外深度传感器开关控制

IN: ir_distance_sensor measure <switch>

  • 描述
    • 打开/关闭所有红外传感器开关
  • 参数
  • 示例
    • ir_distance_sensor measure on; ：打开所有红外深度传感器
红外深度传感器距离获取

IN: ir_distance_sensor distance <id> ?

  • 描述
    • 获取指定 ID 的红外深度传感器距离
  • 参数
    • id (int:[1, 4])：红外传感器的 ID
  • 返回值
    • distance_value：指定 ID 的红外传感器测得的距离值，单位 mm
  • 示例
    • IN: ir_distance_sensor distance 1 ?; ：查询 1 号红外深度传感器测得的距离值
    • OUT: 1000; ：当前查询红外深度传感器距离值为 1000 mm

舵机控制

舵机角度控制

IN: servo angle id <servo_id> angle <angle_value>

  • 描述
    • 设置舵机角度
  • 参数
    • servo_id (int:[1, 3])：舵机的 ID
    • angle_value (float:[-180, 180])：指定的角度，单位 °
  • 示例
    • servo angle id 1 angle 20; ：控制 1 号舵机的角度为 20°
舵机速度控制

IN: servo speed id <servo_id> speed <speed_value>

  • 描述
    • 设置指定舵机的速度
  • 参数
    • servo_id (int:[1, 3])：舵机的 ID
    • speed_value (float:[-1800, 1800])：设置的速度值，单位 °/s
  • 示例
    • servo speed id 1 speed 20; ：设置 1 号舵机的速度为 10°/s
舵机停止控制

IN: servo stop

  • 描述
    • 停止舵机运动
  • 示例
    • servo stop; ：控制舵机停止运动
舵机角度查询

IN: servo angle id <servo_id> ?

  • 描述
    • 获取指定舵机的角度
  • 参数
    • servo_id (int:[1, 3])：舵机的 ID
  • 返回值
    • angle_value : 指定舵机的角度值
  • 示例
    • IN: servo angle id 1 ?; ：获取 1 号舵机的角度值
    • OUT: 30; ：当前查询舵机角度值为 30°

机械臂控制

机械臂相对位置运动控制

IN: robotic_arm move x <x_dist> y <y_dist>

  • 描述
    • 控制机械臂运动一段距离，当前位置为坐标原点
  • 参数
    • x_dist (float:[]) ：x 轴运动距离，单位 cm
    • y_dist (float:[]) ：y 轴运动距离，单位 cm
  • 示例
    • robotic_arm move x 5 y 5; ：控制机械臂在 x 轴运动 5 cm，在 y 轴运动 5 cm
机械臂绝对位置运动控制

IN: robotic_arm moveto x <x_pos> y <y_pos>

  • 描述
    • 控制机械臂运动到某位置，机器人上电位置为坐标原点
  • 参数
    • x_pos (float:[])：x 轴运动到的坐标，单位 cm
    • y_pos (float:[])：y 轴运动到的坐标，单位 cm
  • 示例
    • robotic_arm moveto x 5 y 5; ：控制机械臂 x 轴运动到 5 cm 的坐标位置，y 轴运动到 5 cm 的坐标位置
机械臂回中控制

IN: robotic_arm recenter

  • 描述
    • 控制机械臂回中
  • 参数
    • None
  • 示例
    • robotic_arm recenter; ：控制机械臂回中
机械臂停止运动控制

IN: robotic_arm stop

  • 描述
    • 停止机械臂运动
  • 参数
    • None
  • 示例
    • robotic_arm stop; ：停止机械臂运动
机械臂绝对位置查询

IN: robotic_arm position ?

  • 描述
    • 获取机械臂的位置
  • 参数
    • None
  • 返回值
    • <x_pos> <y_pos>: 机械臂的位置坐标
      • x_pos：x 轴的坐标，单位 cm
      • y_pos：y 轴的坐标，单位 cm
  • 示例
    • IN: robotic_arm position ?; ：查询机械臂的位置
    • OUT：50 60; ：当前查询机械臂的位置距离标定点 x 轴距离为 50 cm, y 轴距离为 60 cm

机械爪控制

机械爪张开运动控制

IN: robotic_gripper open [leve <level_num>]

  • 描述
    • 张开机械爪
  • 参数
    • level_num (int:[1,4])：机械爪张开的力度等级，取值范围[1,4]
  • 示例
    • robotic_gripper open 1; ：控制机械臂以力度 1 打开
机械爪关闭运动控制

IN: robotic_gripper close [leve <level_num>]

  • 描述
    • 闭合机械爪
  • 参数
    • level_num (int:[1,4])：机械爪闭合的力度等级，取值范围[1,4]
  • 示例
    • robotic_gripper close 1; ：控制机械臂以力度 1 关闭

注解

机械爪控制力度

机械爪控制力度 描述了机械爪在运动过程中的运动速度以及在堵转状态下最大夹取力度

力度越大，运动速度越快，夹取力越大；反之。

机械爪开合状态查询

IN: robotic_gripper status ?

  • 描述
    • 获取机械爪开合状态
  • 参数
    • None
  • 返回值
    • status : 机械爪当前的开合状态
      • 0 机械爪完全闭合
      • 1 机械爪既没有完全闭合，也没有完全张开
      • 2 机械爪完全张开
  • 示例
    • IN: robotic_gripper status ?; ：获取机械爪的开合状态
    • OUT: 2; ：当前查询的机械爪状态为张开

智能识别功能控制

智能识别功能属性控制

IN: AI attribute { [line_color <line_color>] [marker_color <marker_color>] [marker_dist <dist>] }

  • 描述
    • 智能识别功能属性控制
  • 参数
    • line_color (line_color_enum): 线识别颜色
    • marker_color (marker_color_enum): 视觉标签颜色
    • marker_dist (float:[0.5, 3]): 视觉标签最小有效距离，单位m
  • 示例
    • IN: AI attribute line_color red; ：设置线识别的颜色为红色
智能识别功能推送控制

IN: AI push <attr> <switch>

  • 描述
    • 智能识别功能推送控制
    • 不同智能识别功能之间存在互斥关系，互斥的功能无法同时开启，若单次同时打开的功能集合中存在互斥关系的功能，则本次功能开启全部失败。关于互斥关系请参见：智能识别功能互斥关系
    • 暂不支持频率设置
    • 数据提送格式参见 智能识别功能推送数据
  • 参数
    • attr (AI_push_attr_enum): 智能识别功能枚举，部分参数之前不可同时打开
    • switch (switch_enum)：当此处参数使用 on 时，表示打开对应属性的推送；当此处参数使用 off 时，表示关闭对应属性的推送
  • 示例
    • IN: AI push marker on line on; ：打开线和视觉标签识别数据推送

注解

智能识别功能互斥关系

由于机器人计算资源有限，智能识别功能中存在互斥关系，互斥的智能功能无法同时开启。 我们将智能识别功能分为AB两组：

A people pose marker robot
B line

以上两组，任意一组内同时仅能开启一个功能，两组间可任意组合功能

智能识别功能推送数据

OUT: AI push <attr> <data>

  • 描述
    • 当用户使能智能识别功能推送后，机器人会以归固定的频率向用户推送相应信息
  • 参数
    • attr (AIi_push_attr_enum): 订阅的功能名称
    • data ：订阅的属性数据
      • 当 attr 为 person 时，内容为 <n> <x1> <y1> <w1> <h1> <x2> <y2> … <wn> <hn>
      • 当 attr 为 gesture 时 内容为 <n> <info1> <x1> <y1> <w1> <h1> <x2> <y2> … <wn> <hn>, info 含义请参见 AI_pose_id_enum
      • 当 attr 为 marker 时，内容为 <n> <info1> <x1> <y1> <w1> <h1> <x2> <y2> … <wn> <hn>, info 含义请参见 AI_marker_id_enum
      • 当 attr 为 line 时，内容为 <n> <x1> <y1> <θ1> <c1> <x2> <y2> … <θ10n> <c10n>
      • 当 attr 为 robot 时，内容为 <n> <x1> <y1> <w1> <h1> <x2> <y2> … <wn> <hn>
  • 示例
    • OUT: AI push person 1 0.5 0.5 0.3 0.7; : 当前识别到1个行人，坐标位于(0.5, 0.5)，目标宽度为0.3，高度为0.7

注解

智能功能推送数据

智能识别功能推送数据中，n,x,y,w,h 均为通用数据，解释如下：

n : 识别到的目标数量

x : 识别到的目标中心点位于视野中的x坐标

y : 识别到的目标中心点位于视野中的y坐标

w : 识别到的目标宽度

h : 识别到的目标高度

线识别推送数据中，n, x, y, θ, c 解释如下：

n : 识别到线的数量，每条线分别存在10个点，详细点数据请参下

x : 线上点位于视野中的x坐标

y : 线上点位于视野中的y坐标

θ : 线上点的切线角角度

c : 线上点对应的曲线的曲率，取值范围 [0, 10], 0表示纯直线

以上 x,y,w,h 均为归一化的值，范围为[0, 1]，坐标远点位于视野左上方

相机控制

相机曝光设置

IN: camera exposure <ev_level>

  • 描述
    • 相机曝光值设置
  • 参数
  • 示例
    • camera exposure small; ：设置相机曝光值为小

视频流控制

视频流开启控制

IN: stream on

  • 描述
    • 打开视频流
    • 打开后，可从视频流端口接收到 H.264 编码的码流数据
  • 示例
    • stream on; ：打开视频流
视频流关闭控制

IN: stream off

  • 描述
    • 关闭视频流
    • 关闭视频流后，H.264 编码的码流数据将会停止输出
  • 示例
    • stream off; ：关闭视频流

音频流控制

音频流开启控制

IN: audio on

  • 描述
    • 打开音频流
    • 关闭音频流后，可以从音频流端口接收到 Opus 编码的音频流数据
  • 示例
    • audio on; ：打开音频流
音频流关闭控制

IN: audio off

  • 描述
    • 关闭音频流
    • 关闭音频流后，Opus 编码的音频流数据将会停止输出
  • 示例
    • audio off; ：关闭音频流

IP 广播

OUT: robot ip <ip_addr>

  • 描述
    • 当未与机器人建立连接时，可以从 IP 广播端口接收到此消息，连接成功后，该消息停止广播
    • 描述当前机器人的 IP 地址，适用于与机器人在同一局域网内，但未知机器人 IP 信息的情况
  • 参数
    • ip_addr : 机器人当前 IP 地址
  • 示例
    • robot ip 192.168.1.102; : 机器人当前的 IP 地址为 192.168.1.102

赛事数据获取

键盘数据数据推送开启

IN: game_msg on

  • 描述
    • 青少年赛事系统，打开键盘鼠标数据推送
  • 参数
    • None
  • 示例
    • game_msg on; ：打开键盘鼠标数据推送
键盘数据数据推送关闭

IN: game_msg off

  • 描述
    • 青少年赛事系统，关闭键盘鼠标数据推送
  • 参数
    • None
  • 示例
    • game_msg off; ：关闭键盘鼠标数据推送
键盘数据数据推送数据

OUT: game msg push <data>

  • 描述
    • 当用户使能赛事数据推送后，机器人会以固定的频率向用户推送相应信息，数据为字符串
  • 参数
    • data ：订阅的属性数据
      • 内容为 [cmd_id, len, mouse_press, mouse_x, mouse_y, seq, key_num, key_1, key2, ….]
      • mouse_press: 1为鼠标右键, 2为鼠标左键, 4为鼠标中间
      • mouse_x : 鼠标移动距离, 范围-100 ~ 100
      • mouse_y : 鼠标移动距离, 范围-100 ~ 100
      • seq: 序列号 0~255
      • key_num: 识别到的按键数, 最多识别三个按键
      • key1: 键值
  • 示例
    • OUT: game msg push [0, 6, 1, 0, 0, 255, 1, 199]; : cmd_id为0, 数据长度为6, 识别到鼠标右击, 按键w按下, 包序号255

数据说明

switch_enum
  • on : 打开
  • off : 关闭
mode_enum
  • chassis_lead : 云台跟随底盘模式
  • gimbal_lead : 底盘跟随云台模式
  • free : 自由模式
chassis_push_attr_enum
  • position : 底盘位置
  • attitude : 底盘姿态
  • status : 底盘状态
gimbal_push_attr_enum
  • attitude 云台姿态
armor_event_attr_enum
  • hit : 装甲被敲击
sound_event_attr_enum
  • applause : 掌声
led_comp_enum
  • all : 所有 LED 灯
  • top_all : 云台所有 LED 灯
  • top_right : 云台右侧 LED 灯
  • top_left : 云台左侧 LED 灯
  • bottom_all : 底盘所有 LED 灯
  • bottom_front : 底盘前侧 LED 灯
  • bottom_back : 所有后侧 LED 灯
  • bottom_left : 所有左侧 LED 灯
  • bottom_right : 所有右侧 LED 灯
led_effect_enum
  • solid : 常亮效果
  • off : 熄灭效果
  • pulse : 呼吸效果
  • blink : 闪烁效果
  • scrolling : 跑马灯
line_color_enum
  • red : 红色
  • blue : 蓝色
  • green : 绿色
marker_color_enum
  • red : 红色
  • blue : 蓝色
ai_push_attr_enum
  • person : 行人
  • gesture : 姿势
  • line ：线
  • marker : 视觉标签
  • robot : 机器人
ai_pose_id_enum
  • 4 : 正V手势
  • 5 : 倒V手势
  • 6 : 拍照手势
ai_marker_id_enum
  • 1 : 停止
  • 4 : 左转
  • 5 : 右转
  • 6 : 前进
  • 8 : 红心
  • 10 - 19 : 数字 0 - 9
  • 20 - 45 : 字母 A - Z
camera_ev_enum
  • default : 默认值
  • small : 小
  • medium : 中
  • large : 大

编队控制

介绍

编队控制功能是通过明文 SDK 对连接在同一个局域网内的多个机器人进行动作编排，实现整体控制的功能。用户可以使用该功能进行更复杂的动作控制，实现编队舞蹈，很具有观赏性。

原理为多台机器人通过 WIFI 路由器模式在同一个局域网内建立连接后，用户在 PC 上通过 Python 脚本与多台机器人通信，同时向多台机器人下发明文 SDK 指令，从而实现编队控制的功能。在本章节中主要介绍一个用 Python 脚本通过明文 SDK 实现编队控制的简单示例。

示例环境

  • 硬件设备：路由器、两台 EP 机器人、 PC
  • Python版本：Python 3.6

建立多机连接

将 EP 机器人设置为 WIFI 路由器模式，使用 APP 将参与编队控制的 EP 依次接入同一个路由器中，连接成功后打开 APP 设置中的连接页面，记录 EP 的 IP 地址。具体步骤请参考 WIFI 路由器模式。

运行示例程序

  1. 将IP地址依次填入参考代码中的 IP_LIST 列表中，并将脚本代码保存为 ep.py。

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
    #!/usr/bin/env python3
# coding=utf-8

import sys
import time
import threading
import socket

IP_LIST = ['192.168.1.103', '192.168.1.117']
EP_DICT = {}

class EP:
        def __init__(self, ip):
                self._IP = ip
                self.__socket_ctrl = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
                self.__socket_isRelease = True
                self.__socket_isConnect = False
                self.__thread_ctrl_recv = threading.Thread(target=self.__ctrl_recv)
                self.__seq = 0
                self.__ack_list = []
                self.__ack_buf = 'ok'

        def __ctrl_recv(self):
                while self.__socket_isConnect and not self.__socket_isRelease:
                        try:
                                buf = self.__socket_ctrl.recv(1024).decode('utf-8')
                                print('%s:%s' % (self._IP, buf))
                                buf_list = buf.split(' ')
                                if 'seq' in buf_list:
                                        self.__ack_list.append(int(buf_list[buf_list.index('seq') + 1]))
                                self.__ack_buf = buf
                        except socket.error as msg:
                                print('ctrl %s: %s' % (self._IP, msg))

        def start(self):
                try:
                        self.__socket_ctrl.connect((self._IP, 40923))
                        self.__socket_isConnect = True
                        self.__socket_isRelease = False
                        self.__thread_ctrl_recv.start()
                        self.command('command')
                        self.command('robot mode free')
                except socket.error as msg:
                        print('%s: %s' % (self._IP, msg))

        def exit(self):
                if self.__socket_isConnect and not self.__socket_isRelease:
                        self.command('quit')
                self.__socket_isRelease = True
                try:
                        self.__socket_ctrl.shutdown(socket.SHUT_RDWR)
                        self.__socket_ctrl.close()
                        self.__thread_ctrl_recv.join()
                except socket.error as msg:
                        print('%s: %s' % (self._IP, msg))

        def command(self, cmd):
                self.__seq += 1
                cmd = cmd + ' seq %d;' % self.__seq
                print('%s:%s' % (self._IP, cmd))
                self.__socket_ctrl.send(cmd.encode('utf-8'))
                timeout = 2
                while self.__seq not in self.__ack_list and timeout > 0:
                        time.sleep(0.01)
                        timeout -= 0.01
                if self.__seq in self.__ack_list:
                        self.__ack_list.remove(self.__seq)
                return self.__ack_buf

if __name__ == "__main__":
        #实例化机器人
        for ip in IP_LIST:
                print('%s connecting...' % ip)
                EP_DICT[ip] = EP(ip)
                EP_DICT[ip].start()

        for ip in IP_LIST:
                EP_DICT[ip].command('gimbal moveto p 0 y 0 vp 90 vy 90 wait_for_complete false')
        time.sleep(3)

        while True:
                for ip in IP_LIST:
                        EP_DICT[ip].command('gimbal moveto p 0 y 45 vp 90 vy 90 wait_for_complete false')
                time.sleep(3)
                for ip in IP_LIST:
                        EP_DICT[ip].command('gimbal moveto p 0 y -45 vp 90 vy 90 wait_for_complete false')
                time.sleep(3)
        for ip in IP_LIST:
                EP_DICT[ip].exit()

  2. 运行脚本

  • Windows系统：完成Python环境后可直接点击 ep.py 启动脚本。
  • Linux系统：在命令终端输入 python ep.py 启动脚本。
  1. 运行效果

编队控制的多台机器人云台步调一致的在 YAW 轴方向往复运动。

_images/form_control.gif
  1. 运行结果

命令行端口输出多台机器人与主机之间的明文通讯数据。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
192.168.1.103 connecting...
192.168.1.103:command seq 1
192.168.1.103:ok seq 1
192.168.1.103:robot mode free seq 2
192.168.1.103:ok seq 2
192.168.1.117 connecting...
192.168.1.117:command seq 1
192.168.1.117:ok seq 1
192.168.1.117:robot mode free seq 2
192.168.1.117:ok seq 2
192.168.1.103:gimbal moveto p 0 y 0 vp 90 vy 90 wait_for_complete false seq 3
192.168.1.103:ok seq 3
192.168.1.117:gimbal moveto p 0 y 0 vp 90 vy 90 wait_for_complete false seq 3
192.168.1.117:ok seq 3

Python 编程介绍

介绍

本章介绍的 Python 编程指的是使用设备连接 EP 机器人后，进入 App 实验室进行 Python 编程。

在 Python 编程界面，允许玩家基于 Python 3.6.6 版本的基础语法完成 Python 编程，并可以参考官方提供的《RoboMaster EP 编程模块手册》和本网站 Python API，调用 RoboMaster EP 提供的编程接口去编写自己的 Python 程序，同时生成的 Python 程序可被装配成自主程序或者自定义技能。

RoboMaster EP 的多机通信接口让多台机器人通过 Python 编程相互通信，实现多机实时互动。 EP 支持编程自定义 UI 系统，通过 Python 编写虚拟控件，自由设计交互界面，拓展无限应用可能。

界面

为了方便代码编辑，一般会使用 PC 端的 App 进行 Python 编程。

_images/python_env.png

PC 端 Python 编程界面

Python 功能介绍

多机通信系统

多机通信系统是一种基于局域网实现多台机器人之间相互通信的功能，让用户可以进行多台机器人协同工作，实现多台机器人编队表演等功能。

使用时需要将所有目标机器人加入到同一个局域网内，并使用官方提供的Python API进行编程，来沟通机器人之间的通信机制，进一步实现具体的功能。

Python API 请参考 自定义UI系统

用户自定义 UI 系统

自定义 UI 系统是用户通过自己编写的程序生成自定义的 UI 控件来拓展程序的输入和输出的一种方式。

我们编程时很重要的一部分工作是处理输入和输出，对我们的机器人来说，程序输出可以是底盘、云台、发射器等模块的动作，也可以是灯光、音效等的表现，输入的途径则有初始的变量，机器人的视觉识别、掌声识别、装甲板打击检测、手机陀螺仪等。现在我们可以通过自定义 UI 系统与生成的 UI 控件进行交互达到输入的目的，也可以将程序的处理结果通过 UI 控件来进行信息的输出。

我们可以在 RoboMaster App 中编写 Python 程序，调用自定义 UI 系统的相关接口，来生成 UI 控件，绑定控件的事件回调。在实验室中完成程序的编写和调试后，可以将程序装配成自定义技能，在单机驾驶或者多人竞技中释放出来。

Python API 请参考 自定义UI系统

Python API

机器人

robot_ctrl.get_battery_percentage()
描述:

机器人电池电量获取
参数:

void – 无
返回:

电池电量百分比 (0, 100]
示例:

>> robot_ctrl.get_battery_percentage()

<< 10
示例说明:

当前机器人电量为10%

多机通信

multi_comm_ctrl.set_group(send_group, recv_group_list)
描述:

设置机器的组号为 send_group ，机器可以接收来自 recv_group_list 中注册的组号的消息。如果不使用 recv_group_list 参数，默认接收组号 0 的消息
参数:
  • send_group (int) – 当前机器的发送组号，默认组号为 0
  • recv_group_list (list/tuple) – 当前接收消息的组别列表，类型可以为列表或元组
返回:

无
示例:

multi_comm_ctrl.set_group(1, (1,2,3))
示例说明:

设置当前发送组号为 1， 接收组号 1,2,3 的消息，若接收组别包含发送组别，则会接收到自己发送的消息
multi_comm_ctrl.send_msg(msg, group)
描述:

通过多机通信发送消息，可以单独设置该消息的发送组号
参数:
  • msg (int) – 需要发送的消息
  • group (int) – 可选参数，指定当前消息发送组号，不指定则默认使用之前设置的组号
返回:

无
示例:

multi_comm_ctrl.send_msg('RoboMaster EP', 3)
示例说明:

向组号 3 发送消息 'RoboMaster EP'
multi_comm_ctrl.recv_msg(timeout)
描述:接收消息（当没有注册`recv_callback`时生效），可设置超时时间
参数:timeout (int) – 等待时间，接收函数等待的时间，精确度为 1 秒，默认为 72 秒
返回:<msg_group>, <msg> 消息发送方的组号和消息内容
示例:group, recv_msg = multi_comm_ctrl.recv_msg(30)
示例说明:接收消息，等待时间为 30 秒，group 为信息发送方的组号，msg 为收到的消息内容
multi_comm_ctrl.register_recv_callback(callback)
描述:注册接收消息的回调函数，当接收到信息后，自动执行回调函数
参数:callback (function) – 需要注册的回调函数, 回调函数原型为 def callback(msg)，其中 msg 参数类型为元组 (msg_group, msg)
返回:无
示例: 
1
2
3
4
5
6
#定义一个函数，并将其注册为接收消息的回调函数

def recv_callback(msg):
    pass

multi_comm_ctrl.register_recv_callback(recv_callback)

提示

模块说明请参考 多机通信

自定义 UI 系统

Common

本部分方法适用于除 Stage 外所有自定义 UI 控件，因此单独拿出来介绍。

common_object.set_active(status)
描述:控制当前控件是否显示
参数:status (bool) – 控件的活动状态，True 表示显示当前控件，False 表示隐藏当前控件
返回:无
示例:my_Slider.set_active(Flase)
示例说明:设置 my_Slider 控件为隐藏状态
common_object.get_active()
描述:获取当前控件的显示状态
参数:void – 无
返回:bool, 表示控件的显示状态
示例:status = my_Slider.get_active()
示例说明:获取 my_Slider 控件的显示状态，赋值给 status 变量
common_object.set_name(name)
描述:设置当前控件的名字
参数:name (string) – 控件的名字
返回:无
示例:my_Dropdown.set_name('my_dropdown')
示例说明:设置 my_Dropdown 控件的名字为『my_dropdown』
common_object.get_name()
描述:获取当前控件的名字
参数:void – 无
返回:string，表示控件的名字
示例:name = my_Dropdown.get_name()
示例说明:获取 my_Dropdown 控件的名字，赋值给 name 变量
common_object.set_position(x, y)
描述:

设置控件的位置坐标，原点在屏幕的中心位置
参数:
  • x (int) – 控件的横坐标，取值为屏幕上实际像素的位置，0 点在屏幕水平中心位置，向右为正方向
  • y (int) – 控件的纵坐标，取值为屏幕上实际像素的位置，0 点在屏幕垂直中心位置，向上为正方向
返回:

无
示例:

my_Text.set_position(-200, 500)
示例说明:

设置 my_Text 控件的坐标为 (-200，500)
common_object.get_position()
描述:获取控件的位置坐标
参数:void – 无
返回:[x,y]，表示控件的位置
示例:pos = my_Text.get_position()
示例说明:获取 my_Text 控件的位置，赋值给变量 pos，pos 为一个列表
common_object.set_size(w, h)
描述:

设置控件的大小
参数:
  • w (int) – 控件的宽度
  • h (int) – 控件的高度
返回:

无
示例:

my_Button.set_size(300, 200)
示例说明:

设置 my_Button 控件的宽度为 300，高度为 200
common_object.get_size()
描述:获取控件的大小
参数:void – 无
返回:[w,h], 表示控件的大小
示例:size = my_Button.get_size()
示例说明:获取 my_Button 控件的大小，赋值给变量 size，size 为一个列表
common_object.set_rotation(degree)
描述:设置控件的旋转角度
参数:degree (int) – 控件的旋转角度，范围为 [0, 360]，正值为顺时针旋转，负值为逆时针旋转
返回:无
示例:my_Button.set_rotation(90)
示例说明:设置 my_Button 控件顺时针旋转 90 度
common_object.get_rotation()
描述:获取控件的旋转角度
参数:void – 无
返回:int, 表示控件的旋转角度，范围为 [0, 360]，正值为顺时针旋转，负值为逆时针旋转
示例:degree = my_Button.get_rotation()
示例说明:获取 my_Button 控件的旋转角度，赋值给变量 degree
common_object.set_privot(x, y)
描述:

设置控件的锚点坐标，输入参数是归一化参数，原点位于控件的左下角，控件的锚点默认为控件中心即 (0.5,0.5)，控件的位置和旋转均以锚点作为控制点
参数:
  • x (int) – 锚点的 x 坐标，范围为 [0, 1]，向右为正方向
  • y (int) – 锚点的 y 坐标，范围为 [0, 1]，向上为正方向
返回:

无
示例:

my_Button.set_privot(0, 1)
示例说明:

设置控件的锚点为控件的左上角
common_object.get_privot()
描述:获取控件的锚点坐标
参数:void – 无
返回:[x,y]，表示控件的锚点坐标
示例:privot = my_Button.get_privot()
示例说明:获取控件的锚点坐标，赋值给变量 privot，privot 为一个列表
common_object.set_order(order)
描述:设置控件的显示优先级，当多个控件重叠时，优先级高的控件在上层，数字越大优先级越高
参数:order (int) – 控件的指定优先级，控件重叠时优先级高的优先显示
返回:无
示例:my_Button.set_order(8)
示例说明:将控件的显示优先级设置为 8，当控件重叠时，低于此优先级的控件将被覆盖
common_object.get_order()
描述:获取控件的显示优先级
参数:void – 无
返回:int，表示控件的显示优先级
示例:order = my_Button.get_order()
示例说明:获取 my_Button 控件的显示优先级，赋值给变量 order
common_object.callback_register(event, callback)
描述:

注册控件事件触发的回调函数，当控件检测到相应的事件后，执行注册的回调函数
参数:
  • event (string) –

    指定回调函数的触发事件

    各控件可注册的事件如下：

    • Button 控件：
      • on_click 一次按下松开按钮的过程, 在松开按钮的时候触发该事件
      • on_press_down 按下按钮的时候触发该事件
      • on_press_up 松开按钮的时候触发该事件
    • Toggle 控件：
      • on_value_changed 值发生改变的时候触发该事件，回调函数中的 args 参数为 bool，表示该 Toggle 控件值发生改变后的值
    • Dropdown 控件：
      • on_value_changed 值发生改变的时候触发该事件，回调函数中的 args 参数为 int，表示该 Dropdown 控件值发生改变后的选中索引
    • Text 控件：
      • 无触发事件
    • InputField 控件：
      • on_value_changed 值发生改变的时候触发该事件，回调函数中的 args 参数为 string，表示该 InputField 控件值发生改变后的值
  • callback (function) – 需要注册的回调函数，回调函数的统一签名为： def callback(widget,*args,**kw): ，其中 widget 为触发事件的控件引用，args，kw为参数.
返回:

无
示例 1: 
1
2
3
4
5
6
# 当 my_Button 控件被点击后，打印信息到控制台上，机器人会开枪射击一次

def button_callback(widget,*args,**kw):
    print('the button is clicked and the button's name is '+ widget.get_name())
    gun_ctrl.fire_once()
my_Button.callback_register('on_click',button_callback)
示例 2: 
1
2
3
4
5
6
7
# 当 my_Toggle 控件被点击后，值会发生改变，打印信息到控制台上，机器人会播放声音

def toggle_callback(widget,*args,**kw):
    print("the toggle's value is changed and the toggle's name is "+ widget.get_name())
    print("the toggle's value now is "+ str(args))
    media_ctrl.play_sound(rm_define.media_sound_recognize_success)
my_Toggle.callback_register('on_value_changed',toggle_callback)
示例 3: 
1
2
3
4
5
6
7
# 当点击 my_Dropdown 控件改变其选中的值，值会发生改变，打印信息到控制台上，机器人会播放声音

def dropdown_callback(widget,*args,**kw):
    print("the dropdown's value is changed and the dropdown's name is "+ widget.get_name())
    print("the dropdown's value now is "+ str(args))
    media_ctrl.play_sound(rm_define.media_sound_solmization_1A)
my_Dropdown.callback_register('on_value_changed',dropdown_callback)
示例 4: 
1
2
3
4
5
6
# 当点击 my_InputField 控件改变其选中的值，值会发生改变，打印信息到控制台上

def input_field_callback(widget,*args,**kw):
    print("the input_field's value is changed and the input_field's name is "+ widget.get_name())
    print("the input_field's value now is "+ str(args))
my_InputField.callback_register('on_value_changed',input_field_callback)

Stage

系统初始化时会自动创建一个 Stage 类的对象 stage ，直接使用即可，不需要用户自己创建。

stage.add_widget(widget_obj)
描述:将参数中的控件添加到 UI 界面中
参数:widget_obj (object) – 需要添加进 UI 界面的控件对象
返回:无
示例: 
1
2
3
4
#创建一个 Button 对象，并将其添加进 UI 界面

my_button = Button()
stage.add_widget(my_button)
stage.remove_widget(widget_obj)
描述:从 UI 界面移除参数传入的控件
参数:widget_obj (object) – 需要从 UI 界面移除的控件
返回:无
示例:stage.remove_widget(my_button)
示例说明:从 UI 界面中移除控件 my_button

Button

Button 控件用于响应来自用户的点击来启动或确认操作。

button_object.set_text(content, [color_r, color_g, color_b, color_a, ]align, size)
描述:

设置按钮对象的文字属性
参数:
  • content (string) – 按钮上显示的字符串内容
  • [color_r, color_g, color_b, color_a] (list) – 可选参数，需要显示的字符串的颜色，参数分别为显示颜色 r 值、b 值，g 值，透明度，取值范围都为 [0, 255]
  • align (enum) – 可选参数，枚举类型，需要显示文字的对齐方式，详细见表格 align
  • size (int) – 显示文字的字号大小
返回:

无
示例:

my_Button.set_text(120, 120, 120, 255, text_anchor.upper_left, 12)
示例说明:

设置文字颜色的 rgb 值为（120, 120, 120），透明度为 255，文字对齐方式为顶端左对齐，字号大小为 12 号
button_object.set_text_color(r, g, b, a)
描述:

设置文字的颜色
参数:
  • r (int) – 文字颜色的 r 值，范围为 [0, 255]
  • g (int) – 文字颜色的 g 值，范围为 [0, 255]
  • b (int) – 文字颜色的 b 值，范围为 [0, 255]
  • a (int) – 文字颜色的透明度，范围为 [0, 255]
返回:

无
示例:

my_button.set_text_color(120, 120, 120, 200)
示例说明:

设置文字颜色的 rgb 值为（120, 120, 120），透明度为 200
button_object.set_text_align(align)
描述:设置文字的对齐方式
参数:align (enum) – 可选参数，枚举类型，需要显示文字的对齐方式，详见表格 align
返回:无
示例:my_button.set_text_align(text_anchor.upper_left)
示例说明:设置文字的对齐方式为顶端左对齐
button_object.set_text_size(size)
描述:设置文字的字号大小
参数:size (int) – 文字的字号值
返回:无
示例:my_button.set_text_size(12)
示例说明:设置文字的字号为 12 号
button_object.set_background_color(r, g, b, a)
描述:

设置按钮的背景色
参数:
  • r (int) – 字体颜色的 r 值，范围为 [0, 255]
  • g (int) – 字体颜色的 g 值，范围为 [0, 255]
  • b (int) – 字体颜色的 b 值，范围为 [0, 255]
  • a (int) – 字体颜色的透明度，范围为 [0, 255]
返回:

无
示例:

my_button.set_background_color(200, 200, 200, 230)
示例说明:

设置背景色的 rgb 值为 (200, 200, 200)，透明度为 230

Toggle

Toggle 控件用于在屏幕上绘制一个开关，通过控制开关的开启与闭合来执行一些具体的操作。

toggle_object.set_text(string, [color_r, color_g, color_b, color_a, ]align, size)
描述:

设置控件的显示文字
参数:
  • string (string) – 控件上显示的字符串内容
  • [color_r, color_g, color_b, color_a] (list) – 可选参数，需要显示的字符串的颜色，参数分别为显示颜色 r 值、b 值、g 值、透明度，取值范围都为 [0, 255]
  • align (enum) – 可选参数，枚举类型，需要显示文字的对齐方式，详细见表格 align
  • size (int) – 显示文字的字号大小
返回:

无
示例:

my_Toggle.set_text(120, 120, 120, 200, text_anchor.upper_left, 12)
示例说明:

设置文字的 rgb 值为（120, 120, 120），透明度为 200，字体对齐方式为顶端左对齐，字号大小为 12 号
toggle_object.set_text_color(r, g, b, a)
描述:

设置文字的颜色
参数:
  • r (int) – 文字颜色的 r 值，范围为 [0, 255]
  • g (int) – 文字颜色的 g 值，范围为 [0, 255]
  • b (int) – 文字颜色的 b 值，范围为 [0, 255]
  • a (int) – 文字颜色的透明度，范围为 [0, 255]
返回:

无
示例:

my_Toggle.set_text_color(120, 120, 120, 200)
示例说明:

设置字体的 rgb 值为（120, 120, 120），透明度为 200
toggle_object.set_text_align(align)
描述:设置文字的对齐方式
参数:align (enum) – 可选参数，枚举类型，需要显示文字的对齐方式，详细见表格 align
返回:无
示例:my_Toggle.set_text_align(text_anchor.upper_left)
示例说明:设置字体的对齐方式为顶端左对齐
toggle_object.set_text_size(size)
描述:设置文字的字号大小
参数:size (int) – 文字的字号值
返回:无
示例:my_Toggle.set_text_size(12)
示例说明:设置文字的字号为 12 号
toggle_object.set_background_color(r, g, b, a)
描述:

设置控件的背景色
参数:
  • r (int) – 背景颜色的 r 值，范围为 [0, 255]
  • g (int) – 背景颜色的 g 值，范围为 [0, 255]
  • b (int) – 背景颜色的 b 值，范围为 [0, 255]
  • a (int) – 背景颜色的透明度，[0, 255]
返回:

无
示例:

my_Toggle.set_background_color(200, 200, 200, 230)
示例说明:

设置背景色的 rgb 值为 (200, 200, 200)，透明度为 230
toggle_object.set_checkmark_color(r, g, b, a)
描述:

设置控件选中图标的颜色
参数:
  • r (int) – 图标颜色的 r 值，范围为 [0, 255]
  • g (int) – 图标颜色的 g 值，范围为 [0, 255]
  • b (int) – 图标颜色的 b 值，范围为 [0, 255]
  • a (int) – 图标颜色的透明度，范围为 [0, 255]
返回:

无
示例:

my_Toggle.set_checkmark_color(200, 200, 200, 230)
示例说明:

设置选中图标的 rgb 值为 (200, 200, 200)，透明度为 230
toggle_object.set_is_on(status)
描述:设置控件的状态
参数:status (bool) – 设置控件是否为打开状态，True 表示打开，False 表示关闭
返回:无
示例:my_Toggle.set_is_on(True)
示例说明:设置 Toggle 控件为打开状态

Text

Text 控件用于显示文本

text_object.set_text(string, [color_r, color_g, color_b, color_a, ]align, size)
描述:

设置控件的文字属性
参数:
  • string (string) – 需要显示的字符串内容
  • [color_r, color_g, color_b, color_a] (list) – 可选参数，需要显示的字符串的颜色，参数分别为显示颜色 r 值、b 值、g 值，透明度，取值范围都为 [0, 255]
  • align (enum) – 可选参数，枚举类型，需要显示文字的对齐方式，详细见表格 align
  • size (int) – 显示文字的字号大小
返回:

无
示例:

my_Text.set_text(120, 120, 120, 200, text_anchor.upper_left, 12)
示例说明:

设置文字颜色的 rgb 值为（120, 120, 120），透明度为 200，字体对齐方式为顶端左对齐，字号大小为 12 号
text_object.set_text_color(r, g, b, a)
描述:

设置控件的文字颜色
参数:
  • r (int) – 文字颜色的 r 值，范围为 [0, 255]
  • g (int) – 文字颜色的 g 值，范围为 [0, 255]
  • b (int) – 文字颜色的 b 值，范围为 [0, 255]
  • a (int) – 文字颜色的透明度，范围为 [0, 255]
返回:

无
示例:

my_Text.set_text_color(120, 120, 120, 200)
示例说明:

设置文字的 rgb 值为（120, 120, 120），透明度为 200
text_object.set_text_align(align)
描述:设置文字的对齐方式
参数:align (enum) – 可选参数，枚举类型，需要显示文字的对齐方式，详细见表格 align
返回:无
示例:my_Text.set_text_align(text_anchor.upper_left)
示例说明:设置文字的对齐方式为顶端左对齐
text_object.set_text_size(size)
描述:设置文字的字号大小
参数:size (int) – 文字的字号值
返回:无
示例:my_Text.set_text_size(12)
示例说明:设置文字的字号为 12 号
text_object.set_border_active(active)
描述:是否显示文字边框
参数:active (bool) – 是否显示文字边框，True 表示显示边框，False 表示不显示边框
返回:无
示例:my_Text.set_border_active(True)
示例说明:显示文字边框
text_object.set_background_color(r, g, b, a)
描述:

设置控件的背景色
参数:
  • r (int) – 背景颜色的 r 值，范围为 [0, 255]
  • g (int) – 背景颜色的 g 值，范围为 [0, 255]
  • b (int) – 背景颜色的 b 值，范围为 [0, 255]
  • a (int) – 背景颜色的透明度，范围为 [0, 255]
返回:

无
示例:

my_Text.set_background_color(200, 200, 200, 230)
示例说明:

设置背景色的 rgb 值为 (200, 200, 200)，透明度为 230
text_object.set_background_active(active)
描述:是否显示文字背景
参数:active (bool) – 是否显示背景，True 表示显示背景，False 表示不显示背景
返回:无
示例:my_Text.set_background_active(True)
示例说明:显示文字背景
text_object.append_text(content)
描述:向 Text 控件中增加文本
参数:content (string) – 需要向 Text 中增加的文本
返回:无
示例:my_Text.append_text('RoboMaster EP')
示例说明:向 Text 中增加的文字 RoboMaster EP
align
text_anchor.upper_left 顶端左对齐
text_anchor.upper_center 顶端居中对齐
text_anchor.upper_right 顶端右对齐
text_anchor.middle_left 中间左对齐
text_anchor.middle_center 中间居中对齐
text_anchor.middle_right 中间右对齐
text_anchor.lower_left 底端左对齐
text_anchor.lower_center 底端居中对齐
text_anchor.lower_right 底端右对齐

InputField

InputField 控件用于接收用户输入的文本信息

inputfield_object.set_text(string, [color_r, color_g, color_b, color_a, ]align, size)
描述:

设置输入框对象中的的文字属性
参数:
  • string (string) – 需要显示的字符串内容
  • [color_r, color_g, color_b, color_a] (list) – 可选参数，需要显示的字符串的颜色，参数分别为显示颜色 r 值、b 值，g 值，透明度，取值范围都为[0, 255]
  • align (enum) – 可选参数，枚举类型，需要显示文字的对齐方式，详细见表格 align
  • size (int) – 显示文字的字号大小
返回:

无
示例:

my_InputField.set_text('Hello RoboMaster',120, 120, 120, 200, text_anchor.upper_left, 12)
示例说明:

设置字体的 rgb 值为（120, 120, 120），透明度为 200 ，字体对齐方式为顶端左对齐，字号大小为 12 号
input_field_object.set_text_color(r, g, b, a)
描述:

设置文字的颜色
参数:
  • r (int) – 文字颜色的 r 值，范围为[0, 255]
  • g (int) – 文字颜色的 g 值，范围为[0, 255]
  • b (int) – 文字颜色的 b 值，范围为[0, 255]
  • a (int) – 文字颜色的透明度， 范围为[0, 255]
返回:

无
示例:

my_button.set_text_color(120, 120, 120, 200)
示例说明:

设置字体的 rgb 值为（120, 120, 120），透明度为 200
input_field_object.set_text_align(align)
描述:设置控件中文字的对齐方式
参数:align (enum) – 可选参数，枚举类型，需要显示文字的对齐方式，详细见表格 align
返回:无
示例:my_Input_field.set_text_align(text_anchor.upper_left)
示例说明:设置文字的对齐方式为顶端左对齐
input_field_object.set_text_size(size)
描述:设置控件中文字的字号大小
参数:size (int) – 文字的字号值
返回:无
示例:my_Input_field.set_text_size(12)
示例说明:设置文字的字号为 12 号
input_field_object.set_background_color(r, g, b, a)
描述:

设置控件的背景色
参数:
  • r (int) – 背景颜色的 r 值，范围为[0, 255]
  • g (int) – 背景颜色的 g 值，范围为[0, 255]
  • b (int) – 背景颜色的 b 值，范围为[0, 255]
  • a (int) – 背景颜色的透明度，[0, 255]
返回:

无
示例:

my_Input_field.set_background_color(200, 200, 200, 230)
示例说明:

设置背景色的 rgb 值为(200, 200, 200) ，透明度为 230
input_field_object.set_hint_text(string, [color_r, color_g, color_b, color_a, ]align, size)
描述:

设置控件中的提示文字的属性
参数:
  • string (string) – 需要显示的字符串内容
  • [color_r, color_g, color_b, color_a] (list) – 可选参数，需要显示的字符串的颜色，参数分别为显示颜色 r 值、b 值，g 值，透明度，取值范围都为[0, 255]
  • align (enum) – 可选参数，枚举类型，需要显示文字的对齐方式，详细见表格 align
  • size (int) – 显示文字的字号大小
返回:

无
示例:

my_Input_field.set_hint_text(120, 120, 120, 200, text_anchor.upper_left, 12)
示例说明:

设置提示文字的 rgb 值为（120, 120, 120），透明度为 200 ，字体对齐方式为顶端左对齐，字号大小为 12 号
input_field_object.set_hint_text_color(r, g, b, a)
描述:

设置控件提示文字的颜色
参数:
  • r (int) – 文字颜色的 r 值，范围为[0, 255]
  • g (int) – 文字颜色的 g 值，范围为[0, 255]
  • b (int) – 文字颜色的 b 值，范围为[0, 255]
  • a (int) – 文字颜色的透明度， 范围为[0, 255]
返回:

无
示例:

my_Input_field.set_text_color(120, 120, 120, 200)
示例说明:

设置提示文字的 rgb 值为（120, 120, 120），透明度为 200
input_field_object.set_hint_text_align(align)
描述:设置提示文字的对齐方式
参数:align (enum) – 可选参数，枚举类型，需要显示文字的对齐方式，详细见表格 align
返回:无
示例:my_Input_field.set_text_align(text_anchor.upper_left)
示例说明:设置提示文字的对齐方式为顶端左对齐
input_field_object.set_hint_text_size(size)
描述:设置提示文字的字号大小
参数:size (int) – 文字的字号值
返回:无
示例:my_Input_field.set_text_size(12)
示例说明:设置 hint 对象中文字的字号为 12 号

提示

功能说明请参考 用户自定义 UI 系统

发射器

ir_blaster_ctrl.set_fire_count(count)
描述:设置红外光束的发射频率，即每秒射出的红外光束次数
参数:color_enum (int) – 发射频率，即每秒射出的红外光束次数，范围为[1:8]
返回:无
示例:ir_blaster_ctrl.set_fire_count(4)
示例说明:设置红外光束的发射频率为 4
ir_blaster_ctrl.fire_once()
描述:控制发射器只发射一次红外光束
参数:void – 无
返回:无
示例:ir_blaster_ctrl.fire_once()
示例说明:控制发射器只发射一次红外光束
ir_blaster_ctrl.fire_continuous()
描述:控制发射器持续发射红外光束
参数:void – 无
返回:无
示例:ir_blaster_ctrl.fire_continuous()
示例说明:控制发射器持续发射红外光束
ir_blaster_ctrl.stop()
描述:停止发射红外光束
参数:void – 无
返回:无
示例:ir_blaster_ctrl.stop()
示例说明:停止发射红外光束

机械爪

gripper_ctrl.open()
描述:控制机械爪打开
参数:void – 无
返回:无
示例:gripper_ctrl.open()
示例说明:控制机械爪打开
gripper_ctrl.close()
描述:控制机械爪关闭
参数:void – 无
返回:无
示例:gripper_ctrl.close()
示例说明:控制机械爪关闭
gripper_ctrl.stop()
描述:控制机械爪停止运动
参数:void – 无
返回:无
示例:gripper_ctrl.stop()
示例说明:控制机械爪停止运动
gripper_ctrl.update_power_level(level)
描述:设置机械爪力度档位
参数:level (int) – 机械爪的力度档位，范围为[1:4]档，默认为 1
返回:无
示例:gripper_ctrl.update_power_level(1)
示例说明:设置机械爪力度档位为 1
gripper_ctrl.is_closed()
描述:获取机械爪夹紧状态
参数:void – 无
返回:机械爪夹紧状态，若机械爪夹紧则返回 true，否则返回 false
返回类型:bool
示例:ret = gripper_ctrl.is_closed()
示例说明:获取机械爪夹紧状态
gripper_ctrl.is_open()
描述:获取机械爪张开状态
参数:void – 无
返回:机械爪张开状态，若机械爪完全张开则返回 true，否则返回 false
返回类型:bool
示例:ret = gripper_ctrl.is_open()
示例说明:获取机械爪张开状态

提示

模块说明请参考 机械臂与机械爪

机械臂

robotic_arm_ctrl.move(x, y, wait_for_complete=True)
描述:

设置机械臂运动的相对位置
参数:
  • x (int32) – 设置机械臂水平运动的距离，正数为向前运动，负数为向后运动，精确度为 1 mm
  • y (int32) – 设置机械臂垂直运动的距离，正数为向上运动，负数为向下运动，精确度为 1 mm
  • wait_for_complete (bool) – 是否等待执行完成，默认为 True
返回:

无
示例:

robotic_arm_ctrl.move(40, 50, True)
示例说明:

设置机械臂向前移动 20 mm，向上移动 30 mm，等待执行完成
robotic_arm_ctrl.moveto(x, y, wait_for_complete=True)
描述:

设置机械臂运动到绝对坐标
参数:
  • x (int32) – 设置机械臂水平运动的坐标值，精确度为 1 mm
  • y (int32) – 设置机械臂垂直运动的坐标值，精确度为 1 mm
  • wait_for_complete (bool) – 是否等待执行完成，默认为 True
返回:

无
示例:

robotic_arm_ctrl.moveto(40, 50, True)
示例说明:

设置机械臂移动到（x=40mm，y=50mm）的绝对坐标，等待执行完成
robotic_arm_ctrl.get_position()
描述:获取机械臂位置
参数:void – 无
返回:机械臂的绝对坐标，精确度为 1 mm
返回类型:列表[x, y], x 和 y 为 int32 类型
示例:[x, y] = robotic_arm_ctrl.get_position()
示例说明:获取机械臂的绝对坐标
robotic_arm_ctrl.recenter()
描述:设置机械臂回中
参数:void – 无
返回:无
示例:robotic_arm_ctrl.recenter()
示例说明:设置机械臂回中

提示

模块说明请参考 机械臂与机械爪

舵机

servo_ctrl.get_angle(servo_id)
描述:获取舵机旋转角度
参数:servo_id (uint8) – 舵机编号，范围为[1:3]
返回:舵机角度，精确度为 0.1 度
返回类型:int32
示例:angle = servo_ctrl.get_angle(1)
示例说明:获取编号为 1 的舵机旋转角度
servo_ctrl.set_angle(servo_id, angle, wait_for_complete=True)
描述:

设置舵机旋转角度
参数:
  • servo_id (uint8) – 舵机编号，范围为[1:3]
  • angle (int32) – 旋转角度，精确度为 0.1 度，正数为顺时针旋转，负数为逆时针旋转
  • wait_for_complete (bool) – 是否等待执行完成，默认为 True
返回:

无
示例:

servo_ctrl.set_angle(1, 900, True)
示例说明:

设置编号为 1 的舵机顺时针旋转 90°，等待执行完成
servo_ctrl.recenter(servo_id, wait_for_complete=True)
描述:

设置舵机回中
参数:
  • servo_id (uint8) – 舵机编号，范围为[1:3]
  • wait_for_complete (bool) – 是否等待执行完成，默认为 True
返回:

无
示例:

servo_ctrl.recenter(1, True)
示例说明:

设置编号为 1 的舵机回中，等待执行完成
servo_ctrl.set_speed(servo_id, speed)
描述:

设置舵机旋转速度
参数:
  • servo_id (uint8) – 舵机编号，范围为[1:3]
  • speed (int32) – 旋转速度，精确度为 1 度/秒，正数为顺时针旋转，负数为逆时针旋转
返回:

无
示例:

servo_ctrl.set_speed(1, 5)
示例说明:

设置编号为 1 的舵机顺时针旋转，旋转速度为 5 度/秒

提示

模块说明请参考 舵机

智能

vision_ctrl.marker_detection_color_set(color_enum)
描述:设置视觉标签识别颜色
参数:color_enum – 标签颜色类型，详细见表格 color_enum
返回:无
示例:vision_ctrl.marker_detection_color_set(rm_define.marker_detection_color_red)
示例说明:设置视觉标签识别颜色为红色
color_enum
rm_define.marker_detection_color_red 红色
rm_define.marker_detection_color_green 绿色
rm_define.marker_detection_color_blue 蓝色

装甲板

def ir_hit_detection_event(msg):
描述:当检测到机器人受到红外光束攻击时，运行函数内程序
参数:msg – 函数内部的消息参数
返回:无
示例: 
1
2
3
4
#当检测到机器人受到红外光束攻击时，运行函数内程序

def ir_hit_detection_event(msg):
    pass
armor_ctrl.cond_wait(condition_enum)
描述:等待机器人受到红外光束攻击时，执行下一条指令
参数:condition_enum – 事件类型，rm_define.cond_ir_hit_detection 表示机器人受到红外光束攻击
返回:无
示例:armor_ctrl.cond_wait(rm_define.cond_ir_hit_detection)
示例说明:等待机器人受到红外光束攻击时，执行下一条指令
armor_ctrl.check_condition(condition_enum)
描述:判断机器人是否受到红外光束攻击
参数:condition_enum – 事件类型，rm_define.cond_ir_hit_detection 表示机器人受到红外光束攻击
返回:机器人是否受到红外光束攻击，受到攻击时返回真，否则返回假。
返回类型:bool
示例:if armor_ctrl.check_condition(rm_define.cond_ir_hit_detection):
示例说明:如果机器人受到红外光束攻击时，执行下一条指令

红外深度传感器

ir_distance_sensor_ctrl.enable_measure(port_id)
描述:开启红外深度传感器测距功能
参数:port_id (int) – 红外深度传感器模块编号，范围为[1:4]
返回:无
示例:ir_distance_sensor_ctrl.enable_measure(1)
示例说明:开启 1 号红外深度传感器测距功能
ir_distance_sensor_ctrl.disable_measure(port_id)
描述:关闭红外深度传感器测距功能
参数:port_id (int) – 红外深度传感器模块编号，范围为[1:4]
返回:无
示例:ir_distance_sensor_ctrl.disable_measure(1)
示例说明:关闭 1 号红外深度传感器测距功能
ir_distance_sensor_ctrl.get_distance_info(port_id)
描述:获取红外深度传感器测距信息
参数:port_id (int) – 红外深度传感器模块编号，范围为[1:4]
返回:红外深度传感器前方障碍物的距离，精确度为 1 cm
返回类型:uint16
示例:ir_distance_sensor_ctrl.get_distance_info(1)
示例说明:获取 1 号红外深度传感器测距信息
def ir_distance_[port_id]_[compare_type]_[dist]_event(msg):
描述:

当检测到红外深度传感器模块前方障碍物距离满足条件时，运行函数内程序
参数:
  • port_id (int) – 红外深度传感器模块编号，范围为[1:4]
  • compare_type – 比较类型，可以为 eq, ge, gt, le, lt, 分别表示等于，大于等于，大于，小于等于，小于
  • dist – 用于比较的距离，精确度为 1 cm，范围为 5~500 cm，误差率为 5%
返回:

无
示例: 
1
2
3
4
#当检测到 1 号红外深度传感器前方障碍物距离小于 10 cm 时，运行函数内程序

def ir_distance_1_lt_10_event(msg):
    pass
ir_distance_sensor_ctrl.cond_wait('ir_distance_[port_id]_[compare_type]_[dist]')
描述:

等待红外深度传感器模块前方障碍物距离满足条件时，执行下一条指令
参数:
  • 'ir_distance_[port_id]_[compare_type]_[dist]' – 用于距离比较的字符串，含模块编号，比较类型和距离
  • port_id (int) – 红外深度传感器模块编号，范围为[1:4]
  • compare_type – 比较类型，可以为 eq, ge, gt, le, lt, 分别表示等于，大于等于，大于，小于等于，小于
  • dist – 用于比较的距离，精确度为 1 cm，范围为 5~500 cm，误差率为 5%
返回:

无
示例:

ir_distance_sensor_ctrl.cond_wait('ir_distance_1_gt_50')
示例说明:

等待 1 号红外深度传感器模块前方障碍物距离大于 50 cm 时，执行下一条指令
ir_distance_sensor_ctrl.check_condition('ir_distance_[port_id]_[compare_type]_[dist]')
描述:

判断红外深度传感器模块前方障碍物距离是否满足条件
参数:
  • 'ir_distance_[port_id]_[compare_type]_[dist]' – 用于距离比较的字符串，含模块编号，比较类型和距离
  • port_id (int) – 红外深度传感器模块编号，范围为[1:4]
  • compare_type – 比较类型，可以为 eq, ge, gt, le, lt, 分别表示等于，大于等于，大于，小于等于，小于
  • dist – 用于比较的距离，精确度为 1 cm，范围为 5~500 cm，误差率为 5%
返回:

是否满足条件，满足条件时返回真，否则返回假。
返回类型:

bool
示例: 
1
2
3
4
#当检测到 1 号红外深度传感器前方障碍物距离小于 10 cm 时，运行函数内程序

if ir_distance_sensor_ctrl.check_condition('ir_distance_1_gt_50'):
    pass

提示

模块说明请参考 红外深度传感器

传感器转接模块

sensor_adapter_ctrl.get_sensor_adapter_adc(board_id, port_num)
描述:

获取传感器转接模块相应端口模拟引脚的 ADC 值
参数:
  • board_id (int) – 传感器转接模块编号，范围为[1:6]
  • port_num (uint8) – 传感器转接模块上的端口号，范围为[1:2]
  • wait_for_complete (bool) – 是否等待执行完成，默认为 True
返回:

传感器转接模块相应端口模拟引脚的 ADC 值，范围为[0:1023]
返回类型:

uint16
示例:

ret = sensor_adapter_ctrl.get_sensor_adapter_adc(1, 2)
示例说明:

获取 1 号传感器转接模块 2 号端口模拟引脚的 ADC 值
sensor_adapter_ctrl.get_sensor_adapter_pulse_period(board_id, port_num)
描述:

获取传感器转接模块相应端口引脚的脉冲持续时间
参数:
  • board_id (int) – 传感器转接模块编号，范围为[1:6]
  • port_num (uint8) – 传感器转接模块上的端口号，范围为[1:2]
返回:

传感器转接模块相应端口引脚的脉冲持续时间，精确度为 1 ms
返回类型:

uint32
示例:

ret = sensor_adapter_ctrl.get_sensor_pulse_period(1, 2)
示例说明:

获取 1 号传感器转接模块 2 号端口引脚脉冲持续时间
def sensor_adapter[board_id]_port[port_id]_[judge_type]_event(msg):
描述:

当检测到传感器转接模块相应端口引脚跳变为高电平/低电平/双向，运行函数内程序
参数:
  • board_id (int) – 传感器转接模块编号，范围为[1:6]
  • port_num (uint8) – 传感器转接模块上的端口号，范围为[1:2]
  • judge_type – 触发条件，可以为 high, low, trigger，分别表示高电平，低电平还是双向跳变
返回:

无
示例: 
1
2
3
4
#当检测到 1 号传感器转接模块 2 号端口引脚跳变为高电平时，运行函数内程序

def sensor_adapter1_port2_high_event(msg):
    pass
sensor_adapter_ctrl.cond_wait(rm_define.cond_sensor_adapter[board_id]_port[port_id]_[judge_type]_event)
描述:

等待传感器转接模块相应端口引脚脉冲为（高/低/跳变）时，执行下一条指令
参数:
  • board_id (int) – 传感器转接模块编号，范围为[1:6]
  • port_num (uint8) – 传感器转接模块上的端口号，范围为[1:2]
  • judge_type – 触发条件，可以为 high, low, trigger，分别表示高电平，低电平还是双向跳变
返回:

无
示例:

sensor_adapter_ctrl.cond_wait(rm_define.cond_sensor_adapter1_port2_high_event)
示例说明:

等待 1 号传感器转接模块 2 号端口引脚为高电平时，执行下一条指令
sensor_adapter_ctrl.check_condition(rm_define.cond_sensor_adapter[board_id]_port[port_id]_[judge_type]_event)
描述:

判断传感器转接模块相应端口引脚脉冲是否为（高/低/跳变）
参数:
  • board_id (int) – 传感器转接模块编号，范围为[1:6]
  • port_num (uint8) – 传感器转接模块上的端口号，范围为[1:2]
  • judge_type – 触发条件，可以为 high, low, trigger，分别表示高电平，低电平还是双向跳变
返回:

是否满足条件，满足条件时返回真，否则返回假。
返回类型:

bool
示例: 
1
2
3
4
#如果 1 号传感器转接模块 2 号端口引脚正在跳变时，执行下一条指令

if sensor_adapter_ctrl.check_condition(rm_define.cond_sensor_adapter1_port2_trigger_event):
    pass

提示

模块说明请参考 传感器转接模块

UART

serial_ctrl.serial_config(baud_rate, data_bit, odd_even, stop_bit)
描述:

设置串口的波特率、数据位、校验位以及停止位属性
参数:
  • baud_rate – 设置波特率，可选波特率为 9600、19200、38400、57600、115200
  • data_bit – 设置数据位，可选的数据位为 cs7、cs8
  • odd_even_crc – 设置奇偶校验，详细见表格 odd_even_crc
  • stop_bit – 设置停止位，可选的停止位为 1、2
返回:

无
示例:

serial_ctrl.serial_config(9600, 'cs8', 'none', 1)
示例说明:

设置串口的波特率为 9600，数据位 8 位，不使用奇偶校验，停止位为 1 位
serial_ctrl.write_line(msg_string)
描述:发送字符串信息，自动添加换行 '\n'
参数:msg_string (string) – 需要发送的字符串信息，发送时字符串后自动添加 '\n'
返回:无
示例:serial_ctrl.write_line('RoboMaster EP')
示例说明:向串口写入 'RoboMaster EP\n' ，最后的换行自动添加，用户只需要发送 'RoboMaster EP'
serial_ctrl.write_string(msg_string)
描述:发送字符串信息
参数:msg_string (string) – 需要发送的字符串信息
返回:无
示例:serial_ctrl.write_string('RoboMaster EP')
示例说明:向串口写入 'RoboMaster EP'
serial_ctrl.write_number(value)
描述:将数字参数转换成字符串，并通过串口发送出去
参数:value (int) – 需要发送的值
返回:无
示例:serial_ctrl.write_number(12)
示例说明:向串口中写入字符串 '12'
serial_ctrl.write_numbers(value1, value2, value3...)
描述:

将数字列表转换成字符串，并通过串口发送出去
参数:
  • value1 (int) – 需要发送数字列表的值
  • value2 (int) – 需要发送数字列表的值
  • value3 (int) – 需要发送数字列表的值
返回:

无
示例:

serial_ctrl.write_numbers(12,13,14)
示例说明:

向串口中写入字符串 '12,13,14'
serial_ctrl.write_value(key, value)
描述:

将参数以键值对的形式组成字符串，并通过串口发送出去
参数:
  • key (string) – 需要发送的关键字
  • value (int) – 需要发送的值
返回:

无
示例:

serial_ctrl.write_value('x', 12)
示例说明:

向串口中写入字符串 'x:12'
serial_ctrl.read_line([timeout])
描述:从串口中读取以 '\n' 结尾的字符串
参数:timeout (float) – 可选，超时时间，单位为秒，默认为永久阻塞
返回:通过串口读取到的字符串
返回类型:string
示例:recv = serial_ctrl.read_line()
示例说明:从串口读取一行以 '\n' 结尾的字符串
serial_ctrl.read_string([timeout])
描述:从串口中读取字符串（字符串可以不以 '\n' 结尾）
参数:timeout (float) – 可选，超时时间，单位为秒，默认为永久阻塞
返回:通过串口读取到的字符串
返回类型:string
示例:recv = serial_ctrl.read_string()
示例说明:从串口读取一个字符串
serial_ctrl.read_until(stop_sig[, timeout])
描述:

从串口中读取字符串，直到匹配到指定的结束字符 'stop_sig'
参数:
  • stop_sig – 指定的结束字符，参数类型为字符，范围为[ '\n' | '$' | '#' | '.' | ':' | ';' ]
  • timeout (float) – 可选，超时时间，单位为秒，默认为永久阻塞
返回:

通过串口读取到的匹配字符串
返回类型:

string
示例:

serial_ctrl.read_until('#')
示例说明:

从串口中读取字符串，直到匹配到 '#' 停止读取
odd_even_crc
none 不使用奇偶校验
odd 使用奇校验
even 使用偶校验

提示

模块说明请参考 UART

版本说明

为了提供更好的使用体验以及配合更强大的功能，开发者文档将会定期进行版本更新。使用前请确认您的机器人版本，SDK版本以及文档版本是否匹配。若不匹配，建议您更新机器人至要求的版本，或者使用对应版本的文档。

版本信息参考下表：

2020/9/30更新：

doc S1 EP Text SDK RoboMaster SDK
v0.3.0(latest) v00.06.01.00 v01.01.05.00 v00.00.00.68 v0.1.1.59

1.增加多机编队sop 2.优化TT编队稳定性 3.增加红外打击事件订阅 4.多机接口优化

2020/10/22更新：

doc S1 EP Text SDK RoboMaster SDK
v0.3.0(latest) v00.06.01.00 v01.01.05.00 v00.00.00.68 v0.1.1.61

1.增加线识别的类型 2.修复底盘模式设置失败 3.增加音效类型定义 4.修复tt连接问题

2020/10/29更新：

doc S1 EP Text SDK RoboMaster SDK
v0.3.0(latest) v00.06.01.00 v01.01.05.00 v00.00.00.68 v0.1.1.62

1.arm版固件版本

2020/11/19更新：

doc S1 EP Text SDK RoboMaster SDK
v0.3.0(latest) v00.06.01.00 v01.01.05.00 v00.00.00.68 v0.1.1.63

1.增加多机编队EP机械爪的控制 2.优化TT的连接

备注：

window、linux_x86架构的最新版本v0.1.1.63

mac 最新版本v0.1.1.61

linux_arm架构最新版本v0.1.1.62

Indices and tables