Commands API

Send commands to your devices and read sensor data on demand.

Not a developer? You don't need this page! Use the Palpable app or talk to PAL to control your devices.

Your API key

Send Command

Execute a command on a device module.

POST /api/devices/command

const res = await fetch('https://palpable.technology/api/devices/command', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deviceId: '550e8400-...',
    moduleId: 'modulino-pixels',
    tool: 'setAll',
    params: { r: 255, g: 0, b: 128 }
  })
})
const data = await res.json()

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

Response

{
  "success": true,
  "message": "Tool \"setAll\" executed on 1 device(s)",
  "results": [
    {
      "deviceId": "550e8400-...",
      "deviceName": "Living Room Hub",
      "moduleId": "modulino-pixels",
      "success": true,
      "method": "websocket"
    }
  ]
}

Command Delivery

Method	Description
`websocket`	Delivered in real-time (device online)
`queued`	Device offline -- command will execute when it reconnects

Read Sensor

Read a current sensor value.

POST /api/devices/read

const res = await fetch('https://palpable.technology/api/devices/read', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deviceId: '550e8400-...',
    moduleId: 'modulino-thermo',
    tool: 'read_temperature'
  })
})
const reading = await res.json()
console.log(reading.value, reading.unit) // 23.5 celsius

Response

{
  "deviceId": "550e8400-...",
  "moduleId": "modulino-thermo",
  "tool": "read_temperature",
  "value": 23.5,
  "unit": "celsius",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Read Commands

Tool	Module Types	Returns
`read_temperature`	modulino-thermo, bme280	`{ value, unit: "celsius" }`
`read_humidity`	modulino-thermo, bme280	`{ value, unit: "percent" }`
`read_pressure`	bme280	`{ value, unit: "hPa" }`
`read_lux`	veml7700	`{ value, unit: "lux" }`
`read_voc`	sgp40	`{ value, unit: "index" }`
`read_distance`	modulino-distance	`{ value, unit: "mm" }`
`read_all`	Any	All available sensor values

Common Actuator Commands

Tool	Module Types	Parameters
`beep`	modulino-buzzer	`{ frequency: Hz, duration: ms }`
`setAll`	modulino-pixels	`{ r: 0-255, g: 0-255, b: 0-255 }`
`setPixel`	modulino-pixels	`{ index, r, g, b }`
`clear`	modulino-pixels	None

Broadcast Commands

Omit deviceId to send a command to every device with the matching module:

{
  "moduleId": "modulino-pixels",
  "tool": "setAll",
  "params": { "r": 0, "g": 255, "b": 0 }
}

Error Handling

Device Offline

Commands are queued and execute when the device reconnects.

Module Not Found

{
  "success": false,
  "error": "Module not found",
  "message": "Could not find module modulino-pixels on your devices."
}

Devices API Behaviors API