Professional Documents
Culture Documents
SkanIt Automation Interface 2.0 User Manual
SkanIt Automation Interface 2.0 User Manual
SkanIt™ Automation
Interface
User Manual
API Version 2.0
Cat. No. N19215 Rev. 2.0 2018
© 2018 Thermo Fisher Scientific Inc. All rights reserved.
Manufacturer:
FI-01621 Vantaa
Finland
Thermo Fisher Scientific Inc. provides this document to its customers with a product purchase to use in the
product operation. This document is copyright protected and any reproduction of the whole or any part of this
document is strictly prohibited, except with the written authorization of Thermo Fisher Scientific Inc.
The contents of this document are subject to change without notice. All technical information in this
document is for reference purposes only. System configurations and specifications in this document supersede
all previous information received by the purchaser.
Thermo Fisher Scientific Inc. makes no representations that this document is complete, accurate or error-
free and assumes no responsibility and will not be liable for any errors, omissions, damage or loss that
might result from any use of this document, even if the information in the document is followed
properly.
This document is not part of any sales contract between Thermo Fisher Scientific Inc. and a purchaser. This
document shall in no way govern or modify any Terms and Conditions of Sale, which Terms and Conditions of
Sale shall govern all conflicting information between the two documents.
Preface
In this document, Automation Interface refers to the complete software package found on the
installation media of SkanIt Software for Microplate Readers, Research Edition, containing both the
automation server and the sample client.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i
About this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
SiLA Compliance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Contents of the Automation Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
User Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Automation Server (AI Server) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Automation Client (AI Tester). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Setting up the Automation Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Testing the AI Server with the AI Tester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Chapter 5 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Introduction
The Automation Interface provides high-level control for Thermo Fisher Scientific microplate
instruments in automation environments. Setting up an automation environment requires:
• robotics or a microplate stacker to handle the microplates
• hardware to integrate the instrument with the robotics, and
• automation master software (commonly called Process Management System or PMS for short) to
control the instrument.
The user can implement these components or acquire them from a third-party automation provider.
The Automation Interface provides a web-service based server (hereinafter AI Server), which enables
instrument control for the integrator's automation management software (hereinafter AI Client) via
web service calls. The AI Server is implemented with Microsoft's WCF technology but the choice of
technology for the AI Client is free as long as it allows web service communication.
The Automation Interface is a part of the SkanIt Software for Microplate Readers, Research Edition
release (hereinafter SkanIt) which must be installed before using the Automation Interface. In the
normal work flow, the end-user creates a session (this includes layout definitions, measurement steps,
possible result steps etc.) using SkanIt. After this step, SkanIt is closed and not needed anymore. Only
basic measurements can be created through the Automation Interface bypassing SkanIt. Through web
service calls to the AI Server, the AI Client then takes control of the instrument, loads the desired plates
using robotics, and starts the session execution. The measurement results are returned as XML data
from the AI Server, and also internally stored in the resulting session file. Session files created through
the Automation Interface can be opened in SkanIt for further analysis. Full reports of the execution can
be generated on demand (PDF, Excel, TXT, XML), including all calculation results, if calculation steps
had been defined in the session.
The Automation Interface 2.0 as described here and included in SkanIt Software 6.0 and later is not
compatible with Automation clients developed against version 1.0 (included in SkanIt Software
4.0-5.0). For a list of changes, see “Breaking changes” on page 13.
SiLA Compliance
The Automation Interface has been implemented to conform to the SiLA Device Class Interface
Design Guidelines Version 0.3 and the SiLA Device Control & Data Interface Version 1.3.08. The
Automation Interface provides an API according to the SiLA Command Dictionary Specification
Version 0.3 (herinafter the Standard) for an instrument of the SiLA Device Class "Reader / Imager".
In terms used by the SiLA Standard, the AI Server is the SiLA Service Provider for a "Reader" device.
Any SiLA-compliant Process Management System (PMS) can access and control the device, therefore
acting as a SiLA Service Consumer.
The SiLA compliance is implemented on the software level, i.e. the controlled devices themselves are
not SiLA-aware. The Automation Server hosts its own Web Service so it can be run either on the same
PC as the PMS, or on a separate PC. Thus the automation interface fulfills the SiLA integration level
2.
Due to the nature of the supported instruments, not all parts of the Standard are implemented.
Exceptions to the standard are listed in “Deviations from the SiLA Standard” on page 13.
For more information, visit the web page of the SiLA Standard at: http://www.sila-standard.org/.
Requirements
The Automation Interface requires the installation of the SkanIt Software for Microplate Readers,
Research Edition on the PC hosting the automation web service. For its system requirements, refer to
the SkanIt™ Software for Microplate Readers User Manual.
Note The Automation Interface is not supported for the Drug Discovery Edition (DDE) version of
SkanIt Software.
It is highly recommended to thoroughly familiarize yourself with the SiLA Standard, especially its
architecture and the SiLA state machine, prior to developing your own client.
Some basic knowledge about Microsoft WCF services is recommended, especially if you need to tweak
the AI Server configurations.
User Manual
This document.
Installation
This is the fastest way to get started. However, it is recommended to go through the configuration files
as described in “Configuration Files” on page 7.
Configuration Files
The Automation Interface consists of two configuration files that are used to set up the automation
environment, both AI Server and AI Client. All parts that the integrator might have to edit are listed
below, all other sections shall be kept unchanged unless the user is fully aware about their meaning.
Most WCF-specific settings are left at their default values.
AIServer.exe.config
This configuration file is needed for correctly setting up the AI Server. It is located in the SkanIt
installation folder alongside the main AIServer.exe executable.
Section <applicationSettings>
This section configures the device parameters.
Table 1. Device parameters.
Parameter Description
<add key="consoleApp" value="true" /> When set to "true", the server is running as a Windows console
application, on "false", the server is running as a Windows
Service. See comments in the configuration file for more details.
<add key="statusEventTimer" value="30000" /> Defines how often the server sends basic instrument status events
(e.g. temperature). The value is time in milliseconds.
<add key="aiDevice" value="1234-1234" /> Configures the device that shall be controlled. The value is the
device's serial number. Initially, there is a device simulator
defined so you can startup the AI Server without connecting a
real instrument. Only one device can be connected at a time. See
comments in the configuration file for more details about using a
device simulator.
Section <services>
This section configures how the automation server is accessible to incoming connections. Here only
the row for setting up the address and port has to be considered:
Section <system.diagnostics>
This section configures the server's logging. It is implemented according to Microsoft WCF
recommendations. The log is created to the path as specified in the <sharedListeners> element. All log
entries with "AISiLATrace" are created by the automation server's own code, everything else by the
underlying WCF framework.
AITester.config
The AI Tester is a sample AI Client that connects to the AI Server and uses the services the AI Server
provides. As it is implemented as a SiLA Service Consumer, it has a separate EventHandler (where the
AI Server sends events) which is a web server on its own. Therefore two addresses have to be defined in
the AI Tester config:
• the address and port of the server it connects to, and
• the address of the AI Tester and the port on which it is listening to incoming requests from the AI
Server.
Section <client>
This section contains the information about the automation server. Only the value of the parameter
"address" has to be edited. The value shall be the same address as described in Section <services> for
AIServer.exe.config above.
Section <services>
This section contains the information about the AI Tester (i.e. its event receiver). Can be "localhost"
only when both the server and client reside on the same machine. Otherwise, the correct IP has to be
used. Only the value of the parameter "baseAddress" has to be edited.
Section <system.diagnostics>
See Section <system.diagnostics> for AIServer.exe.config above.
For the values that can be set, see Table “Values for the
GetParameters command.” on page 10.
PrepareForInput (int requestId, string lockId, int This command puts the instrument into a state where it
position) is ready to accept new labware, i.e. the same as the
CloseDoor command.
PrepareForOutput (int requestId, string lockId, int This command puts the instrument into a state to release
position) the processed labware, i.e. the same as the OpenDoor
command.
SetParameters (int requestId, string lockId, string This command is used to send new parameter values to
paramsXML) the instrument. The format of the paramsXML can be
retrieved by using the GetParameters command. You can
use the AITester application's GetSetParameters button
to see what GetParameters returns and what will be sent
with the SetParameters command.
Custom commands
Note The GetErrors command is not supported by Fluoroskan, Fluoroskan FL and Luminoskan.
Mandatory commands Pause() and DoContinue() have been removed. Thus there is no state "Paused"
and no transition to or from such a state. Some instruments supported by SkanIt do not support
Pausing in between execution. Therefore the Automation Interface only supports functionality that is
also available in the SkanIt Software.
Breaking changes
Due to major redesign of the SkanIt Software in version 6.0, the API for the Automation Interface has
also changed and is not compatible with the previous version 1.0 (as included with SkanIt 4.0 to 5.0).
The following lists the breaking changes which have to be taken into account when updating AI
Clients from AI version 1.0 to 2.0.
The biggest change is the removal of the database and thus the file-based handling of SkanIt session
files (*.skax).
Other changes:
• GetMethods() command has been removed.
• Get-/SetParamaters(): the parameter SessionName is now OutputSessionPath and defines the file
name and location of the resulting session file.
• Delay() command has been removed.
• DoContinue() command has been removed.
• Pause() command has been removed.
• ImportMethods() command has been removed.
Troubleshooting
Table 7. Troubleshooting cases.
Case Issue How to fix
AIServer as a Windows Service and AIServer will not start automatically 1. Open the Registry Editor
Startup type is Automatic (can be and if starting it manually from (regedit.exe).
reproduced at least with slower services.msc, it will give an error:
machines) "Error 1053: The service did not 2. Create a new DWORD to
respond to the start or control HKEY_LOCAL_MACHINE\SYST
request in a timely fashion." EM\CurrentControlSet\Control.
Name it to "ServicesPipeTimeout"
and set its value e.g. to 60000 (60
seconds).