Send commands to devices

Why

A button that says "Sent" tells you nothing about whether pod-7 powered off. A retried request can run a command twice. And someone who should only look at a dashboard should never be able to press it. So commands are declared by your code, checked twice, recorded, and shown only as far as the device has confirmed.

How it works

Your client declares its commands when it connects. Each one has a name, a title, parameters and a danger level. Parameters are flat: strings, integers, numbers and booleans, with limits like minimum, maximum and enum. Plexus checks them when you press Run, and the SDK checks them again when the command arrives.

The danger level sets the confirmation. Normal runs on one click. Dangerous asks you to review the target and every parameter. Critical also makes you type the device's slug.

Every run expires, after 30 seconds by default (5 seconds to an hour). An offline device gets the run when it reconnects, if it hasn't expired. If the connection drops after sending and the device can't say whether it ran, the run shows "Outcome unknown" and is never retried automatically.

• Queued, then Sent · waiting for acknowledgement
• Acknowledged: the device checked the parameters and accepted it
• Running, then Succeeded or Failed, with the result your handler returned
• Expired · never ran, or Outcome unknown

Using it

Create an API key with "Receive commands" checked on the API Keys page. Existing keys don't gain command access. Then declare a command with the Python SDK (0.12.0 or later):

from plexus import Plexus

px = Plexus(source_id="pod-7")

@px.command("power_off", title="Power off", danger="critical",
            idempotent=True, expires_in=30,
            params={"outlet": {"type": "integer", "minimum": 1, "maximum": 8}})
def power_off(run, outlet):
    pdu.outlet(outlet).off()          # your code
    return {"outlet": outlet, "state": "off"}

px.serve()   # or keep calling px.send(...) in your own loop

Where you run it

The Commands page lists every command your devices offer and whether each device is connected. Select rows to run one command on up to 25 devices; each gets its own run. History shows who ran what and how it ended, step by step. Declarations shows when a command changed. Fleet versions flags a device missing a command its fleet mates have.

Or add a Command panel to a dashboard: a parameter form and a Run button that turns into the live state.

Limits

Editors and admins can run commands by default; custom roles can change that. Viewers, share links and embeds never see a Run button, and API keys can't trigger a run. Commands use the SDK's live connection, which needs a paid plan. Python is the only SDK today. Progress updates and cancelling a running command aren't in this release.