Hamilton Microlab STAR

This page covers connector installation, configuration, and a first test for the Hamilton Microlab STAR line of liquid handlers. The Hamilton manuals cover instrument installation, maintenance, and safety. To operate the instrument, see the Hamilton STAR guides.

This page applies to connector version 0.9.0 and later. If you use an older version, update the connector before you continue.

What you need

Close Venus, Hamilton Service Software, and any other program with an open connection to the instrument before starting the connector.

Models

The models of the STAR line differ in deck size, which Hamilton measures in tracks. The STARlet has 30 tracks, the STAR 54, and the STARplus up to 71.

STAR line instruments differ in their hardware configuration, including the presence and number of pipetting channels, pipetting heads, and transport tools. The same connector supports all models and reads the device configuration from the instrument firmware. It exposes only the modules present on the physical device through the SiLA 2 interface. See Supported modules. If you start the connector in simulation mode, it exposes all modules, so you can try every service without the hardware. The connector continues to expose all modules after you switch to the real instrument. See Simulation. For detailed model and configuration specifications, consult the manufacturer's documentation.

Install and configure the connector

1. In GroundControl, add a device, search for Star, and select the model: Microlab STAR, Microlab STARlet, or Microlab STARplus (how to add a connector).
2. Fill in the device-specific configuration:

   Field	Value
   simulation_mode	false for the real instrument (the default). true starts the connector with a simulated, fully equipped STAR, with no instrument connected. The connector then shows all modules, also after a switch to the real instrument. See Simulation
   use_usbio	true (the default) uses Hamilton's STAR USB driver on Windows. Set it to false if the STAR is bound to WinUSB or libusbK. See USB driver on Windows

3. Start the connector. It opens a connection to the instrument and reads which modules are installed. GroundControl then lists the services for those modules.

To run the connector on a machine without GroundControl, see Headless install.

USB driver on Windows

On Windows, the driver that the STAR is bound to must match the use_usbio setting:

• Hamilton's STAR USB driver (STAR_USB_W10.inf, installed with Venus): keep use_usbio: true, the default. With this driver, you can switch between Venus and the connector without swapping drivers. Venus and the connector can't connect to the instrument at the same time, so close one before you start the other.
• WinUSB or libusbK, for example bound with Zadig: set use_usbio: false.

If the driver and the setting don't match, the connector doesn't come online. It logs NoSuchDeviceFound: Device not found and tries again every 20 seconds.

USB setup on Linux

On Linux, the connector uses the libusb library for USB communication. Add a udev rule that grants members of the plugdev group access to the device. Without it, the connector only runs with sudo.

1. Plug in the STAR. To find its vendor and product IDs, run:

   lsusb
   

   
   The STAR appears as Hamilton Bonaduz AG ML STAR with an ID such as 08af:8000. Note both parts of the ID.
2. To grant access, create the rule file /etc/udev/rules.d/99-hamilton-microlab.rules with the IDs from step 1:
   /etc/udev/rules.d/99-hamilton-microlab.rules

   SUBSYSTEM=="usb", ATTR{idVendor}=="08af", ATTR{idProduct}=="8000", MODE="0660", GROUP="plugdev"
   

3. Check that your user is in the plugdev group. Most Ubuntu users already are.

   groups $USER
   

4. Optional: if plugdev is missing, add your user to it, then log out and back in.

   sudo usermod -a -G plugdev $USER
   

5. To apply the rule, reload the udev rules:

   sudo udevadm control --reload-rules
   sudo udevadm trigger
   

6. Unplug and replug the USB cable, then start the connector without sudo.

Supported modules

The UniteLabs Microlab STAR connector supports the following modules.

The connector reads the instrument configuration from the firmware and registers services only for the modules that the configuration reports. If a service is missing, check the instrument configuration.

The connector doesn't detect a heater shaker itself. It reads the "shaking incubator installed" flag from the STAR firmware configuration, which is set by Hamilton service technicians. To control a heater shaker as a module through the STAR connector, connect it to the STAR with an RS232 cable at the TCC 1 or TCC 2 port of the STAR's periphery connector board. If the heater shaker is instead connected directly to the computer via a USB cable, use the separate Hamilton Heater Shaker connector.

Not yet supported: XL (5 ml) channels and the 384 head.

Simulation

The Simulation Controller Service is always registered. Use it to switch between the simulation and the real instrument while the connector runs. The services stay the same after a switch, because the mode that the connector starts in sets them:

• Started with the real instrument, then switched to simulation: the simulation keeps the configuration of the real instrument, with the same modules and services.
• Started in simulation, then switched to the real instrument: the connector continues to show all modules, including modules that the real instrument doesn't have. The connector doesn't stop commands to these modules. It sends them to the instrument, and the command fails with a firmware error. To see only the modules that the instrument has, start the connector with the real instrument connected.

When you switch to the real instrument, the connector waits 10 seconds for the instrument to connect and answer. If it doesn't, the switch fails and the connector stays in simulation mode.

First successful test

The STAR connector is a SiLA 2 server and can be used like any other device through the UniteLabs SDK, as described in UniteLabs SDK & REST API. Run this code in a notebook or an async script to confirm a roundtrip from instrument to SDK. This example reads the firmware version and doesn't move the instrument.

Replace Microlab STAR with the service name shown in GroundControl. Microlab STAR is only the default name. After a rename, the lookup returns None and the next line fails.

from unitelabs.sdk import AsyncApiClient

client = AsyncApiClient()
hamilton = await client.get_service_by_name(name="Microlab STAR")

print(await hamilton.device_service.get_firmware_version())

Run the same test with the Liquid Handling SDK

To work with liquid handlers, use the Liquid Handling SDK. It models the deck and the labware, provides programming abstractions, and adds a layer of safety checks.

This code reads the firmware version and the instrument configuration. get_configuration() collects the configuration from several connector commands and returns it as a single object. As in the previous example, use the service name shown in GroundControl.

from unitelabs.liquid_handling.hamilton import MicrolabSTAR

hamilton = MicrolabSTAR(name="Microlab STAR")

print(await hamilton.get_firmware_version())

configuration = await hamilton.get_configuration()
print(configuration)

Command execution

• Canceling. The connector can't cancel or interrupt a running command. Stop on the Device Service goes into the same queue as all other commands, so the connector sends it only after the current command finishes. If that takes longer than 60 seconds, Stop times out and the connector doesn't send it.
• One execution per command. A second call to a command that is still running fails. Await the first call before sending the second (see Observable commands).
• Command timeouts. Every command has a timeout, which is how long the connector waits for the instrument's response. If the response doesn't arrive in time, the command fails with a timeout error. The default is 60 seconds. Commands that usually run longer have a longer timeout, for example 5 minutes for initialization and pipetting commands. Maximal single command length of STAR firmware is limited to 5 minutes.

Troubleshooting and known issues

• NoSuchDeviceFound: Device not found on Windows. The connector doesn't come online and tries again every 20 seconds. Check that the driver matches use_usbio (see USB driver on Windows). If Device Manager shows "Unknown USB Device (Port Reset Failed)", turn the STAR off and on again.
• Connector can't open the STAR after an update. If you bound the STAR to libusbK with Zadig for an older connector, set use_usbio: false, or switch the STAR back to Hamilton's driver in Device Manager.
• USB on macOS. USB communication between a Mac and the STAR is unreliable. Run the connector on Windows or Linux. On Linux, see USB setup on Linux. A Raspberry Pi also works.
• Firmware timeout of 5 minutes. The STAR firmware ends a command that runs longer than 5 minutes. A longer connector timeout doesn't extend this firmware limit. Split work that needs more time, such as complex mixing, into several commands.

Vendor documentation

The Hamilton manuals shipped with the instrument cover operating limits, deck layout, maintenance, and safety.