Capabilities

What are Capabilities?

Capabilities are actions your pilot can perform. Each capability defines:

What the action does (name and description)
Input parameters (JSON Schema)
Output data (JSON Schema)
Events it may trigger

Capability Structure

{
  "action": "domain.action_name",
  "name": "Human Readable Name",
  "description": "Detailed description for AI and users",
  "params": {
    "type": "object",
    "properties": { ... },
    "required": [ ... ]
  },
  "returns": {
    "type": "object",
    "properties": { ... }
  },
  "events": ["event.name1", "event.name2"]
}

Required Fields

Field	Type	Description
`action`	string	Unique action identifier (`domain.action`)
`name`	string	Short human-readable name
`params`	JSON Schema	Input parameter definition
`returns`	JSON Schema	Output data definition

Optional Fields

Field	Type	Description
`description`	string	Detailed description (used by AI)
`events`	string[]	Events this action may trigger

JSON Schema

Capabilities use JSON Schema Draft 2020-12 to define parameters and return values.

Why JSON Schema?

✅ Self-documenting - Describes data structure
✅ Validation - Qaptly validates params before sending
✅ Type safety - Catches errors early
✅ AI-friendly - AI can understand your API

Basic Types

{
  "type": "string"    // Text
}

{
  "type": "number"    // Numeric (int or float)
}

{
  "type": "boolean"   // true/false
}

{
  "type": "array",    // List
  "items": { ... }
}

{
  "type": "object",   // Dictionary/Map
  "properties": { ... }
}

Example Capabilities

1. Simple Action (No Parameters)

Get current WiFi status with no input parameters:

{
  "action": "wifi.status",
  "name": "Get WiFi Status",
  "description": "Returns the current WiFi connection status including SSID, signal strength, and IP address",
  "params": {
    "type": "object",
    "properties": {},
    "required": []
  },
  "returns": {
    "type": "object",
    "properties": {
      "connected": {
        "type": "boolean",
        "description": "Whether WiFi is connected"
      },
      "ssid": {
        "type": "string",
        "description": "Network name (if connected)"
      },
      "signal": {
        "type": "number",
        "description": "Signal strength in dBm"
      },
      "ip": {
        "type": "string",
        "description": "Assigned IP address"
      }
    }
  },
  "events": []
}

2. Action with Required Parameters

Connect to WiFi with required SSID and optional password:

{
  "action": "wifi.connect",
  "name": "Connect to WiFi",
  "description": "Connects to a specified WiFi network. Password is optional for open networks.",
  "params": {
    "type": "object",
    "properties": {
      "ssid": {
        "type": "string",
        "description": "The SSID of the WiFi network to connect to",
        "minLength": 1,
        "maxLength": 32
      },
      "password": {
        "type": "string",
        "description": "WiFi password (not required for open networks)"
      },
      "timeout": {
        "type": "number",
        "description": "Connection timeout in seconds",
        "default": 30,
        "minimum": 5,
        "maximum": 300
      }
    },
    "required": ["ssid"]
  },
  "returns": {
    "type": "object",
    "properties": {
      "connected": {
        "type": "boolean"
      },
      "ip": {
        "type": "string"
      },
      "gateway": {
        "type": "string"
      }
    }
  },
  "events": ["wifi.connected", "wifi.connection_failed"]
}

3. Action with Array Parameters

Control multiple GPIO pins at once:

{
  "action": "gpio.set_multiple",
  "name": "Set Multiple GPIO Pins",
  "description": "Set multiple GPIO pins to HIGH or LOW state simultaneously",
  "params": {
    "type": "object",
    "properties": {
      "pins": {
        "type": "array",
        "description": "Array of pin configurations",
        "items": {
          "type": "object",
          "properties": {
            "pin": {
              "type": "number",
              "description": "GPIO pin number",
              "minimum": 0,
              "maximum": 40
            },
            "state": {
              "type": "string",
              "description": "Pin state",
              "enum": ["HIGH", "LOW"]
            }
          },
          "required": ["pin", "state"]
        },
        "minItems": 1
      }
    },
    "required": ["pins"]
  },
  "returns": {
    "type": "object",
    "properties": {
      "success": {
        "type": "boolean"
      },
      "updated_pins": {
        "type": "array",
        "items": {
          "type": "number"
        }
      }
    }
  },
  "events": []
}

4. Action with Enum Choices

Set LED color from predefined options:

{
  "action": "led.set_color",
  "name": "Set LED Color",
  "description": "Changes the LED to one of the predefined colors",
  "params": {
    "type": "object",
    "properties": {
      "color": {
        "type": "string",
        "description": "LED color",
        "enum": ["red", "green", "blue", "yellow", "white", "off"]
      },
      "brightness": {
        "type": "number",
        "description": "Brightness level (0-100)",
        "minimum": 0,
        "maximum": 100,
        "default": 100
      }
    },
    "required": ["color"]
  },
  "returns": {
    "type": "object",
    "properties": {
      "success": {
        "type": "boolean"
      },
      "current_color": {
        "type": "string"
      }
    }
  },
  "events": ["led.color_changed"]
}

JSON Schema Features

Validation Constraints

{
  "type": "string",
  "minLength": 1,
  "maxLength": 100,
  "pattern": "^[a-zA-Z0-9_]+$"
}

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "multipleOf": 5
}

{
  "type": "array",
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

Default Values

{
  "properties": {
    "timeout": {
      "type": "number",
      "default": 30,
      "description": "Request timeout in seconds"
    }
  }
}

Enumerations

{
  "properties": {
    "mode": {
      "type": "string",
      "enum": ["auto", "manual", "scheduled"],
      "description": "Operation mode"
    }
  }
}

Nested Objects

{
  "properties": {
    "config": {
      "type": "object",
      "properties": {
        "host": {"type": "string"},
        "port": {"type": "number"},
        "ssl": {"type": "boolean"}
      },
      "required": ["host", "port"]
    }
  }
}

Event Declaration

Declare which events a capability may trigger:

{
  "action": "wifi.scan",
  "events": [
    "wifi.scan_complete",
    "wifi.scan_failed",
    "wifi.network_found"
  ]
}

Best Practice: Only list events that are directly related to this action. Don’t list all possible events your pilot can emit.

Action Naming Conventions

Format

domain.action

Standard Domains

Domain	Use Case	Examples
`wifi`	WiFi control	`scan`, `connect`, `disconnect`, `status`
`bluetooth`	Bluetooth	`scan`, `pair`, `unpair`
`network`	Network diagnostics	`ping`, `traceroute`, `dns_lookup`
`gpio`	Hardware GPIO	`read`, `write`, `mode`
`sensor`	Sensor readings	`temperature`, `humidity`, `pressure`
`system`	System ops	`reboot`, `shutdown`, `info`
`file`	File operations	`read`, `write`, `list`, `delete`

Custom Domains

For vendor-specific actions, use:

vendor.domain.action

Examples:

acme.motor.rotate
acme.motor.stop
acme.motor.set_speed

Description Best Practices

Good descriptions help AI understand your pilot:

❌ Bad Description

{
  "description": "Scans WiFi"
}

✅ Good Description

{
  "description": "Scans for available WiFi networks within range and returns their SSID, signal strength in dBm, frequency in MHz, and security type (open, WEP, WPA, WPA2, WPA3)"
}

Guidelines

Be specific - What exactly does it do?
Mention key data - What information is returned?
Include units - dBm, MHz, seconds, etc.
Note side effects - Does it change state?
Write for AI - Future AI integration will use descriptions

Complete Example

A comprehensive capability with all features:

{
  "action": "sensor.read_temperature",
  "name": "Read Temperature Sensor",
  "description": "Reads the current temperature from the DHT22 sensor and returns the value in Celsius or Fahrenheit. Optionally applies a calibration offset. Triggers temperature_changed event if value differs by more than 0.5 degrees from last reading.",
  "params": {
    "type": "object",
    "properties": {
      "unit": {
        "type": "string",
        "description": "Temperature unit",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      },
      "offset": {
        "type": "number",
        "description": "Calibration offset to apply (in selected unit)",
        "default": 0,
        "minimum": -10,
        "maximum": 10
      },
      "precision": {
        "type": "number",
        "description": "Number of decimal places",
        "enum": [0, 1, 2],
        "default": 1
      }
    },
    "required": []
  },
  "returns": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "description": "Current temperature reading"
      },
      "unit": {
        "type": "string",
        "description": "Unit of measurement used"
      },
      "timestamp": {
        "type": "string",
        "description": "ISO 8601 timestamp of reading",
        "format": "date-time"
      },
      "sensor_id": {
        "type": "string",
        "description": "Sensor hardware identifier"
      }
    }
  },
  "events": ["sensor.temperature_changed", "sensor.read_error"]
}

Validation

Qaptly validates parameters before sending commands:

# Command from Qaptly
{
  "action": "wifi.connect",
  "params": {
    "ssid": "HomeWiFi",
    "timeout": 45
  }
}

# ✅ Valid: all required params present, types correct

# ❌ Invalid: missing required param
{
  "action": "wifi.connect",
  "params": {
    "timeout": 45  // Missing "ssid"
  }
}

# ❌ Invalid: wrong type
{
  "action": "wifi.connect",
  "params": {
    "ssid": 12345,  // Should be string
    "timeout": "45"  // Should be number
  }
}

Dynamic Capabilities (Advanced)

For pilots with changing capabilities (e.g., detected sensors), you can:

Initial registration - Register with basic capabilities
Discovery - Detect available hardware
Reconnect - Disconnect and reconnect with updated capabilities

# After detecting new sensor
async def update_capabilities():
    # Close current connection
    await websocket.close()

    # Add new capability
    capabilities.append({
        "action": "sensor.read_humidity",
        "name": "Read Humidity Sensor",
        ...
    })

    # Reconnect with updated capabilities
    await connect_and_register()

Capability updates require disconnection and re-registration. Plan your pilot architecture accordingly.

Testing Capabilities

Test your JSON Schema definitions:

import jsonschema

# Define schema
schema = {
    "type": "object",
    "properties": {
        "ssid": {"type": "string"},
        "timeout": {"type": "number"}
    },
    "required": ["ssid"]
}

# Valid params
params = {"ssid": "HomeWiFi", "timeout": 30}
jsonschema.validate(params, schema)  # ✅ No error

# Invalid params
params = {"timeout": 30}  # Missing ssid
jsonschema.validate(params, schema)  # ❌ ValidationError

Next Steps

Protocol Reference

Message format specifications

Examples

Complete working implementations

Quick Start

Build your first pilot

Authentication

Security and key management

Android Pilot

iOS Pilot

Chrome Extension Pilot

Custom Pilots (UPP)

What are Capabilities?

Capability Structure

Required Fields

Optional Fields

JSON Schema

Why JSON Schema?

Basic Types

Example Capabilities

1. Simple Action (No Parameters)

2. Action with Required Parameters

3. Action with Array Parameters

4. Action with Enum Choices

JSON Schema Features

Validation Constraints

Default Values

Enumerations

Nested Objects

Event Declaration

Action Naming Conventions

Format

Standard Domains

Custom Domains

Description Best Practices

❌ Bad Description

✅ Good Description

Guidelines

Complete Example

Validation

Dynamic Capabilities (Advanced)

Testing Capabilities

Next Steps

Protocol Reference

Examples

Quick Start

Authentication

​What are Capabilities?

​Capability Structure

​Required Fields

​Optional Fields

​JSON Schema

​Why JSON Schema?

​Basic Types

​Example Capabilities

​1. Simple Action (No Parameters)

​2. Action with Required Parameters

​3. Action with Array Parameters

​4. Action with Enum Choices

​JSON Schema Features

​Validation Constraints

​Default Values

​Enumerations

​Nested Objects

​Event Declaration

​Action Naming Conventions

​Format

​Standard Domains

​Custom Domains

​Description Best Practices

​❌ Bad Description

​✅ Good Description

​Guidelines

​Complete Example

​Validation

​Dynamic Capabilities (Advanced)

​Testing Capabilities

​Next Steps

Protocol Reference

Examples

Quick Start

Authentication

What are Capabilities?

Capability Structure

Required Fields

Optional Fields

JSON Schema

Why JSON Schema?

Basic Types

Example Capabilities

1. Simple Action (No Parameters)

2. Action with Required Parameters

3. Action with Array Parameters

4. Action with Enum Choices

JSON Schema Features

Validation Constraints

Default Values

Enumerations

Nested Objects

Event Declaration

Action Naming Conventions

Format

Standard Domains

Custom Domains

Description Best Practices

❌ Bad Description

✅ Good Description

Guidelines

Complete Example

Validation

Dynamic Capabilities (Advanced)

Testing Capabilities

Next Steps