check, logging: Optional extensions#

These sets of messages are optional feature - the SEC node does not need to support them and should reply with a ProtocolError error to indicate this.

Dry run functionality#

request check <module>:<accessible> [<value>]#
reply checked <module>:<accessible> <data-report>#
reply error_check <module>:<accessible> <error-report>#

The check value message is used to enable dry run functionality on parameters and commands. It consists of the module and accessible name, in addition to the value to be verified. It allows an ECS to verify if a value can be set on a particular parameter without actually changing it with a change message. Similarly, it can be used on commands to check if a value is a valid argument, without executing the command. This check goes beyond a simple validity check based on the accessible’s datainfo and may depend on the current configuration of the entire SEC node. Upon successful completion of the check, a checked response is sent, containing a Data report of the verified value. The accessible property checkable indicates whether an accessible can be checked.

Remarks

  • The response to a check message must not depend on the current status of the module.

  • A check message must not change anything, neither on the hardware nor on any parameter.

  • The checked and error_check messages are only sent in response to the check message on the same connection, and not to other clients with an activated connection.

  • If the check fails, the error report should indicate whether this is due to the current configuration of the SEC node (Impossible), or because the checked value is outside the range (RangeError) specified by the datainfo property.

Examples:

> check mf:target [1.0, 1.0, 2.0]
< checked mf:target [[1.0, 1.0, 2.0], {}]

> check mf:target [1.0, 2.0, 2.5]
< error_check mf:target ["BadValue", "value outside allowed sphere", {"closest_valid": [0.8, 1.6, 2.0]}]

> check cryo:target 2.7
< error_check cryo:target ["NotCheckable", "", {}]
Related issues
SECoP Issue 075 New messages check and checked

Logging support#

request logging <module>[:<parameter>] <level>#
reply logging <module>[:<parameter>] <level>
reply error_logging <module> <error-report>#

Enables the SEC node to send log messages generated by the given module.

The level is a JSON string, either “debug”, “info”, “error” or “off”. This is supposed to set the ‘logging level’ of the given module (or the whole SEC node if the specifier is empty) to the given level:

This scheme may also be extended to configure logging only for selected parameters of selected modules.

“off”

Remote logging is completely turned off.

“error”

Only errors are logged remotely.

“info”

Only ‘info’ and ‘error’ messages are logged remotely.

“debug”

All log messages are logged remotely.

A SEC node should reply with an Error report (ProtocolError) if it doesn’t implement this message. Otherwise it should mirror the request, which may be updated with the logging-level actually in use. I.e. if an SEC node does not implement the “debug” level, but “error” and “info” and an ECS requests “debug” logging, the reply should contain “info” (as this is ‘closer’ to the original request than “error”) or “off”. Similarly, if logging of a too specific item is requested, the SEC node should activate the logging on the least specific item where logging is supported. E.g. if logging for <module>:<param> is requested, but the SEC node only supports logging of the module, this should be reflected in the reply and the logging of the module is to be influenced.

Note

It is not foreseen to query the currently active logging level. It is supposed to default to "off".

event log <modulename>:<loglevel> <message>#

This is an asynchronous event only to be sent by the SEC node to the ECS which activated logging.

Logging example:

# note: empty specifier -> select all modules
> logging  "debug"
# SEC node confirms
< logging  "debug"
< log mod1:debug "polling value"
< log mod1:debug "sending request..."
...

Another example:

# enable full logging of mod1
> logging mod1 "debug"
# SEC node can only log errors, logging of errors of mod1 is now active
< logging mod1 "error"
< log mod1:error "value par1 can not be determined, please refill read-out liquid"
...
> logging mod1 false
< logging mod1 false