Protocol Reference - Qaptly Docs

Protocol Overview

The Unified Pilot Protocol (UPP) uses JSON messages over WebSocket. All messages follow a standard structure with protocol versioning and message correlation.

Connection Details

Protocol: WebSocket (ws://)
Host: <qaptly_desktop_ip> (local network IP)
Port: 18765
Path: /upp
Full URL: ws://<qaptly_desktop_ip>:18765/upp

Network Configuration: <qaptly_desktop_ip> represents the IP address of the machine running Qaptly Desktop on your local network (e.g., 192.168.1.100, 10.0.0.5).⚠️ Internal Network Only: UPP is designed for local network deployments. Do not expose the WebSocket server to the public internet.

Protocol Version

Current version: 1.0.0 (semantic versioning) All messages must include protocolVersion: "1.0.0" for compatibility checking.

Base Message Structure

Every UPP message follows this format:

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

Field	Type	Required	Description
`id`	string	Yes	Unique message ID (UUID v4)
`protocolVersion`	string	Yes	Protocol version (semver)
`type`	string	Yes	Message type (see below)
`timestamp`	string	Yes	ISO 8601 timestamp with Z
`payload`	object	Yes	Message-specific content

Message Types

Type	Direction	Description
`register`	Pilot → Qaptly	Pilot registers itself
`register_response`	Qaptly → Pilot	Registration response
`command`	Qaptly → Pilot	Execute a command
`response`	Pilot → Qaptly	Command execution result
`event`	Pilot → Qaptly	Real-time event notification
`subscribe`	Qaptly → Pilot	Subscribe to events
`heartbeat`	Bidirectional	Keep connection alive

Register Message

Pilot sends this message immediately after connecting. Direction: Pilot → Qaptly

First-Time Connection (No Key)

{
  "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"]
      }
    ]
  }
}

Reconnection (With Key)

{
  "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": [...]
  }
}

Pilot Info Fields

Field	Type	Required	Description
`id`	string	Yes	Unique pilot ID (use format: `<type>-<instance>`)
`name`	string	Yes	Human-readable name
`version`	string	Yes	Pilot version (semver)
`vendor`	string	No	Developer/company name
`description`	string	No	What this pilot does

Auth Fields

Field	Type	Required	Description
`key`	string	Conditional	Pre-shared key (required for known pilots)

Capability Fields

Field	Type	Required	Description
`action`	string	Yes	Action identifier (format: `domain.action`)
`name`	string	Yes	Human-readable name
`description`	string	No	What this action does (used by AI)
`params`	JSON Schema	Yes	Parameter definition (Draft 2020-12)
`returns`	JSON Schema	Yes	Return value definition
`events`	string[]	No	Events this action may trigger

Register Response

Qaptly sends this after processing registration. Direction: Qaptly → Pilot

Success (Known 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
    }
  }
}

Pending Approval (New Pilot)

{
  "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"
  }
}

Approved (With Key)

{
  "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
    }
  }
}

Failure

{
  "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"
    }
  }
}

Error Codes

Code	Description
`AUTH_FAILED`	Key verification failed
`USER_REJECTED`	User rejected the pilot
`DUPLICATE_PILOT_ID`	Pilot ID already registered
`INVALID_PILOT_INFO`	Missing or invalid pilot information
`INVALID_CAPABILITY`	Capability definition is invalid
`PROTOCOL_VERSION_MISMATCH`	Protocol version not supported

Command Message

Qaptly sends commands to execute actions. Direction: 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
  }
}

Fields

Field	Type	Required	Description
`commandId`	string	Yes	Unique command ID (UUID)
`action`	string	Yes	Action to execute
`params`	object	Yes	Parameters (matches capability schema)
`timeout`	number	No	Timeout in milliseconds (default: 30000)

Response Message

Pilot responds with execution results. Direction: Pilot → Qaptly

Success

{
  "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"
        }
      ]
    }
  }
}

Failure

{
  "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"
    }
  }
}

Fields

Field	Type	Required	Description
`commandId`	string	Yes	Must match command’s commandId
`success`	boolean	Yes	Whether command succeeded
`data`	object	On success	Return data (matches capability schema)
`error`	object	On failure	Error details
`error.code`	string	Yes	Error code (use `domain.ERROR_NAME`)
`error.message`	string	Yes	Human-readable error message

Event Message

Pilot sends events for subscribed listeners. Direction: 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"
    }
  }
}

Important: Only send events that Qaptly has subscribed to. Unsubscribed events are ignored.

Qaptly subscribes to specific events. Direction: 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": []
  }
}

Unsubscribe from Events

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

Wildcard Support

Subscribe to all events: ["*"]
Subscribe to domain: ["wifi.*"] (all wifi events)

Heartbeat Message

Keep connection alive. Both parties send this every 30 seconds. Direction: Bidirectional

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

Heartbeat Policy

Parameter	Value	Description
Interval	30 seconds	Send heartbeat every 30 seconds
Timeout	90 seconds	No message for 90s = disconnection
Initiator	Both	Qaptly and Pilot both send
Response	None	Fire-and-forget, no response needed

If your pilot doesn’t send heartbeat for 90 seconds, Qaptly will close the connection.

Action Naming Convention

Actions use the format: domain.action

Standard Domains

Domain	Examples	Description
`wifi`	`scan`, `connect`, `disconnect`, `status`	WiFi control
`bluetooth`	`scan`, `pair`, `unpair`	Bluetooth control
`network`	`ping`, `traceroute`, `dns_lookup`	Network diagnostics
`gpio`	`read`, `write`, `mode`	GPIO control
`sensor`	`temperature`, `humidity`, `pressure`	Sensor reading
`system`	`reboot`, `shutdown`, `info`	System operations

Custom Domains

Use vendor prefix for custom domains:

vendor.domain.action

Examples:

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

Connection Lifecycle

Disconnection

Clean disconnect: Close WebSocket normally
Timeout: No message for 90 seconds
Grace period: 5 minutes to reconnect with same key

Best Practices

Message IDs

Use UUID v4 for all message IDs:

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

Timestamps

Use ISO 8601 format with ‘Z’ suffix (UTC):

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

Error Handling

Always include meaningful error codes and messages:

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

Event Filtering

Only send events that Qaptly subscribed to:

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

Next Steps

Authentication

Security model and key management

Capabilities

Define capabilities with JSON Schema

Examples

Complete working implementations

Quick Start

Build your first pilot

​Protocol Overview

​Connection Details

​Protocol Version

​Base Message Structure

​Message Types

​Register Message

​First-Time Connection (No Key)

​Reconnection (With Key)

​Pilot Info Fields

​Auth Fields

​Capability Fields

​Register Response

​Success (Known Pilot)

​Pending Approval (New Pilot)

​Approved (With Key)

​Failure

​Error Codes

​Command Message

​Fields

​Response Message

​Success

​Failure

​Fields

​Event Message

​Subscribe Message

​Subscribe to Events

​Unsubscribe from Events

​Wildcard Support

​Heartbeat Message

​Heartbeat Policy

​Action Naming Convention

​Standard Domains

​Custom Domains

​Connection Lifecycle

​Disconnection

​Best Practices

​Message IDs

​Timestamps

​Error Handling

​Event Filtering

​Next Steps

Authentication

Capabilities

Examples

Quick Start

Protocol Overview

Connection Details

Protocol Version

Base Message Structure

Message Types

Register Message

First-Time Connection (No Key)

Reconnection (With Key)

Pilot Info Fields

Auth Fields

Capability Fields

Register Response

Success (Known Pilot)

Pending Approval (New Pilot)

Approved (With Key)

Failure

Error Codes

Command Message

Fields

Response Message

Success

Failure

Fields

Event Message

Subscribe Message

Subscribe to Events

Unsubscribe from Events

Wildcard Support

Heartbeat Message

Heartbeat Policy

Action Naming Convention

Standard Domains

Custom Domains

Connection Lifecycle

Disconnection

Best Practices

Message IDs

Timestamps

Error Handling

Event Filtering

Next Steps