仙知網絡協議API使用指南

  在操作移動機器人時，用戶需要使用相關 API，

  有這方面需求的小伙伴，請認真看這篇文章哦！

一、API 簡介

  整套 API 采用 TCP request/response 問答的方式, 機器人作為服務器接受客戶端的請求并向客戶端作出響應。

  API 請求由頭部和數據區組成，頭部為普通定長的字節, 用于標識數據包基本信息以及數據區的長度及類型等，數據區為序列化后的 JSON 數據，根據頭部中的類型信息進行反序列化可以得到相應的 JSON 對象。

  API 的響應也由頭部和數據區組成，頭部為根據請求得到的定長字節(響應頭部與對應請求頭部的關系見下文), 數據區也為序列化后的 JSON 數據。

二、API 測試及例程

  我們將 API 測試工具開源在 Github,Source, 該工具使用 Qt 編寫, 其源碼可以作為例程參考。

  編譯后的單 Windows 可執行文件也可在Release中下載。

三、API 類別

  API 分為六類, 分別為機器人狀態 API、機器人控制 API、機器人導航 API、機器人配置 API、其他 API。

  1、機器人狀態 API

  用于查詢機器人各種狀態量, 如位置、速度、報警信息等。

  2、機器人控制 API

  用于向機器人發送開環控制指令, 如前進速度、轉向速度，重定位等。

  3、機器人導航 API

  用于向機器人發送導航指令, 如去路徑返航、自由導航等。

  4、機器人配置 API 

  用于設置機器人的參數, 以及下載、上傳地圖等。

  5、其他 API

  雜項, 如喇叭控制等。

  每個類別使用不用的端口, 相互獨立, 因此對不同的類別可以使用不同的傳輸協議。

四、API 簡介

  備注

  1. 每個端口 API 請求的時間間隔為 200ms，請勿過快。

  2. 機器人將對每個建立的 TCP 連接進行 KeepAlive 保活, 對已死的連接會及時的清除。

  3. 機器人若收到任何不符合本協議報文頭部的錯誤數據包, 將會主動關閉該 TCP 連接（不會回復任何信息）。

  4. 其他情況下, 機器人不會主動斷開連接, API 使用者應自己控制連接何時中斷。

  5. 對于僅允許建立一個連接的端口, 如果該端口已經有連接建立, 那么機器人將不響應其他任何建立連接的請求, 直到先建立的連接斷開。

  6. 對于每個連接, 機器人都是以一問一答的形式處理的, 即未作出響應前是不會處理下一個請求的, 因此建議使用時等收到上一次請求的響應后再發送下一個請求。

上海仙工智能科技有限公司（簡稱仙工智能或 SEER）由 RoboCup 世界冠軍團隊創立，是一家以智能控制及數字化為核心的工業物流解決方案提供商。公司總部位于上海，全國設有 7 個辦事處、2 個生產基地，業務遍及全球 20 多個國家和地區。

仙工智能掌握世界領先的技術與理念，打造智能、高效、可靠、易用的端到端工業物流解決方案，方案涵蓋移動機器人控制器、各類移動機器人及相關數字化系統軟件，幫助客戶降本增效，實現智能化與數字化升級。

以【惠人達己，守正出奇，始終創業，追求極致】的品牌價值觀為導向，憑借卓越的產品力、方案力與服務力，仙工智能為西門子、菲尼克斯、濰柴動力、格力等全球 800 多家企業提供服務。客戶覆蓋半導體、3C、鋰電、光伏、汽車零部件、PCB、紡織、醫療等行業，項目交付率達 100%。仙工智能，以實力引領工業物流智能化進程。