WebSocket

The WebSocket plugin creates a websocket server on the given ip address and port. The default behaviour is to listen on all available network interfaces on port 5005. When two or more websocket plugins are initialises, a different port must be specified, the instances from 2 upwards will error out.

A server name can be specified with the options/server_name parameter. This defaults to ‘dcontrol’.

SSL

SSL handshaking is nog supported by the plugin. It’s intended use is that it will be proxied by a webserver, e.g. NGINX which will terminate the SSL encryption.

Supported data types

Data type	QVariant bool	QVariant int	QVariant float	QVariant string
WebSocket::bool	•
WebSocket::double		⤶	•
WebSocket::string				•
WebSocket::array	n/a
WebSocket::object	n/a
WebSocket::null	n/a

Configuration options

The minimal device config when using the default options would be:

settings.yml

devices:
  - type: websocket
    name: websocketserver

This defaults to listen on all available interfaces on port 5005.

A complete config would look like this:

settings.yml

devices:
  - type: websocket
    name: websocketserver
    options:
      ip:
        10.0.0.1 # the ip address the websocket server will bind to,
        # defaults to Any address, which means the
        # server will listen on all interfaces/addresses
      port: 5005 # defaults to port 5005
      server_name:
        myserver # defaults to "dcontrol"
        # This is the server name used in the HTTP
        # handshake phase to identify the server
      json_schema: '{"key":"val","arr":{},"dcontrol":{"data":"%PLACEHOLDER%"}}'

where

type

is always “websocket” as this is the name of this plugin.

name

unique arbitrary name.

options/ip

the ip address of the interface to listen on. (default: All)

options/port

the tcp port the websocket server is listening on. (default: 5005)

options/server_name

the identification name for the websocket server. (default: dcontrol)

options/json_schema

a custom json schema to use as the data container. (default: {"servername:{"data":"%PLACEHOLDER%"}})

json_schema

The json schema defines a custom json schema to be used for sending and receiving data. By default, the following schema is used:

{
  "dcontrol": {
    "data": {
      "%PLACEHOLDER%"
    }
  }
}

The placeholder gets replaced with the key’s and values defined in the mapping settings. The end result will then look like:

{
  "dcontrol": {
    "data": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

Also, “dcontrol” is replaced by the options/server_name value if it is defined.

When sending data the entire structure is honored and send over, data send to the websocket must mach the structure, but can omit the additional key/value pairs.

Make sure that the value in the yaml file is valid json, so using double quotes for the keys and string values, the entire string should then be surrounded with single quotes to make it valid yaml.

Example

settings.yml

devices:
  - type: websocket
    name: websocketserver
    options:
      ip: 10.0.0.1
      server_name: myserver
      json_schema: '{"key":"val","arr":{},"dcontrol":{"data":"%PLACEHOLDER%"}}'

mappings:
  - name: test0
    from:
      name: GP111
      address: 0
      type: bool
    to:
      name: websocket
      address: in0
      type: bool
  - name: test1
    from:
      name: GP111
      address: 1
      type: bool
    to:
      name: websocket
      address: in1
      type: bool
  - name: test2
    from:
      name: websocket
      address: out0
      type: bool
    to:
      name: GP111
      address: 0
      type: bool
  - name: test2
    from:
      name: websocket
      address: out1
      type: bool
    to:
      name: GP111
      address: 1
      type: bool

When a new client connects, the entire json object will be sent:

{
  "dummy-key": "dummy-val",
  "dummy-array": {
    "dummy-array-key": "dummy-array-val",
    "dummy-array-key2": "dummy-array-val2"
  },
  "myserver": {
    "data": {
      "in0": 0,
      "in1": 0
    }
  }
}

When GP111 address 0 changes to 1, the update will be sent:

{
  "dummy-key": "dummy-val",
  "dummy-array": {
    "dummy-array-key": "dummy-array-val",
    "dummy-array-key2": "dummy-array-val2"
  },
  "myserver": {
    "data": {
      "in0": 1
    }
  }
}

setting GP111 address 0 to 1 can be done by sending the following json to the server:

{
  "myserver": {
    "data": {
      "out0": 1
    }
  }
}