The ENVision Protocol
The ENVision Protocol has been designed in connection with the FGF project, to establish an interface based on standard protocols used by ESO for the ELT.
The interface consists of two parts:
RTMS/MUDPI for the data transfer.
An OPC UA interface for the control and status monitoring of the camera.
State Machine
The state machine of an FGF Application is documented in Overview: State Machine.
OPC UA Interface
The ENVision control interface consists of four categories of nodes:
Nodes to control the frame grabber application, e.g. to set the exposure time and other parameters.
Nodes to display the status of the device.
OPC UA methods (aka RPC calls), used to control the device, e.g. starting and stopping the frame acquisition.
Application specific OPC UA nodes and methods needed for e.g. specific camera models.
The nodes are listed and documented in the following sections. The standard OPC UA nodes in the tables below are defined, applying the same notation as used for the PLC OPC UA interfaces for the device control in the ELT Instrument Control Framework.
The standard nodes described in the following must be defined as a minimum for an application to be a fully functioning ENVision-based application. It is allowed, to add additional nodes, if required to control and monitor the camera used.
ENVision OPC UA Control Nodes
The following control nodes are defined (category/prefix: “ctrl”):
Node |
Type |
Description |
|---|---|---|
ctrl.lrExpoTime |
Double |
Set the exposure time, applied during the frame acquisition. Given in seconds. Valid range: 1E-6 to infinity. |
ctrl.lrFrameRate |
Double |
Set the desirable frame rate in Hz. The frame rate may be constrained by the exposure time. The node “stat.lrFrameRate” indicates the actual frame rate obtained/applied. |
ctrl.nBinX |
Integer |
Set binning in X to apply during the acquisition. Valid range: 1 or more; the upper limit is defined by the ROI width (“ctrl.win.nWidth”). |
ctrl.nBinY |
Integer |
Set binning in Y to apply during the acquisition. Valid range: 1 or more; the upper limit is defined by the ROI height (“ctrl.win.nHeight”). |
ctrl.nFrameTarget |
Integer |
Defines how many frames to acquire in Finite Operational Mode. Valid range: 1 to infinity. |
ctrl.nOpMode |
Integer |
Controls whether to run the frame grabber in continuous or finite mode. Valid values: 1 (Finite Mode) or 2 (Continuous Mode). When running in Finite mode, “ctrl.nFrameTarget” will indicate the number of frames to acquire. |
ctrl.nOffsetX |
Integer |
Lower left pixel of ROI on the X axis. Given in pixels. Valid range: 0 to <chip width>. |
ctrl.nOffsetY |
Integer |
Lower left pixel of ROI on the Y axis. Given in pixels. Valid range: 0 to <chip height>. |
ctrl.nWidth |
Integer |
The width of the window read out. Given in pixels. Valid range: 1 to <chip width>. |
ctrl.nHeight |
Integer |
The height of the window read out. Given in pixels. Valid range: 1 to <chip height>. |
ENVision OPC UA Status Nodes
The following status nodes are defined (category/prefix: “stat”):
Node |
Type |
Description |
|---|---|---|
ctrl.lrExpoTime |
Double |
Actual exposure time, applied during the frame acquisition. Given in seconds. Valid range: 1E-6 to infinity. |
stat.lrFrameRate |
Float |
Frame rate in frames per second (Hz) currently obtained. |
stat.nFrameCounter |
Integer |
Indicates the number of frames acquired since the last “RpcStart”. |
stat.nTotalFrameCounter |
Integer |
Indicates the number of frames acquired by the frame grabber since it was started. |
stat.nWidth |
Integer |
The width of the window read out. Given in pixels. Valid range: 1 to <chip width>. |
stat.nHeight |
Integer |
The height of the window read out. Given in pixels. Valid range: 1 to <chip height>. |
stat.sCameraInterface |
String |
Defines the protocol, hardware, and SDK used to interface with the camera. Format: “<protocol>/<hardware interface>/<SDK name/version>”. |
stat.sCameraModel |
String |
Indicates the model of the camera controlled. |
stat.sCameraName |
String |
Indicates the logical (ESO) name assigned to the camera, normally in the context of the system (instrument) where it is used. |
stat.sCameraSn |
String |
Indicates the serial number allocated by the manufacturer of the camera. |
stat.sRpcErrorText |
String |
Provides the diagnostic in case an RPC (method) invocation failed and returned an error code. An empty string means no error. |
stat.sState |
String |
Indicates the state of the frame grabber. Valid values: “Off”, “On”, “Operational”. |
stat.sSubstate |
String |
Substate given as a string representation. Valid values: “NotRunning”, “Initialising”, “Idle”, “Acquisition”, “Error”. |
stat.sSystemErrorText |
String |
Indicates if the frame grabber application has encountered a failure condition. This node will be set if the camera enters the Error Substate. |
ENVision OPC UA Methods
For the method calls returning a status, a value of 0 (zero) indicates success. A value of 1 (one) indicates a general error. Other error code above zero may be allocated. Error codes below zero can be allocated/used by the specific frame grabber application.
Node |
Type |
Description |
|---|---|---|
Reset |
Input: None
Output: Return value (Int16)
|
Reset the frame grabber, triggering it to carry out a transition to “NotReady”. It may either remain in this state, until “rpc.Init” is submitted or it may auto-transition to “Initialising”, if the Auto-Init-Feature is enabled. During the re-initialisation, the configuration is re-loaded and applied as well as the connection to the camera reestablished. If the camera supports a ‘reset mechanism’ it will be invoked. |
Setup |
Input: None | “”
Output: Return value (Int16)
|
Instruct the camera to take over the present setup (control nodes) values. Only valid when in Idling substate. |
Start |
Input: <start time> (ISO8601) | “”
Output: Return value (Int16)
|
Start the frame acquisition. If no ISO8601 time stamp is given (= empty string), this means that the acquisition shall start immediately. |
Stop |
Input: None
Output: Return value (Int16)
|
Stop the frame acquisition. |
GetLoggers |
Input: None
Output: Return value (String)
|
Return the names of the loggers currently allocated in the application. |
SetLogLevel |
Input: level: String, logger: String
Output: Return value (Int16)
|
Set the logging conditions. This is the log level applied and the loggers that should be activated. level: “ERROR”, “WARNING”, “INFO”, “DEBUG”, “TRACE”.
logger: <name of logger>|””, empty string = all loggers.
|
Application Specific OPC UA Nodes and Methods
The ENVision protocol allows for camera/user specific applications, to add additional OPC UA nodes, to accommodate specific needs, e.g. for controlling a camera or to replicate status parameters, or for telemetry purposes.
The user is encouraged to follow the already existing structure and conventions.
It is possible to add new categories, e.g. “telemetry”.