It´s time for a new software release CE9.7.1 has just arrived, introducing an interesting feature called XoWS (pronounced cows)

This feature basically allows you to setup a persistent bi-directional connection to the xAPI. WebSocket is just an alternative way of communicating with the xAPI like SSH, Serial or XMLAPI, but using JSON RPC 2.0 as data transport, you send and receive all the data in JSON format which is easier to work with than parsing XML or scraping plain text.

Most of the popular programming languages have a WebSocket module you can use to integrate your app/script with XoWS.

The difference between a HTTP request and a WebSocket is that a HTTP request is client initiated and a response is received for the request before the connection is closed. To send and receive more data you have to generate new client requests.

With a WebSocket the communication channel is open both ways and the server can send data to the client when new data is available.

In order to get started and open the device for connections you need to enable the WebSocket service on the device.

xConfiguration NetworkServices Websocket: FollowHTTPService

We set the Websocket config to FollowHTTPService. The connection is setup via HTTP so if you disable the HTTP service on the device, Websocket will not work.

The WebSocket entrypoints is:

ws(s)://<codecip>/wsws(s)://<codecip>/ws?legacy

These are the URLs you use when setting up the connection /ws and /ws?legacy is essentially the same but /ws is integer aware which means switching your jsxapi app from SSH directly to using WebSocket will most likely break something in your existing code. Legacy is setup to avoid that and returns all values as strings. This is the difference between the two.

Feature summary

Benefits

Simple mapping between request and response, no difference between "sync" and "async" responses.

Each message contains a complete JSON document and nothing else, no need to parse text or a mix of text and XML.

Can be accessed directly from a browser using javascript (using auth protocol header)(Currently not supported)

Benefits with respect to HTTP API (I.E XMLAPI)

Much faster. No need to re-authenticate for every request.

Clients can get events from the codec. No need to run your own web server and register for HttpFeedback or listen for HTTP POSTS and PUT from the codec.

Benefits with respect to XAPI over SSH/telnet/RS-232

The SSH/telnet/RS-232 services can be turned off if not used for anything else.

Feature description, functional overview, compatibility

Purpose

Provide a modern an powerful way of interacting with the xAPI using WebSocket. Keep in mind that this is an integration feature which allows flexibility on how you choose to use the API. You can write an application that uses WebSocket to monitor devices or whatever other use-case you can think of.

Auth protocol header(Disabled in CE9.7.1, planned for a future release)

Because browser based clients have no direct control over headers, you can also authenticate using an auth protocol header. The authentication is sent similarly to basic authentication, i.e. as a base64 encoded string of username:password. The complete header looks like this: Sec-WebSocket-Protocol: auth-dXNlcjpwYXNz. Example usage from javascript (the replace train is for making sure the base64 is "url-safe" else it will not always work):

Let´s take a look at the JSON documents that we can send and receive to the codec.

In the JSON document we have some required fields, jsonrpc, id, method and params.

jsonrpc needs to be set to 2.0 since that is the version we are using.

id can be set to anything you like in order to map the request with the response, the response will contain the same id as the request.

method is basically the "xcommand/xconfig" but its a little bit different, since with WebSocket we use xGet, xSet, xQuery, xCommand/path/to/basic etc.. but we will get back to that as we move on.

params is all the parameters to the method, it could be parameters or a path

To get started you need to choose your cup of language that you wish to use and find out if it has a websocket library. I will be using mostly Python3.7 in my examples and at the end I will show you how to start using WebSocket with jsxapi and NodeJS.

I also assume you have some experience of python and how to setup your environment.

Before you read further: Note that the following examples are not using the newly released XoWS library (pyxows for Python 3.7). If you scroll further down you will find examples that uses the pyxows library. I strongly recommend you to use the pyxows library but I will keep the below examples in this article for learning purposes.

For Python3.7 you can use a WebSocket library (I am using the websockets module) which can be acquired by issuing

pip install websockets

Below is a basic script I will use to show you how it works, as a start.

So the connection works, we can send data and receive data. In a WebSocket connection we dont deal with posts / puts / gets we send data and receive data back or we just receive data (feedback events, for example).

Here is a modified version of the above to make sending data a little bit easier, as the functions create the json documents automatically and I can interact with the xAPI by writing much simpler commands if you look in the "task" function now I use the get function to generate the JSON document while keeping the syntax almost the same as I would type it in the xAPI CLI.

Sending commands is a little different since the command path is in the method field, but the command function in the script will take care of building the JSON blob, all I need to type in is something that reminds me a lot of the macro command syntax:

Multi-line commands are identical to regular commands, but they provide the command body in the "body" parameter. A Multi-line command is a command that takes text as input. For example if you want to upload In-Room Control design as pure XML via WebSocket instead of uploading as a file through the web interface. Please see the API Reference guides for more information about Multi-line commands.

Feedback events is one of the more powerful things you can do with websockets without the need for a web server to receive the feedback events. The feedback events will be sent through the open connection from the codec when new feedback is available.

This is just deregistering the feedback based on the feedback ID you registered with.

Receiving feedback

Feedback is received as JSON-RPC notifications. The feedback message will include the feedback id. By changing the audio level we receive the following feedback message (after we registered the above feedback subscription):

If you are using jsxapi which is the NodeJS module for writing "external macros" you can switch from SSH to using WebSocket. See the following example (I know it seems cumbersome but this will improve going forward, finding easier ways of utlizing the WebSocket as a backend):

NEW: PYXOWS - XoWS Python Library for Python 3.7 =<

pyxows is a Python library or XoWS written by the super hero Morten Minde Neergaard and wraps around the XoWS feature to make it easier for you to get started! This library requires Python3.7 and above.

Callback is the function that is ran every time we receive feedback from the subscription. You can create several subscriptions on one device by adding more susbcriptions. I set True to report the current value of the feedback setting I am listening for.

When something happens on the feedback we can parse it in the callback function. I have modified the function a bit here, I am checking the first feedback id (id 0) if the audio volume goes above 60, set it back.

The request/response is close to realtime and very cool to work with, and with the async aspect of this you can create several instances with multiple devices at the same time. Lets do some more modifications to the script so it looks like this:

With these examples in place I hope you are able to take advantage of the pyxows library and create something awesome. The above works like a charm for test sequences, provisioning of multiple commands / configs and status checks etc. Use with Macros and In-Room Control? Go ahead!

Have fun, and please ask if you have questions.

Implementation

This is an integration feature like the XMLAPI its a different way of communicating with the xAPI but with the speedy benefits of WebSockets and pure JSON communication. Feel free to build on the examples in this blog post and create something awesome!

Known Issues & Limitations

Degraded error handling for WebSocket - improvment request for this is filed. Application errors will also be better documented in the future for those that wants to build their own WebSocket implementations.

Troubleshooting, diagnostics, limitations and advisories

When a new configuration or command is issues via WebSocket you will see this in the endpoint logs with the user that issued the command.

Websockets are a great idea if they’re implemented properly. Do you know if they are strictly following RFC-6455 and are they going to force TLS or can we test insecure and then add TLS before wide scale deployment?

0
Helpful

You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.

Hi,I have queries regarding Webex Teams:1.Can we segregate the teams(group) space and one to one space.2.Can we create different folders or directories in Webex Team chat space.3.Can we download Third party applications directly from Webex Teams instead o...
view more

Just wondering if anyone of you had experience to migrate CMBE 8.X to BE6K 11.X. As you know, CMBE shares IP with CUCM and Unity, so I am curious to know how to migrate or restore the Unity Connection. Thanks for any replies.

I have node unreachable showing in RTMT for 2 of my 5 servers.SDL Link OOS generated every 2 mins.Note* There is nothing down and there is full communication between all nodes and phones. I noticed after using the show network ipprefs all command tha...
view more

Fix:Log in to the codec.(you need the IP address, username / password) Go to:Setup > Configuration > Peripherals > (in the “Profile” area, set “Cameras” to 0.Press “Save” on the top right of the screen.Message went away.

Hello,I bought a DX80 with a defective touchscreen and I'm trying to use it with a mouse and/or keyboard, but none of these are working. Is there a way to configure DX80 to use a USB mouse? Software version: ce 9.2.4 4de75bc 2018-02-20 Than...
view more