PROTOCOL

LUYU Link 通訊規章

所有 LUYU 機器人共用的 serial 通訊規格。照這份規章寫韌體,接上電腦就能用同一個控制台操作。

v0.1DRAFTUPDATED 2026-11-21原始檔:docs/protocol/luyu-link.md開控制台

版本 0.1(草案)

0.x 階段還在試用,小版本之間可能不相容。到 1.0 之後才保證「小版本只加東西、不改舊東西」。

1. 目標

  1. 一個控制台控制所有機器人。 機器人先說自己有哪些馬達、伺服機、感測器,控制台照著自動長出按鈕、滑桿和儀表。做新機器人時不用改控制台。
  2. 韌體好寫。 Arduino Uno(2 KB RAM)也做得到:純文字、一行一則訊息、不需要 JSON 函式庫。
  3. 人看得懂。 用 Arduino IDE 的序列埠監控視窗就能手動打指令除錯。
  4. 安全優先。 一開機是鎖定狀態,要解鎖才會動;斷線會自動停車;緊急停止任何時候都有效。

2. 名詞

名詞 意思
主機(host) 電腦上的控制台,或任何下指令的程式
機器人(robot) 跑韌體的控制板
指令 主機傳給機器人的一行
回應 機器人對某一個指令的答覆,以 !OK 或 !ERR 結尾
能力(capability) 機器人身上一個可以控制或讀取的東西,例如一顆馬達
解鎖(armed) 允許馬達和伺服機動作的狀態

3. 傳輸層

方式 設定
USB 序列埠 115200 bps,8N1。瀏覽器用 Web Serial 連線
藍牙 BLE Nordic UART Service:服務 6E400001-B5A3-F393-E0A9-E50E24DCCA9E,主機寫入 …0002,機器人通知 …0003。瀏覽器用 Web Bluetooth 連線
  • 文字編碼 UTF-8。名稱可以用中文,但指令、關鍵字和 ID 只用 ASCII。
  • 每一行以 \n 結尾。收到的 \r 一律忽略,所以 \r\n 也可以。空白行直接忽略,不回應。
  • 一行最長 128 bytes(含 \n)。中文一個字佔 3 bytes。超過的行,接收端整行丟棄並回 !ERR E02。
  • BLE 一個封包可能只有 20 bytes,一行會被拆成好幾包。接收端要累積到 \n 才處理。

4. 一行的格式

一行由空白分隔的欄位組成,連續空白視為一個。

欄位 寫法 例子
字 不含空白和 = SET、m1、-35、0.5
鍵值 key=value,value 是一個字或一段引號文字 max=100、label="左輪"
引號文字 "…",裡面可以有空白;\" 代表引號、\\ 代表反斜線 "low battery"
  • 數字:十進位,可以有正負號和小數點,不用科學記號。例如 50、-12、0.25。
  • ID:小寫英文開頭,後面接小寫英文、數字或底線,最多 16 字。例如 m1、arm_base、dist。
  • 布林值:0 或 1。

4.1 機器人傳出的行,第一個字元是類型

開頭 類型 例子
! 回應 !OK、!ERR E03 "no such id: m9"、!INFO …、!CAP …
= 數值回報 =dist 132
~ 事件 ~state armed、~boot
# 除錯訊息,控制台只顯示在紀錄裡 # pid kp=1.2
其他 當作除錯訊息 韌體裡沒改到的 Serial.println("hi") 不會讓控制台出錯

主機傳出的指令沒有前綴,第一個字就是指令名稱,一律大寫。機器人比對時建議不分大小寫,方便人工輸入。

5. 回應規則

  1. 每個指令剛好得到一個結尾回應:!OK 或 !ERR。
  2. 機器人依照收到的順序處理和回應。主機只要把送出的指令排成佇列,收到結尾回應就對應到佇列最前面的那個,不需要訊息編號。
  3. 有些指令會先回幾行資料再結尾,例如 CAPS 先回好幾行 !CAP,最後才 !OK。
  4. = 數值和 ~ 事件可以出現在任何兩行之間,主機依開頭字元分辨,不會跟回應搞混。
  5. 主機等結尾回應最多 500 ms,超過就當作逾時。
  6. 機器人的主迴圈不可以卡住超過 20 ms(不要用長的 delay()),才能及時處理 STOP 和看門狗。

錯誤回應:!ERR <錯誤碼> ["說明"],說明可以省略。

6. 連線流程

主機打開序列埠
  (Arduino Uno 會因此重開機,最多等 2 秒,或等到收到 ~boot)
主機 → HELLO 0.1
機器人 ← !INFO proto=0.1 name="越野偵察車" model=R-01 fw=1.0.0 id=a1b2c3 watchdog=1000
機器人 ← !OK
主機 → CAPS
機器人 ← !CAP drive base max=100 label="底盤"
機器人 ← !CAP servo arm min=0 max=180 unit=deg label="手臂"
機器人 ← !CAP sensor dist min=0 max=400 unit=cm label="前方距離"
機器人 ← !CAP sensor battery min=6000 max=8400 unit=mV low=6800 label="電池"
機器人 ← !OK
主機 → STREAM 100
機器人 ← !OK
機器人 ← =dist 132
機器人 ← =battery 7840
            …每 100 ms 一輪
  • HELLO 沒有回應時,每 700 ms 重送一次,最多 3 次。
  • 機器人開機完成時送 ~boot,主機可以用它判斷重開機完成,也能察覺機器人中途重開。

6.1 !INFO 的欄位

鍵 必填 意思
proto ✓ 機器人實作的規章版本,例如 0.1
name ✓ 顯示名稱,可以用中文
fw ✓ 韌體版本
model 作品編號,對應總站作品頁的 code,例如 R-01
id 這一台的唯一編號,同型號有好幾台時用來分辨
watchdog 看門狗時間(ms),預設 1000

7. 能力清單

CAPS 會回一行或多行:

!CAP <種類> <id> [key=value …]

7.1 種類

種類 是什麼 控制台畫成 用哪個指令 需要解鎖
motor 單顆馬達,正負代表方向 滑桿,放開回 0 SET ✓
servo 伺服機角度 滑桿 SET ✓
out 開關或 PWM 輸出:LED、蜂鳴器 開關(max=1)或滑桿 SET ✓
drive 整個底盤:油門+轉向 搖桿,鍵盤 WASD DRIVE ✓
action 一鍵動作,例如「夾起來」「跳舞」 按鈕 DO ✓
sensor 唯讀數值 數字+長條+小折線圖 GET、STREAM
param 可以調整的參數,例如 PID 係數 數字輸入框 SET、GET

一台機器人最多一個 drive。主機遇到不認得的種類或鍵要直接忽略,這樣新版韌體接上舊版控制台也不會壞。

7.2 共用的鍵

鍵 意思 預設
label 顯示名稱 用 id
min、max 範圍 motor、drive 是 -100~100;servo 是 0~180
step 調整的最小單位 1
unit 單位:%、deg、cm、mm、mV、lx… 無
group 控制台裡的分組名稱 無
value 目前的值,讓控制台一開始就顯示正確位置 無

sensor 另外可以加 low=、high=,超出時控制台會標示警告。

7.3 保留的 ID

ID 種類 約定
base drive 底盤
battery sensor 電池電壓,單位 mV。有的話控制台右上角會一直顯示電量,低於 low 會警告

8. 指令

8.1 每台機器人都必須支援

指令 機器人做什麼 回應
HELLO <版本> 自我介紹 !INFO …,然後 !OK
CAPS 列出能力 一行或多行 !CAP …,然後 !OK
PING 心跳,什麼都不做 !OK
ARM 解鎖,允許動作 !OK,並送出 ~state armed
STOP 緊急停止:所有馬達、底盤立刻歸零,然後鎖定 !OK,並送出 ~state disarmed reason=stop
GET <id> 讀一個 sensor 或 param =<id> <值>,然後 !OK

8.2 有對應能力才需要支援

指令 適用 機器人做什麼
SET <id> <值> motor、servo、out、param 設定輸出或參數
DRIVE <油門> <轉向> drive 兩個值都在 -100~100。油門正值前進;轉向正值右轉
DO <id> action 開始執行動作。動作要分段做完,不能卡住主迴圈
STREAM <ms> sensor 每隔 ms 毫秒送一輪所有 sensor 的 = 數值。0 停止。最小 20 ms

9. 安全:解鎖、緊急停止、看門狗

機器人只有兩個狀態:

          ARM
鎖定 ──────────────▶ 解鎖
 ▲                   │
 └───────────────────┘
  STOP/看門狗逾時/故障
  1. 開機是鎖定狀態。 鎖定時只有 sensor、param 可以讀寫,其他會被拒絕(!ERR E06)。
  2. STOP 在任何狀態都有效,而且必須立刻把輸出歸零,不能排在其他動作後面。
  3. 看門狗:解鎖狀態下,超過 watchdog 毫秒沒有收到任何一行,機器人要自己停車並鎖定,然後送出 ~state disarmed reason=watchdog。主機在解鎖期間要每 watchdog ÷ 3 毫秒送一次 PING。
  4. 狀態改變時,機器人一定要送出 ~state armed 或 ~state disarmed reason=<原因>。原因有 boot、stop、watchdog、fault。
  5. 伺服機在停止時保持目前角度,不要突然回到預設值,以免夾子鬆開或手臂掉下來。
  6. 主機這邊:解鎖期間超過 watchdog 毫秒沒收到機器人任何一行,就當作機器人已經被看門狗鎖定(那行 ~state 可能在斷線時遺失了)。要重新 ARM 才能再控制。

10. 錯誤碼

碼 意思 例子
E01 不認得的指令 JUMP
E02 格式錯誤:參數數量不對、不是數字、行太長 SET m1
E03 沒有這個 id SET m9 50
E04 超出範圍。不要自動夾到範圍內,要拒絕,主機才知道哪裡寫錯 SET arm 200
E05 忙碌中,例如動作還沒做完 連按兩次 DO dance
E06 還沒解鎖 鎖定時 DRIVE 50 0
E07 硬體問題,例如電池太低不讓解鎖 ARM
E08 這個 id 的種類不能用這個指令 SET dist 3
E09 其他內部錯誤

檢查順序固定,同一行有好幾個問題時,回第一個遇到的:

E01 指令 → E02 格式 → E03 id → E08 種類 → E04 範圍 → E06 解鎖 → E05 忙碌

例如鎖定狀態下送 SET arm 200,回 E04 而不是 E06。

11. 版本規則

  • 版本號是 主.次,例如 0.1、1.2。
  • 主機用 HELLO 告訴機器人自己支援的版本,機器人在 !INFO proto= 回報自己實作的版本。
  • 主版本不同:控制台顯示警告,只讀數值,不送控制指令。
  • 次版本不同(1.0 以後):照常使用。新功能只會用「加一個指令」「加一種能力」「加一個鍵」的方式加入,舊的不會改,所以忽略不認得的東西就能相容。
  • 0.x 是草案期,次版本之間可能不相容,控制台遇到不同的 0.x 也會警告。

12. 完整範例

< ~boot
> HELLO 0.1
< !INFO proto=0.1 name="越野偵察車" model=R-01 fw=1.0.0 watchdog=1000
< !OK
> CAPS
< !CAP drive base label="底盤"
< !CAP servo arm min=0 max=180 unit=deg value=90 label="手臂"
< !CAP out led max=1 label="頭燈"
< !CAP sensor dist min=0 max=400 unit=cm label="前方距離"
< !OK
> DRIVE 50 0
< !ERR E06 "not armed"
> ARM
< ~state armed
< !OK
> DRIVE 50 0
< !OK
> SET arm 200
< !ERR E04 "arm range 0..180"
> GET dist
< =dist 132
< !OK
> STOP
< ~state disarmed reason=stop
< !OK

> 是主機送出,< 是機器人回覆。~ 事件可以出現在 !OK 前面或後面,兩種都合法。

13. 韌體檢查清單

寫完韌體,逐項確認:

  • 115200 bps;開機完成送 ~boot
  • HELLO、CAPS、PING、ARM、STOP、GET 都有回應,而且都以 !OK 或 !ERR 結尾
  • 開機是鎖定狀態;鎖定時 DRIVE、馬達的 SET 會回 E06
  • STOP 讓所有馬達立刻停止,伺服機保持角度
  • 解鎖後 1 秒不送任何東西,機器人會自己停下來並送 ~state disarmed reason=watchdog
  • 超出範圍回 E04,不會偷偷夾值
  • 主迴圈沒有超過 20 ms 的 delay()
  • 範例韌體(docs/protocol/examples/)可以跑過 docs/protocol/conformance.txt 這份標準對話(npm run link:check)

13.1 一致性測試

docs/protocol/conformance.txt 是一份「標準對話」:主機送什麼、機器人該回什麼。三個參考實作都用同一份對話檢查:

實作 位置
JavaScript 模擬機器人(控制台開發用) packages/link/src/fake-robot.ts
MicroPython(ESP32 等) docs/protocol/examples/micropython/luyu_link.py
Arduino(Uno、UNO R4) docs/protocol/examples/arduino/luyu_link_demo/

這份對話用的是一台固定配置的「標準測試機」(底盤、手臂、頭燈、距離、電池、Kp、揮手)。自己的機器人能力不同,就照這份對話改一份自己的版本。

14. 還沒決定的事

  • 高頻資料(例如 IMU 每秒 200 筆)要不要另外定義二進位模式。
  • 一台電腦同時連好幾台機器人時,控制台怎麼分頁。
  • param 要不要有「存到 EEPROM」的指令。
  • 透過 Wi‑Fi(WebSocket)連線,讓 UNO R4 WiFi 不用接線。
ESC

↑↓ 選擇 ↵ 開啟 / 或 ⌘K 隨時叫出