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:
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.
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:
Unbind
unbind
command terminates an existing binding for the given driver module.
Example of a unbind
command:
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.
Execute
The exec
command allows you to call available methods on the target driver.
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.
Debug
This lowers the drivers log level to debug and forwards messages to the connection.
Responds with the module ID that uniquely identifies the code being monitored
Log messages are then sent to the browser
Ignore
The ignore
command cancels any debug subscriptions and the log level is restored (if no other connections are debugging).
responds
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)
Last updated