3.3. Complete message syntax#

This section formally defines the syntax of SECoP messages with the use of so-called “railroad diagrams”.

Basic grammar of messages

../_images/basic-grammar.svg

Requests and replies

The specification defines a set of requests and replies. Only those messages are allowed to be generated by any software complying to this specification:

Any ECS is allowed to generate the following messages:

../_images/defined-requests.svg

Any SEC node is allowed to generate the following messages:

../_images/defined-replies.svg

Compatibility

The specification is intended to grow and adapt to new needs. To futureproof the the communication, the following messages MUST be parsed and treated correctly (i.e. the ignored_value part is to be ignored).

Related issues
SECoP Issue 038 Extension mechanisms

Any SEC node MUST accept the following messages and handle them properly:

../_images/must-accept-requests.svg

Any ECS MUST accept the following messages and handle them accordingly:

../_images/must-accept-replies.svg

As a special case, an argumentless command may also by called without specifying the data part. In this case an argument of null is to be assumed. Also, an argumentless ping is to be handled as a ping request with an empty token string. The corresponding reply then contains a double space. This MUST also be parsed correctly.

Similarly, the reports need to be handled like this:

Data report:

../_images/data-report.svg

Error report:

../_images/error-report.svg

Essentially this boils down to:

  1. ignore additional entries in the list-part of reports

  2. ignore extra keys in the qualifiers, structure report and error report mappings

  3. ignore message fields which are not used in the definition of the messages (i.e. for describe)

  4. treat needed, but missing data as null (or an empty string, depending on context)

  5. if a specifier contains more “:” than you can handle, use the part you understand, ignore the rest (i.e. treat activate module:parameter as activate module, ignoring the :parameter part)

  6. same for error class (i.e. treat WrongType:MustBeInt as WrongType, ignoring the :MustBeInt part)

  7. upon parsing a value, when you know it should be one element from an enum (which SHOULD be transported as integer), if you find a string instead and that string is one of the names from the Enum, use that entry.

  8. check newer versions of the specification and check the issues as well, as the above may change

Complying to these rules maximizes the possibility of future and backwards compatibility.

This Page