WebSocket Communication

Real time bidirectional communication between Vizard and a web browser is supported using WebSockets. You can send and receive messages and find out when socket connections open or close. On the server (Vizard) side, the vizhtml module provides Vizard commands for sending messages and handling message and connection events. Similar functionality is provided on the client (browser) side using JavaScript functions through vizhtml's JavaScript library.

All the major web browsers support WebSockets. The minimum supported version for each browser is:

Vizard commands

Use the following commands to send WebSocket messages and get information about connected clients:

Sending data to a specific client is accomplished through it's associated vizhtml.WebSocketClient object. You can get a handle to this object when a WebSocket event occurs (e.g. connection event) or by using the vizhtml.getClientList() command. Each object provides the client's IP address and a method to send it data:

Handling events

The following events will get triggered when messages are received and connections are opened and closed:

Javascipt commands

Use vizhtml's JavaScript library to create a WebSocket client that communicates with vizhtml's HTTP server. In order to access the library within your own JavaScript code, link to vizhtml.js as an external script:

To implement a WebSocket client create an instance of the viz.WebSocket class. Before creating a WebSocket, you can check whether the browser supports WebSockets by calling the viz.isWebSocketSupported() command. This provides a way to display a helpful error message to the user.

Sending a viz.Data object to Vizard

If you want the JavaScript code to send an object that appears to Vizard as a viz.Data object, then you can use the viz.Data JavaScript function:

In the following JavaScript code, the integer value stored in click_count is sent as the count attribute of a viz.Data object:

var click_count = 0;
function onButtonClick()
{
click_count += 1;
socket.send( 'button_click' , viz.Data({'count':click_count}) );
}

def OnButtonClick(e):
data = e.data
print('BUTTON CLICK',data.count)
vizhtml.onMessage('button_click',OnButtonClick)

Example

The following example script shows how to communicate between Vizard and a browser via WebSockets.

Note: If no communication occurs it's likely your browser does not support WebSockets.

For remote browsers replace computer name or IP address with the Vizard machine's name or address

import viz
import vizhtml
viz.go()

code = """
<html>
<head>
    <title>vizhtml WebSocket Example</title>
    <script type="text/javascript" src="vizhtml.js"></script>
</head>
<body>
<script language="javascript">

var socket = new viz.WebSocket();

socket.onevent('open', function(e){
    document.getElementById('status').innerHTML = 'connected';
    document.getElementById('my_button').disabled = false;
})

socket.onevent('close', function(e){
    document.getElementById('status').innerHTML = 'waiting for connection';
    document.getElementById('my_button').disabled = true;
    socket.reconnect();
})

socket.onevent('set_time', function(e){
    document.getElementById('script_time').innerHTML = e.data.time;
})

var click_count = 0;
function onButtonClick()
{
    click_count += 1;
    socket.send( 'button_click' , viz.Data({'count':click_count}) );
}

</script>

<div>Status:</div><div id='status'>waiting for connection</div></br>
<div>Time:</div><div id='script_time'></div></br>
<div><input id='my_button' type=button value="Send Message" onclick="onButtonClick();"></div></br>
</body>
</html>
"""

# http://localhost:8080/vizhtml/websocket
vizhtml.registerCode('websocket',code)

def ClientConnect(e):
    print('Client connected at',e.client.address)
vizhtml.onConnect(ClientConnect)

def ClientDisconnect(e):
    print('Client disconnected at',e.client.address)
vizhtml.onDisconnect(ClientDisconnect)

def SendTime():
    d = viz.Data(time='%.1f'%(viz.tick()))
    vizhtml.sendAll('set_time',d)
vizact.ontimer(0.1,SendTime)

def OnButtonClick(e):
    print('BUTTON CLICK',e.data.count,'from',e.client.address)
vizhtml.onMessage('button_click',OnButtonClick)

Command	Description
vizhtml.sendAll(event, data)	Sends WebSocket data to all connected clients. event: A string value that defines the event name. data: Any basic object type (e.g. int, string , list, ...) or a viz.Data object.
vizhtml.getClientList()	Gets a list containing the currently connected clients. Each element in the list is an instance of the vizhtml.WebSocketClient class.
vizhtml.getClientCount()	Returns the number of currently connected clients.

Attribute	Description
<WebSocketClient>.address	The IP address of the client.

Event	Description
vizhtml.MESSAGE_EVENT	Generated when a WebSocket message is received. It provides a single event structure e with the following attributes: e.event: A string with the event name. This should match an event_name defined in a <VizardWebSocket>.send command (described in the JavaScript section below). e.data: The data sent. e.client: A vizhtml.WebSocketClient object.
vizhtml.CONNECT_EVENT	Generated when a WebSocket client connects. It provides a single event structure e with the following attribute: e.client: A vizhtml.WebSocketClient object.
vizhtml.DISCONNECT_EVENT	Generated when a WebSocket client disconnects. It provides a single event structure e with the following attribute: e.client: A vizhtml.WebSocketClient object.