HTTP Server Simple WebSocket Demonstration

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

To set up a WebSocket on your Gecko OS 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 Gecko OS device.

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

At the Gecko OS 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.

Setup

Open a Gecko OS terminal.

Configure Gecko OS Device

Configure as follows:

set wlan.ssid <your_wlan_SSID>
set wlan.passkey <your_wlan_password>
set wlan.auto_join.enabled 1
set http.server.enabled 1
set mdns.name mymodule
set mdns.enabled 1
save
reboot

Set wlan ssid - substitute your own
Set wlan password - substitute your own
Enable WLAN auto join
Enable HTTP server
Set mDNS name
Enable mDNS
Save
Reboot

After rebooting, the Gecko OS Terminal displays messages similar to:

> Security type from probe: WPA2-AES
Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.126
Starting mdns
User hostname - mymodule
HTTP and REST API server listening on port: 80
[Associated]

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 Gecko OS 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 Gecko OS Terminal, Gecko OS indicates a connection has been opened with a response similar to:

> [2019-01-12 | 06:12:09: Opened: 0]

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

> list
! # Type  Info
# 0 WEBS  10.5.6.55:80 10.5.6.60:63745

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

In the Gecko OS 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 Gecko OS!

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

write 0 5
Hello

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 Gecko OS Terminal, switch to stream mode:

set bus.mode stream
save
reboot

The Gecko OS 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 Gecko OS Terminal console.

Type a message on the Gecko OS 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 Gecko OS 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 Gecko OS 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:

> [2019-01-04 | 23:56:40: Opened: 0]
> [2019-01-04 | 23:56:52: Opened: 1]
> list
! # Type  Info
# 0 WEBS  10.5.6.108:80 10.5.6.153:54997
# 1 WEBS  10.5.6.108:80 10.5.6.153:55000
> read 0 1000
Hello from WebSocket A

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

> write 1 17
Hello WebSocket B
Success

JavaScript

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 Gecko OS Versions

• Gecko OS 4

Change Log