Skip to main content

Device API

The Device API provides comprehensive endpoints for managing and controlling smart building devices.

Base URL​

/api/devices

Authentication​

All device API endpoints require JWT authentication:

Authorization: Bearer YOUR_JWT_TOKEN

Device Types​

FMP Devices​

Fault Managed Power (Class 4) devices for high-voltage power distribution.

Endpoint: /api/devices/fmp

Network Switches​

Cisco and other network switches with PoE capabilities.

Endpoint: /api/devices/switches

HVAC Systems​

Heating, ventilation, and air conditioning systems.

Endpoint: /api/devices/hvac

Lighting​

Smart lighting controls including dimmers and color control.

Endpoint: /api/devices/lights

Window Shades​

Automated window treatments and blinds.

Endpoint: /api/devices/shades

Smart Desks​

Sit-stand desks and ergonomic furniture.

Endpoint: /api/devices/desks

Sensors​

Environmental and occupancy sensors.

Endpoint: /api/devices/sensors

Common Operations​

List Devices​

Get all devices of a specific type:

GET /api/devices/{type}

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.aida-platform.com/api/devices/lights

Example Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Reception Light",
      "type": "led_panel",
      "zone": "reception",
      "status": "online",
      "state": {
        "power": "on",
        "brightness": 80,
        "color": "#FFFFFF"
      },
      "lastSeen": "2024-01-01T12:00:00Z"
    }
  ],
  "message": "Devices retrieved successfully"
}

Get Device Details​

Get detailed information about a specific device:

GET /api/devices/{type}/{id}

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.aida-platform.com/api/devices/lights/1

Control Device​

Send control commands to a device:

POST /api/devices/{type}/{id}/control

Example Request:

curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"power": "on", "brightness": 100}' \
     https://api.aida-platform.com/api/devices/lights/1/control

Example Response:

{
  "success": true,
  "data": {
    "id": 1,
    "state": {
      "power": "on",
      "brightness": 100,
      "color": "#FFFFFF"
    },
    "timestamp": "2024-01-01T12:00:00Z"
  },
  "message": "Device controlled successfully"
}

Device-Specific Endpoints​

Lighting Control​

Set Brightness​

POST /api/devices/lights/{id}/brightness
Content-Type: application/json

{
  "brightness": 75
}

Set Color​

POST /api/devices/lights/{id}/color
Content-Type: application/json

{
  "color": "#FF5733"
}

Apply Scene​

POST /api/devices/lights/{id}/scene
Content-Type: application/json

{
  "scene": "meeting"
}

HVAC Control​

Set Temperature​

POST /api/devices/hvac/{id}/temperature
Content-Type: application/json

{
  "temperature": 22,
  "unit": "celsius"
}

Set Fan Speed​

POST /api/devices/hvac/{id}/fan
Content-Type: application/json

{
  "speed": "medium"
}

Set Mode​

POST /api/devices/hvac/{id}/mode
Content-Type: application/json

{
  "mode": "cool"
}

Window Shades​

Set Position​

POST /api/devices/shades/{id}/position
Content-Type: application/json

{
  "position": 50
}

Set Tilt​

POST /api/devices/shades/{id}/tilt
Content-Type: application/json

{
  "tilt": 45
}

Batch Operations​

Control Multiple Devices​

POST /api/devices/batch/control
Content-Type: application/json

{
  "devices": [
    {
      "type": "lights",
      "id": 1,
      "action": "turnOn"
    },
    {
      "type": "hvac",
      "id": 2,
      "action": "setTemperature",
      "value": 22
    }
  ]
}

Get Device Status​

POST /api/devices/batch/status
Content-Type: application/json

{
  "devices": [
    {"type": "lights", "id": 1},
    {"type": "hvac", "id": 2}
  ]
}

Real-time Updates​

WebSocket Connection​

Connect to real-time device updates:

const ws = new WebSocket('wss://api.aida-platform.com/ws/devices');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Device update:', data);
};

Subscribe to Device Events​

POST /api/devices/{id}/subscribe
Content-Type: application/json

{
  "events": ["status_changed", "control_received"]
}

Error Handling​

Common Error Responses​

Device Not Found​

{
  "success": false,
  "error": "Device not found",
  "code": "DEVICE_NOT_FOUND"
}

Device Offline​

{
  "success": false,
  "error": "Device is offline",
  "code": "DEVICE_OFFLINE"
}

Invalid Command​

{
  "success": false,
  "error": "Invalid control command",
  "code": "INVALID_COMMAND"
}

Rate Limiting​

Device control operations are rate limited:

  • Individual Control: 10 requests per minute per device
  • Batch Operations: 5 requests per minute
  • Status Queries: 100 requests per minute

Webhooks​

Subscribe to device events:

POST /api/webhooks/devices
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/devices",
  "events": ["device.status_changed", "device.control_received"],
  "secret": "your_webhook_secret"
}

SDK Examples​

JavaScript/TypeScript​

import { AidaClient } from '@aida-platform/sdk';

const client = new AidaClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.aida-platform.com'
});

// Control a light
await client.devices.lights.control(1, {
  power: 'on',
  brightness: 80
});

// Get all HVAC devices
const hvacDevices = await client.devices.hvac.list();

Python​

from aida_platform import AidaClient

client = AidaClient(
    api_key='your-api-key',
    base_url='https://api.aida-platform.com'
)

# Control a light
client.devices.lights.control(1, {
    'power': 'on',
    'brightness': 80
})

# Get all HVAC devices
hvac_devices = client.devices.hvac.list()

Next Steps​

Ready to control devices? Start with our Quick Start Guide or explore specific device types for detailed control options.