Webifi.me

WebSocket Protocol

 

Index

1. Introduction
2. Important facts about the protocol
2.1 Control Character
2.2 ID Parameter
2.3 Data type field
2.4 End of message field
3. Protocol Details
3.1 Request Credentials
3.2 WebSocket Connection and Authentication
3.3 Setting Listen to Networks
3.4 Sending Data
3.4 Receive Data
3.5 Keep Alive Message
3.6 Close Connection

1. Introduction

This document explains how to communicate with the Webifi servers to transfer data using HTML5 WebSocket. For more information about HTML5 WebSocket, please see the Wikipedia page about WebSocket. We have a couple of libraries written in different languages but it would be impossible to write an interface to our service for every language. This page allows an user that would like to use our service to write their own interface. A user creates a Connect Name, a Connect Password and Network Names for the connection on webifi.me. First the library requests the credentials from connect.webifi.me using a normal html request. The response consists of an unique code, the IP addresses and domain names of the server that will provide the service.

WebSocket is a technique where the connection is kept open indefinitely. The connection only has to be authenticated once and then data can be freely sent back and forth.

All examples in this document will use the following account details:
Connect Name: webifi
Network Password: pswd
Network Name 1: net1
Network Name 2: net2

2. Important facts about the protocol

2.1 Control Character

This protocol uses the ~ (126 decimal) character as the control character and the = character to separate the parameters and values.
For example the protocol value will be sent as:

~p=1

Example of multiple fields where we send the protocol, connect name and password to the server:

~p=1~cn=webifi~cp=pswd

If the ~ character is present in your string then it must be encoded as ~~
For example:
Unencoded: test~123
Encoded: test~~123

2.2 ID Parameter

As part of the Get Credentials response the server sends back an id field which must be sent to the server as authentication when a WebSocket connection is established. The id field is made up of three parts:

  • A session ID, this is the address of the device. When other devices needs to send data only to you then they need to send it to your session ID
  • Lower case s. This marks the end of the session ID
  • 16 random characters, this is to make sure that your session ID cannot be guessed.

Example ID (Session ID is 16): 16s1234567890abcdef

2.3 Data type field

As part of the upload request the user can specify a data type. This is an optional field which can be used to implement a very basic protocol. For example, if the receiving device has 4 UARTs then the data type field can specify for which UART the data is intended. This can reduce the complexity of the receiving device considerably because it does not need to implement a user protocol to figure out where to send data.

2.4 End of message field

Because WebSocket is a streaming protocol it is not clear to the receiving side if all the data has been received. It simplifies the code on the receiving side dramatically if there is a terminating field. Every message in the WebSocket protocol ends with the field:
~t=1

3. Protocol Details

3.1 Request Credentials

This is always the first step, a lot of error conditions will revert back to this step. The server providing the service will not be the same server as the one hosting connect.webifi.me. The client will make a request to http://connect.webifi.me to request a unique identification code and details of the server that will handle communication. Two IP addresses and two domain names are returned. Any of the IP addresses or domain names can be used to establish a WebSocket connection. When SSL communication is used then the client must use one of the domain names.

Request:
http://connect.webifi.me
Request SSL
https://connect.webifi.me

Get Credentials Request Parameters

Parameter Description
p Protocol number, for this request this must be “1”
cn Connect Name
cp Connect Password
ec Optional, if this field is set to 1 then all the error codes with their descriptions are sent back to the client. This is useful if the client application wants to show useful information to the user in response to an error code.
gt Optional, if this field is set to 1 then the epoch time will be sent back.

Example request Post data:
~p=1~cn=webifi~cp=pswd

Get Credentials Response Parameters

Parameter Description
e Error code, 0 if successfull. If non zero then other parameters are omitted because of error condition.
id The id is your unique code that must be sent as authentication when WebSocket connection is established.
ip Two of these fields are returned and they are the IP addresses of the server that will provide the service.
dn Two of these fields are returned and they are the domain names of the server that will provide the service.
0 If the parameter field is a number then it represents an error code description. The description field will be an explanation for this error code number. These values are only sent if ~ec=1 was part of the request post data. See below for an example.

Successful response:
~e=0~id=xxxxxxxxxxxxxxxxxxxxxxxxxxx~ip=1.2.3.4~ip=5.6.7.8~dn=www.webifi1up.com~dn=www.webifi1down.com
Failed response (the user made a mistake in the connect name or password):
~e=8

Error responses

Error code Description
0 Success
1 Unknown error
7 Protocol error
8 Invalid connect name or password

Request post data with error codes
~p=1~u=webifi~ps=pswd~ec=1
Response with error codes
~e=0~id=xxxxxxxxxxxxxxxxxxxxxxxxxxx~ip=1.2.3.4~ip=5.6.7.8~dn=www.webifi1up.com~dn=www.webifi1down.com~0=No error~1=Unknown error

3.2 WebSocket Connection and Authentication

To establish a WebSocket connection the user need to use one of the IP addresses or domain names. For our example we will use the domain name for the server, which will look something like this: www.webifiXup.com, where X will be a number. The connection URL will look as follows:
Request:
ws://www.webifiXup.com/api/WebSocket
Request SSL
wss://www.webifiXup.com/api/WebSocket

When the WebSocket connection is established, the first thing that must be done is that the connection must be authenticated. The id that was received from connect.webifi.me is the unique code that must be used for authentication. The code must be sent as follows (including the terminating tag at the end):
~id=xxxxxxxxxxxxxxxxxxxxxxxxxxx~t=1

Authentication Response Parameters

Parameter Description
e Error code, 0 if successfull
rt Response type, will be “a” for an authentication message response
t End of message field, must the set to 1. This lets the other side know that all the data was sent.

Successful response:
~e=0~rt=a~t=1
Failed response (the session id is invalid):
~e=12~rt=a~t=1

Error response codes

Error code Description
0 Success
1 Unknown error
7 Protocol error
12 Invalid/expired id
14 WebSocket connection not authenticated yet
20 Could not establish connection to website

3.3 Setting default networks

This command is used to set or change the networks that your device is listening to. If your device has not set any networks then it will not receive any data unless data is sent to its session ID.

Request Parameters

Parameter Description
nc Set this parameter equal to 1 if all the existing networks must be cleared before adding new networks. Can be omitted if you are just adding networks.
ns Network set, name of network that this device is listening to, this field can be repeated as many times as needed.
t End of message field, must the set to 1. This lets the other side know that all the data was sent.

Example set networks request:
~nc=1~ns=net1~ns=net2~t=1

Set Networks Response Parameters

Parameter Description
e Error code
rt Response type, will be “n” for setting networks message response
t End of message field, must the set to 1. This lets the other side know that all the data was sent.

Successful response (all the networks are valid):
~e=4~rt=n~t=1
Failed response (Not all of the networks to which device is listening was set):
~e=5~rt=n~t=1

Error response codes

Error code Description
1 Unknown error
4 New set of networks to which device is listening was set
5 Not all of the networks to which device is listening was set
7 Protocol error
12 Invalid/expired id, connection not authenticated yet
20 Could not establish connection to website

3.4 Sending Data

This request is used to send data to other devices connected to your networks. It is very important that the data must be the last parameter of a message. For example, if the user wants to send a message to network 1 and network 2 then the message must be network 1 name, message for network 1, network 2 name, message for network 2.

Sending Data Parameters

Parameter Description
n Network that this message must be sent to, can be repeated as many times as needed, can be omitted if you are sending to your default networks.
s Session ID that this message must be sent to, can be repeated as many times as needed, can be omitted if sending to networks only.
dt Data type, only one data type can be sent for each data parameter, can be omitted.
d Data that the user or device wants to send to other connected devices.
t End of message field, must the set to 1. This lets the other side know that all the data was sent.

Example send data request:
~d=this is a message~t=1

Sending Data Response Parameters

Parameter Description
e Error code, 0 if successful
rt Response type, will be “s” for sending data response
t End of message field, must the set to 1. This lets the other side know that all the data was sent.

Successful response:
~e=0~rt=s~t=1
Failed response (Protocol error):
~e=7~rt=s~t=1

Error response

Error code Description
0 Success
1 Unknown error
2 Data could not be sent to one or more recipients
7 Protocol error
20 Could not establish connection to website

Send data destination options
There are three ways of choosing who to send data to:

  • Send the data to all the networks to which this device is listening. In section 3.3, the networks the device is listening to was set. When both the network (n parameter) and session id (s parameter) are omitted then the data will be sent to these networks.
  • Send to specific devices. This is done using the s parameter. Multiple session IDs can be specified, each with a separate s parameter. Please see the examples below. A message can be sent to Session IDs and to networks. Even if the Session ID also belongs to one or more of the networks it will still just receive one copy of the message.
  • Send to specific networks. This is done using the n parameter. Multiple networks can be specified, each with a separate n parameter. Please see the examples below.

Examples
To demonstrate using practical examples we have the following setup:

  • There are 3 networks for this user: Home, Office and Friend’s house
  • The device we are uploading data from is listening to only two of these network: Home and Office
  • There are two other devices connected, their session IDs are 8 and 25
  • Your own Session ID is 41

It is very important to note that the data must be the last parameter for a message. All the parameters before a data parameter applies to this data parameter. The order of the parameters before the data parameter does not matter.

Send two messages with different data types in the same upload. The destination device will send the messages to the serial port specified in the data type field. No networks or session IDs are specified, therefore the messages will be sent to the networks you are listening to, which are Home and Office.
~dt=com 1~d=message for serial port 1~dt=com 2~d=message for serial port 2~t=1

Send one message to session ID 25 only.
~s=25~d=message will be sent to session id 25~t=1

Send two messages, message 1 must go to all three networks and message 2 you want to send to the device with session ID 8 and you want to echo the message back to yourself.
~dt=to networks~n=Home~n=Office~n=Friend’s house~d=Everybody will receive this message~s=8~s=41~dt=to specific devices~d=Only 8 and myself will receive this message~t=1

3.4 Receive Data

After the conection is authenticated the server can send data to the device at any time.

Receive Data Parameters

Parameter Description
rt Response type, will be “r” for receiving data
f From field, this contains the session ID of the device that sent this data
dt Data type, can be missing if the sending device did not send a data type
d Data that was sent to this device
t End of message field, must the set to 1. This lets the other side know that all the data was sent.

Receive data example (from session ID 31, the data type that was sent with the message was “configuration”):
~rt=r~f=31~dt=configuration~d=led on~t=1

3.5 Keep Alive Message

If data is not exchanged regularly then the connection could be dead and neither side would notice. The keep alive message is exchanged every 30 seconds if there are no other communication to make sure this does not happen. If no response is received for a couple of seconds after the request was sent the connection needs to be re-established.

Sending Parameters

Parameter Description
t End of message field, must the set to 1. This lets the other side know that all the data was sent. The keep alive message only consists of this parameter.

Example request:
~t=1

Response Parameters

Parameter Description
rt Response type, will be “k” for keep alive response
t End of message field, must the set to 1. This lets the other side know that all the data was sent.

Successful response:
~rt=k~t=1

3.6 Close Connection

This message is used to close the WebSocket connection. If the application or device is switched off without closing the connection then it will time out on the server side. If possible it is cleaner for the connection to be closed on the server. There are two options, the connection can be closed without terminating the session. This is useful if you plan to immediately reconnect, then the session will be resumed. The second option is to close the connection and the session, for example when the application will be closed.

Sending Parameters

Parameter Description
c Close connection message. Set equal to c to close the connection but not to terminate the session. Set equal to t to close the connection and terminate the session.
t End of message field, must the set to 1. This lets the other side know that all the data was sent.

Example request (close connection):
~c=c~t=1
Example request (close connection and terminate session):
~c=t~t=1

Response Parameters

Parameter Description
e Error code, 0 if successful
rt Response type, will be “c” for close connection message
t End of message field, must the set to 1. This lets the other side know that all the data was sent.

Successful response:
~e=0~rt=c~t=1
Error Response Parameters

Error code Description
0 Success
1 Unknown error
7 Protocol error
20 Could not establish connection to website