VISCA 指令產生器 / 封包解析器

VISCA 是怎麼運作的（實作說明）

1. 一個封包只有三段

Header（1 byte）+ Message（最多 14 bytes）+ Terminator（0xFF），總長 3~16 bytes。Header 的 bit 7 固定為 1，bit 6~4 是發送端位址，bit 3 是廣播旗標，bit 2~0 是接收端位址。所以控制器（位址 0）送給裝置 1 的封包開頭是 0x81，裝置 1 回給控制器的則是 0x90（裝置位址 + 8）。

2. MSB 規則是整個協定的鑰匙

Message 的每個 byte 都必須小於 0x80。這條規則保證 0xFF 只可能出現在終止符，接收端任何時候失去同步，只要往前掃到下一個 0xFF 就能重新對齊。代價是參數的有效範圍只有 0~127，而 16-bit 數值必須拆成 4 個 nibble byte——這就是為什麼變焦位置要寫成 0p 0q 0r 0s。

3. 命令回兩次，查詢只回一次

送出命令（com-mode 01）會先收到 ACK（90 4Y FF）代表「收到了，開始做」，馬達實際跑完之後才收到 Completion（90 5Y FF）。查詢（com-mode 09）則不回 ACK，直接回 Completion 帶資料。這一點是實作 parser 時第二常見的錯誤——等 ACK 才處理的話，所有查詢都會逾時。

4. 只有兩個 socket，所以要等

相機端只有兩個命令緩衝區。沒等 Completion 就連送第三個命令，會收到 90 60 03 FF（Command buffer full）。搖桿控制若每個 tick 都送 Pan/Tilt Drive 而不等回覆，兩個 socket 會在 100 毫秒內用完。查詢不佔 socket，可以與命令交錯發送——這是位置回授迴路能高頻執行的前提。

5. 接收端不能用 0xFF 切包

這個頁面的解析器是離線分析已知內容，才允許用 0xFF 分段。但真實的 UART 接收不行：只要掉一個 byte，兩個封包就會黏成一包，而黏起來的那一包同樣以 0xFF 結尾、看起來完全合法，無法從錯誤中恢復。正確做法是狀態機——

SYNC      逐 byte 掃描，直到遇到合法 Header（MSB = 1）
CLASSIFY  讀第 2 個 byte 決定類型與期望長度：
            0x40~0x4F → ACK，3 B
            0x50~0x5F → Completion，長度由「送出的是哪個查詢」決定
            0x60~0x6F → Error，4 B
            0x01/0x09 → 命令／查詢（通常只有裝置端會收到）
COLLECT   收滿期望長度後驗證：
            (a) Terminator 前每個 byte 都 < 0x80
            (b) 最後一個 byte 是 0xFF
          任一失敗 → 丟棄、記錄、回到 SYNC

查詢回覆的長度無法從封包本身推得——同樣是 90 50 開頭，Power 查詢回 4 bytes、變焦位置回 7 bytes、Pan/Tilt 位置回 11 bytes。所以控制端必須維護一個「待回覆佇列」：送出查詢時記下期望長度，收到 90 5Y 時據以判定。

6. 位置是有號數

Pan/Tilt 位置是 16-bit 二補數有號數。把 4 個 nibble 還原成 16-bit 之後，必須轉成 int16 才正確；用 uint16 接會讓左半邊或下半邊的所有位置變成三萬多、六萬多。這通常是位置回授迴路第一次跑就會炸的地方，而且症狀是「雲台突然往一個方向衝到底」，不容易一眼看出是型別問題。

7. 廠商差異是整合失敗的主因

• 波特率：Sony EVI 系列預設 9600、BRC 可切 38400，第三方（PTZOptics、AVer 等）常見 115200。
• 預設點數量：EVI-D30 只有 0~5、BRC-X400 為 0~99、部分第三方到 0~254。超出範圍是 Syntax Error 而不是被截斷。
• 速度階數：標準 Pan 是 0x01~0x18、Tilt 是 0x01~0x14，但有些機種只到 0x0E，超出時的行為各家不一致。
• 位置單位：絕對位置的角度換算完全是機種相關，不可移植，一定要查該機種的命令表。
• 方向定義：Pan 正方向左右相反的機種確實存在；吊掛安裝（Picture Flip）又會再翻一次。

8. VISCA over IP 只是多一個標頭

指令層完全不變，只在原封包前面加 8 bytes：Payload Type（2）+ Payload Length（2）+ Sequence Number（4），以 UDP 送到預設埠 52381。Payload Type 常見值為 01 00（命令）、01 10（查詢）、01 11（回覆）。因為是 UDP，沒有重送機制——掉了就是掉了，逾時重送要自己做；序號的用途是把回覆配對回請求，不是用來重排順序。