HTTP Server Simple WebSocket Demonstration

The ZentriOS HTTP Server WebSocket support can be accessed from JavaScript without any special libraries.

To set up a WebSocket on your ZentriOS device, and connect to it, you use the standard JavaScript WebSocket object, in conjunction with a HTTP RESTful API call to ws://deviceName/stream that causes the device to open a WebSocket. For more on the WebSocket API, see Mozilla WebSocket API.

With the socket open, you can send and receive messages between the client and the ZentriOS device.

From the web page client end you use the standard JavaScript library to handle WebSocket input and output.

At the ZentriOS device end, in command mode, you can read messages with stream_read and send messages with stream_write. In stream mode, data streams directly to and from the WebSocket.


Open a ZentriOS terminal.

Configure ZentriOS Device

Configure as follows:

ZentriOS CommandsDescription

set wlan.ssid <your_wlan_SSID>
set wlan.passkey <your_wlan_password>
set wlan.auto_join.enabled 1
set http.server.enabled 1
set mymodule
set mdns.enabled 1
set network.buffer.rxtx_ratio 25

Set wlan ssid - substitute your own
Set wlan password - substitute your own
Enable WLAN auto join
Enable HTTP server
Set mDNS name
Enable mDNS
Increase Tx network buffer (Numbat)

Note:The network.buffer.rxtx_ratio setting is necessary only for the Numbat, which has a smaller memory. See Memory.

After rebooting, the ZentriOS Terminal displays messages similar to:

[Associating to Zentri]
> Obtaining IPv4 address via DHCP
IPv4 address:
Starting mDNS
mDNS domain: mymodule.local
HTTP and REST API server listening on port: 80

Download and Launch the HTML page

Download the HTTP Server Simple WebSocket Demonstration web page: http_server_ws_simple.html.

Run this page in a web browser to act as the client. You can run it as a file:// URL.

Open the browser development tools to view the web page console log.

The web page has input boxes for the device IP or name, and for a message to send from the client.

Command Mode

By default, the ZentriOS device bus mode is command. You issue commands to read from and write to the WebSocket.

In the web page Device IP or Name input box, specify the mDNS name or the IP address of the module. If you used the command sequence above, the mDNS name is the default, mymodule.

Click the Open WebSocket button to open the WebSocket.

The web page session log indicates a successful connection.

In the ZentriOS Terminal, ZentriOS indicates a connection has been opened with a response similar to:

> [2015-02-12 | 06:12:09: Opened: 0]

The stream_list command displays a list of open streams, similar to:

> list
! # Type  Info
# 0 WEBS

In the web page, enter a message in the Message input box and press Enter to send the message.

In the ZentriOS Terminal, view the message by issuing the command:

read 0 1000

The first argument is the stream id, and should be modified depending on the WebSocket stream. See stream_read. The response is similar to:

Hello ZentriOS!

To send a message back to the web page via the WebSockets, in the ZentriOS Terminal issue the command:

write 0 5

Press Enter after typing 'write 0 5', then type the text of the message, hello. The first argument is the stream id, and should be modified depending on the WebSocket stream. See stream_write.

The web page message log shows the message received.

Stream Mode

Now, in the ZentriOS Terminal, switch to stream mode:

set bus.mode stream

The ZentriOS device reboots in stream mode and displays messages indicating the the HTTP server and mDNS are running.

In the web page, open a new WebSocket.

When the WebSocket opens successfully, send a message to the device from the web page. It appears immediately on the ZentriOS Terminal console.

Type a message on the ZentriOS Terminal console. Depending on terminal echo settings, it may not appear on the terminal, but each character you type is streamed directly to the the web page message log, via the WebSocket connection.

Using Multiple Websockets

You can launch multiple instances of the http_server_ws_simple.html page simultaneously in a browser. Each instance of the demonstration JavaScript uses a different WebSocket and corresponding ZentriOS stream, and can send and receive data independently. A maximum of 8 websockets can be opened simultaneously to the same module, one for each available ZentriOS stream. See Network Connections and Streams.

Note that you can handle multiple streams only in command mode. To read from and write to the individual streams, you have to identify the stream with the <handle> argument to the read or write command. For example, here is a sample session where stream 0 corresponds to websocket A, and stream 1 corresponds to websocket B:

> [2015-05-04 | 23:56:40: Opened: 0]
> [2015-05-04 | 23:56:52: Opened: 1]
> list
! # Type  Info
# 0 WEBS
# 1 WEBS
> read 0 1000
Hello from WebSocket A

> write 0 17
Hello WebSocket A
> read 1 1000
Hello from WebSocket B

> write 1 17
Hello WebSocket B


The demonstration web page uses simple JavaScript to establish the WebSocket, and send and receive messages.

The WebSocket is initialized in the initWebSocket() function, with the line: ws = new WebSocket('ws://'+ipName+'/stream') In the same function, calls to the WebSocket onopen, onclose and onmessage functions set callbacks for those events.

In the sendMessage function, a call to the WebSocket send method sends the message to the device.

The rest of the JavaScript is plumbing to handle the user interface.

Supporting ZentriOS Editions and Versions

Change Log

2015-May-05Added note on connecting multiple websockets