tangods-isara 5.1.0

Tango device server for ISARA and ISARA2 sample changers.

Tango device server for Irelec Isara sample changer robot

This repository implements a Tango device server for controlling an Irelec Isara sample changer robot.

This Tango device server supports the Isara1 and Isara2 models of the Irelec sample changer robots (where Isara1 is the unofficial name for the robot model at BioMAX). The device server automatically detects the model on the start-up. The aim of this implementation to provide same Tango API for both Isara1 and Isara2 systems as much as possible. However, the available Tango attributes and commands are different, as not all features are available on both Isara1 and Isara2 sample changes.

Tango device server API

Properties

The Tango device is configured using properties below.

property	mandatory	default	purpose
host	yes	n/a	network address of the ISARA device
operate_port	no	10000	TCP port number of the process control socket
monitor_port	no	1000	TCP port number of the status feedback socket

Note that the process control socket is also referred as Socket 1 and status feedback socket as Socket 2 in Irelec documentation.

When this Tango device is used for Isara1 robot, it's soak position coordinates must be configured. Use the following soak position configuration properties.

property	mandatory	default	purpose
soak_pose_rx	no	0.0	Reference RX orientation in soaking pose (°)
soak_pose_ry	no	0.0	Reference RY orientation in soaking pose (°)
soak_pose_rz	no	0.0	Reference RZ orientation in soaking pose (°)
soak_pose_x	no	0.0	Reference X position in soaking pose (mm)
soak_pose_y	no	0.0	Reference Y position in soaking pose (mm)
soak_pose_z	no	0.0	Reference Z position in soaking pose (mm)

Note that Isara2 does not need soak configuration. The soak_* configuration properties will be ignored.

Attributes

Following attributes are available on both Isara1 and Isara2 systems:

attribute	description
AvailableTools	list of tools available for the current robot
Barcode	last datamatrix read value
CurrentNumberOfSoaking	soaking phases number for grippers that need to be cooled
FaultStatus	is system in fault or stop mode
LN2Regulation	is LN2 regulation running
Message	last information message from PLC
Path	currently running path's name
PathRunning	is path running
PathSafe	arm is parked
PlateNumberOnTool	number of the plate mounted on the tool
PoseRX	Rx orientation coordinate of current cartesian pose (°)
PoseRY	Ry orientation coordinate of current cartesian pose (°)
PoseRZ	Rz orientation coordinate of current cartesian pose (°)
PoseX	X position coordinate of current cartesian pose (mm)
PoseY	Y position coordinate of current cartesian pose (mm)
PoseZ	Z position coordinate of current cartesian pose (mm)
PositionName	robot arm's current position name
Powered	is robot arm powered on
PuckNumberOnDiff*	puck number of the sample mounted on diffractometer
PuckNumberOnTool*	puck number of the sample mounted on jaw A tool
PuckNumberOnToolB*	puck number of the sample mounted on jaw B tool
RemoteMode	is remote operating mode enabled
SampleDetectedOnGonio	is a sample currently detected on the gonio
SampleNumberOnDiff*	number of the sample mounted on diffractometer
SampleNumberOnTool*	number of the sample on jaw A tool
SampleNumberOnToolB*	number of the sample on jaw B tool
SampleOnDiff	sample mounted on diffractometer, puck and pin numbers
SampleOnToolA	sample on jaw A tool, puck and pin numbers
SampleOnToolB	sample on jaw B tool, puck and pin numbers
SpeedRatio	current robot arm speed ratio (%)
Tool	tool name

* - deprecated attributes, they are slated for removal in the future

Following attributes are available only on Isara2 model:

attribute	description
BinaryAlarms	binary alarms flags
CryoVisionData	puck and sample presence info from cryo-vision controller
GripperDrying	is gripper drying in progress
HeatingCablesOn	are heating cables turned ON
LN2Level	LN2 current level in the Dewar (%)
PathPause	is path paused
PlateNumberOnDiff	number of the plate mounted on the diffractometer

Following attributes are available only on Isara1 model:

attribute	description
GonioX	goniometer position (X)
GonioY	goniometer position (Y)
GonioZ	goniometer position (Z)

Commands

Isara1

Command	Description
ChangeToolAndCalibrate	Change tool and perform calibration afterwards.
GetPlate	Get plate from the goniometer and place it back on its support.
GetPutPlate	Get plate currently on goniometer and put a new plate.
PutPlate	Take plate from support and put it on the goniometer.

Tango command ChangeTool on Isara1 uses home command, which behaves strange for Double Gripper tool (id 5). It puts current tool on the parking, picks Double Gripper, soaks it, then goes home, skipping dry path. Isara2 protocol has dedicated traj(changetool, tool n) command, which only changes the tool.

For the Tango commands SpeedUp and SpeedDown on Isara1 the command remotespeedon is called beforehand and remotespeedoff afterwards.

For the Tango commands Soak and Back on Isara1 if the current position is estimated to be the soaking position then the command raises an exception and is not forwarded to the robot. Indeed Isara1 has an issue where it makes an horizontal move even if the gripper is still in the dewar which causes a collision.

Tests

To run tests, install this package with optional tests dependencies. For example, when using pip:

$ pip install --editable .[tests]

Run tests with:

$ pytest

Emulation

This package contains code that can emulate network API of Isara1 and Isara2 robots. This emulation is used by the tests described above. The emulator can also be run as a stand-alone process, which can be helpful when developing the tango device code.

To start the emulator use IsaraEmulator command. This command is provided by this package, when installed with for example pip utility. To start emulator, use:

$ IsaraEmulator --enable-logging ISARA2 2222 3333

This will start Isara2 API emulation. The process control socket will be emulated on port 2222. The status feedback socket will be emulated on port 3333. Use IsaraEmulator --help to get description of all available options and features.

For more information on the emulator, see the isara/emulator/readme.md file.