XPress Remote Actions API Guide

This guide explains how to use the Python API in /XPressRemoteWrapper/xpress_actions_interface.py to expose remote actions to XPress.

What This API Does

XPressActionController provides the callback features. It notifies UI about all available features and the user can use them for tests (Remote execution).

Supported action groups: - power - measure - switch - rpc

When XPress sends a JSON action request, the controller: 1. Finds the registered callback for the action type and channel. 2. Calls your callback with (channel, *arguments). 3. Sends a normalized JSON response back to XPress.

Core Class

XPressActionController

Create one controller, register channels, then run main_loop().

from XPressRemoteWrapper.xpress_actions_interface import XPressActionController

xpress = XPressActionController(ip="0.0.0.0", port=8082)
# register channels here
xpress.main_loop()

Constructor:

XPressActionController(ip="0.0.0.0", port=8080)

Parameters: - ip: bind address used by the remote wrapper TCP communication. - port: TCP port used by XPress to connect.

Available Methods

add_power_supply_channel(name, callback)

Registers a power channel.

Expected callback signature:

def callback(channel: str, state: bool, voltage: float, current_limit: float):
    ...

Recommended return:

return power_result(state="on", voltage=5.0, current_limit=1.0, message="Applied")

add_measure_channel(name, types, callback)

Registers a measurement channel and its supported measurement types.

Expected callback signature:

def callback(channel: str, measure_type: str, duration: float, samples: int):
    ...

types is a list of measurement type names, for example:

["voltage", "current"]

Recommended return:

return measure_result(values=[0.1, 0.2, 0.3], message="OK")

add_switch_channel(name, types, callback)

Registers a switch matrix channel.

Expected callback signature:

def callback(channel: str, switch_type: str, state: bool, delay: float):
    ...

types is a list of supported switch types for that matrix.

Recommended return:

return switch_result(matrix=switch_type, state="on", delay_ms=10, message="Switched")

add_rpc_channel(name, json, callback)

Registers an RPC channel with a JSON schema-like descriptor for the UI.

Expected callback signature:

def callback(channel: str, json_dict: dict):
    ...

json describes request fields, for example:

{"filename": "str"}

Recommended return:

return rpc_result(data={"echo": True}, message="Done")

main_loop()

Starts processing requests. This is a blocking loop.

xpress.main_loop()

Callback Return Helpers

Use these helpers from xpress_actions_interface.py so payloads stay consistent.

Power helpers

power_result(state: str, voltage: float, current_limit: float, message: str = "")
power_error(message: str = "Power command failed")

Power status schema:

{
  "state": "on" | "off",
  "voltage": float,
  "current_limit": float
}

Switch helpers

switch_result(matrix: str, state: str, delay_ms: int = 0, message: str = "")
switch_error(message: str = "Switch command failed")

Switch status schema:

{
  "matrix": str,
  "state": "on" | "off",
  "delay_ms": int
}

Measure helpers

measure_result(values, message: str = "")
measure_error(message: str = "Measurement failed")

Allowed values shapes: - scalar number - 1D list, example [0.1, 0.2, 0.3] - 2D list, example [[t0, t1], [v0, v1]]

RPC helpers

rpc_result(data: dict, message: str = "")
rpc_error(message: str = "RPC call failed")

Request and Response Shape

Incoming request format:

{
  "type": "power | measure | switch | rpc",
  "channel": "Channel Name",
  "arguments": []
}

General response behavior: - The original request is echoed. - result is added with a type-specific payload. - For missing callbacks, API returns:

{
  "result": false,
  "message": "Could not find associated function"
}

Notes and Best Practices

• Keep callbacks fast. Long blocking calls delay all action processing.
• Use helper factories (*_result, *_error) to keep response fields correct.
• For switch callbacks, return string state values ("on" or "off") in switch_result.
• The controller automatically publishes channel metadata to the UI through the info channel.