Websocket Interface

Websocket Interface

Hubitat allows for opening and maintaining a connection to a websocket endpoint from the hub. All code needs to be contained in a driver; there is no option to open a websocket connection from an app. Hubitat provides methods to connect and disconnect to the endpoint. In addition, it is required to create a method in the driver that accepts incoming messages (parse) and another method that will be called with any status updates for the endpoint (webSocketStatus).

Hubitat-Provided Methods (Since 2.1.2)

connect

Signature

  • void connect(String url)
  • void connect(String url, [options (name/value pairs)])

Parameters

  • url - The url to connect to.
  • options - Optional parameters to configure the web socket connection. Possible values:
    • byteInterface - defaults to 'false'. If set to true, messages are handled as byte arrays and will be hex string encoded.
    • pingInterval - The number of seconds to send a ping message. Defaults to 30.
    • headers - A Map of key/value pairs to send as header values when connecting to the web socket server.

Examples

// Connect with basic settings
interfaces.webSocket.connect("http://websocket.com")

// Connect with headers and adjusted pingInterval
interfaces.webSocket.connect("http://websocket.com", pingInterval: 45, headers: ["header1":"value1"])

close

Signature

void close()

Examples

// Close connection
interfaces.webSocket.close()

sendMessage

Signature

void sendMessage(String message)

Parameters

message - The message to send. If this connection is a byte interface, then this must be a hex encoded String.

Examples

// Send string message
interfaces.webSocket.sendMessage("My message")

Hubitat-Provided Methods (Deprecated)

These methods were available in earlier platform versions and may be removed in the future. New code should use the methods above.

webSocketConnect

Signature

void hubitat.helper.InterfaceUtils.webSocketConnect(DeviceWrapper device, String url)` `void hubitat.helper.InterfaceUtils.webSocketConnect(DeviceWrapper device, String url, [options (name/value pairs)])

Parameters

  • device - The current device that is calling the method.
  • url - The url to connect to.
  • options - Optional parameters to configure the web socket connection. Possible values:
    • byteInterface - defaults to 'false'. If set to true, messages are handled as byte arrays and will be hex string encoded.
    • pingInterval - The number of seconds to send a ping message. Defaults to 30.
    • headers - A Map of key/value pairs to send as header values when connecting to the web socket server.

Examples

// Connect with basic settings
hubitat.helper.InterfaceUtils.webSocketConnect(device, "http://websocket.com")

// Connect with headers and adjusted pingInterval
hubitat.helper.InterfaceUtils.webSocketConnect(device, "http://websocket.com", pingInterval: 45, headers: ["header1":"value1"])

webSocketClose

Signature

void webSocketClose(DeviceWrapper device)

Parameters

device - The current device that is calling the method.

sendWebSocketMessage

Signature

void sendWebSocketMessage(DeviceWrapper device, String message)

Parameters

  • device - The current device that is calling the method.
  • message - The message to send. If this connection is a byte interface, then this must be a hex encoded String.

User-Defined Methods

Methods with the following signatures must be provided in your code and will be called as described.

  • parse(String message) - This method is called with any incoming messages from the web socket server. This is a standard method for drivers.
  • webSocketStatus(String message) - This method is called with any status messages from the web socket client connection (disconnections, errors during connect, etc)