Difference between revisions of "Websocket Interface"

From Hubitat Documentation
Jump to: navigation, search
(Replaced content with "<big>'''We're moving!''' Please visit http://docs2.hubitat.com for the latest documentation.</big> <big> This document is available at: http://docs2.hubitat.com/en/develo...")
(Tag: Replaced)
 
Line 1: Line 1:
{{Top}}
+
<big>'''We're moving!''' Please visit http://docs2.hubitat.com for the latest documentation.</big>
  
=Overview=
+
<big>
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).
+
This document is available at: http://docs2.hubitat.com/en/developer/interfaces/websocket-interface
 
+
</big>
=Methods=
 
 
 
==Hubitat Provided Methods (Since 2.1.2)==
 
 
 
===<code>connect</code>===
 
 
 
:;Signature
 
:: <code>void connect(String url)</code>
 
:: <code>void connect(String url, [options (name/value pairs)])</code>
 
 
 
:;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"])
 
 
 
 
 
===<code>close</code>===
 
 
 
:;Signature
 
:: <code>void close()</code>
 
 
 
:;Examples
 
 
 
// Close connection
 
interfaces.webSocket.close()
 
 
 
===<code>sendMessage</code>===
 
 
 
:;Signature
 
:: <code>void sendMessage(String message)</code>
 
 
 
:;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)==
 
 
 
===<code>webSocketConnect</code>===
 
 
 
:;Signature
 
:: <code>void hubitat.helper.InterfaceUtils.webSocketConnect(DeviceWrapper device, String url)</code>
 
:: <code>void hubitat.helper.InterfaceUtils.webSocketConnect(DeviceWrapper device, String url, [options (name/value pairs)])</code>
 
 
 
:;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"])
 
 
 
 
 
===<code>webSocketClose</code>===
 
 
 
:;Signature
 
:: <code>void webSocketClose(DeviceWrapper device)</code>
 
 
 
:;Parameters
 
:: device - The current device that is calling the method.
 
 
 
===<code>sendWebSocketMessage</code>===
 
 
 
:;Signature
 
:: <code>void sendWebSocketMessage(DeviceWrapper device, String message)</code>
 
 
 
:;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==
 
 
 
: '''<code>parse(String message)</code>'''  - This method is called with any incoming messages from the web socket server. This is a standard method for drivers.
 
 
 
: '''<code>webSocketStatus(String message)</code>''' - This method is called with any status messages from the web socket client connection (disconnections, errors during connect, etc)
 

Latest revision as of 20:28, 25 September 2022

We're moving! Please visit http://docs2.hubitat.com for the latest documentation.

This document is available at: http://docs2.hubitat.com/en/developer/interfaces/websocket-interface