VisionMate Client

A Java client for accessing a Thermo Scientific VisionMate scanner via TCP/IP.

Compatibility

Scanner model AB-1850, software v3.2.1.10: works as is
Scanner model 312800, software v4.0.4.1: works with patches. There are bugs in this version of the VisionMate software. Thermo Fisher has provided these two patches, which are required in order for this library to communicate with the scanner software. Unfortunately, the patches have not yet been included in an official release. Installation instructions are included in the archives.
- TCPUpdate_dependencies.zip
- SBTCPServerV4.0.3.6.zip

Compile

mvn clean install

This will run unit tests, and compile the project, creating two jars

visionmate-client-<version>.jar
visionmate-client-<version>-jar-with-dependencies.jar

Testing

Mock server

A mock server class is included to allow testing without interacting with a real server. The mock server is made to imitate the real server as much as possible. Methods are provided to manipulate its current state and data before issuing commands to it over TCP/IP.

CLI

java -jar <jar-with-dependencies> <server-ip> <server-port>

A small CLI application is included for testing with a real server. Run it and type 'help' for a list of commands.

Unit tests

mvn test

The unit tests make use of the mock server, so that a real server is not required.

Release procedure

Choose the release type according to semantic versioning:
- "patch" if there are only fixes
- "minor" for most updates that add features
- "major" for milestone/huge updates

Release

git checkout master
git pull
./release.sh <release_type>

Usage

Configuration

Server Setup - V3 VisionMate Software

Enable the TCP/IP server: Open the VisionMate software and go to Export > Enable TCP/IP Server
Display the TCP/IP tabs: Config > Show TCP/IP Tab
Set a suffix character (TCP/IP Server tab). A suffix character marks the end of response data and is required for the client to function correctly. It is ideal to use a non-printable character to ensure that it is not found in barcodes or other data that the server may send. The suggested character is ASCII control character 3 (the end of text character), which can be chosen by entering '[3]'
Use a fixed rack ID: Rack ID > Use Fixed ID
Enable auto-login (optional) and ensure that settings are saved when the software is restarted
- Options > Auto Login > As Admin
- Options > Use Global Settings for all Users

It is recommended to leave other settings at their default, but if you'd like to change anything else, ensure that the option is supported in the client (see below).

Server Setup - V4 VisionMate Software

Enable the TCP/IP server: Export Options > TCP Server (a checkmark should appear to indicate it is enabled)
Set a suffix character: Export Options > TCP Server > Config > Data Field Suffix. The suggested character is ASCII control character 3 (the end of text character), which can be chosen by entering '[3]'
Add a rack type: You will need a rack with tubes in it in order to set this up as there is no option to manually define a rack type. Click Settings > RAD and follow the on-screen instructions to scan the rack. Name it in the format MRRCC, replacing "RR" with the number of rows, and "CC" with the number of columns. e.g. "M0812" for a rack with 8 rows and 12 columns. Ensure that this rack type is selected in Rack Formats

It is recommended to leave other settings at their default, but if you'd like to change anything else, ensure that the option is supported in the client (see below).

Client Setup

A ServerConfig object holds configuration settings that MUST match the server's configuration. It is recommended to use the default settings for everything EXCEPT for the suffix character. The default and recommended suffix character in the client is control character 3, as noted above.

Supported Operations

The following operations are available via the VisionMateClient

get status
reset status
get current product
set current product
get scan data
get last error

There are also convenience methods for monitoring status updates and getting scan data when a fresh scan is completed.

Example

try (VisionMateClient scanner = new VisionMateClient(<host-ip> <port>) {
	scanner.connect();
	// expect a matrix box with 8 rows and 12 columns
	scanner.setCurrentProduct(Manufacturer.MATRIX, 8, 12);

	// reset status, so we can observe status updates to find when a new scan has occurred
	scanner.resetStatus();

	System.out.println("Scan the rack now");
	Scan scan = scanner.waitForScan();
	if (scan == null) {
		// timed out; no rack was scanned
	}
	else {
		// rack was scanned
	}
}

miso-lims / visionmate-client