Froid.

Free Open Instrument Middleware

Fluffy and dated Functional Specification

version 0.8 lemoene, 30 January 2015. Requires a re-write

Creative Commons Bika Lab Systems

Table of contents

1 Purpose of this document 2

1.1 Document history v 0.8 2
2 Overview – instrument interface 2
2.1 Goal 2
2.2 Objective 2
2.3 Flexible design 3
2.4 Other products in this domain 4
3 CSV file exchange 4
3.1 Exporting worksheets to instruments 4
3.2 Importing analysis results from instruments 4
3.3 Easy enhancements 5
3.3.1 Correcting problematic imports 5
3.3.2 Referencing import files 5

4 Mirth 5

5 Froid 6
5.1 Protocols 6
5.2 LIMS-side. One interface only 6
5.3 LIMS-side. Exporting worksheets 6
5.4 LIMS-side. Importing results 7
5.4.1 Format 7
5.5 Instrument-side. Importing Worksheets/Sample lists 9
5.6 Instrument-side. Exporting analysis results 9
5.6.1 'Fetching' results 9

6 Managing Instruments 9
 1 Purpose of this document
This is a discussion document to establish a common understanding, in
layman's language, what the Free and Open Source Instrument Middleware,
Froid, does.
It is not a technical specification, but will be used to ensure Froid fulfils basic
functions.

1.1 Document history v 0.8

Requires a re-write. It essential remains the same document first completed
late 2012.

2 Overview – instrument interface

2.1 Goal
The Free Open Instrument Middleware (Froid) will be a free­standing 
instrument server for easy interface of any laboratory instrument to any 
laboratory software. Once established, the software should be vendor neutral 
to attract as many interfaces possible, all open sourced on the AGLP for 
protection. 
The current Bika LIMS interface module was designed with this in mind and 
can be used as a basis. Please see the Wiki pages:
Supported Instruments1
Creating an Instrument Import Interface 2
One of the purposes of Froid is to resolve serial RS232 communications with 
laboratory instruments.
The software will be well documented and easy to maintain to encourage
LIMS developers and instrument manufacturers to add interfaces to the
system.

2.2 Objective
The main purpose of the Froid is to resolve serial (RS232) and upcoming
USB communications with laboratory instruments.
Froid must communicate bi-directionally with LIMS using a singular easy to
understand file format while converting these to and from all possible
instrument communication protocols and formats. This will keep the
customisation in the LIMS itself down to a minimum.
For better load balancing, Froid must be free-standing to allow for it to be
deployed on its own hardware in high volume labs.
The Froid user interface for management and maintenance is to be web
based for easy remote access.
The LIMS/Froid import and export format must be defined as broadly as
possible, to include imagery and data blobs, and with enough redundancy to
take care of future interface developments.
Communication between the Froid server and the LIMS itself must be in line
with standards-compliant secure communication protocols offering
comprehensive data encryption.

1 https://github.com/bikalabs/Bika-LIMS/wiki/Supported-instrument-interfaces
2 https://github.com/bikalabs/Bika-LIMS/wiki/creating-an-instrument-import-interface
Page 2 of 9
 2.3 Flexible design

Froid logical design

For instruments not connected to PCs and capable of serial communication
only, Ethernet converters are recommended. These are not only cheaper
than providing PCs for all instruments, but also don't require cabling if Wi-Fi
with secure encryption is chosen. They often feature on-board web servers
which make remote support possible.
For an example, see Gridconnect's Wi232 3 and Net2324 converters:
Wi232 is a one-port device server that lets you connect serial
devices to 802.11b/g wireless or 10/100M Ethernet networks, quickly
and easily. FCC certified.
By merging wireless communications device server technology, the
Wi232 simplifies connectivity to devices where cabling is prohibited
or mobility is required. Serial RS-232 flexibility, robust data handling
capabilities and high serial speeds are all built in.
Using a method called serial tunnelling, the Wi232 encapsulates
serial data into packets and transports it over 802.11b or 802.11g
wireless Wi-Fi or 10/100 Ethernet networks. By connecting two
Wi232 units via a network, virtual serial connections can securely be
extended across your facility or around the world.
And:
The NET232 is an intelligent plug-and-play RS232-to-Ethernet cable
adaptor that enables any device or machine with a serial port, to
become Ethernet network and Internet enabled. Go from TCP/IP to
serial with the NET232. It features a powerful built-in device server,
so you can access your serial device from anywhere in the world
over internet.
The NET232 is easily configured via a web page, and can also be
set up through the serial port. You can use DHCP, AutoIP or assign a
Static IP address to the NET232
More technical information on Gridconnect's web pages. There are many
products like these available.

3 http://www.industrialethernet.com/gc-wi232.html
4 http://www.industrialethernet.com/net232-dte.html
Page 3 of 9
 2.4 Other products in this domain
Bartelt once interfaced Bika LIMS with their data collector5.
Data Innovations has 70% of the global middleware market with their
Instrument Manager™6 and recently bought the other big player, Dawning7.

3 CSV file exchange

Using Bika's interface handling as context:
Bika currently uses CSV or TXT files to 'interface' with a limited number of
instruments using the instruments' native file formats and identifying
samples by analysis request ID and individual analyses by their keywords
configured in the LIMS set-up.
See Wiki pages:
• Instrument Interfacing
• Supported Instruments
It does not interface directly with instruments only capable of serial
communications.
For the quickest solution, this infrastructure can be maintained with Froid
just slotting in as another CSV 'interface', but should ideally be automated
and 'modernised', using XML and web requests.

3.1 Exporting worksheets to instruments

Worksheet exports are written to a networked disk, using a file name
concatenated from the worksheet ID and instrument name. The user selects
which instrument the export is intended for from a drop-down menu of
instrument export templates available in the LIMS. These were developed
for, and sponsored by, Bika clients and are currently all hard coded...
The destination folder is determined by the browser used, e.g. it could be
configured to put the file in the browser's default downloads folder. The
instrument then picks the file up from this location and imports it.
For the Bartelt Data Collector8, the CSV also contains information about the
serially connected destination instrument for the Data Collector to convert
the worksheet into the correct format for the instrument.

3.2 Importing analysis results from instruments

The current text only Bika interface assumes instruments save their results
as CSV or TXT files on a network drive, most likely via a PC it is connected
to, and that the analyst gave the file a meaningful and easily recognisable
name.
From the same PC the analyst then navigates in its browser to the 'import
instrument' tab in Bika LIMS.
The user is then prompted to select the correct format from a drop-down
menu of all the import templates available in the system, and uses the PC's
standard 'browse' function to locate the file to be imported.

5 http://www.bartelt.at/home/unternehmen/bereiche/datentechnik/laborgeraeteserver/Data-
Collector-2.en.php
6 http://datainnovations.com/support/driver-downloads
7 http://www.dawning.com/InstrumentInterfaces/DriversCables.aspx
8 http://www.bartelt.at/home/unternehmen/bereiche/datentechnik/laborgeraeteserver/Data-
Collector-2.en.php

Page 4 of 9
 The user presses the [import] button, the LIMS reads the file and submits
the results to the database after validating them using the AR IDs and
analysis keywords.
A log is written to the screen during this process and all issues such as
unknown IDs or keywords highlighted. No results are ever overwritten in the
LIMS.
After the import, the results enter standard Bika workflow and QC, see flow
diagram above – none of these steps have to be duplicated during the
import. Only the import process itself needs to be properly managed for
accuracy.
For instruments such as NIRs capable of multiple analyses on the same
sample, all analysis regardless of whether they were requested by clients are
imported. Those not requested are not available to clients unless they
explicitly ask for them later.

3.3 Easy enhancements

3.3.1 Correcting problematic imports
Bika already uses a 2 phased import process for bulk analysis requesting. It
alerts users to non problematic import files, e.g. the use of non-compliant
keywords, and allows for human interaction to fix issues via an easy to use
GUI before data are submitted to the LIMS DB. This could easily be
implemented for instrument imports too

3.3.2 Referencing import files

For traceability purposes, analysis results imported from an instrument
should be linked to the raw input file where they originated from.

4 Mirth
Since Bika Health will also implement Open Source Mirth9 Connect10 to
facilitate HL7 messaging for EMR and other medical interfaces, it could be
worth our while to investigate it as instrument server too. Initial investigation
looks promising.
Update. This has since been commercially implemented by Lablynx, running
on a Pi with channels for instruments a s well as EMR comms in HL7, etc. At
the writing of this, no trace can be found of it on the Internet. Questions
remained about how they could integrate Mirth's FOSS license with
proprietary distribution.
From the Wikipedia 11:
Mirth is an open source cross-platform HL7 interface engine that
enables bi-directional sending of HL7 messages between systems
and applications over multiple transports.
HL7 has established itself as a standard in healthcare information
exchange. In order for an electronic health record system to integrate
or exchange data with HL7 systems, an adapter layer must be
implemented to transform messages.
Mirth allows messages to be filtered, transformed, and routed based
on user-defined rules. A web-based interface and channel creation
wizard associates applications with Mirth engine components.

9 http://www.mirthcorp.com/
10 http://www.mirthcorp.com/products/mirth-connect
11 http://en.wikipedia.org/wiki/Mirth_(software)

Page 5 of 9
 Mirth uses a channel-based architecture to connect systems with
other HL7 systems. Channels consist of endpoints (both inbound and
outbound), filters, and transformers. Multiple filters and a chain of
transformers can be associated with a channel. The Mirth web
interface allows for reuse of filters and transformers on multiple
channels.
Endpoints are used to configure connections and their protocol
details. Inbound endpoints are used to designate the type of listener
to use for incoming messages, such as TCP/IP or a web service.
Outbound endpoints are used to designate the destination of
outgoing messages, such as an application server, a JMS queue, or
a database
Some instruments need low-level harvesting of data, and to receive
commands to issue results, there is no streaming as such. It needs to be
investigated how Mirth would do this.

5 Froid
This functional description is more than 3 years old ...

5.1 Protocols
Special attention should be paid to the way Froid communicates with the
LIMS. It should follow recognised standards, such as https, possibly
enhanced to accommodate WebDAV. Moreover, the data format of the data
to be transmitted should comply with easy to handle file formats, such as
ASCII text or, preferably, UNICODE-enabled CSV.
Two different parts of of the Interface needs specification: communication
protocol on one hand, and data format on the other. There is, for instance,
no point in insecurely serving .CSV formatted data via USB storage.

5.2 LIMS-side. One interface only

Froid strives for a single interface to the LIMS to keep work on the LIMS
itself down to a minimum. This however will be tricky due to the different
interim values returned by many instruments in addition to the actual result
that will be reported to the lab client. See Importing results from instruments
below. This objective most certainly rules CSVs out in favour of more flexible
XML.
Current Bika CSV interfaces, as well as CSVs produced by other instruments
not requiring serial conversion, should also go through Froid to keep
everything uniform on the LIMS-side.

5.3 LIMS-side. Exporting worksheets

This is the simplest part of the interface LIMS-side, and many dedicated
instruments will do with a simple list of Sample IDs and their analysis
sequence or position in the instrument's tray. On the other hand it can be
elaborated to contain as much information possible.
A slightly enhanced export to an instrument capable of multiple analyses per
sample could look like this in CSV format:

Page 6 of 9
Worksheet
Analyst Instrument Method
ID
WS11-123 John Smith AA-002 AA
Tray Date Time Sample Analysis Analysis Analysis Analysis Analysis
Sample ID --
position sampled sampled Type 1 2 3 4 n
1 AR11-123 11/09/01 09:01 Ore Ag Al Au Cu -- Pb
2 AR11-124 11/09/01 09:08 Slag Ag Al Au Cu -- Pb
3 AR11-125 11/09/01 09:15 Core Ag Al Au Cu -- Pb
4 AR11-126 11/09/01 09:22 Ore Ag Al Au Cu -- Pb
--- --- --- --- --- --- --- --- --- --- ---
n AR11-222 11/09/01 12:36 Ore Ag Al Au Cu -- Pb

A header section identifies the export, which is then followed by a number of

samples, each on its own row, with the requested analyses in columns. An
XML representation of this will be equally simple.

5.4 LIMS-side. Importing results

5.4.1 Format
Note that instrument imports do not have to match worksheets in the LIMS,
the sample and AR IDs are used to match the results to requested analyses
regardless of whether they were grouped together on worksheets or not.
Many instruments produce analysis results that are reported with a number
of interim values. In the case of the different spectrometers, the result itself is
reported, say in ppm, as well as any combination of: dilution factor, reagent
volume, peak number, peak height, mean, standard deviation, relative
standard deviation, coefficients, etc.
These are then repeated per analyte on the sample while at the same time a
differing number of data fields can be reported for the sample itself, e.g.
temperature, number of data points (on the curve), starting peak width, peak
threshold, etc.
The analysis batch itself could have a number of attributes too, seen before:
reagent ID, batch no, electrode ID, serial no, column, etc.
This scenario makes a very strong case for XML.
In pseudo format:
Repeat for Import header:
Field title
Field value
Repeat for Samples
Field title
Field value
Repeat for Analytes
Field title
Field value
Repeat for Interim values
Field title
Field value

Page 7 of 9
 There's not enough space here to express this as a detailed CSV definition.
An overview:

Inport header information

Analysis 1 Analysis 2 Analysis 3

Sample
information,
1 sample Interim Interim Interim Interim Interim Interim Interim Interim Interim
Result Result Result
per row value 1 value 2 value 3 value 1 value 2 value 3 value 1 value 2 value 3

The table can be expanded further to the right if required, some NIRs are
known to do 30 or more different analyses on the same sample.
The Import header in rows 1 and 2, more fields can be added, TBD indicates
'to be defined':

Import ID Analyst Instrument Method TBD --- TBD

I11-0123 John Smith AA-002 AA --- --- ---

The next rows per sample (excluding analysis results which will follow in
further columns to the right):

Position Sample ID Date analysed Time analysed Duration TBD --- TBD
1 AR11-123 11/09/01 11:00:00 00:04:39 --- --- ---
2 AR11-124 11/09/01 11:05:00 00:04:24 --- --- ---
3 AR11-125 11/09/01 11:10:00 00:04:49 --- --- ---
--- --- --- --- --- --- --- ---
n AR11-222 11/09/01 12:20:00 00:04:15 --- --- ---

On the same rows to the right follows a number of columns per analysis:

Analysis 1 Interim field 1 Interim field 2 --- Interim field n

Pos Sample ID --- Keyword Value Unit Notes File name File Title Value Unit Title Value Unit --- Title Value Unit
1 --- --- ---
2 --- --- ---
3 --- --- ---
--- --- --- ---
n --- --- ---

These are repeated for each analysis in the Import and in real life could look
like this:

Position Sample ID --- Keyword Value Unit Title Value Unit Title Value Unit Title Value Unit
1 AR11-123 --- Ag 1.66 ppm Dilution 1 SD 0.33 ppm RSD 0.23 %
2 AR11-124 --- Ag 2.43 ppm Dilution 1 SD 0.68 ppm RSD 0.45 %
--- --- --- --- --- --- --- --- --- --- --- --- --- --- ---

And then repeat for more analyses to the right.

Page 8 of 9
5.5 Instrument-side. Importing Worksheets/Sample lists
Once the worksheets from the LIMS land in Froid, it interprets the worksheet
and prepares it in the correct format for the corresponding instrument. From
here on it depends on how the specific instrument functions. Loosely
defined, it could be 'listening' to Froid, and the data simply streamed to it.
Either way, Froid writes the data to the instrument when it is ready to receive
it.
Once the analyst is satisfied the worksheet has been successfully
transferred, he/she proceeds with analysing the samples.

5.6 Instrument-side. Exporting analysis results

Once analysis is completed, the analyst exports it from the instrument. How
this is done will depend on the individual instrument. It might happen
automatically or the instrument operator has to action a 'send' function.
Froid continually polls the instruments connected to it and when the data
becomes available, parses and converts it to the LIMS import format, likely to
be XML, and passes it on to the LIMS.
The best way to do this is to be determined after technical analysis. Some
guidelines are:
No validation other than checking for matching the data correctly to
analyses in the LIMS needs to be performed. The LIMS is configured
for complete QC and that should not be a Froid function.
The process should be automated as far as possible – only when
keyword inconsistencies or other import issues arise should user
interaction be necessary. The Bika bulk AR import functionality could
be re-cycled for use here – it features a validation step with clear
user interface for fixing errors in import files.

5.6.1 'Fetching' results

Some instruments only issue results data streams in response to a command
that have different lengths in accordance to the number of samples in
process. The number of samples is not always evident at the time when
sending of the data request. Example: Becton Dickinson MGIT 960 in GND
mode.
Froid should therefore have the ability to issue commands to be sent to the
instrument serial interface, and to receive data sets from the serial interface
in response to these commands.
The user should be able to request the results from the LIMS itself without
having to log into Froid itself. This will mean a “go ask the instrument”
function/button in the LIMS.

6 Managing Instruments
Some LIMS implementations will also require instruments to be managed
from the LIMS itself, e.g. started up and initialised, shut down, cleaned etc.
This opens an additional spec for Froid: An open, modular interface structure
that allows for easy extension for both data input (commands) and output
(data streams).
This could be implemented in a second phase for Froid.

Page 9 of 9