Commands

Send a command to a device. Commands are delivered over the real-time gateway channel, so the device must be online to receive one — always check the queued field in the response to confirm delivery.

Request body

Example

curl -X POST https://api.plexus.company/v1/sources/robot-01/commands \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "reboot"}'

curl -X POST https://api.plexus.company/v1/sources/robot-01/commands \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "set_speed", "params": {"rpm": 3000}}'

Response

{ "queued": true }

queued reflects delivery: true means the command reached a connected device. If the device is offline, the request still returns HTTP 200 with { "queued": false } and the command is dropped — so inspect this field rather than relying on the status code. queued: false also comes back when the device is online but its command buffer (64 commands) is full. A 502 is returned only when the gateway itself is unreachable.

Receiving commands on device

Register handlers with the SDK before the first send() call so they are advertised during connection:

import time

from plexus import Plexus

px = Plexus(api_key="YOUR_API_KEY", source_id="robot-01")

def handle_set_speed(command, params):
    motor.set_rpm(params["rpm"])
    return {"ok": True}

def handle_reboot(command, params):
    import subprocess
    subprocess.Popen(["reboot"])

px.on_command("set_speed", handle_set_speed)
px.on_command("reboot", handle_reboot)

while True:
    px.send("motor.rpm", motor.current_rpm())
    time.sleep(0.1)

The handler receives (command_name, params_dict) and can return a dict result or raise to signal an error.