LUYU Link 通訊規章
所有 LUYU 機器人共用的 serial 通訊規格。照這份規章寫韌體,接上電腦就能用同一個控制台操作。
版本 0.1(草案)
0.x 階段還在試用,小版本之間可能不相容。到 1.0 之後才保證「小版本只加東西、不改舊東西」。
1. 目標
- 一個控制台控制所有機器人。 機器人先說自己有哪些馬達、伺服機、感測器,控制台照著自動長出按鈕、滑桿和儀表。做新機器人時不用改控制台。
- 韌體好寫。 Arduino Uno(2 KB RAM)也做得到:純文字、一行一則訊息、不需要 JSON 函式庫。
- 人看得懂。 用 Arduino IDE 的序列埠監控視窗就能手動打指令除錯。
- 安全優先。 一開機是鎖定狀態,要解鎖才會動;斷線會自動停車;緊急停止任何時候都有效。
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. 回應規則
- 每個指令剛好得到一個結尾回應:
!OK或!ERR。 - 機器人依照收到的順序處理和回應。主機只要把送出的指令排成佇列,收到結尾回應就對應到佇列最前面的那個,不需要訊息編號。
- 有些指令會先回幾行資料再結尾,例如
CAPS先回好幾行!CAP,最後才!OK。 =數值和~事件可以出現在任何兩行之間,主機依開頭字元分辨,不會跟回應搞混。- 主機等結尾回應最多 500 ms,超過就當作逾時。
- 機器人的主迴圈不可以卡住超過 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/看門狗逾時/故障
- 開機是鎖定狀態。 鎖定時只有
sensor、param可以讀寫,其他會被拒絕(!ERR E06)。 STOP在任何狀態都有效,而且必須立刻把輸出歸零,不能排在其他動作後面。- 看門狗:解鎖狀態下,超過
watchdog毫秒沒有收到任何一行,機器人要自己停車並鎖定,然後送出~state disarmed reason=watchdog。主機在解鎖期間要每watchdog ÷ 3毫秒送一次PING。 - 狀態改變時,機器人一定要送出
~state armed或~state disarmed reason=<原因>。原因有boot、stop、watchdog、fault。 - 伺服機在停止時保持目前角度,不要突然回到預設值,以免夾子鬆開或手臂掉下來。
- 主機這邊:解鎖期間超過
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 不用接線。