Getting Started

Log-in

Login to a standard ELT machine.

IFW Software

If not yet done, retrieve and install the complete ICS Framework from the ESO RPMs repository. For more details, please have a look to the installation procedure here

You should create your software based on the provided template by following the procedure in the Getting Started guide here

This guide assumes you have followed all the steps in the above guide. The examples assume you selected the instrument as tins, the FCS component as fcs and the custom device as mirror. You can adapt the configuration according to your needs.

Database Server

The present version of the Device Manager uses Redis as the database engine to store run-time configuration (Redis documentation).

The DB server shall be running after following the general Getting Started guide here

The data is stored in the DB using a list of keyword/values. Each keyword has a hierarchical name that helps to idenfify its context, for instance the keys associated to a Device Manager start with the <server id> defined in the FCF configuration.

The ELT development environment provides a DB browser tool (dbbroser) that can be used to monitor the database keywords in an easy way similar to the ccseiDb tool in the VLT project.

alternate text

Dbbrowser tool screenshot showing Device Manager attributes.

dbbrowser &

Note

To get list of attributes in the dbbrowser is needed to configure the connection first. Menu Application option Open. Consult the dbbrowser User Manual in case of problems.

Note

The attributes will be populated only when the Device Manager server is started.

FCS Configuration

The project template includes a sample of a FCF configuration. The generated directory contains a fully working waf project with a custom device to be used as starting point for the development. After executing the cookiecutter command with the provided template, you can build, install and deploy the provided example.

Please follow the instructions in the general Getting Started guide here

The Device Server requires a configuration file including all the relevant information for the server. A pre-defined configuration has been created as part of the generation process. This configuration include three standard devices plus a the custom device.

Generated server configuration: <ins id>/resource/nomad/<component>.yml.tpl. This files contains the Nomad tags so it should not be used directly but through a nomad job command.

server_id           : 'fcs'

fcs:

    req_endpoint    : "zpb.rr://{{ range service "fcs-req" }}{{ .Address }}:{{ .Port }}{{ end }}/"
    pub_endpoint    : "zpb.ps://{{ range service "fcs-pub" }}{{ .Address }}:{{ .Port }}{{ end }}/"
    db_endpoint     : "{{ range service "tinsredis" }}{{ .Address }}:{{ .Port }}{{ end }}"

    db_timeout      : 2
    scxml           : "fcf/devmgr/server/sm.xml"
    dictionaries    : ['dit/stddid/primary.did', 'fcf/devmgr/server/fcf.did']
    fits_prefix     : "FCS1"

    devices         : ['shutter1', 'lamp1', 'motor1', 'mirror1']
    cmdtout         : 60000

shutter1:
type: Shutter
cfgfile: "local/shutter1.yml"

lamp1:
type: Lamp
cfgfile: "local/lamp1.yml"

motor1:
type: Motor
cfgfile: "local/motor1.yml"

mirror1:
type: Mirror
cfgfile: "local/mirror1.yml"

Note

This configuration shall be adapted to the instrument specific needs.

Device Manager Logs

$ nomad alloc logs -job fcs

The output of the server shall be something like the following:

2021-04-20T08:19:13.783333   INFO CfgFile - req_endpoint = <zpb.rr://134.171.2.250:24738/>
2021-04-20T08:19:13.783420   INFO CfgFile - db_endpoint = <134.171.2.250:27874>
2021-04-20T08:19:13.783437   INFO CfgFile - pub_endpoint = <zpb.ps://134.171.2.250:21765/>
2021-04-20T08:19:13.783519   INFO CfgFile - Devices: 4
2021-04-20T08:19:13.783535   INFO shutter1
2021-04-20T08:19:13.783552   INFO lamp1
2021-04-20T08:19:13.783566   INFO motor1
2021-04-20T08:19:13.783578   INFO mirror1
2021-04-20T08:19:13.799213   INFO Application fcsDevmgr started.
2021-04-20T08:19:13.817823   INFO PS Endpoint: zpb.ps://134.171.2.250:21765/std/status
2021-04-20T08:19:13.934309   INFO [shutter1] Warning device simulated !
2021-04-20T08:19:13.934391   INFO [shutter1] reading configuration keywords ...
2021-04-20T08:19:13.934943   INFO [shutter1] Publishing Endpoint: zpb.ps://134.171.2.250:21765/shutter1
2021-04-20T08:19:14.074730   INFO [lamp1] Warning device simulated !
2021-04-20T08:19:14.074812   INFO [lamp1] reading configuration keywords ...
2021-04-20T08:19:14.075311   INFO [lamp1] Publishing Endpoint: zpb.ps://134.171.2.250:21765/lamp1
2021-04-20T08:19:14.177424   INFO [motor1] Warning device simulated !
2021-04-20T08:19:14.178016   INFO [motor1] reading init sequence ...
2021-04-20T08:19:14.178057   INFO [motor1] number of init actions: 4
2021-04-20T08:19:14.178197   INFO [motor1] reading name position:motor1
2021-04-20T08:19:14.178222   INFO [motor1] number of named positions: 2
2021-04-20T08:19:14.178308   INFO [motor1] reading named position tolerance:motor1
2021-04-20T08:19:14.178344   INFO [motor1] named position tolerance: 1
2021-04-20T08:19:14.179338   INFO [motor1] Publishing Endpoint: zpb.ps://134.171.2.250:21765/motor1
2021-04-20T08:19:14.180703   INFO [motor1] Publishing Motor Endpoint: zpb.ps://134.171.2.250:21765/motor1/position
2021-04-20T08:19:14.382390   INFO [mirror1] Warning device simulated !
2021-04-20T08:19:14.382480   INFO [mirror1] reading configuration keywords ...
2021-04-20T08:19:14.382698   INFO [mirror1] Publishing Endpoint: zpb.ps://134.171.2.250:21765/mirror1

Note

The server can be started with option -l ERROR to remove the information logs.

Initialising the server

The client application can be used to send commands to the server from the command line:

$ fcfClient `geturi fcs-req` GetState ""

Note

geturi is an utility to compose the expected URI from the name of the registered Consul service.

The reply from the server shall be something like the following:

Idle/Operational/On/

Besides the above, you can also use the FCF CLI to interact with the server.

$ fcfcli --name fcs-req --module fcsclib.fcs_commands
zpb.rr://134.171.2.250:24738
fcsclib.fcs_commands
fcsSh> status

Note

In this case, the FCF CLI needs the parameter –module to include the changes to manage the custom device. If you do not have custom devices, you do not need to specify –module.

Using the DeviceManager GUI

Starting the GUI

$ fcsGui --uri `geturi fcs-req` &

You can control the devices from the GUI, for instance by selecting the action OPEN or CLOSE from the shutter widget and then pressing Setup button.

alternate text

Device Manager Engineering Graphical Interface.

Using the Motor Engineering GUI

Starting the GUI

This GUI can be started from the command line or launched from the fcfGui by clicking with the mouse pointer over the small ‘gui’ button on each motor widget.

pymotgui -d motor1 -a opc.tcp://127.0.0.1:7578 -p MAIN.Motor1 &
alternate text

Motor Engineering GUI.

Controlling Custom Device

Warning

The mirror device is a dummy device that is a showcase how to develop custom devices.

The mirror device includes a setup that triggers the execution of a custom RPC in the controller (simulator).

$ fcsSh> setup_spf mirror1:action="MOVE",mirror1:tip=2.1,mirror1:tilt=4.3

Note

The client library will convert the Simple Parameter Format (SPF) into JSON and check against the defined schema. If the validation is okay, it will send this JSON string to the server which it will pass it to the corresponding device to be processed.

Note

The same you can do from the custom GUI which provides a custom widget for this device.

The reply from the server shall be something like the following:

2021-04-20T13:01:55.551216   INFO Started SETUP command
2021-04-20T13:01:55.551443   INFO Processing Setup command ...
2021-04-20T13:01:55.551506   INFO ID: mirror1
2021-04-20T13:01:55.551621   INFO Setup buffer: {"action": "MOVE", "tip": 2.1, "tilt": 4.3}
2021-04-20T13:01:55.552321   INFO Action: MOVE
2021-04-20T13:01:55.552358   INFO Tip: 2.1
2021-04-20T13:01:55.552365   INFO Tilt: 4.3
2021-04-20T13:01:55.552373   INFO [mirror1] Executing RPC_PING ...
2021-04-20T13:01:55.553805   INFO [mirror1] Successful call of Mirror ping:

Forcing a Syntax Error

The custom device defines a sample schema where parameters tip and tilt are mandatory. If a setup is sent with a missing required parameter, this will be detected when validating against the schema, see below.

$ fcsSh> setup_spf mirror1:action="MOVE", mirror1:tip=3
'tilt' is a required property

Failed validating 'required' in schema['items']['properties']['param']['properties']['mirror']:
    {'properties': {'action': {'description': 'Mirror action.',
                               'enum': ['MOVE'],
                               'type': 'string'},
                    'piston': {'description': 'piston.', 'type': 'number'},
                    'tilt': {'description': 'tilt.', 'type': 'number'},
                    'tip': {'description': 'tip.', 'type': 'number'}},
     'required': ['action', 'tip', 'tilt'],
     'type': 'object'}

On instance[0]['param']['mirror']:
    {'action': 'MOVE', 'tip': 3}
JSON data not valid !
ERROR: something went wrong, setup buffer not modified
...

Working with a PLC

The following steps can be done to use the server configuration that was generated with controllers running in a PLC.

Note

The provided PLC project includes the corresponding simulators so hardware is not needed only a bare PLC. All the mapping is pre-configured and the PLC code is generated to match the server configuration (only the three standard devices).

Requirements

  • PLC available with required version of TwinCAT run-time and OPC-UA Server.

  • Windows development environment with required TwinCAT software installed.

  • All ESO PLC libraries installed in the Windows development environment.

  1. Load the PLC Project

From a Visual Studio load the PLC project generated. The project can be found in fcs1/LCS/plcprj1.

  1. Select Target System

Select the target system, this is the PLC that you want to use.

  1. Build the PLC Project

If you have errors, make sure you have all ESO libraries installed.

  1. Activate Configuration

This active the project configuration and restart the OPC-UA Server in the PLC.

  1. Login to the target system.

This will download the code to the PLC.

  1. Update the configuration of each device with the corresponding PLC address (IP).

lamp1:
  type: Lamp
  interface: Softing
  identifier: PLC1                             # OPCUA Object Identifier
  prefix: MAIN.Lamp1                           # OPCUA attribute prefix
  simulated: true
  ignored: false
  address: opc.tcp://134.171.59.99:4840        # <<<---- Change the IP here

  simaddr: opc.tcp://{{ range service "lamp1sim" }}{{ .Address }}:{{ .Port }}{{ end }}

  mapfile: "fcf/devmgr/server/mapLamp.yml"
  fits_prefix: "LAMP1"
  ctrl_config:
    low_fault:        false                     # If T, signal is active low
    low_on:           false                     # If T, signal is active low
    low_switch:       false                     # If T, signal is active low
    initial_state:    false
    timeout:          2000

  1. Stop the simulation for the devices

$ fcfClient `geturi fcs-req` Reset ""
$ fcfClient `geturi fcs-req` StopSim "lamp1, shutter1, motor1"

Note

By changing the flag simulated to false in the device configuration it is possible to make this change persistent.

  1. Set the server to operational state

$ fcfClient `geturi fcs-req` Init ""
$ fcfClient `geturi fcs-req` Enable ""

You can now operate the server with devices connected to the PLC controllers.

Stopping the Software

Stopping the GUI

The menu File has an option Exit. Please select this option if you want to stop properly the GUIs.

Stopping the Software

You can use the startup/shutdown script provide to stop the whole software. For more details please check the general Getting Started guide here