Control Gateway Model Objects

The document details standard response objects returned by the Control Gateway.

Referenced Entities

The Control Gateway uses Pydantic to marshal JSON payloads to native Python objects. Pydantic model objects have been included for reference, or use in your own Python based application.

ControlRequestPayload

All request objects extend from ControlRequestPayload which in-turn implements Pydantic's BaseModel. This model does not currently implement any additional logic, but it is provided for convenience for operations like isinstance(message, ControlRequestPayload).

class ControlRequestPayload(BaseModel):
    pass

ControlResponseType

Request Objects use a string literal for the response object type. The provided model objects reference the following literals:

class ControlRequestType(str, Enum):
    CONTROL_GET = 'ControlGet'
    CONTROL_SET = 'ControlSet'
    VALUE_SET = 'ValueSet'
    VALUSE_SET_BOOLEAN = 'ValueSetBoolean'

ControlResponsePayload

All response objects extend from ControlResponsePayload which in-turn implements Pydantic's BaseModel. The model does not currently implement any additional logic, but it is provided for convienience for operations like isinstance(message, ControlResponsePayload).

class ControlResponsePayload(BaseModel):
    pass

ControlResponseType

Response Objects use a string literal for the response object type. The provided model objects reference the following literals:

class ControlResponseType(str, Enum):
    ACK = 'Ack'
    CONTROL_STATE = 'ControlState'
    CONTROL_STATES = 'ControlStates'
    MEDIA_STATE = 'MediaState'
    POWER_STATE = 'PowerState'
    VERSION = 'Version'

Request Objects

ControlGet

Get the value of a generic control pre-assigned, or a named constant within a control system.

Field	Type	Default	Description
type	str	ControlGet	Message type constant
id	str		The pre-define ID or constant of the control to get

Model object:

class ControlGet(ControlRequestPayload):
    id: Union[str]

Example Request:

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "control",
    "data": {
        "type": "ControlGet",
        "id": "2060"
    },
    "mid": "123abc"
}

ControlSet

Set the value of a generic control pre-assigned, or a named constant within a control system.

Field	Type	Default	Description
type	str	ControlGet	Message type constant
id	str		The pre-define ID or constant of the control to get
int	int	str

Model object:

class ControlSet(ControlRequestPayload):
    id: Union[str]
    value: Union[int, str]

Example Request:

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "control",
    "data": {
        "type": "ControlSet",
        "id": "2060",
        "value": 256
    },
    "mid": "123abc"
}

ValueSetBoolean

Set the value of a boolean control such as on/off, low/high or true/false. This is used for control such a power.

Field	Type	Default	Description
type	str	ValueSetBoolean	Message type constant
value	bool		Boolean value true or false to set the control to

Model Object:

class ValueSetBoolean(ControlRequestPayload):
    value: bool

Example Request:

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "power",
    "data": {
        "type": "ValueSetBoolean",
        "value": true
    },
    "mid": "123abc"
}

ValueSet

Set the value of a named control within an interface such as volume where the control ID is implied by the method name, such a volume.

Field	Type	Default	Description
type	str	ValueSet	Message type constant
value	int	str

Model Object

class ValueSet(ControlRequestPayload):
    value: Union[int, str]

Example Request:

{
    "msg": "io.upswell.xagent.ControlRequest",
    "device": "<device alias>",
    "method": "volume",
    "data": {
        "type": "ValueSet",
        "value": 0.5
    },
    "mid": "123abc"
}

Response Objects

Ack

Object representing an acknowlegdement that a command was acknowledged (or not).

Field	Type	Default	Description
type	str	Ack	Message type constant
ack	bool	False	Whether the player is in fullscreen mode
raw	str	None	(optional) Raw (unparsed) value provide back from the device

Model Object:

class AckState(ControlResponsePayload):
    type: Literal[ControlResponseType.ACK] = ControlResponseType.ACK
    ack: bool
    raw: Optional[str] = None

Example Response:

{
    "msg": "io.upswell.xagent.ControlResponse",
    "device": "<device alias>",
    "method": "status",
    "data": {
        "type": "Ack",
        "ack": true
    },
    "status_code": 200,
    "mid": "123abc"
}

ControlState

A pre-assigned controls state within a Control System such as a DSP or Show Controller.

Field	Type	Default	Description
type	str	ControlState	Message type constant
id	str		The ID of the control being returned
value	int		The current value of the control normalized to 0 (low, off, false), 1 (high, on, true)
raw	str	None	(optional) Raw (unparsed) value provide back from the device

Model object:

class ControlState(ControlResponsePayload):
    type: Literal[ControlResponseType.CONTROL_STATE] = ControlResponseType.CONTROL_STATE
    id: str
    value: int
    raw: Optional[str] = None

Example Response:

{
    "msg": "io.upswell.xagent.ControlResponse",
    "device": "<device alias>",
    "method": "control",
    "data": {
        "type": "ControlState",
        "id": "2060",
        "value": 0.5,
        "raw": "2056"
    },
    "status_code": 200,
    "mid": "123abc"
}

ControlStates

A pre-assigned controls states (multiple) within a Control System such as a DSP or Show Controller.

Field	Type	Default	Description
type	str	ControlStates	Message type constant
values	List[ControlState]

Model object:

class ControlStates(ControlResponsePayload):
    type: Literal[ControlResponseType.CONTROL_STATES] = ControlResponseType.CONTROL_STATES
    values: List[ControlState] = []

Example Response:

{
    "msg": "io.upswell.xagent.ControlResponse",
    "device": "<device alias>",
    "method": "controls",
    "data": {
        "type": "ControlStates",
        "values" [
            {
                "type": "ControlState",
                "id": "2060",
                "value": 0.5,
                "raw": "2056"
            },
            {
                "type": "ControlState",
                "id": "2061",
                "value": 0,
                "raw": "0"
            }
        ]
    },
    "status_code": 200,
    "mid": "123abc"
}

PowerState

Field	Type	Default	Description
on	bool	—	Current power state of the device (true = on, false = off)
was_on	bool?	None	Optional previous power state before the last change

Example Response:

{
    "msg": "io.upswell.xagent.ControlResponse",
    "device": "<device alias>",
    "method": "get",
    "data": {
        "type": "PowerState",
        "on": true,
        "was_on": true
    },
    "status_code": 200,
    "mid": "123abc"
}

RequestError

Field	Type	Default	Description
error	str	—	The error generated by the request

Example Response:

{
    "msg": "io.upswell.xagent.ControlResponse",
    "device": "<device alias>",
    "method": "get",
    "data": {
        "type": "RequestError",
        "error": "Error string ..."
    },
    "status_code": 400,
    "mid": "123abc"
}

Version

Field	Type	Default	Description
type	str	Ack	Message type constant
version	str		The device version

Example Response:

{
    "msg": "io.upswell.xagent.ControlResponse",
    "device": "<device alias>",
    "method": "status",
    "data": {
        "type": "Version",
        "version": "1.0.0"
    },
    "status_code": 200,
    "mid": "123abc"
}