Ctrl+K

6. Future Compatibility - notes for implementors#

6.1. notes for implementors of current specification#

# As JSON can not handle non-numerical quantities like ‘Inf’ or ‘NaN’,

either an appropriate error message should be generated, or the closest representable numerical value (+/- double_max?) should be used.

# all values transferred between ECS and sec-node should be validated on both sides.

This may be relaxed in future specifications. Errors, which arise from the validation of SEC-node values on the ECS-side should not crash the ECS and should inform the user about this violation of specification along with the data, the validator and why validation failed.

6.2. Data transfer#

SECoP relies on a stream transport of 8-bit bytes. Most often this will be TCP. In those cases the SEC-node SHOULD support several simultaneous connections.

RS232 style connections may also be used. Here, only a single connection can be used. If several connections are needed, a ‘multiplexer’ is needed. This should offer multiple TCP connections and contain the necessary logic to map requests/replies from/to those network connections onto/from the serial connection to the actual SEC-node.

6.3. Foreseen extension mechanisms#

The herein specified protocol has foreseen some extension mechanisms in its design:

  • add actions, keeping the ‘triple’ structure of action/specifier/data

    Note

    That is why custom actions MUST be prefixed with an underscore.

  • extent specifier with ‘:’ separated identifiers, getting more and more specific

    An empty string as specifier addresses the SEC-node, <module> addresses a module, and <module>:<accessible> addresses an accessible of a module.

    If there will ever be such things as node-accessibles, they will be addressed as :<accessible>. Also properties may be addressed like <module>:<accessible>:<property>.

    In the same sense as an empty string selects the whole SEC-node, <module>: may select ALL parameters of a module.

  • define additional parameter/command/property names

  • extend reports (only append to them, never changing the already defined fields)

    Note

    The structure report may need to be nested inside a JSON-array in the future, should we need to extend that.

  • use so far unused datafields (there are not so many).

  • define additional status groups or statuscodes

  • define additional interface classes

  • define additional features, being listed in an additional property

6.4. Message handling#

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

Any ECS is allowed to generate the following messages:

defined_requests

Any SEC-node is allowed to generate the following messages:

defined_replies

The specification is intended to grow and adopt to new needs. (related issue SECoP Issue 038 Extension mechanisms) To future proof the the communication the following messages MUST be parsed and treated correctly (i.e. the ignored_value part is to be ignored).

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

must_accept_requests

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

must_accept_replies

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:

data_report ::= "[" JSON-value "," qualifiers ("," ignored_value)* "]"

Error report:

error_report ::= '["' errorclass '","' error_msg '",' error_info ("," ignored_value)* "]"
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) (i.e. treat error BadValue:WrongType as error BadValue, ignoring the :WrongType part)

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

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

Complying to these rules maximize to possibility of future + backwards compatibility.

Note

Also check SECoP Issue 036 Dynamic units as it may have implications for a certain implementation.

6.5. Binary representations of the protocol#

so far only the above described, textual protocol is defined. Since this is not optimal for bandwidth limited connections (e.g. RS232), a shorter, binary representation may be developed. This will essentially keep the structure of the messages, but replace the components of a message with shorter, binary representations.

Good candidates for this are CBOR (see RFC 7049) and MessagePack (see https://msgpack.org/).

On this page
Show Source