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.

POST/v1/sources/{source_id}/commands

Request body

Field	Type	Required	Description
`command`	string	✓	Command name
`params`	object	—	Optional parameters passed to the handler

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. A 502 is returned only when the gateway itself is unreachable.

Receiving commands on device


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.