Websocket¶

Warning

This functionality may undergo modifications in future updates and it is recommended to use an alternative feature if one is available. Alternatively, please carefully review the changelog when performing updates for comprehensive information.

Capabilities¶

Capability	Support	Comment
HTTP support
HTTPS support
Register on values changes		See register to values
Un-register on values changes		See register
Update values		See updating value

Concept¶

Overview¶

It is possible to access values directly with the same concept as the web-client does.

Warning

This functionality may undergo modifications in future updates, and it is recommended to use an alternative feature if one is available. Alternatively, please carefully review the changelog when performing updates for comprehensive information.

Performance consideration¶

Using this feature extensively for the osp-web may result in elevated resources consumption, particularly when subscribing to a wide array of values that undergo frequent changes. Exercise caution regarding the volume of values and events you subscribe to in order to effectively manage resources cost.

Register a WebSocket¶

To access WebSocket endpoints, an HTTP(s) request on http://[HOSTNAME]:5000/osp/web/api/websocket with authentication header is required. The result is an identifier that can be passed to WebSocket endpoints with ?id= parameter.

Register/unregister to values¶

Overview¶

Registering to values enabled the fact that the websocket will be notified each time a value is changed.

Usage¶

Register

Subscribe to receive updates on changes to the specified Values. Upon registration for a particular value, the most recently published value is transmitted to the websocket.

Note

The request can be made multiple times but trying to register multiple times on the same Value will have no effect.

{
  "requestId": "d3e5e69f-ea95-48c9-acd7-fe2c332626c9",
  "requestName": "register-values",
  "values": [
    "root.office.light",
    "root.office.door"
  ]
}

Un-register

Un-register for listening on changes of specified Values. The request can be made multiple times.

Trying to un-register on a non-registered Value will have no effect.

{
  "requestId": "d3e5e69f-ea95-48c9-acd7-fe2c332626c9",
  "requestName": "unregister-values",
  "values": [
    "root.office.light",
    "root.office.door"
  ]
}

Use-case¶

Create a dedicated front-end with some values
Forward values to another application which doesn’t support standard protocols

Update a values¶

Overview¶

Updating a value send a request to the module owning the value and it will update it if it support the operation.

Usage¶

Be aware that :

Trying to update a Value owned by a module that does not support this operation or that does not exist will have no effect.
There is no lock on changing value. This means there can be concurrent modifications and only the last one received will take effect

{
  "requestId": "d3e5e69f-ea95-48c9-acd7-fe2c332626c9",
  "requestName": "update-value",
  "value": "root.office.light",
  "content": 255
}

{
  "requestId": "d3e5e69f-ea95-48c9-acd7-fe2c332626c9",
  "requestName": "update-value",
  "value": "root.office.light",
  "content": "on"
}

{
  "requestId": "d3e5e69f-ea95-48c9-acd7-fe2c332626c9",
  "requestName": "update-value",
  "value": "root.office.light",
  "content": true
}

Note

The type of the content field depends on the value type.

Use-case¶

Call a script from an external service
Update counter from an external service