Introduction#

This section will give an overview over the different parts of SECoP described in the different chapters of the specification.

We will start with the structural concept for the SECoP server, move on to the messages and in the end learn what the description is for a SECoP server and which datatypes are supported.

Background#

SECoP developed out of the need of multiple large scale facilities in the neutron science world to make equipment easier to share between facilities. This should not deter you from using it, as its flexibility allows for a wide range of use cases.

SECoP Node Structure#

  • SECoP is a communication protocol with a client-server model. The server is called the “SEC node”.

  • Each SEC node consists of one or more “modules”. These represent the main interface for interacting with the hardware.

  • Each of these modules can have static values which are known at startup and dynamic values. These are called “properties” and parameters respectively. Parameters can in turn have their own properties.

    Examples of properties would be the datatype of the parameter or the readonly flag that shows whether a parameter may be written to or not.

    To initiate actions that may not necessarily be tied to a parameter, modules can also have commands, like stopping the current movement or running a calibration.

  • To show which capabilities a module supports, and to give a name to common groupings, there are Interface classes and Features.

    The most important interface classes are Readable, Writable and Drivable.

  • Readable modules have a value and a status parameters, which show the current error state of the module. As the name implies, the main value can only be read.

  • Writable and Drivable modules allow influencing their value by writing to a target parameter. Writables are intended for fast operations like switches, where the target state can be reached quickly (i.e. sub-second operations or similar). Drivables funcion similar, but they can take longer to reach the target state. Think of a motor that has to drive to a position along a rail. For this, they would reflect the ongoing operation in their status, setting it to BUSY and returning to IDLE once the operation is complete.

Description#

The description is a formalized structure containing all information about the SEC node’s modules and their properties, parameters and commands. It is machine readable, with all details about modules, parameters, datatypes and so on included. Additionally, the implementor of the SEC node has to include textual descriptions for the important parts of the SEC node. These short documentation texts are not intended for machines, but for the human operators of the equipment. Functional dependencies that have to be machine readable are exposed through the already mentioned Interface classes and Features.

For the representation details, see the section Properties and descriptive data.

Data types#

A variety of datatypes are covered in SECoP. There are simple datatypes, for example:

For more complicated values, there are three structured datatypes:

  • Array, an array of uniform values

  • Tuple, a fixed sequence of items that can be of different types

  • Struct, a collection of named members, each of which has its own type

Implementations#

Implementing SEC nodes is best done with one of the preexisting frameworks.

Depending on your background or the technologies already in use with your facility, you can choose the implemenation that suits your needs best.

Communication protocol#

If you prefer to implement SECoP from ground up, this section gives the basics about the protocol.

SECoP is a line-based protocol. The communication between client and server builds upon messages which are transferred between SEC node and client.

Examples of messages are:

describe
read temp:setpoint
change temp:target 15.0
update temp:value [15.3, {"t": 1736239123.0}]

There are three parts a message can have: action, specifier and data. Of these, depending on the action, specifier and data may not be needed.

  • The first part, action, specifies the kind of message we want to send.

  • The middle part, specifier, points to the module, parameter or command we want to operate on.

  • Finally, data is the JSON-formatted data that may be needed for the specified action, like the new value when writing to a parameter, or the argument of a command.

The default mode for communicating between SEC node and client is a classic request-response mode, where the client initiates an exchange. However, if the SEC node implementation supports it, the client may choose to move to the asynchronous mode, where the SEC node will send updates asynchronously when they occur. For more details on this, see the activate message.