Real-time Websocket

Specifications for interaction with PlaceOS realtime websocket

The real-time WebSocket works in conjunction with the PlaceOS API. The PlaceOS API can list systems and zones that are then used with the WebSocket.

PlaceOS exposes the endpoint wss://<app_domain>/api/engine/v2/systems/control to allow for real-time communication. The endpoint requires a valid API token.

API tokens are sent in the header of the request.

X-API-Key: <token>

The /websocket endpoint is used to provide real-time interaction with modules running on Engine. It provides an interface to build efficient, responsive user interfaces, monitoring systems and other extensions which require live, two-way or asynchronous interaction.

Heartbeat

The client can periodically send a raw string as an application layer keep-alive.

ping

the server will respond

pong

Commands

Command messages are the basis for interacting with the real-time API. All commands take the form of a JSON payload, and will return a JSON response.

Attribute	Type	Description
id	number or string	A unique ID to associated with the command. This is returned as part of the response. Generally an incrementing counter, however any string or numerical value may be used.
cmd	string	The command type. One of bind, unbind, exec, debug, orignore.
sys	string	The system ID that the command targets.
mod	string	The name of the module that the command targets.
name	string	Method, or status variable name to be interacted with.

5 commands available for the user to perform over the API. These are:

Bind

bind command allows the user to bind to status variable values on a given driver module.

Example of a bind command:

{
  
  "id": 1, # Any number
  "cmd": "bind", # ID of the PlaceOS system
  "sys": "sys-1234", # Name of the PlaceOS module
  "mod": "Bookings",
  "index": 1, # Non-zeroed index of the module in the system. i.e. 1st index is 1
  "name": "bookings" # Name of the variable to bind to
}

After a successful bind you will receive a success response from the server. The ID of the response will match the ID of the message.

{
    "id": 1,
    "type": "success",
    "meta": {
        "sys": "sys-1234",
        "mod": "Bookings",
        "index": 1,
        "name": "bookings"
    }
}

After binding to a status variable the WebSocket will post the current value and any changes to the value until the unbind command is issued.

Example of the value change notification:

{
    "id": 18,
    "type": "notify",
    "value": "[]", # Stringified JSON
    "meta": {
        "sys": "sys-1234",
        "mod": "Bookings",
        "index": 1,
        "name": "bookings"
    }
}

Unbind

unbind command terminates an existing binding for the given driver module.

Example of a unbind command:

{
  "id": 2, # Any number
  "cmd": "unbind",
  "sys": "sys-1234", # ID of the PlaceOS system
  "mod": "Bookings", # Name of the PlaceOS module
  "index": 1, # Non-zeroed index of the module in the system. i.e. 1st index is 1
  "name": "bookings" # Name of the variable to bind to
}

After a successful unbind you will receive a success response from the server. The ID of the response will match the ID of the message.

{
    "id": 2,
    "type": "success",
    "meta": {
        "sys": "sys-1234",
        "mod": "Bookings",
        "index": 1,
        "name": "bookings"
    }
}

Execute

The exec command allows you to call available methods on the target driver.

{
  "id": 3, # Any number
  "cmd": "exec",
  "sys": "sys-1234", # ID of the PlaceOS system
  "mod": "Bookings", # Name of the PlaceOS module
  "index": 1, # Non-zeroed index of the module in the system. i.e. 1st index is 1
  "name": "make_booking", # Name of the method to call
  "args": [1631058815] # List of arguments to pass into the function
}

After a successful execution you will receive a success response from the server. The ID of the response will match the ID of the message. The value return is the value returned by the called method.

{
    "id": 3,
    "type": "success",
    "meta": {
        "sys": "sys-1234",
        "mod": "Bookings",
        "index": 1,
        "name": "bookings"
    },
    "value": {}
}

Debug

This lowers the drivers log level to debug and forwards messages to the connection.

{
    "id": 4,
    "cmd": "debug",
    "sys": "sys-Z6XXA-Kc_v",
    "mod": "Bookings",
    "index": 1,
    "name": "debug"
}

Responds with the module ID that uniquely identifies the code being monitored

{
    "id": 4,
    "type": "success",
    "mod_id": "mod-Z6XXB1doL4",
    "meta": {
        "sys": "sys-Z6XXA-Kc_v",
        "mod": "Bookings",
        "index": 1
    }
}

Log messages are then sent to the browser

{
    "type": "debug",
    "mod": "mod-Z6XXB1doL4",
    "klass": "::Some::Display",
    "level": "debug",
    "msg": "input changed to HDMI"
}

Ignore

The ignore command cancels any debug subscriptions and the log level is restored (if no other connections are debugging).

{
    "id": 5,
    "cmd": "ignore",
    "sys": "sys-Z6XXA-Kc_v",
    "mod": "mod-Z6XXB1doL4",
    "index": null,
    "name": "ignore"
}

responds

{
    "id": 5,
    "type": "success"
}

Errors

Name	Code	Description
parse error	0	invalid JSON sent to the server
bad request	1	request was missing required fields
access denied	2	you don’t have permission to access this system, the access attempt is logged
request failed	3	an error was raised or a promise rejected when processing the request
unknown command	4	the command type unknown, the connection is logged as suspicious
system not found	5	the system does not exist
module not found	6	the module does not exist in the system
unexpected failure	7	a framework level error occurred (this should never happen)