21. SiLA 2 Add-on
21.1. Introduction to SiLA 2 Add-on
The SiLA Add-on allows you to integrate any SiLA device into the CETONI Elements software. A generic, dynamically generated interface allows you to manually access all SiLA features, commands and properties of any SiLA device. With the help of several script functions you can automate your SiLA devices and integrate them into CETONI Elements scripts.
21.2. Installation of SiLA 2 Add-on
The SiLA 2 add-on is not included in the standard CETONI Elements installation package, but must be installed additionally as an add-on. The versions of SiLA 2 Plugin and installed CETONI Elements software should match. For example, if you want to install SiLA 2 Plugin with version number 20210707, CETONI Elements software should be installed with version number 20210707.
Important
The version number of the CETONI Elements software and the SiLA add-on should match. The version number of the SiLA add-on must never be greater than that of the CETONI Elements software. The greater the difference between the version numbers, the greater the risk of problems and errors.
Please close all other programs before installation.
Start the file CETONI_Elements_SiLA_64bit_Setup.exe for installation.
The installation wizard will then guide you through the installation of
the software and hardware drivers.
During the installation, the Bonjour Print Services are installed which are necessary for the automatic discovery of SiLA Servers in the network. This step is only required if the Bonjour Services are not already installed on your computer. If they are already installed, please deactivate the corresponding component (figure below).
Important
On Windows, you must be logged in with administrator privileges to install the hardware drivers.
21.3. SiLA 2 Basics
SiLA 2 is a communication standard for laboratory instruments, such as readers, liquid handling robots and chromatography and other analytical equipment. The primary goal of SiLA is to create an international, open connectivity standard in laboratory automation that allows devices from different manufacturers to communicate with each other in one application.
21.3.1. Client-Server concept
Communication is client-server based and uses established network standards. A SiLA server is usually provided by a device while a SiLA client is usually a control software (e.g. a LIMS or CETONI Elements). Since a SiLA server represents a device in most cases, the terms SiLA server (or just server) and device are used synonymously in this document.
Each SiLA Server has a certain number of Features implemented. SiLA Features are a key component of the SiLA 2 Standard as they define the interaction between the SiLA Client and the SiLA Server. Every single Feature describes a certain aspect of the overall behavior of the Server.
The features of a device (that is, a SiLA server) are described using an XML file where the functionality is described using:
Properties: data values that can be static (e.g. serial number) or dynamic (e.g. current temperature)
Commands: an interaction to control or pass information to/from the SiLA , an action that can be executed by a SiLA server
Parameters: expected information required to execute the command
Return values: expected output of the command
Errors: expected errors that might occur during the operation
21.3.2. Commands and Properties
Properties and commands can be both unobservable and observable.
Unobservable properties are static data of a server that do not change during the runtime of a server (e.g. the number of possible switching positions of a valve).
Observable properties are dynamic data of a server that can change during the runtime of a server and about which clients should be informed (e.g. the current flow rate of a syringe pump). Clients can subscribe to observable properties so that they are notified of any changes to the property.
Unobservable commands are actions that can be performed on a device and that take very little time (e.g., to change settings such as the syringe parameters of a pump).
Observable commands are actions that can potentially take a long time to execute on the device (e.g., fluid dispensing). Here, a client can subscribe to the so-called Execution Info to be notified about the progress of the command execution.
Tip
A comprehensive introduction to the SiLA standard is available on the SiLA homepage: https://sila-standard.com/standards/ or in this blog post.
21.4. Enabling the SiLA 2 Plugin
The SiLA 2 Plugin will not be automatically loaded after you have installed the AddOn. To enable the plugin you need to change your device configuration or create a new one.
In the device configurator’s device list there are two new devices available with the SiLA Plugin: A “Generic SiLA Client” and a “SiLA Device”.
21.4.1. “Generic SiLA Client”
This “device” enables the support for the generic SiLA Client UI (see section Overview of generic UI) and is thus only allowed once in a device configuration.
21.4.2. “SiLA Device”
Using this device you can statically configure any number of SiLA 2 Servers that should always be present in your device configuration. Simply drag and drop the number of desired SiLA Devices from the devices list into the configuration area and configure the connection to the Servers.
To configure the device enter the SiLA Server’s IP address or hostname and the port on which the Server is running. I necessary you can also force the use of insecure (i.e. unencrypted) communication to the Server. Then hit the Check Connection button. If the connection to the Server could be established you’ll see the green check mark.
Attention
Unencrypted communication should only be used for testing purposes but not in a production environment!
21.5. SiLA UI Overview
By clicking the SiLA 2 button and selecting Server Overview ❶ in the sidebar, you switch to the SiLA 2 add-on (see figure below).
SiLA 2 button for display of Server Overview and connected SiLA 2 servers.
Button to perform a network scan to find available SiLA 2 servers
Button to connect to all servers in the list
Display of all SiLA 2 servers found in the network or added manually
Button for adding a SiLA 2 server manually
Indicator displaying whether the connection to th SiLA 2 server is secure or insecure
Button to connect or disconnect from a SiLA 2 server
Button to delete the server from the list
You can use the sidebar button ❶ or the view tabs to switch between the currently connected SiLA 2 servers and the Server Overview. A tab is created for each server.
21.6. Connecting to a SiLA 2 server
21.6.1. Connecting to automatically detected servers
To connect to a SiLA 2 server that was found in the local network via SiLA Server Discovery, simply click on the Connect icon ❶ in the corresponding row in the Server Overview.
After the connection has been successfully established, the Disconnect icon ❷ appears instead of the Connect icon. By clicking on this icon you can disconnect from this device again.
Tip
The Connect-To-All ❸ button allows you to connect to all devices at once, rather than having to connect to each device individually.
Tip
If the software did not find one or more of your SiLA devices, it may help to restart the servers and run a new network scan ❹.
Tip
If you close the software while still connected to one or more SiLA servers, it will attempt to restore those connections the next time you start the software.
Important
If you delete a server with an active connection to the software from the Server Overview list, then the connection is automatically disconnected.
Normally, communication between SiLA server and client is encrypted. If you try to connect to a server that does not provide encryption a dialog will warn you about the insecure connection that will be established to the server. If you are sure that you want to connect to the server then selecting Yes will connect to the server without encryption.
Attention
You should never establish an unencrypted connection to a device that is outside your local network, otherwise all communication between the device and the software can be read by third parties.
21.6.2. Manually add and connect to a server
If a server in your local network is not found automatically, or if you want to connect to a server outside your local network, you must add this server manually. To do this, click the Add server ❻ button (see figure above). The following dialog box appears.
Enter either the host name or the IP address of your device and the port on which the SiLA server is running. Additionally, you have the option to force using an unencrypted communication to the Server. Then click Connect.
The software will now try to connect to this server. If this is successful, the server will appear in the Server Overview list. If the connection cannot be established, you will find an error message in the Event Log with information about why the connection failed.
21.6.3. Accept untrusted certificates
SSL certificates are used to encrypt the communication between server and client, which are also used to encrypt the communication on the Internet. Usually, these certificates are signed by a trusted certificate authority. If you try to connect to a server that uses a self-signed certificate, the following dialog box appears:
If you trust the certificate, click Yes in the dialog box to continue the connection, otherwise click No. In this case, the connection will be aborted.
By default the software will only remember your choice until you close the software. If you want the software to save your choice you can check the Always trust this certificate box. The next time you connect to this server you won’t be asked again to accept the certificate.
By clicking View Certificate you get more information about the certificate. There you can see, most importantly, which institution created and signed the certificate.
21.7. Control of a SiLA 2 server
21.7.1. Overview of generic UI
After you have successfully connected to a SiLA server, you can control it via a generic interface. This interface looks the same for any type of SiLA server, that is, for any device regardless of the type or manufacturer of the device.
Tip
While this interface allows you to control every aspect of a SiLA server, it cannot be used to create complex workflows. For this purpose, the script functions provided by the plugin, which are presented in Section SiLA 2 Script Functions, are more suitable.
Open the generic interface by selecting the desired server with the SiLA 2 button in the sidebar (see section SiLA 2 Basics). You will first see all SiLA 2 features provided by the server ❶. If you move the mouse pointer over one of the i icons, a tooltip with the description of the feature ❷ will appear.
By clicking on the feature name or the arrow to the left of the name, you can expand the feature (see figure below). Now you can see all available commands and properties of this feature. Commands can be found on the left side ❶, properties on the right side ❷. With the splitter ❸ you can resize the width that is available to the commands or properties.
21.7.2. SiLA Commands UI
If a command has parameters metadata or return values, such as the Set Fill Level command ❶ in the figure below, it can also be expanded to enter the parameters ❷ or metadata and display the return values. The following picture shows all commands of the Pump Fluid Dosing Service feature:
If a command has no parameters or only one, such as the Generate Flow command in the figure above, then the command cannot be expanded and at most one input field is displayed directly next to the command name ❸. To execute the command, click the Execute button ❹.
21.7.3. SiLA Properties UI
Normally, properties cannot be expanded. The picture below shows the SiLA properties of the Analog In Channel Provider feature. Here, only a field with the current value of the property is displayed ❶. To the right is a button for re-polling the property ❷.
Clicking the re-polling button button ❷ triggers one of the following two actions:
If the property is Unobservable (see Section Commands and Properties), then it is simply queried again by the server.
If the property is Observable, the subscription running in the background is canceled and a new subscription is started. This may be necessary, for example, if the subscription was automatically canceled due to an error.
It is possible that a property requires metadata. In this case, the property can be expanded like a command and the input fields for the metadata ❸ appear. After you have entered the metadata, you must query the property again or start a new subscription so that this data is sent to the server.
Important
When the generic interface is opened for the first time, all unobservable properties are queried once and subscriptions are automatically started in the background for observable properties. However, this only works if the property does not require metadata. In this case you have to enter the metadata first and then query the value yourself or start a subscription yourself.
21.7.4. Terminating a connection to a server
If you terminate the connection to a server or the connection is automatically terminated, e.g. due to a network error, the interface remains open, but all input fields and buttons are locked. If you then want to close the tab for the affected server, the following dialog box appears:
Clicking on Yes will close the interface (View) for this server and recreate it when the same server is reconnected later. By clicking on No, the view is retained and is only hidden. This allows you to reopen the view later, for example to see certain parameters or command responses. Furthermore, this view is automatically reused when the connection to the server is re-established.
21.8. Automatic reconnect
If you’re repeatedly working with SiLA devices that were connected to the corresponding server via the Server Overview you can enable that the servers that were connected the last time you used the software are automatically reconnected at the next start of the software.
To do this select from the top menu.
In the settings window select SiLA 2. To enable the automatic reconnect to previously connected servers check the first box.
In this windows you can also enable that the software tries to automatically reconnect to a server that disappeared from the network (e.g. due to a temporary network issue). To enable this feature check the second box. If the connection to a server is lost the software monitors the network and tries to reconnect to the server once it thinks that the server is available again. How many times the software will try to connect can also be specified.
If you don’t enable these features then you have to manually reconnect to the server in these cases.
21.9. SiLA 2 Script Functions
21.9.1. Introduction to SiLA Script Functions
The SiLA 2 plugin contains various script functions for script-driven execution of commands and querying of properties.
21.9.2. Execute SiLA Command
With this function you can execute a SiLA command and store the result of the execution in a variable.
You can set the command to be executed ❶, as well as the required parameters and metadata ❷ in the configuration area.
In addition, you can enable or disable the Run to completion ❸ option for Observable Commands. If Run to completion is enabled, script execution will not continue until the command has been fully executed. If this option is not active, the command is only started and then the next script function is processed immediately.
If the command has return values, you can also specify variables ❹ in which these values are to be stored.
Tip
All SiLA script functions support the use of variables. This means that you can enter variables in all input fields marked with a colored V in the configuration area.
21.9.3. Read SiLA Property
With this function you can query a property and store the value into a variable.
You can set the property ❶ to be queried and the possible required metadata ❷ in the configuration area.
Enter the name of the variable that is supposed to store the value of the read property in the field below ❸. If the property returns a structure of several values, corresponding fields will appear for each element of the structure, in which you can enter the individual script variables.
21.9.4. Wait For SiLA Property Value
This function allows you to make the script execution wait for a specific property to meet a defined condition. The function will not continue until the condition is met.
In the configuration area, first select the property ❶ you want to check and the optionally required metadata ❷, as described for the Read SiLA Property function.
Important
The SiLA property must be Observable to be used in this script function.
In the Condition area ❸, you configure the check condition. To do this, first select a comparison operator and then the value to be compared with. In the value fields you can also use variables to set the check condition.
Tip
To quickly find a specific feature, command or property, you can enter the name or part of the name in the filter input field. The selection boxes for the feature, command or property will then only contain entries that match the filter entered.
To prevent the function from blocking further execution for too long, you can
set a time limit in the Timeout (ms) field. If the time limit has expired and
the test condition is not yet true, the function generates an ERR_TIMEOUT error.
To deactivate the timeout, simply set the value to 0.
In short, the function can be described as follows:
Continue script execution, if the selected property of the device ❶ meets the condition ❸ or throw an error in case of a timeout.
Tip
Script Variables (such as $Value) can be used as test / comparison condition.
Tip
A timeout value of 0 deactivates the time limit.
21.9.5. Replace SiLA server
A SiLA server is always uniquely identified by its UUID (Universally Unique Identifier). When you create a script function for a specific server, this UUID is stored in the background. As a result, scripts are always bound to the SiLA server for which they were written. Now it can be possible that you want to use e.g. a script that you have written for a Nemesys low pressure pump with another low pressure pump or that a certain SiLA server had to be exchanged and therefore its UUID has changed. In these cases, you can replace the configured SiLA servers in your scripts with the new servers.
To do this, load the script in where you want to replace the servers into the script editor. Then select a SiLA 2 function where you want to change the server. The configuration interface of the function should be grayed out because the corresponding SiLA server is not connected. In addition, you will also see a warning message ❶.
Now click on the icon for changing the SiLA server ❷. The following dialog box opens:
Here you can now select one of the connected SiLA servers to be used instead of the configured server.
Important
The new server must provide exactly the same features as the previous server. The selection dialog will inform you if this is not the case.
If you have selected a compatible server, click on Assign selected Server. Now the previous server will be replaced by the selected server in all script functions. Afterwards, the configuration areais no longer grayed out and you can edit the function again. When you save the script, the server you just selected will be saved and used the next time you load the script.
21.10. Read SiLA properties via process data identifiers
Certain SiLA properties are automatically provided as process data. This makes it possible, for example, to initialize script variables directly via the respective process date or to use this data in the graphical process data logger.
For this purpose, the SiLA Properties must fulfill the following requirements:
the property must be observable.
the property must not require metadata.
the data type of the property must be a numeric (integer or real) or Boolean data type.
21.10.1. Use in other script functions
SiLA process data can be accessed in exactly the same way as other process data from other devices:
The selected process data identifier is now entered in the input field. These also have a specific form based on the usual process data identifier:
$$ServerName_ServerUUID.FeatureIdentifier_PropertyIdentifier
Each identifier starts with two dollar signs and a dot separates the unique device name from the unique process data name. The device name is derived from the name of the SiLA server as well as its unique ID (UUID, Universally Unique Identifier) and the name for the process data is derived from the name of the feature and the respective property. The entire process data identifier must not contain any spaces or other special characters.
21.10.2. Use in graphical process data logger
SiLA process data can be used in the graphical process data logger as known from other devices:
First, open the Plotlogger configuration ❶. There, drag and drop the desired SiLA device into the list of plot curves ❷. Then double-click on the device property cell to select the SiLA property to be recorded ❸.