Websocket Interface

Overview

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).

Methods

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)

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

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)