プロトコルリファレンス

プロトコル概要

Unified Pilot Protocol (UPP) は WebSocket 上の JSON メッセージ を使用します。すべてのメッセージは標準構造に従い、プロトコルバージョン管理とメッセージ相関性を備えています。

接続詳細

プロトコル: WebSocket (ws://)
ホスト: <qaptly_desktop_ip> (ローカルネットワーク IP)
ポート: 18765
パス: /upp
完全 URL: ws://<qaptly_desktop_ip>:18765/upp

ネットワーク構成: <qaptly_desktop_ip> は、ローカルネットワーク上の Qaptly Desktop を実行しているマシンの IP アドレス（例：192.168.1.100、10.0.0.5）を表します。⚠️ 内部ネットワークのみ: UPP はローカルネットワーク展開用に設計されています。WebSocket サーバーを公共インターネットに公開しないでください。

プロトコルバージョン

現在のバージョン: 1.0.0 (セマンティックバージョン) すべてのメッセージは互換性チェックのために protocolVersion: "1.0.0" を含める 必要があります。

ベースメッセージ構造

すべての UPP メッセージは以下の形式に従います:

{
  "id": "<message-uuid>",
  "protocolVersion": "1.0.0",
  "type": "<message_type>",
  "timestamp": "<ISO8601>",
  "payload": { ... }
}

フィールド	型	必須	説明
`id`	string	はい	一意のメッセージ ID (UUID v4)
`protocolVersion`	string	はい	プロトコルバージョン (semver)
`type`	string	はい	メッセージタイプ (下記参照)
`timestamp`	string	はい	ISO 8601 タイムスタンプ (Z 付き)
`payload`	object	はい	メッセージ固有のコンテンツ

メッセージタイプ

タイプ	方向	説明
`register`	Pilot → Qaptly	実行ノードが自分を登録
`register_response`	Qaptly → Pilot	登録応答
`command`	Qaptly → Pilot	コマンドを実行
`response`	Pilot → Qaptly	コマンド実行結果
`event`	Pilot → Qaptly	リアルタイムイベント通知
`subscribe`	Qaptly → Pilot	イベントを購読
`heartbeat`	双方向	接続を保持

登録メッセージ

実行ノードは接続直後にこのメッセージを送信します。方向: Pilot → Qaptly

初回接続 (キーなし)

{
  "id": "msg-uuid-001",
  "protocolVersion": "1.0.0",
  "type": "register",
  "timestamp": "2026-01-21T10:30:00.000Z",
  "payload": {
    "pilot": {
      "id": "my-pilot-001",
      "name": "My WiFi Controller",
      "version": "1.0.0",
      "vendor": "My Company",
      "description": "Controls WiFi networks for testing"
    },
    "auth": {},
    "capabilities": [
      {
        "action": "wifi.scan",
        "name": "Scan WiFi Networks",
        "description": "Scans for available WiFi networks and returns their SSID, signal strength, and security type",
        "params": {
          "type": "object",
          "properties": {
            "timeout": {
              "type": "number",
              "description": "Scan timeout in seconds",
              "default": 10
            }
          },
          "required": []
        },
        "returns": {
          "type": "object",
          "properties": {
            "networks": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "ssid": { "type": "string" },
                  "signal": { "type": "number" },
                  "security": { "type": "string" }
                }
              }
            }
          }
        },
        "events": ["wifi.scan_complete"]
      }
    ]
  }
}

再接続 (キーを使用)

{
  "id": "msg-uuid-100",
  "protocolVersion": "1.0.0",
  "type": "register",
  "timestamp": "2026-01-21T15:00:00.000Z",
  "payload": {
    "pilot": {
      "id": "my-pilot-001",
      "name": "My WiFi Controller",
      "version": "1.0.0"
    },
    "auth": {
      "key": "abc123-generated-key-xyz789"
    },
    "capabilities": [...]
  }
}

実行ノード情報フィールド

フィールド	型	必須	説明
`id`	string	はい	一意の実行ノード ID (形式: `<type>-<instance>`)
`name`	string	はい	人間が読める名前
`version`	string	はい	実行ノードバージョン (semver)
`vendor`	string	いいえ	開発者/企業名
`description`	string	いいえ	この実行ノードが何をするか

認証フィールド

フィールド	型	必須	説明
`key`	string	条件付き	事前共有キー (既知の実行ノードに必須)

機能フィールド

フィールド	型	必須	説明
`action`	string	はい	アクション識別子 (形式: `domain.action`)
`name`	string	はい	人間が読める名前
`description`	string	いいえ	このアクションが何をするか (AI が使用)
`params`	JSON Schema	はい	パラメータ定義 (Draft 2020-12)
`returns`	JSON Schema	はい	戻り値定義
`events`	string[]	いいえ	このアクションが発生させる可能性のあるイベント

登録応答

Qaptly は登録を処理した後、このメッセージを送信します。方向: Qaptly → Pilot

成功 (既知の実行ノード)

{
  "id": "msg-uuid-002",
  "protocolVersion": "1.0.0",
  "type": "register_response",
  "timestamp": "2026-01-21T10:30:00.100Z",
  "payload": {
    "success": true,
    "pilotId": "my-pilot-001",
    "message": "Pilot registered successfully",
    "heartbeat": {
      "interval": 30000,
      "timeout": 90000
    }
  }
}

承認待ち (新しい実行ノード)

{
  "id": "msg-uuid-002",
  "protocolVersion": "1.0.0",
  "type": "register_response",
  "timestamp": "2026-01-21T10:30:00.100Z",
  "payload": {
    "success": false,
    "pending": true,
    "message": "Waiting for user approval"
  }
}

承認済み (キー付き)

{
  "id": "msg-uuid-003",
  "protocolVersion": "1.0.0",
  "type": "register_response",
  "timestamp": "2026-01-21T10:30:15.000Z",
  "payload": {
    "success": true,
    "pilotId": "my-pilot-001",
    "assignedKey": "abc123-generated-key-xyz789",
    "message": "Pilot approved and registered",
    "heartbeat": {
      "interval": 30000,
      "timeout": 90000
    }
  }
}

失敗

{
  "id": "msg-uuid-002",
  "protocolVersion": "1.0.0",
  "type": "register_response",
  "timestamp": "2026-01-21T10:30:00.100Z",
  "payload": {
    "success": false,
    "error": {
      "code": "AUTH_FAILED",
      "message": "Invalid authentication key"
    }
  }
}

エラーコード

コード	説明
`AUTH_FAILED`	キー検証に失敗
`USER_REJECTED`	ユーザーが実行ノードを拒否
`DUPLICATE_PILOT_ID`	実行ノード ID が既に登録されている
`INVALID_PILOT_INFO`	実行ノード情報が無効または欠落
`INVALID_CAPABILITY`	機能定義が無効
`PROTOCOL_VERSION_MISMATCH`	プロトコルバージョンがサポートされていない

コマンドメッセージ

Qaptly はアクション実行のためにコマンドを送信します。方向: Qaptly → Pilot

{
  "id": "msg-uuid-010",
  "protocolVersion": "1.0.0",
  "type": "command",
  "timestamp": "2026-01-21T10:31:00.000Z",
  "payload": {
    "commandId": "cmd-uuid-12345",
    "action": "wifi.scan",
    "params": {
      "timeout": 15
    },
    "timeout": 20000
  }
}

フィールド

フィールド	型	必須	説明
`commandId`	string	はい	一意のコマンド ID (UUID)
`action`	string	はい	実行するアクション
`params`	object	はい	パラメータ (機能スキーマと一致)
`timeout`	number	いいえ	タイムアウト (ミリ秒、デフォルト: 30000)

応答メッセージ

実行ノードは実行結果で応答します。方向: Pilot → Qaptly

成功

{
  "id": "msg-uuid-011",
  "protocolVersion": "1.0.0",
  "type": "response",
  "timestamp": "2026-01-21T10:31:05.000Z",
  "payload": {
    "commandId": "cmd-uuid-12345",
    "success": true,
    "data": {
      "networks": [
        {
          "ssid": "HomeWiFi",
          "signal": -45,
          "security": "wpa2"
        }
      ]
    }
  }
}

失敗

{
  "id": "msg-uuid-011",
  "protocolVersion": "1.0.0",
  "type": "response",
  "timestamp": "2026-01-21T10:31:05.000Z",
  "payload": {
    "commandId": "cmd-uuid-12345",
    "success": false,
    "error": {
      "code": "wifi.SCAN_FAILED",
      "message": "WiFi adapter is disabled"
    }
  }
}

フィールド

フィールド	型	必須	説明
`commandId`	string	はい	コマンドの commandId と一致する必要があります
`success`	boolean	はい	コマンドが成功したかどうか
`data`	object	成功時	戻りデータ (機能スキーマと一致)
`error`	object	失敗時	エラー詳細
`error.code`	string	はい	エラーコード (形式: `domain.ERROR_NAME` を使用)
`error.message`	string	はい	人間が読めるエラーメッセージ

イベントメッセージ

実行ノードは購読者にイベントを送信します。方向: Pilot → Qaptly

{
  "id": "msg-uuid-020",
  "protocolVersion": "1.0.0",
  "type": "event",
  "timestamp": "2026-01-21T10:35:00.000Z",
  "payload": {
    "event": "wifi.disconnected",
    "data": {
      "reason": "signal_lost",
      "lastSsid": "HomeWiFi"
    }
  }
}

重要: Qaptly が購読したイベントのみを送信します。購読されていないイベントは無視されます。

購読メッセージ

Qaptly は特定のイベントを購読します。方向: Qaptly → Pilot

イベントを購読

{
  "id": "msg-uuid-030",
  "protocolVersion": "1.0.0",
  "type": "subscribe",
  "timestamp": "2026-01-21T10:30:05.000Z",
  "payload": {
    "subscribe": ["wifi.connected", "wifi.disconnected"],
    "unsubscribe": []
  }
}

イベントから購読解除

{
  "id": "msg-uuid-031",
  "protocolVersion": "1.0.0",
  "type": "subscribe",
  "timestamp": "2026-01-21T10:30:06.000Z",
  "payload": {
    "subscribe": [],
    "unsubscribe": ["wifi.signal_changed"]
  }
}

ワイルドカードサポート

すべてのイベントを購読: ["*"]
ドメインを購読: ["wifi.*"] (すべての wifi イベント)

ハートビートメッセージ

接続を保持します。両当事者は 30 秒ごとにこれを送信します。方向: 双方向

{
  "id": "msg-uuid-100",
  "protocolVersion": "1.0.0",
  "type": "heartbeat",
  "timestamp": "2026-01-21T10:32:00.000Z",
  "payload": {}
}

ハートビートポリシー

パラメータ	値	説明
間隔	30秒	30秒ごとにハートビートを送信
タイムアウト	90秒	90秒間メッセージなし = 切断
イニシエータ	両方	Qaptly と実行ノード両方が送信
応答	なし	火災と忘却、応答不要

実行ノードが 90 秒間ハートビートを送信しない場合、Qaptly は接続を閉じます。

アクション命名規則

アクションは形式を使用します: domain.action

標準ドメイン

ドメイン	例	説明
`wifi`	`scan`, `connect`, `disconnect`, `status`	WiFi 制御
`bluetooth`	`scan`, `pair`, `unpair`	Bluetooth 制御
`network`	`ping`, `traceroute`, `dns_lookup`	ネットワーク診断
`gpio`	`read`, `write`, `mode`	GPIO 制御
`sensor`	`temperature`, `humidity`, `pressure`	センサー読み取り
`system`	`reboot`, `shutdown`, `info`	システム操作

カスタムドメイン

カスタムドメインにはベンダープレフィックスを使用します:

vendor.domain.action

例:

acme.motor.rotate
acme.motor.stop
mycompany.led.set_color

接続ライフサイクル

切断

クリーン切断: WebSocket を正常に閉じる
タイムアウト: 90秒間メッセージなし
猶予期間: 同じキーで再接続するまで 5 分

ベストプラクティス

メッセージ ID

すべてのメッセージ ID に UUID v4 を使用:

import uuid
message_id = str(uuid.uuid4())

タイムスタンプ

ISO 8601 形式を ‘Z’ サフィックス (UTC) で使用:

from datetime import datetime
timestamp = datetime.utcnow().isoformat() + "Z"
# "2026-01-21T10:30:00.000000Z"

エラー処理

常に意味のあるエラーコードとメッセージを含める:

{
  "code": "wifi.AUTHENTICATION_FAILED",
  "message": "WiFi password is incorrect"
}

イベントフィルタリング

Qaptly が購読したイベントのみを送信:

if event_manager.is_subscribed("wifi.connected"):
    await send_event("wifi.connected", {...})

次のステップ

Authentication

セキュリティモデルとキー管理

Capabilities

JSON Schema で機能を定義

Examples

完全な実装例

Quick Start

最初の実行ノードを構築

​プロトコル概要

​接続詳細

​プロトコルバージョン

​ベースメッセージ構造

​メッセージタイプ

​登録メッセージ

​初回接続 (キーなし)

​再接続 (キーを使用)

​実行ノード情報フィールド

​認証フィールド

​機能フィールド

​登録応答

​成功 (既知の実行ノード)

​承認待ち (新しい実行ノード)

​承認済み (キー付き)

​失敗

​エラーコード

​コマンドメッセージ

​フィールド

​応答メッセージ

​成功

​失敗

​フィールド

​イベントメッセージ

​購読メッセージ

​イベントを購読

​イベントから購読解除

​ワイルドカード サポート

​ハートビートメッセージ

​ハートビートポリシー

​アクション命名規則

​標準ドメイン

​カスタムドメイン

​接続ライフサイクル

​切断

​ベストプラクティス

​メッセージ ID

​タイムスタンプ

​エラー処理

​イベントフィルタリング

​次のステップ

Authentication

Capabilities

Examples

Quick Start

プロトコル概要

接続詳細

プロトコルバージョン

ベースメッセージ構造

メッセージタイプ

登録メッセージ

初回接続 (キーなし)

再接続 (キーを使用)

実行ノード情報フィールド

認証フィールド

機能フィールド

登録応答

成功 (既知の実行ノード)

承認待ち (新しい実行ノード)

承認済み (キー付き)

失敗

エラーコード

コマンドメッセージ

フィールド

応答メッセージ

成功

失敗

フィールド

イベントメッセージ

購読メッセージ

イベントを購読

イベントから購読解除

ワイルドカードサポート

ハートビートメッセージ

ハートビートポリシー

アクション命名規則

標準ドメイン

カスタムドメイン

接続ライフサイクル

切断

ベストプラクティス

メッセージ ID

タイムスタンプ

エラー処理

イベントフィルタリング

次のステップ