Overview¶

Introduction¶

XO-VAC+ includes an API that can be accessed over its ethernet connection and allows the user to control the various components. These are based on a socket.io WebSockets connection built on top of TCP/IP. While normal usage is through the XO-VAC+ User Interface software, it is possible to control XO-VAC+ through the API directly with a configuration like this.

flowchart LR
  subgraph Y [Client Device]
    A(XO-VAC+ User Interface software)
  end
  subgraph X [XO-VAC+]
    B[XO-VAC+ Firmware]
    C[Sensors]
    D[Temperature Control]
    E[Vacuum Control] 
    B -->|RS485/Modbus| C
    B -->|RS485/Modbus| D
    B -->|RS485/Modbus| E
  end
  Y <-->|TCP/IP + WebSockets + Encryption| X

For the purposes of this documentation, the firmware and external software used to communicate with it are referred to as the 'server' and the 'client' respectively;

• Server - The XO-VAC+ embedded firmware.
• Client - The software communicating with the XO-VAC+ embedded firmware (either the XO-VAC+ User Interface software, or a user developed programme running through the API described in these pages).

Communication Direction¶

As the web-socket is bidirectional, there is no strict source-sink relationship between the server and the client. In the documentation below, we've differentiated between client-server and server-client communications in terms of the direction of information flow. Informally this documentation refers to:

• Commands - Sent from the client to the server to request a response or behavior.
• Responses - Sent from the server to the client to as the response to a command.
• Messages - Sent from the server to the client on an adhoc basis depending on the server's current state.

This has no physical meaning but helps to clarify the role of different communication packets.

Workflow¶

--Under Development--

Example¶

The server can be connected at the device IP and port using any implementation of the socket.io framework¹. For example, Python includes python-socketio which can be installed with

pip install python-socketio

This can then be used in scripts similar to the following

import socketio

sio = socketio.Client()

@sio.event
def connect():
    print('connection established')
    sio.emit('cancel_recipe', '')

@sio.event
def cancel_recipe_ack(data):
    print('message received with ', data)

@sio.event
def disconnect():
    print('disconnected from server')

sio.connect('http://localhost:8080')
sio.wait()

which should output something similar to

connection established
message received with  {"result": "warning", "message": "Could not cancel server running as server is not running."}
disconnected from server

Refer to the python-socketio for more details on the python example and refer to the following pages for details of the available commands and expected responses/messages