Commands & Control

Commands let you send instructions from the Plexus dashboard to a connected device and see results in real time. The dashboard auto-generates UI controls (sliders, dropdowns, toggles) from the command schema you define in your agent code.

How It Works

Your device registers commands with the Python agent, including parameter schemas
The dashboard reads those schemas and renders appropriate input controls
You fill in the parameters and click Execute
The command is sent over WebSocket to the device
The device executes the command and returns a result
The dashboard displays the result

Commands travel through the PartyKit WebSocket server, so your device must be connected via plexus run (not HTTP-only mode).

Defining Commands

Define commands in your Python agent using the @px.command decorator:

from plexus import Plexus, param
 
px = Plexus()
 
@px.command("set_speed", description="Set motor speed")
@param("rpm", type="float", min=0, max=10000, unit="rpm")
async def set_speed(rpm):
    motor.set_rpm(rpm)
    return {"actual_rpm": motor.read_rpm()}
 
@px.command("set_mode", description="Set operating mode")
@param("mode", type="enum", options=["idle", "run", "calibrate"])
async def set_mode(mode):
    controller.set_mode(mode)
    return {"mode": mode, "status": "ok"}
 
@px.command("toggle_led", description="Toggle status LED")
@param("enabled", type="bool")
async def toggle_led(enabled):
    gpio.write(LED_PIN, enabled)
    return {"led": enabled}

Auto-Generated UI

The dashboard generates input controls based on parameter types:

Parameter Type	UI Control
`float` / `int`	Slider (when `min`/`max` defined) or number input
`bool`	Toggle switch
`enum`	Dropdown selector
`string`	Text input

When you provide min, max, and unit metadata, the slider shows the range and unit label.

Executing Commands

From the dashboard:

Navigate to your device's detail page
Open the Commands tab
Select a command from the list
Set the parameter values using the generated controls
Click Execute

The result appears below the command form once the device responds. If the command takes time to complete, a progress indicator shows the execution status.

Execution Status

Status	Description
Pending	Command sent, waiting for device to acknowledge
Running	Device is executing the command
Completed	Command finished, result available
Failed	Command raised an error on the device
Timeout	Device did not respond within 30 seconds
Cancelled	Command was cancelled from the dashboard

Command History

Every command execution is logged. View the history from the Commands tab on the device page. Each entry shows:

Command name and parameters
Execution timestamp
Duration
Status and result (or error message)

Error Handling

If a command raises an exception on the device, the error is sent back to the dashboard:

@px.command("self_test", description="Run hardware self-test")
async def self_test():
    result = hardware.run_diagnostics()
    if not result.passed:
        raise Exception(f"Self-test failed: {result.reason}")
    return {"status": "passed", "duration_ms": result.duration}

The dashboard displays the error message in the result area.

Next Steps

Python Agent Commands — Full reference for defining commands
Dashboards — Visualize telemetry alongside command controls

Alerts Overview