Metadata-Version: 2.4
Name: tangods-isara
Version: 5.1.0
Summary: Tango device server for ISARA and ISARA2 sample changers.
Author-email: KITS <kits-sw@maxiv.lu.se>
License-Expression: GPL-3.0-or-later
Project-URL: homepage, https://gitlab.com/MaxIV/isara/dev-maxiv-isara
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytango
Requires-Dist: telnetlib3>=2.0.5
Requires-Dist: typing-extensions>=4.10.0
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: pytest-forked; extra == "tests"
Dynamic: license-file

# 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, `soak`s 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](isara/emulator/readme.md) file.
