MatlabWebSocket

MatlabWebSocket is a simple library consisting of a websocket server and client for MATLAB built on Java-WebSocket, a java implementation of the websocket protocol. Encryption is supported with self-signed certificates made with the java keytool.

Installation and Uninstallation

IMPORTANT: you must make sure to install the java library to the static class path by following the instructions below. MatlabWebSocket will not work otherwise!

First, download the latest release on GitHub or MATLAB Central and extract the contents where you want.

The required java library is a jar file located in the /jar/ folder. It must be placed on the static java class path in MATLAB. For example, if the location of the jar file is C:\\MatlabWebSocket\\jar\\matlab-websocket-*.*.jar, then open the static class path file with the following command:

edit(fullfile(prefdir,'javaclasspath.txt'))

and add the line C:\\MatlabWebSocket\\jar\\matlab-websocket-*.*.jar to it. Make sure that there are no other lines with a matlab-websocket-* entry.

Make sure to replace the stars matlab-websocket-*.*.jar with the correct version number that you downloaded.

After having done this, restart MATLAB and check that the line was read by MATLAB properly by running the javaclasspath command. The line should appear at the bottom of the list, before the DYNAMIC JAVA PATH entries. Note that seeing the entry here does not mean that MATLAB necessarily found the jar file properly. You must make sure that the actual jar file is indeed at this location.

You must now add the /src/ folder to the MATLAB path. If you want to run the examples, add the /examples/ folder as well.

Simply undo these operations to uninstall MatlabWebSocket.

See the MATLAB Documentation for more information on the static java class path.

Usage

To implement a WebSocket server or client, a subclass of either WebSocketServer or WebSocketClient must be defined. For more details (see the object-oriented programming documentation of MATLAB).

The WebSocketServer.m file is an abstract MATLAB class. The behavior of the server must therefore be defined by creating a subclass that implements the following methods:

onOpen(obj,conn,message)
onTextMessage(obj,conn,message)
onBinaryMessage(obj,conn,message)
onError(obj,conn,message)
onClose(obj,conn,message)

obj is the object instance of the subclass, it is implicitly passed by MATLAB (see the object-oriented programming documentation of MATLAB).
message is the message received by the server. It will usually be a character array, except for the onBinaryMessage method, in which case it will be an int8 array
conn is a WebSocketConnection object representing the client connection that caused the event. For example, if a message is received, the conn object will represent the client that sent this message. You can send messages to that client through this object.

The WebSocketClient.m class is very similar to the server, except that no conn object is passed to the onSomething methods.

These methods will be automatically called when the corresponding event (connection is opened, message received, etc…) occurs. In this way, a reactive behavior can be defined.

The server supports a variety of methods to help talk to clients, look in the MATLAB class file to see what methods are available.

When you are done, do not forget to delete the clients and/or servers.

See the EchoServer.m and SimpleClient.m files in the examples folder for an implementation example. A good resource on classes is the MATLAB object-oriented documentation.

Example

The example is an echo server, it returns to the client whatever was received.

Run the echo server by making sure that the example file EchoServer.m is on the MATLAB path and executing

server = EchoServer(30000)

to start the server on port 30000.

To test the server, make a client object from the SimpleClient.m class:

>> client = SimpleClient('ws://localhost:30000');
Connected to server at ws://localhost:30000
Client 1063680447 at 127.0.0.1:42520 opened a connection

You can now connect and send messages (client.send('hi!')). If the server is working properly, you will receive messages identical to the ones you send.

The server can enumerate clients that are connected, just type:

server.Connections % view the result as a table: struct2table(server.Connections)

This allows you to send a message to the client via its identifying HashCode:

>> clientCode = server.Connections(1).HashCode;
>> server.sendTo(clientCode,'hi, this is the server!')
Message received:
hi, this is the server!

The server can be stopped and restarted (this will disconnect clients):

>> server.stop
Disconnected from server at ws://localhost:30000

To delete the server, type:

delete(server);
clear server;

SSL / WebSocket Secure (wss)

To enable SSL, you must first have a certificate. A self-signed key store can be generated with the java keytool, but you should always use a valid certificate in production. From there, open the server by passing the location of the store, the store password, and the key password. With the EchoServer, for example:

PORT = 8887; % choose an other port!
STORE = 'C:\\keystore.jks';
STOREPASSWORD = 'storepassword';
KEYPASSWORD = 'keypassword';
s = EchoServer(PORT,STORE,STOREPASSWORD,KEYPASSWORD);

The client can then connect to it:

URI = sprintf(wss://localhost:%d',PORT);
c = SimpleClient(URI,STORE,STOREPASSWORD,KEYPASSWORD);

If a valid certificate is used, the default java keystore can be used. For example, we can connect a client directly the the secured websocket.org test server:

>> c2 = SimpleClient('wss://echo.websocket.org');
Connected to server at wss://echo.websocket.org
>> c2.send('hi, this communication is secured!')
Message received:
hi, this communication is secured!

Building the Java JAR

To build the jar file yourself, it is recommended to use Apache Maven. Maven will automatically take care of downloading Java-WebSocket and neatly package everything into a single file (an "uber jar").

Once the mvn command is on your path, simply cd to the matlab-websocket folder and execute mvn package.