WebSocket DAT

From TouchDesigner 099 Wiki

Summary

The WebSocket DAT receives and parses WebSocket messages. WebSockets are fast an efficient two way communication protocol used by web servers and clients. Each message is parsed and appended as a row in the DAT's table. The table is FIFO "first-in first-out" and limited to parameter-set number of lines. An optional script may be run for each packet received. The WebSocket DAT also supports the Socket.IO up to version 0.9.14 handshake protocol. Secure (tls) websocket servers are also supported. Connections to different websocket sites are supported without requiring manual header setup.


See also: TCP/IP DAT

Example project: chat with WebSockets

PythonIcon.png websocketDAT_Class

Parameters - WebSocket Page

Active /active - While on, the DAT receives information sent to the network port. While Off, no updating occurs. Data sent to the port is lost.

Network Address /netaddress - The network address of the server computer. This address is a standard WWW address, such as foo or foo.bar.com. You can put an IP address (e.g. 100.123.45.78). If you put localhost, it means the other end of the connection is on the same computer.

Network Port /port - The port in which the DAT will accept messages.

Socket.io Format /socketio - When on, a Socket.io handshake is negotiated after the WebSocket handshake. Messages will continue as normal, plus Socket.IO heartbeats, timeouts and disconnection support are additionally available, which are useful for realtime applications.

Socket.io Address /socketioaddress - Can be used to define initial socket.io header requests.

Parameters - Received Messages Page

Script DAT script - the Script DAT will execute once for each message coming in. The first argument ($arg1) is the message, the second argument ($arg2) is the line number (index starting at 0) in the DAT of the message.

Execute From executeloc - Determines the location the script is run from.

  • Current Node current - The script is executed from the current node location (for example, where 'cc' points to).
  • Script DAT script - The script is executed from the location of the DAT specified in the Script DAT parameter.
  • Specified Operator op - The script is executed from the operator specified in the From Operator parameter below.

From Operator fromop - The operator whose state change will trigger the DAT to execute its script when Execute is set to Specified Operator. This operator is also the path that the script will be executed from if the Execute From parameter is set to Specified Operator.

Clamp Output clamp - The DAT is limited to 100 messages by default but with Clamp Output, this can be set to anything including unlimited.

Maximum Lines maxlines - Limits the number of messages, older messages are removed from the list first.

Clear Output clear - Deletes all lines except the heading. To clear with a python script op("opname").par.clear.pulse()

Keep First Row firstrow - Keeps first row in table.

Bytes Column bytes - Outputs the raw bytes of the message in a separate column.


Scripting with the WebSocket DAT

When a WebSocket DAT is first placed down, a new Text DAT with default scripts are appended. These scripts are called whenever the WebSocket receives any messages or first connects to a server.

The callback methods are:

  • monitor(dat, message)

This method is called to relay handshake and other progress from the socket. It is only used for debugging connection problems, in which case the following simple script may be useful:

def monitor(dat, message):
    print("websocket: ", dat, " monitor message:", message)

  • receiveText(dat, rowIndex, message)

This method is called whenever a Text frame is received. The messages are also appended to the WebSocket DAT output, at the specified rowIndex.

  • receiveBinary(dat, contents)

This method is called whenever a Binary frame is received. The contents are a byte array of arbitrary data, and may be zero bytes in length. Binary messages are not logged in the WebSocket DAT output.

  • receivePing(dat, contents)

This method is called whenever a ping request is received. The contents are a byte array of arbitrary data, and may be zero bytes in length. When this type of message is received, it is should be replied with a call to sendPong with the same contents. For example:

def receivePing(dat, contents):
    #send reply with same contents
    dat.sendPong(contents)

  • receivePong(dat, contents)

This method is called whenever a pong reply is received. The contents are a byte array of arbitrary data, and may be zero bytes in length.


In addition to the above callback functions, data may be sent at any time through the WebSocket DAT with the following methods:


  • webSocketDAT.sendText(message)

This will send one text frame with the specified message.

  • webSocketDAT.sendBinary(contents)

This will send one binary frame with the specified binary contents.

  • webSocketDAT.sendPing(contents)

This will send a ping request to the originating server. The contents are optional and arbitrary.

  • webSocketDAT.sendPong(contents)

The will send a pong message to the originating server, in reply to a previous ping request. The contents should match the contents of the originally received ping message.

A Simple Example

Place down a new WebSocket DAT. It should default to echo.websocket.org. This website simply accepts messages and echoes them back. In the websocket script DAT, change the receive Text message to:

def receiveText(dat, rowIndex, message):
    print("RECEIVED MESSAGE: ", message)

Now create a new Text DAT called text1. In it type:

op('websocket1').sendText("Hello it's me!")

Right click on text1, and run its contents. It will then send a simple message to the external webserver, which in turn will send the message back to the WebSocket DAT. The receiveText callback will then be called, printing the exact same message back to the texport.

Working with the Socket.io Format

The Socket.io Format is a protocol layer built upon the WebSocket layer. Note only the websocket transport protocol is supported When communicating with a Socket.io server, all messages are text messages. That is, it is sufficient to only use the receiveText callback message, and the websocketDAT.sendText() method. The contents of these text messages should then contain Socket.io formatted messages. For more information on this format see: [1]