Codex Micro Vendor HID JSON-RPC Transport解析

Codex-Micro-JSON-RPC-Transport.md

Codex Micro Vendor HID JSON-RPC Transport解析

解析日: 2026-08-07

Transport

Codex独自通信はHID Report ID 6、Usage Page 0xFF00を使う。

Channel	値	用途
Debug	1	Device log
JSON-RPC	2	リクエスト、応答、通知

64-byte node-hid形式

byte 0      Report ID = 6
byte 1      Channel
byte 2      Payload length = 0...61
byte 3...63 Payload

63-byte BLE Characteristic Value

byte 0      Channel
byte 1      Payload length
byte 2...62 Payload

リクエスト

{"method":"device.status","params":null,"id":123}

• idは0...998のランダム整数
• 非ASCII文字はUnicode escapeされる
• 61 bytesを超えるJSONは連続したReportへ分割する
• リクエスト末尾に改行は付かない
• デバイス側は断片を連結し、完全なJSONとしてparseできた時点で処理する

応答

{"result":{"ok":1},"id":123,"method":"example.method"}

応答は末尾へ\r\nを付け、Report ID 6 Inputでnotifyする。Codex側は改行単位で受信し、idに対応する待機中リクエストを解決する。

通知

デバイス起点通知はidを持たない。

{"m":"v.oai.hid","p":{"k":"ACT06","act":1}}

Codex側は次の別名を受け付ける。

完全名	短縮名
method	m
params	p
id	i

QueueとTimeout

• Codex側はRPCを順次キュー処理する
• 各タスク間には約50 msのクールダウンがある
• RPC Timeoutは10秒
• 照明RPCはTimeout時に一度再試行される
• 応答しない互換デバイスは、接続済みでもControl Plane初期化失敗として扱われる

BLE実装の注意

1. Report ID 6 Inputのnotificationを有効にする。
2. Output 0x2908=06 02で受信する。
3. Input 0x2908=06 01で応答する。
4. 複数notificationを順序通り送る。
5. idを変更せず応答へコピーする。
6. 不明なメソッドにも最低限の成功応答を返すとCodexのキューを止めにくい。