Socket Events
The XRTL Hardware is based on modules that control the various interfaces that connect the virtual representations of the exeriment to the real hardware representation located at the ESP32. This concept means that every motor, output or input is represented by a single (software) module that needs to communicate with the server. Communication is entirely event based, so every module updates relevant changes to the server and the server instructs the modules to actively change their state should it be necessary.
Events used for communication overall have 4 subtypes:
-
command-- instruct a module to execute a certain action -
status-- carries information about the current state of the module -
binary-- used to stream binary input data to the server (e.g. images or voltage values) -
error-- reports if something (and whenever possible details what) went wrong
payload of the command event consists of two parts, the controlId and the actual command. The former is a string specifying the addressed module; modules will ignore any commands that do not match their preset controlId exactly. The command contains at least one key value pair that specifies the instructions to the module. The command keys available vary depending on the module and can be found on the individual module sites. Multiple different keys can be combined within the same event, but only the first instance of identical keys will be executed.
A module will send a status message whenever a relevant change occurs, when it (re-)connects to the server or when the status is requested from the server. The payload of the status event contains two entries, the controlId of the sending module and the current status of that module. Contents of the status vary depending on the module type and can be found on the individual sites of the module.
Binary events are used to stream data from modules that continuously generate data from the module to the server. Because some events use the binary attachment methode of the socket.io protocole, the payload structure is slightly more complex. It contains the controlId of the module sending the data, a string type specifying the data type and the data itself.
In case a module encounters a command, value or situation outside its defined parameters, it will issue a report to the server containing the error type errnr and a short description errmsg. Furthermore, every error message starts with [controlId] to identify the module throwing the error. Note that some modules may have IDs that are not unique globally if they are not supposed to react on command events (e.g. socket and WiFi modules).
