Socket Events

The communication of the individual modules with the socket server is entirely event based. Depending on the purpose, one of 4 event subtypes might be used:

• 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

Additionally, there are other event types for internal use, currently only one concerning the function of the hardware:

• Auth -- used exclusively by the server to acknowledge a successful negotiation and to signal that the exchanged token was accepted

Command

payload of the command event consists of two functional parts, the controlId and one or more key value pair. The former is a string specifying the addressed module; modules will ignore any commands that do not match their preset controlId exactly^[1]. The key value pair carries one specific instruction 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.

This form of communication does not fully rely on the socket server. If a module or internal event issues a command, it is first checked if the target controlId can be found on the same ESP32. Only if this check fails the command is send to the socket server which distributes it to every available module.

[
    "command",
    {
        "controlId":"moduleId",
        "key":"val"
    }
]

1. ↑ The only exception is *: This wildcard is accepted by any module. This should be used sparsely and only for very specific tasks that need to address all modules simultaneously.

Status

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.

[
"status",
    {
        "controlId":"moduleId",
        "status":
        {
            "busy":true,
            "absolute":0,
            "relative":50
        }
    }
]

Binary

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 method of the socket.io protocol, 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.

[
    "data",
    {
        "controlId":"moduleId",
        "type":"data",
        "data":"_placeholder",
    }
]

Error

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).

errnr	name	description/cause
0	deserialization failed	The ESP received a message that it could not interpret. Either the transport does not work as intended or there is noise on the USB interface
1	field is null	A field in the JSON formatted message was mandatory (e.g. controlId in a command) but could not be found
2	wrong type	A key value pair was found, but the value had an unexpected type for the key (e.g. a string instead of a float) and could not be converted
3	out of bounds	The command was received and accepted, but led to a target state outside the defined parameter range. It was constrained to the valid parameter range.
4	hardware failure	Hardware not working as expected. Might be a settings problem (wrong pin) or connection/hardware communication failing (e.g. camera not connected properly).
5	disconnected	An action was requested that the current connection state does not allow for. internal use only
6	busy	The module is currently carrying out a task and only accepts high priority commands like stop (the received command was rejected)

[
    "error",
    {
        "errnr":,
        "errmsg":"[moduleId] I encountered something I did not expect"
    }
]