歡迎來到 RoboMaster 開發者頁面¶

開篇介紹¶

EP套裝介紹¶

RoboMaster EP 教育拓展套裝在 RoboMaster S1 教育機器人的基礎上延展出豐富的拓展性，配有完善的課程內容及全新 RoboMaster 青少年專屬賽事；各類編程模塊均圍繞教學需求精心設計，帶來煥然一新的教學與學習體驗，拓展未來教育的全新邊界。

EP機器人形態¶

RoboMaster EP 教育套裝可以組裝出步兵機器人或工程機器人。其中步兵機器人在外觀上與常規版本的 S1 較為接近，並在軟硬件上進行了升級，增加了許多新部件，極大地提升了拓展能力，升級後的機器人能夠通過傳感器轉接模塊接入第三方傳感器，擁有更多的可編程空間。

步兵機器人

工程機器人在外觀上基於 S1 做了較大的改動：採用一個並聯機械臂代替安裝在底盤正中央的雲台結構，保留了圖傳系統，並且在機械臂末端裝配一個機械夾爪，從而可以執行更加複雜的任務。在底盤的行動能力和整機的拓展能力方面，則與步兵機器人水準相當。

工程機器人

網站內容¶

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 位

從python官網 python 官網鏈接找到可以下載的安裝包，以Python3.7.8 為例，選擇安裝文件進行下載。

警告

請確保下載的 python.exe 是64位的，python sdk適配3.6.6以上至3.8.9版本python版本，否則會影響python sdk的使用，切記。

步驟（1）：確認安裝包版本是 64-bit, 否則會影響Python sdk使用。

步驟（2）：勾選 Add Python 3.7 to Path。

步驟（3）：選擇 Install Now 進行安裝，如下圖所示。

安裝完成後按 win+r，在彈出窗口中輸入 cmd 打開命令提示符界面，在命令行裡面輸入 python, 確認 Python 3.7.8 安裝成功。

備註

cmd窗口會顯示對應的版本信息，否則，請從第一步重新安裝

在 Ubuntu 上安裝 Python¶

環境： ubuntu 16.04 64 位，Python 3.7.8

Ubuntu16.04 默認安裝了Python2.7和3.5，輸入命令 python，可以查看 Python 默認版本。請注意，系統自帶的python千萬不能卸載。
輸入如下命令安裝 python 3.7 軟件包：

sudo add-apt-repository ppa:jonathonf/python-3.7
sudo apt-get update
sudo apt-get install python3.7

輸入如下命令，調整 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

此時再輸入命令 python ，確認 Python 3.7 安裝成功。

第三方平台通信¶

介紹¶

用戶使用第三方平台跟 RoboMaster EP 建立連接後，通過明文 SDK 和 EP 機器人進行通信，可以控制各個內置模塊和拓展模塊，並獲取 EP 機器人的視頻流、音頻流，極大地豐富了 EP 的擴展性，解鎖更多玩法。

第三方平台類型¶

用戶使用的第三方平台為有自主計算能力，具有 WIFI 、 USB 和 UART 接口的計算平台，包括但不限於 DJI 妙算、Arduino 開發板、Micro:bit、樹莓派、Jetson Nano 和 PC。

通信方式¶

第三方平台和 RoboMaster EP 的通信方式包括三種： WIFI、 USB 和 UART。下面介紹這三種通信方式的連接方法。

WIFI 連接¶

WIFI 連接包括直連模式和路由器模式，具體參考如下說明。

直連模式¶

條件:
第三方平台具有 WIFI 連接功能。

用途:
第三方平台使用 WIFI 連接到 EP 後，通過明文 SDK 和 EP 進行通信。

步驟:

啟動 EP，切換智能中控的連接模式開關至 直連模式。

打開第三方平台的無線網絡，掃瞄 EP 的熱點，進行連接。

通過明文 SDK 和 EP 進行通信。（詳細步驟參考 WIFI 直連模式)

應用舉例:
DJI 妙算、Jetson Nano 或 PC 使用 WIFI 連接到 EP 後，通過明文 SDK 和 EP 進行通信，並獲取 EP 的視頻流、音頻流。

示意圖:

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

路由器模式¶

條件:
第三方平台具有 WIFI 或有線網絡連接功能。

用途:
第三方平台和 EP 連接到同一個局域網中，通過明文 SDK 和 EP 進行通信。

步驟:

啟動 EP，切換智能中控的連接模式開關 路由器模式。

通過官方 App 的掃碼連接方式將 EP 連接到路由器。

第三方平台通過 WIFI 或有線網絡連接到同一路由器。

通過官方 App 的設置頁面或是編寫腳本等方式獲取到 EP 的 IP 地址。

通過明文 SDK 和 EP 進行通信。（詳細步驟參考 WIFI 路由器模式)

應用舉例:
DJI 妙算、Jetson Nano 或 PC 和 EP 連接到同一個局域網後，通過明文 SDK 和 EP 進行通信，並獲取 EP 的視頻流、音頻流。

示意圖:

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

USB 連接¶

條件:
第三方平台具有 TypeA USB 接口，並支持 RNDIS 功能。

用途:
第三方平台通過 USB 線連接到 EP 的智能中控的 Micro USB 端口，使用明文 SDK 和 EP 進行通信。

步驟:

啟動 EP，無需關心智能中控的連接模式開關位置。

第三方平台通過 USB 線連接到 EP 的智能中控。

通過明文 SDK 和 EP 進行通信。（詳細步驟參考 USB 連接)

應用舉例:
樹莓派或 Jetson Nano 固定在 EP 小車上，並由 EP 的電源轉接模塊供電，通過 USB 連接到 EP，使用明文 SDK 和 EP 進行通信，並獲取 EP 的視頻流、音頻流。

示意圖:

樹莓派連接示意圖

Jetson Nano連接示意圖

UART 連接¶

條件:
第三方平台具有 UART 接口或有串口轉 USB 功能。

用途:
第三方平台通過 UART 連接到 EP 運動控制器的 UART 接口，使用明文 SDK 和 EP 進行通信。

步驟:

啟動 EP，無需關心智能中控的連接模式開關位置。

第三方平台 UART 的 TX/RX 和 GND 分別連接到 EP 運動控制器 UART 的 RX/TX 和 GND。（參考引腳說明)

通過明文 SDK 和 EP 進行通信。（詳細步驟參考 UART 連接)

應用舉例:
Arduino 或 Micro:bit 固定在 EP 小車上，並由 EP 的電源轉接模塊供電，通過 UART 連接到 EP 運動控制器，使用明文 SDK 和 EP 進行通信。

示意圖:

Arduino連接示意圖

Micro:bit連接示意圖

RoboMaster SDK 安裝¶

安裝 SDK 到 Windows平台¶

開發環境準備¶

小訣竅

在使用python sdk前，需要確保編程平台端安裝對應的python環境，如果沒有，請參考以下鏈接進行安裝： python編程環境安裝

安裝必要的VC庫環境¶

下載（下載地址：GitHub RoboMaster SDK repository , 備用地址：Gitee RoboMaster SDK repository）安裝VC庫的exe可執行文件：

警告

不安裝VC庫，使用SDK，會引起以下問題:

安裝robomaster python sdk¶

安裝RoboMaster SDK，點開開始菜單，在搜索框中輸入 cmd ，在搜索結果中，對著命令提示符程序，單擊鼠標右鍵，菜單中點擊選擇 以管理員身份運行 ,並輸入以下指令:

pip install robomaster

小訣竅

如果出現下列情況，請參考以下鏈接進行python環境安裝：python編程環境安裝

升級 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 SDK 支持3種與EP的連接方式：WiFi 直連模式，WiFi 組網模式和 USB(RNDIS) 連接模式。

WIFI直連 ：

Wi-Fi 直連 ：通過將機器人設置為直連模式，並連接機器人的 Wi-Fi 熱點進行接入，Wi-Fi 直連模式下，機器人默認 IP 為 192.168.2.1

開啟機器人電源，切換智能中控的連接模式開關至 直連模式，如下圖所示：
準備具有WIFI連接功能的設備，例如：DJI 妙算、Jetson Nano 或 PC：

DJI 妙算、Jetson Nano 或 PC 通過 WIFI 直連到 EP
參考sdk代碼 /examples/01_robot/04_ap_conn.py 目錄下的例程（GitHub RoboMaster SDK repository）

運行結果:
```
Robot Version: xx.xx.xx.xx
```

USB連接

USB 連接 ：通過機器人的智能中控上的 USB 端口接入，機器人默認 IP 為 192.168.42.2

USB 連接模式，實質上是使用 RNDIS 協議，將機器人上的 USB 設備虛擬為一張網卡設備，通過 USB 發起 TCP/IP 連接更多 RNDIS 內容請參見 RNDIS Wikipedia。

選擇具有 TypeA USB 接口，並支持 RNDIS 功能的第三方平台，這邊列舉樹莓派的連接，圖中藍線即為USB連接，紅線為供電線：

樹莓派連接示意圖
參考sdk代碼 /examples/01_robot/06_rndis_conn.py 目錄下的例程（GitHub RoboMaster SDK repository）

運行結果:
```
Robot Version: xx.xx.xx.xx
```

組網連接 ：

Wi-Fi 組網 ：通過將機器人設置為組網模式，並將計算設備與機器人加入到同一個局域網內，實現組網連接

開啟機器人電源，切換智能中控的連接模式開關至 組網模式
DJI 妙算、Jetson Nano 或 PC 和 EP 連接到同一個局域網後和 EP 進行通信。

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）

警告

示例代碼13行中的，ssid （路由器名稱）和 password (路由器密碼)，需要根據實際的路由器信息進行填寫

運行示例代碼，會出現二維碼圖片，按下機器人智能中控上的掃碼連接按鍵，掃瞄二維碼進行組網連接。
運行結果:
```
Connected!
```

同時機器人的燈效變為白色呼吸變為青綠色常亮。

小訣竅

支持在組網模式下通過SN連接指定的機器人，用戶通過在初始化時給 sn 參數賦值完成對機器人 sn 的輸入，參考例程 /examples/01_robot/05_sta_conn_sn.py （GitHub RoboMaster SDK repository）。在不指定 sn 時，SDK默認與搜索到的第一台機器人建立連接。

教育無人機系列連接方式¶

教育無人機目前主要包括 Tello EDU 以及 Tello Talent，Robomaster SDK支持通過WIFI直連模式與這兩款產品建立連接。

WIFI直連 ：

Wi-Fi 直連 ：通過將機器人設置為直連模式，並連接機器人的 WIFI 熱點進行接入，WIFI 直連模式下，機器人默認 IP 為 192.168.10.1

首先將機器人設置為 WIFI 直連模式
- Tello EDU : 短按圖中紅色剪頭所示電源按鍵，等待黃燈快閃開機完成，機器人出廠默認即為 WIFI 直連模式，如果開機時為組網模式，可以通過電源按鍵重置 WIFI：在開機狀態下，長按電源鍵 5s，期間狀態指示燈將熄滅後再閃爍黃燈。狀態指示燈顯示黃燈快閃後， WIFI 的 SSI 和密碼將重置為出廠設置，默認無密碼
- Tello Talent :: 開啟機器人電源，切換擴展模塊的模式開關至 直連模式，如下圖所示：
準備具有WIFI連接功能的設備連接教育無人機的 WIFI，例如：DJI 妙算、Jetson Nano 或 PC：
參考sdk代碼 /examples/12_drone/01_ap_conn.py 目錄下的例程（GitHub RoboMaster SDK repository）

運行結果:
```
Drone SDK Version: xx.xx.xx.xx
```

組網模式 ：

組網模式 ：將機器人設置為組網模式，並連接SDK運行設備所在的局域網進行接入，

首先將飛機設置為 直連模式，並且與運行SDK的設備連接，具體操作參考上一小節
運行提供的示例程序 /examples/12_drone/23_set_sta.py （GitHub RoboMaster SDK repository），將程序中的 ssis 與 password 參數改為當前使用的路由器的賬號與密碼

切換擴展模塊的模式開關至組網模式，之後機器會自動連接到指定的路由器所在的局域網內
將運行SDK的設備也連接至該局域網內，此時SDK與機器即在同一網絡內

通訊方式¶

EP通訊方式¶

Robomaster SDK 與EP的3種連接方式在通訊協議上支持 TCP 和 UDP 通訊。

參數	TCP	UDP
可靠性	可靠	不可靠
連接性	面向連接	無連接
效率	低	高
場景	對數據準確性要求高	對數據傳輸的實時性要求高

小訣竅

機器人要實時的控制運動的可以選用 UDP, 機器人進行事件型控制可以選用 TCP

用戶可以根據自己的運用場景去設置對應的通訊方式更多TCP通訊內容可以參考：TCP Wikipedia ，UDP通訊可以參考：UDP Wikipedia。

TCP通訊

參考sdk代碼 /examples/01_robot/07_tcp_protocol.py 目錄下的例程（GitHub RoboMaster SDK repository）

組網連接

這邊可以根據代碼第8行中的 connect_type 參數進行修改 sta 對應組網連接，ap 對應WIFI直連，rndis 對應USB連接。

運行程序，並得到結果返回:
```
Robot Version: xx.xx.xx.xx
```

UDP 通訊

參考sdk代碼 /examples/01_robot/08_udp_protocol.py 目錄下的例程（GitHub RoboMaster SDK repository）

進行組網連接

這邊可以根據代碼第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

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

示例二：獲取機器人SN號¶

首先按照初始化機器人章節的介紹完成機器人對象的初始化操作
利用 Robot 對像使用 get_sn() 方法，方法的返回值即為代表機器人SN號的字符串，並且將獲取到的SN號打印出來:
```
SN = ep_robot.get_sn()
print("Robot SN:", SN)
```
利用釋放機器人資源章節的介紹釋放相關資源

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

設置類接口的使用¶

設置類接口可以完成對機器人的相關模塊的設置，本文檔接下來將通過設置機器人整機運動模式與設置機器人裝甲燈兩個例子講解設置類接口的使用

示例一：設置機器人整機運動模式¶

機器人的運動模式有三種：自由模式（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

示例二：設置機器人裝甲燈¶

下面介紹如何通過 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/09_set_mode.py，例程中利用了for循環，實現了led燈的8次顏色變換，每次維持1秒鐘

動作類接口的使用¶

動作類接口是用來控制機器人執行某些指定動作的接口，根據動作本身特性的不同， 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

示例二：控制底盤速度¶

控制底盤速度是一種典型的即時控制，發出控制指令後機器人將會立即按照指定速度運動

首先按照初始化機器人章節的介紹完成機器人對象的初始化操作
底盤控制接口屬於 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，例程中每次令機器人按照指定速度運動三秒鐘，然後改變速度

任務動作控制¶

任務動作是指需要持續一段時間才能完成的動作，比如控制底盤向前運動一米，底盤對於該動作需要執行一段時間才能到達指定地點。通過 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，

多媒體接口的使用¶

多媒體接口主要包括視頻流與音頻流兩部分，接下來將通過兩個示例介紹該類型接口的使用

示例一：獲取視頻流¶

獲取機器人採集到的視頻流有助於實現一些非常實用的案例，下面本文檔將介紹如何通過 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

示例程序中同時提供了一個完整的獲取視頻流之後利用cv2提供的方法顯示圖像的例程 examples/04_camera/03_video_without_display.py

示例二：獲取音頻流¶

本示例將會通過 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

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

示例二：獲取機器人SN號¶

首先按照初始化機器人章節的介紹完成機器人對象的初始化操作
利用 Drone 對像使用 get_sn() 方法，方法的返回值即為代表機器人SN號的字符串，並且將獲取到的SN號打印出來:
```
SN = tl_drone.get_sn()
print("drone sn: {0}".format(SN))
```
利用釋放機器人資源章節的介紹釋放相關資源

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

設置類接口的使用¶

設置類接口可以完成對機器人的相關模塊的設置，本文檔接下來將通過設置擴展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秒鐘

動作類接口的使用¶

動作類接口是用來控制機器人執行某些指定動作的接口，根據動作本身特性的不同， 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，

即時動作控制¶

即時控制類動作是指設置後馬上生效的動作，特指宏觀上是「瞬時」執行的動作，接下來本文檔將通過控制遙控器桿量帶大家熟悉此類動作接口

示例一：控制遙控器桿量¶

控制遙控器桿量是一種典型的即時控制，發出控制指令後機器人將會立即按照指定速度與方向飛行

首先按照初始化機器人章節的介紹完成機器人對象的初始化操作
飛行控制接口屬於 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，

多媒體接口的使用¶

教育系列無人機的多媒體部分主要指獲取視頻流

示例一：獲取視頻流¶

獲取機器人採集到的視頻流有助於實現一些非常實用的案例，下面本文檔將介紹如何通過 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

RoboMaster SDK 新手入門 - 多機控制篇¶

多機控制簡介¶

RobomasterSDK 支持多機控制，用戶可以調用相應的多機接口，輕鬆控制多台機器，實現複雜的多機編隊等任務

多機控制流程¶

多機控制主要分為以下方面：

多機初始化 ，與局域網內的多台機器建立連接，並初始化相關機器人

多機編號 ，通過飛機的SN號對飛機進行編號，便於後面進行多機的選中控制

多機分組 & 群組控制 ，通過將多台機器進行分組，實現多機選中的效果

任務控制 ，通過任務控制的方式可以同時控制不同組執行不同的動作

接下來本文檔將對這幾部分別進行介紹。

多機初始化¶

環境準備安裝netifaces包:

pip install netifaces

小訣竅

如果出現以下問題，請下載安裝visualcppbuildtools_full.exe(下載地址：GitHub RoboMaster SDK repository)

1. 首先將機器人設置為路由器組網模式，並將所有機器人與運行 RobomasterSDK 的設備連接至同一個局域網內。關於本部分如何操作，RobomasterEP參考 EP連接方式，教育飛機參考教育無人機系列連接方式

導入多機控制相關的包:

from multi_robomaster import multi_robot

生成多機對像

示例一：生成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 目錄下的例程

運行程序後SDK會在在程序的同級目錄下會自動生成系統日誌文件,如下圖所示

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_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输出占空比，单位%

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轴方向旋转角度，单位 °
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:调用结果

class robomaster.led.TelloLed(robot)¶

基礎類別：object

教育无人机扩展LED模块

set_led(r=0, g=255, b=0)¶

设置扩展模块led颜色

參數:	r – int:[0, 255], 扩展led红色通道的强度 g – int:[0, 255], 扩展led绿色通道的强度 b – int:[0, 255], 扩展led蓝色通道的强度
傳回:	bool: 扩展led模块控制结果

set_led_blink(freq=5, r1=0, g1=255, b1=0, r2=0, g2=255, b2=255)¶

设置扩展模块led以制定的两种颜色与频率实现闪烁效果

參數:

freq – int:[0.1, 10], 扩展ked闪烁模式下的频率，共十档，随着数字增大速度变快
r1 – int:[0, 255], 第一种颜色的红色通道的强度
g1 – int:[0, 255], 第一种颜色的绿色通道的强度
b1 – int:[0, 255], 第一种颜色的蓝色通道的强度
r2 – int:[0, 255], 第二种颜色的红色通道的强度
g2 – int:[0, 255], 第二种颜色的绿色通道的强度
b2 – int:[0, 255], 第二种颜色的蓝色通道的强度

傳回:

bool: 扩展led模块控制结果

set_led_breath(freq=1, r=0, g=255, b=0)¶

设置扩展模块led以指定的颜色与频率实现呼吸效果

參數:	freq – int:[0.1, 2.5], 扩展led呼吸模式下的频率，共十档，随着数字增大速度变快 r – int:[0, 255], 扩展led红色通道的强度 g – int:[0, 255], 扩展led绿色通道的强度 b – int:[0, 255], 扩展led蓝色通道的强度
傳回:	bool: 扩展led模块控制结果

set_mled_boot(display_graph)¶

设置点阵屏的开机画面

參數:	display_graph – string: 长度最大为64，点阵屏显示图案的编码字符串，每个字符解读为二进制后对应位置的led点的状态，

『0’为关闭该位置led，』r’为点亮红色，』b’为点亮蓝色，』p』为点亮紫色，输入的长度不足64，后面对应的led点默认都是’0’熄灭状态 :return: bool: 设置开机动画的结果

set_mled_bright(bright=255)¶

设置点阵屏的亮度

參數:	bright – int:[0, 255] 点阵屏的亮度
傳回:	bool: 点阵屏亮度的设置结果

set_mled_char(color='r', display_char='0')¶

控制扩展点阵屏模块，显示输入的字符

Param:	color: char: 『r’为红色，』b’为蓝色，』p』为紫色
Param:	display_char: char: [0~9, A~F, heart]，显示的字符
傳回:	bool: 控制结果

set_mled_char_scroll(direction='l', color='r', freq=1.5, display_str='DJI')¶

控制扩展点阵屏滚动显示字符串

Param:	direction: char: 点阵屏滚动方向，』l』: 字符串向左移动，』r』: 字符串向右移动，』u』字符串向上移动，』d』字符串向下移动
Param:	color: char: 点阵屏显示的颜色，『r’红色，』b’蓝色，』p’紫色
Param:	freq: float:[0.1, 2.5], 点阵屏滚动的频率, 0.1-2.5HZ之间, 随着数字增大速度变快
Param:	display_str: string:需要显示的字符串
傳回:	设置结果

set_mled_graph(display_graph)¶

用户自定义扩展点阵屏显示图案

參數:	display_graph – string: 长度最大为64，点阵屏显示图案的编码字符串，每个字符解读为二进制后对应位置的led点的状态，

『0’为关闭该位置led，』r’为点亮红色，』b’为点亮蓝色，』p』为点亮紫色，输入的长度不足64，后面对应的led点默认都是’0’熄灭状态 :return:bool: 控制结果

set_mled_graph_scroll(direction='l', freq=1.5, display_graph='00rrrr000r0000r0r0r00r0rr000000rr0r00r0rr00rr00r0r0000r000rrrr00')¶

控制扩展点阵屏滚动显示图像

Param:	direction: char: 点阵屏滚动方向，』l』: 字符串向左移动，』r』: 字符串向右移动，』u』字符串向上移动，』d』字符串向下移动
Param:	freq: float:[0.1, 2.5], 点阵屏滚动的频率, 0.1-2.5HZ之间, 随着数字增大速度变快
Param:	display_str: string:需要显示的图像
傳回:	设置结果

set_mled_sc()¶

清除点阵屏开机显示画面

傳回:	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

class robomaster.sensor.TelloDistanceSensor(robot)¶

基礎類別：object

教育无人机距离传感器模块

get_ext_tof()¶

获取扩展模块tof传感器的数值

傳回:	float: 扩展模块tof传感器的值

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: 调用结果

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)
blaser	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()

以下兩個接口在多機中的使用與單機不同：

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 對像

led 模塊的指令:

新增command_dict參數，通過使用command_dict實現對單個飛機led的控制，功能與go類似

參數： command_dict: {robot_id1: [*args], robot_id2: [*args], ... }
      其中 robot_id 是飛機的編號， *args為各led模塊的參數

返回值： multi_action 對像

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 )進行編寫如下:

飛機的SN號和電量會在控制台打印出來，打印格式為：「DRONE id: {}, reply: {}」

利用釋放無人機資源章節的介紹釋放相關資源

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

設置類接口的使用¶

設置類接口可以完成對無人機的相關模塊的設置，本文檔接下來將通過設置擴展led模塊講解設置類接口的使用

小訣竅

設置擴展led燈目前只有 Tello Talent 機器支持！

示例一：設置無人機擴展led模塊¶

下面介紹如何通過 SDK 實現設置無人機擴展led模塊的操作

首先按照控制無人機執行命令章節的介紹完成無人機對象的各項操作
對 base_action_1 進行編寫如下:

使用 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

動作類接口的使用¶

動作類接口是用來控制無人機執行飛行動作的接口，本文檔接下來將講解飛行類接口的使用

警告

飛機固件版本v2.5.1.4 和 wifi模塊版本v1.0.0.33 以下的用戶，請升級後再使用動作類接口，否則會導致執行飛行動作異常，查詢方式請參考單機接口文檔

示例一：控制飛機起飛並前後飛行¶

在本例程中，首先需要控制兩組共兩架飛機起飛，之後控制飛機起飛並向前向後各飛行100cm

首先按照控制無人機執行命令章節的介紹完成無人機對象的各項操作,隨後編寫如下程序:

利用釋放無人機資源章節的介紹釋放相關資源

警告

不同於單機，多機執行飛行動作時，wait_for_completed()接口為必寫項，如忘記書寫則可能導致當前動作的下一動作無法運行，在等待一段時間後會執行當前動作之後的第二個動作

示例二：控制飛機移動到目標坐標點¶

在本例程中，首先需要控制兩架飛機起飛，之後控制飛機起飛並以大地毯中點為圓心，以50cm為邊長，在100cm高度上以100cm/s的速度按正方形軌跡運動

首先按照控制無人機執行命令章節的介紹完成無人機對象的各項操作
對 base_action_1 進行編寫如下:

值得注意的是，多機編隊的go指令強制用戶使用地毯坐標進行運動，為了編程安全不支持飛機自身坐標系移動，字典中的飛機數必須等於當前group中的飛機數，不支持默認設置。

利用釋放無人機資源章節的介紹釋放相關資源

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

RoboMaster SDK 多機編隊EP¶

這裡以window 64位為例，介紹robomaster SDK的EP編隊教程：

Demo的環境要求及物料清單¶

編程環境

（1）下載RoboMaster-SDK壓縮包，Github下載鏈接：RoboMaster-SDK壓縮包 (備用Gitee下載鏈接：RoboMaster-SDK壓縮包)，下載步驟：

點擊 Code ,點擊 Download ZIP 下載壓縮包。

解壓下載完的RoboMaster-SDK-master.zip壓縮包：

壓縮文件包含：

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 ，並完成安裝：

警告

不安裝VC庫，使用SDK，會引起以下問題:

（3）安裝VS Build Tool：

運行RoboMaster-SDK壓縮包中的 visualcppbuildtools_full.exe ，並完成安裝：

（4）python環境安裝：

從 python 官網上找到可以下載的安裝包，以Python3.7.8 為例，選擇安裝文件進行下載。

警告

請確保下載的 python.exe 是64位的，python sdk適配3.6.6以上python版本，否則會影響python sdk的使用，如果電腦上已經安裝了python環境，建議卸載重新安裝。

步驟（1）：確認安裝包版本是 64-bit, 否則會影響Python sdk使用。

步驟（2）：勾選 Add Python 3.7 to Path。

步驟（3）：選擇 Install Now 進行安裝，如下圖所示。

安裝完成後按 win+r，在彈出窗口中輸入 cmd 打開命令提示符界面，在命令行裡面輸入 python, 確認 Python 3.7.8 安裝成功。

（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

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 目錄下的例程

警告

示例代碼13行中的：

info = helper.build_qrcode_string(ssid=」RoboMaster_SDK_WIFI」, password=」12341234」)

ssid （路由器名稱）和 password (路由器密碼)，需要根據實際的路由器信息進行填寫

運行示例代碼，會出現二維碼圖片，按下機器人智能中控上的掃碼連接按鍵，掃瞄二維碼進行組網連接。
運行結果:
```
Connected!
```

同時機器人的燈效變為白色呼吸變為青綠色常亮。

備註

一共6台EP小車需要連接WiFi，首次逐個連接6台EP小車時，連接每台小車都要重複運行示例代碼，連接完成後，下次重啟小車時會自動連接。

運行多機編隊示例代碼¶

參考下載的RoboMaster-SDK壓縮包目錄下的示例代碼 /examples/15_muti_robot/multi_ep/03_six_ep_demo.py 目錄下的例程

待每台機器人連接同一個路由器成功後，需手動修改示例代碼中的機器人SN編號，每台機器人的SN編號位於智能中控的標籤中，如下圖所示：

2.編輯示例代碼，找到示例代碼的203行：

根據機器人的SN依次修改示例代碼裡的SN。

根據6個SN的順序，依次按照下圖擺放6台機器人，箭頭方向為機器人朝向。

運行修改後的示例程序¶

打開 /examples/15_muti_robot/multi_ep/ 目錄，按住鍵盤shift，然後再目錄任意空白處單擊鼠標右鍵，單擊選擇「在此處打開Powershell窗口」，或「在此處打開命令窗口」
運行代碼,命令窗口輸入:
```
python 03_six_ep_demo.py
```

機械臂與機械爪¶

介紹¶

機械臂支持 FPV 精準遙控，機械爪配合機械臂使用，支持夾力控制，用戶可在 App 中通過第一人稱視角操控機械臂和機械爪完成任務。

使用說明¶

用戶可以控制機械臂的移動範圍、機械爪的開合距離。其中，機械臂的水平移動範圍為 0-0.22 米，垂直移動範圍為 0-0.15 米；機械爪的開合距離約為 10 厘米。

警告

1.當機械臂或機械爪處於工作狀態時，請盡量避免對其施加外力。

2.請勿碰撞或損傷機械臂或機械爪，避免導致性能下降或舵機運行異常。

3.避免因用身體部位接觸機械臂或機械爪旋轉或尖銳部分而導致受傷。

4.及時清理水滴、水晶彈殘渣等異物，避免腐蝕結構表面。

機械爪PWM 接口說明:¶

機械爪支持力矩控制模式

序號	引腳
1	485A/PWM
2	485B
3	VCC-12V
4	GND

PWM 信號為50Hz，占空比為2.5%~12.5%。

2.5%~7.5% 占空比對應閉合力度[ 最大，0];
7.5%~12.5% 占空比對應開合力度[0，最大]。

Python API¶

請參考機械臂和機械爪

舵機¶

介紹¶

舵機的油門控制方式除了支持 485 控制，還可以進行 PWM 控制，控制模式包含：速度模式和角度模式。

備註

舵機的控制模式

舵機的控制模式需要通過官方的編程接口（ Scratch / Python ）進行切換，並且會記錄在舵機內部，不會隨著舵機掉電而重置。使用 PWM 控制前請確認舵機當前的控制模式。

引腳說明¶

舵機上的 485 管腳和 PWM 管腳復用，如下圖所示

序號	引腳
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,順時針
速度模式	50hz	7.5%~12.5%	0rpm~—49rpm,逆時針

Python API¶

請參考舵機

紅外深度傳感器¶

介紹¶

紅外深度傳感器的設計是基於飛行時間 TOF (Time of Flight) 原理，即傳感器發出經調製的近紅外光，遇物體後反射，傳感器通過計算光線發射和反射時間差或相位差，來計算距離物體的距離。

產品特性¶

紅外深度傳感器的探測面積見下圖：

其發出的是一個角度為 20° 的圓錐光，這個光斑 D 與距離 Dist 的關係：

D=2×Dist×tan⁡(10)

要實現最佳測試效果，應保證目標物的尺寸要至少等於 TOF 光斑的尺寸。

小訣竅

如果目標物小於光斑大小，那麼應保證目標物盡量在光斑的中心位置，因為光斑內的光強分佈並不是均勻的，而是呈一個類高斯分佈，中間光強大，四周光強小，為了保證返回光能量足夠，應盡量保證目標物在光斑中心。

引腳說明¶

這裡介紹紅外深度傳感器的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 編程環境中獲取傳感器數據信息，每個模塊均有兩個傳感器接口，兩個接口功能相同。

引腳說明¶

端口	引腳	功能
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 接口設置在運動控制器上，引腳說明如下：

串口配置¶

通訊接口	波特率	數據位	停止位	奇偶校驗
UART	115200	8	1	none

第三方平台連接方式¶

請參考 UART 連接

Python 編程示例¶

PC 通過串口轉 USB 連接到 EP 運動控制器的 UART 接口上。
PC 端開啟串口調試助手，選擇打開串口對應 COM 口。
打開已跟 EP 建立連接設備的官方 App，進入 Python 編程模式。
在 Python 編程界面下，寫一個簡單的程序，使用 read_string() 讀取串口數據，打印出來後再通過 write_string() 進行轉發，並點擊「開始」按鈕運行程序。
在串口調試助手上發送一個字符串，看是否能正確收到發出去的字符串。並查看 App 上是否正確打印了收到的字符串。

串口調試助手發送並回顯字符串

App 打印收到的字符串並進行轉發

明文 SDK 示例¶

PC 通過串口轉 USB 連接到 EP 運動控制器的 UART 接口上。
PC 端開啟串口調試助手，選擇打開串口對應 COM 口。
在串口調試助手上發送字符串 command;，若能收到 EP 發回來的 ok 表示明文 SDK 解析成功。

串口調試助手發送 SDK 字符串收到回應

警示

在通過 UART 發送明文 SDK 指令時，一定要記得在命令後面加 ; 分號，否則會解析失敗。

Python API¶

請參考 UART

明文 SDK 介紹¶

RoboMaster EP 最重要的一個功能是支持明文 SDK，包含各個內置模塊和拓展模塊的控制接口，以及視頻流、音頻流的輸出接口。 EP 支持 USB、 WIFI、 UART 等多種接入方式，用戶可根據平台接口選擇任意方式接入。

明文 SDK 極大的豐富了 EP 的擴展性，使其能夠方便地與第三方平台通信，提供了二次開發的可能性。下面將使用 Wi-Fi 直接連接 方式（其他連接模式請參考建立連接），以完成 控制發射器發射 功能為例，介紹SDK中明文協議的使用。

開發前的準備¶

準備一台 PC 電腦，需具備 Wi-Fi 功能
PC 上搭建 Python 3.x 環境，安裝方式請參考 Python Getting Started

建立連接¶

開啟電源

開啟機器人電源，切換智能中控的連接模式開關至 直連模式，如下圖所示：
建立Wi-Fi連接

打開電腦的無線網絡訪問列表，選擇位於機身貼紙上對應的 Wi-Fi 名稱，輸入 8 位密碼，選擇連接
準備連接腳本

在完成 Wi-Fi 後，我們還需要編程與機器人建立 TPC/IP 連接，並在對應的端口上傳輸特定的 明文協議，就可以實現相應的控制，更多 明文協議 請參考協議內容。

這裡我們以 Python 編程語言為例，編寫腳本來完成 建立控制連接，接收用戶指令，傳輸明文協議 的過程，達到控制機器人的目的。

參考代碼如下

# -*- 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()

將上述代碼保存為 rm_sdk.py
運行腳本

運行 rm_sdk.py 文件 (Windows系統在安裝完成Python環境後可直接雙擊 *.py 文件運行，若無法運行，請按鍵 win+r 並輸入 cmd，按回車後打開命令運行, 鍵入 python rm_sdk.py 運行；Linux系統請按鍵 ctrl+alt+t 打開命令行鍵入 python rm_sdk.py)
建立 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	當機器人未與任何設備建立連接時，會有數據輸出

UART 連接方式請參考以下 UART 參數配置

波特率	數據位	停止位	校驗位
115200	8	1	None

警告

UART 連接方式下的數據說明：

UART 連接方式下，僅提供 控制命令/消息推送/事件上報 數據，如需 視頻流/音頻流 數據，請使用 Wi-Fi/USB 連接模式

連接示例¶

下面我們將以 Python 編程語言為基礎，介紹多種連接方式的使用範例。以下所有示例中，默認 PC 上需要集成 Python 3.x 環境（安裝方式請參考 Python Getting Started），後面不再贅述。

WIFI 直連模式¶

環境準備

準備一台 PC 電腦，需具備 Wi-Fi 功能。

建立連接

開啟電源

開啟機器人電源，切換智能中控的連接模式開關至 直連模式，如下圖所示：
建立 Wi-Fi 連接

打開電腦的無線網絡訪問列表，選擇位於機身貼紙上對應的 Wi-Fi 名稱，輸入 8 位密碼，選擇連接

準備連接腳本

建立 Wi-Fi 連接後，我們還需要編程與機器人建立 TPC/IP 連接機器人開放多個連接端口可供連接，我們首先應完成 控制命令端口 的連接（直連模式下機器人 IP 地址為 192.168.2.1, 控制命令端口號: 40923），以使能機器人 SDK 模式。

這裡我們以 Python 編程語言為例，編寫腳本來完成 建立控制連接，使能 SDK 模式 功能

參考代碼如下

# -*- 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()

將上述代碼保存為 rm_direct_connection_sdk.py
運行腳本

Windows 系統 在安裝完成 Python 環境後可直接雙擊*.py 文件運行，若無法運行，請按 win+r 並輸入 cmd，按回車後打開命令運行, 鍵入 python rm_direct_connection_sdk.py 運行；

Linux 系統 請按 ctrl+alt+t 打開命令行鍵入 python rm_direct_connection_sdk.py 運行
建立 TCP/IP 控制連接

當運行窗口輸出 Connecting... 時，代表正在嘗試與機器人建立連接，當運行窗口輸出 Connected!; 時，表示已經成功建立控制連接。

驗證

在成功建立控制連接後，在命令行裡輸入 command, 機器人返回 ok;，則表示已經完成連接，並且機器人進入 SDK 模式成功，之後您就可以輸入任意控制指令控制機器人了。

其他

UART物理鏈路連接示例請參考：UART

WIFI 路由器模式¶

環境準備

準備一台 PC 電腦，具備網絡功能（Wi-Fi 或者有線網絡皆可）
準備一台家用路由器

建立連接

開啟電源

開啟機器人電源，切換智能中控的連接模式開關至 組網模式
建立組網連接

Wi-Fi：

若使用 Wi-Fi 連接，請將 PC 電腦通過 Wi-Fi 連接至路由器上

有線網絡：

若使用有線網絡連接，請將 PC 電腦通過網線連接至路由器的 LAN 口

確保 PC 已經接入路由器後，打開 RoboMaster App，進入組網連接頁面，按下機器人智能中控上的掃碼連接按鍵，掃瞄二維碼進行組網連接，直到連接成功。

獲取機器人在局域網內的 IP 地址

在完成組網連接後，我們的 PC 機已經和機器人處於同一個局域網內，接下來需要編程與機器人建立 TPC/IP 連接，並連接到 控制命令端口 端口，以使能機器人 SDK 模式。

若您使用的路由器開啟了 DHCP 服務，則機器人的 IP 地址為路由器動態分配，我們需要進一步獲取機器人在局域網內的 IP 地址。這裡提供兩種辦法獲取：
若您通過 RoboMaster App 進行的組網連接，則進入 RoboMaster App的 設置->連接 頁面，機器人在局域網內的 IP 地址會在此處顯示。

若您通過其他方式進行的組網連接，則需要通過 監聽機器人地址廣播 來獲取機器人在局域網內的 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

準備連接腳本

我們已經獲取到機器人的 IP 地址，這裡我們仍以 Python 編程語言為例，編寫腳本來完成 建立控制連接，使能 SDK 模式 功能

參考代碼如下

# -*- 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()

將上述代碼保存為 rm_networking_connection_sdk.py
運行腳本

Windows 系統：在安裝完成 Python 環境後可直接雙擊*.py 文件運行，若無法運行，請按 win+r 並輸入 cmd，按回車後打開命令運行, 鍵入 python rm_networking_connection_sdk.py 運行；

Linux 系統 請按：ctrl+alt+t 打開命令行鍵入 python rm_networking_connection_sdk.py 運行
建立 TCP/IP 控制連接

當運行窗口輸出 Connecting... 時，代表正在嘗試與機器人建立連接，當運行窗口輸出 Connected!; 時，表示已經成功建立控制連接。

驗證

在成功建立控制連接後，在命令行裡輸入 command, 機器人返回 ok;，則表示已經完成連接，並且機器人進入 SDK 模式成功，之後你就可以輸入任意控制指令進行機器人控制了。

USB 連接¶

USB 連接模式，實質上是使用 RNDIS 協議，將機器人上的 USB 設備虛擬為一張網卡設備，通過 USB 發起 TCP/IP 連接。更多 RNDIS 內容請參見 RNDIS Wikipedia。

環境準備

準備一台具備 RNDIS 功能的 PC 電腦（請確認 PC 電腦上已經配置好 RNDIS 功能）
準備一根 Micro-USB 數據線

建立連接

開啟電源

開啟機器人電源，無需關心連接模式開關位置
建立 USB 連接

將 USB 數據線接入到機器人智能中控上的 USB 口，另一端與電腦相連

測試連接

打開命令行窗口，運行:

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

準備連接

連接過程與 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 連接¶

環境準備

一台 PC 電腦，並確定已安裝 USB 轉串口模塊驅動
USB 轉串口模塊
三根杜邦線

建立連接

開啟電源

開啟機器人電源，無需關心連接模式開關位置
連接 UART

將杜邦線插在機器人底盤主控上的 UART 接口上，分別插在 GND, RX, TX 引腳上，另一端對應插在 USB 轉串口模塊的 GND, TX, RX 引腳

配置 UART，建立通信連接

這裡，我們仍以 Python 編程為例，進行 Windows 系統下 UART 相關配置。

確認 PC 已識別 USB 轉串口模塊，並在 電腦設備管理器 中的端口裡確認對應的串口號，如 COM3。
安裝 serial 模塊:
```
pip install pyserial
```
編寫代碼進行 UART 控制，參考代碼如下：

# -*- 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()

將上述程序保存為 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>

描述

設置機器人運動模式

參數

mode (mode_enum): 機器人運動模式

示例

robot mode chassis_lead; : 將機器人的運動模式設置為「雲台跟隨底盤模式」

備註

機器人運動模式

機器人運動模式描述了雲台與底盤之前相互作用與相互運動的關係，每種機器人模式都對應了特定的作用關係。

機器人運動模式分為三種模式：

雲台跟隨底盤模式：該模式下，雲台的 YAW 軸會進入持續跟隨底盤 YAW 軸的運動的狀態，雲台將不響應所有控制指令中 YAW 軸控制的部分，影響指令有雲台運動速度控制雲台相對位置控制雲台絕對位置控制
底盤跟隨雲台模式：該模式下，底盤的 YAW 軸會進入持續跟隨雲台 YAW 軸的運動的狀態，底盤將不響應所有控制指令中 YAW 軸控制的部分，影響指令有底盤運動速度控制底盤輪子速度控制底盤相對位置控制
自由模式：該模式下，雲台的 YAW 軸與底盤的 YAW 軸運動互不影響

機器人運動模式獲取¶

IN: robot mode ?

描述

查詢當前機器人運動模式

返回值

mode (mode_enum): 機器人運動模式

示例

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>

描述

控制裝甲板檢測事件上報

事件上報數據格式參見裝甲板事件上報數據

參數

attr (armor_event_attr_enum) : 事件屬性名稱

switch (switch_enum) : 事件屬性控制開關

示例

armor event hit on; ：打開裝甲板檢測事件推送

裝甲板事件上報數據¶

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>

描述

聲音識別時間上報控制，開啟之後會有相關的事件上報

事件上報數據格式詳參見聲音識別事件上報數據

參數

attr (sound_event_attr_enum) : 事件屬性名稱

switch (switch_enum) : 事件屬性控制開關

示例

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>

描述

打開/關閉所有紅外傳感器開關

參數

switch (switch_enum)：紅外傳感器的開關

示例

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>

描述

相機曝光值設置

參數

ev_level (camera_ev_enum): 相機曝光值檔位枚舉

示例

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 路由器模式。

運行示例程序¶

將IP地址依次填入參考代碼中的 IP_LIST 列表中，並將腳本代碼保存為 ep.py。

#!/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()

運行腳本

Windows系統：完成Python環境後可直接點擊 ep.py 啟動腳本。
Linux系統：在命令終端輸入 python ep.py 啟動腳本。

運行效果

編隊控制的多台機器人云台步調一致的在 YAW 軸方向往復運動。

運行結果

命令行端口輸出多台機器人與主機之間的明文通訊數據。

168.1.103 connecting...
168.1.103:command seq 1
168.1.103:ok seq 1
168.1.103:robot mode free seq 2
168.1.103:ok seq 2
168.1.117 connecting...
168.1.117:command seq 1
168.1.117:ok seq 1
168.1.117:robot mode free seq 2
168.1.117:ok seq 2
168.1.103:gimbal moveto p 0 y 0 vp 90 vy 90 wait_for_complete false seq 3
168.1.103:ok seq 3
168.1.117:gimbal moveto p 0 y 0 vp 90 vy 90 wait_for_complete false seq 3
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 編程。

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)`
傳回:	無
示例:

#定義一個函數，並將其註冊為接收消息的回調函數

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:

# 當 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:

# 當 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:

# 當點擊 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:

# 當點擊 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 界面的控件對像
傳回:	無
示例:

#創建一個 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 號

Dropdown¶

Dropdown 控件通常用於在某個對象的多個屬性選項中，選中某個特定值

dropdown_object.set_options(*options)¶

描述:	設置下拉框中的內容，輸入為字符串列表，列表中元素個數為下拉框選項個數
參數:	args (string*) – 下拉框中的選項內容
傳回:	無
示例:	`my_Dropdown.set_options('RoboMaser EP', 'People')`
示例說明:	下拉框中有兩個選項，分別為 `RoboMaster EP` 與 `People`

dropdown_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_DropDown.set_background_color(200, 200, 200, 230)`
示例說明:	設置下拉框中選中的條目的背景色的 rgb 值為(200, 200, 200) ，透明度為 230

dropdown_object.set_arrow_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_Dropdown.set_arrow_color(120, 120, 120, 200)`
示例說明:	設置下拉框選中箭頭顏色的 rgb 值為（120, 120, 120），透明度為 200

dropdown_object.set_item_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_DropDown.set_item_background_color(200, 200, 200, 230)`
示例說明:	設置下拉框中未被選擇的條目的背景色的 rgb 值為(200, 200, 200) ，透明度為 230

dropdown_object.set_item_checkmark_color(r, g, b, a)¶

描述:	設置下拉框中選中圖標的顏色
參數:	r (int) – checkmark顏色的 r 值，範圍為[0, 255] g (int) – checkmark顏色的 g 值，範圍為[0, 255] b (int) – checkmark顏色的 b 值，範圍為[0, 255] a (int) – checkmark 顏色的透明度，範圍為[0, 255]
傳回:	無
示例:	`my_DropDown.set_item_checkmark_color(200, 200, 200, 230)`
示例說明:	設置下拉框中 checkmark 顏色的 rgb 值為(200, 200, 200) ，透明度為 230

提示

功能說明請參考用戶自定義 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 – 函數內部的消息參數
傳回:	無
示例:

#當檢測到機器人受到紅外光束攻擊時，運行函數內程序

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 號紅外深度傳感器前方障礙物距離小於 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 號紅外深度傳感器前方障礙物距離小於 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 號端口引腳跳變為高電平時，運行函數內程序

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 號端口引腳正在跳變時，執行下一條指令

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.多機接口優化

歡迎來到 RoboMaster 開發者頁面¶

開篇介紹¶

EP套裝介紹¶

EP機器人形態¶

網站內容¶

聯繫我們¶

編程環境安裝¶

介紹¶

在 Windows 上安裝 Python¶

在 Ubuntu 上安裝 Python¶

第三方平台通信¶

介紹¶

第三方平台類型¶

通信方式¶

WIFI 連接¶

直連模式¶

路由器模式¶

USB 連接¶

UART 連接¶

RoboMaster SDK 安裝¶

安裝 SDK 到 Windows平台¶

開發環境準備¶

安裝必要的VC庫環境¶

安裝robomaster python sdk¶

升級 RoboMaster SDK¶

安裝 SDK 到 Linux平台¶

安裝 SDK 到 macOS X平台¶

RoboMaster SDK 下載源碼¶

RoboMaster SDK 和機器人建立連接¶

EP連接方式¶

教育無人機系列連接方式¶

通訊方式¶

EP通訊方式¶

教育無人機 通訊方式¶

RoboMaster SDK 新手入門 - 基礎篇¶

SDK 能做什麼?¶

第一個SDK程序¶

RoboMaster SDK 新手入門 - EP 篇¶

初始化機器人¶

獲取模塊對像¶

釋放機器人資源¶

查詢類接口的使用¶

示例一：查詢機器人版本¶

示例二：獲取機器人SN號¶

設置類接口的使用¶

示例一：設置機器人整機運動模式¶

示例二：設置機器人裝甲燈¶

動作類接口的使用¶

即時動作控制¶

示例一：控制發射器射擊¶

示例二：控制底盤速度¶

任務動作控制¶

示例一：控制底盤移動指定距離¶

多媒體接口的使用¶

示例一：獲取視頻流¶

示例二：獲取音頻流¶

RoboMaster SDK 新手入門 - 教育系列無人機篇¶

初始化機器人¶

獲取模塊對像¶

釋放機器人資源¶

查詢類接口的使用¶

示例一：查詢機器人固件SDK版本¶

示例二：獲取機器人SN號¶

設置類接口的使用¶

示例一：設置機器人擴展led模塊¶

動作類接口的使用¶

任務動作控制¶

示例一：控制飛機起飛並前後飛行¶

即時動作控制¶

示例一：控制遙控器桿量¶

多媒體接口的使用¶

示例一：獲取視頻流¶

RoboMaster SDK 新手入門 - 多機控制篇¶

多機控制簡介¶

多機控制流程¶

多機初始化¶

多機編號¶

多機分組 & 群組控制¶

生成 組對像¶

組對像 的相關操作¶

教育無人機通訊方式¶

生成組對像¶

組對像的相關操作¶