Commands API

Send commands to your devices and read sensor data in real-time.

Send Command

Execute a tool/command on a device module.

POST /api/devices/command

Request Body

{
  "deviceId": "550e8400-e29b-41d4-a716-446655440000",
  "moduleId": "NeoPixel",
  "tool": "set_pixel",
  "params": {
    "index": 0,
    "r": 255,
    "g": 0,
    "b": 128
  }
}

Field	Type	Required	Description
`deviceId`	uuid	No	Target specific device (omit for all devices)
`moduleId`	string	No	Target specific module type
`tool`	string	Yes	The tool/command to execute
`params`	object	No	Tool-specific parameters

Response

{
  "success": true,
  "message": "Tool \"set_pixel\" executed on 1 device(s)",
  "results": [
    {
      "deviceId": "550e8400-e29b-41d4-a716-446655440000",
      "deviceName": "Living Room Hub",
      "moduleId": "NeoPixel",
      "moduleName": "RGB LED Strip",
      "success": true,
      "method": "websocket",
      "result": { "status": "ok" }
    }
  ],
  "summary": {
    "total": 1,
    "successful": 1,
    "queued": 0,
    "failed": 0
  }
}

Command Delivery

Commands are delivered via WebSocket for immediate execution. If a device is offline, commands are queued and will be executed when the device reconnects.

Method	Description
`websocket`	Command delivered in real-time
`queued`	Device offline, command queued for later

Read Sensor

Read a current sensor value from a device.

POST /api/devices/read

Request Body

{
  "deviceId": "550e8400-e29b-41d4-a716-446655440000",
  "moduleId": "SHT40",
  "tool": "read_temperature"
}

Field	Type	Required	Description
`deviceId`	uuid	Yes	The device to read from
`moduleId`	string	Yes	The module to read from
`tool`	string	Yes	The read tool to execute
`params`	object	No	Tool-specific parameters

Response

{
  "deviceId": "550e8400-e29b-41d4-a716-446655440000",
  "moduleId": "SHT40",
  "tool": "read_temperature",
  "value": 23.5,
  "unit": "celsius",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Tools

Sensors

Tool	Module Types	Description	Returns
`read_temperature`	SHT40, SHTC3, BMP280	Read temperature	`{ value: number, unit: "celsius" }`
`read_humidity`	SHT40, SHTC3	Read relative humidity	`{ value: number, unit: "percent" }`
`read_lux`	VEML7700	Read ambient light	`{ value: number, unit: "lux" }`
`read_pressure`	BMP280	Read barometric pressure	`{ value: number, unit: "hPa" }`
`read_voc`	SGP40	Read VOC index	`{ value: number, unit: "index" }`
`read_all`	Any	Read all available sensors	`{ temperature: ..., humidity: ..., ... }`

Actuators

Tool	Module Types	Description	Parameters
`turn_on`	Relay, NeoPixel	Turn output on	None
`turn_off`	Relay, NeoPixel	Turn output off	None
`toggle`	Relay, NeoPixel	Toggle state	None
`set_brightness`	NeoPixel	Set LED brightness	`{ brightness: 0-255 }`
`set_color`	NeoPixel	Set LED color	`{ r: 0-255, g: 0-255, b: 0-255 }`
`set_pixel`	NeoPixel	Set individual pixel	`{ index: number, r, g, b }`
`play_tone`	Buzzer	Play a tone	`{ frequency: Hz, duration: ms }`

Broadcast Commands

To send a command to all devices with a specific module type, omit the deviceId:

{
  "moduleId": "NeoPixel",
  "tool": "set_color",
  "params": { "r": 0, "g": 255, "b": 0 }
}

This will execute the command on every device that has a NeoPixel module.

Error Handling

Device Offline

{
  "success": true,
  "message": "Tool \"set_color\" queued for 1 offline device(s)",
  "results": [
    {
      "deviceId": "...",
      "success": false,
      "method": "queued",
      "queued": true,
      "error": "Device not connected"
    }
  ]
}

Module Not Found

{
  "success": false,
  "error": "Module not found",
  "message": "Could not find module NeoPixel on your devices.",
  "availableDevices": [
    {
      "id": "...",
      "name": "Living Room Hub",
      "modules": [
        { "id": "SHT40", "name": "Temperature & Humidity" }
      ]
    }
  ]
}

Devices API Automations API