ProstateBRP OpenIGTLink Communication June 2013
From NAMIC Wiki
Home < ProstateBRP OpenIGTLink Communication June 2013
The following table shows message exchange diagram for the communication between 3D Slicer (and other navigation software) and the robot in each workhpase.
Notations
- STRING(NN, SS) (see http://openigtlink.org/protocols/v2_string.html)
- NN: Device name in the OpenIGTLink header. (Max. 20 bytes)
- SS: String in the message body. (Max. 65536 bytes)
- STATE(NN, CC:SS:EE:MM) (see http://openigtlink.org/protocols/v2_status.html )
- NN: Device type in the OpenIGTLink header. (Max. 20 bytes)
- CC: Code
- SS: Subcode
- EE: Error name (Max 20 bytes)
- MM: Message
- TRANSFORM(NN, TT) (see http://openigtlink.org/protocols/v2_transform.html)
- NN: Device type in the OpenIGTLink header. (Max. 20 bytes)
- TT: 4x4 linear transformation matrix
Diagram
| 3D Slicer (operator) | Message | Robot Controller | Radiologist | Note |
| Start-up | ||||
| The operator presses "Start-up" button | ||||
| Send command to robot | >> STRING(CMD_XXXX, START_UP) >> | XXXX is a unique query ID (string of any ASCII letters up to 16 bytes) | ||
| << STRING(ACK_XXXX, START_UP) << | Echo back an acknowledgement command was received, but not yet completed | XXXX is the same unique query ID as the START_UP message. | ||
| Start up and initialize the hardware. Run the robot homing procedure if necessary (skip if already successfully completed). Move robot to home (loading) configuration. | ||||
| << STATUS(START_UP, OK:??:??) << DEVICE_NAME=START_UP C=1(OK), SubCode=??, ErrorName=?? |
Confirm when robot is initialized TODO: Refine error/status codes |
|||
| Display the result of start up process. | ||||
| Planning | ||||
| The operator opens the planning panel | ||||
| >> STRING(CMD_XXXX, PLANNING) >> | XXXX is a unique query ID (string of any ASCII letters up to 16 bytes) | |||
| << STRING(ACK_XXXX, PLANNING) << | Echo back an acknowledgement command was received | XXXX is the same unique query ID as the PLANNING message. | ||
| Do nothing except keep track of current state, robot is awaiting next workphase. | ||||
| Show that the robot is in PLANNING phase. | ||||
| Calibration | ||||
| The operator opens the calibration panel | ||||
| >> STRING(CMD_XXXX, CALIBRATION) >> | XXXX is a unique query ID (string of any ASCII letters up to 16 bytes) | |||
| << STRING(ACK_XXXX, CALIBRATION) << | Echo back an acknowledgement command was received | XXXX is the same unique query ID as the CALIBRATION message. | ||
| Do nothing except keep track of current state, robot is awaiting calibration transform | ||||
| Show that the robot is in CALIBRATION phase. | ||||
| Nav Software (3D Slicer or RadVision) calculates calibration matrix | ||||
| >> TRANSFORM(CLB_XXXX, 4x4 calibration matrix in RAS coordinates) >> | XXXX is a unique query ID (string of any ASCII letters up to 16 bytes) | |||
| << TRANSFORM(ACK_XXXX, 4x4 calibration matrix in RAS coordinates) << | Echo back an acknowledgement transform was received | XXXX is the same unique query ID as the CLB message. | ||
| Update calibration transform, set flag that registration has been set externally, reply with confirmation | ||||
| << STATUS(CALIBRATION, OK:??:??) << DEVICE_NAME=CALIBRATION C=1(OK), SubCode=??, ErrorName=?? |
Confirm that calibration was received and robot is ready for next workphase (targeting) | |||
| Show that calibration successfully sent to robot. | ||||
| Targeting | ||||
| The operator enters "Targeting" mode | ||||
| >> STRING(CMD_XXXX, TARGETING) >> | XXXX is a unique query ID (string of any ASCII letters up to 16 bytes) | |||
| << STRING(ACK_XXXX, TARGETING) << | Acknowledge receiving targeting command | XXXX is the same unique query ID as the TARGETING message. | ||
| Confirm if robot is ready for targeting; check if calibration was received; return robot to home (loading) position, if needed. | ||||
| << STATUS(TARGETING, OK:??:??) << DEVICE_NAME=TARGETING C=1(OK), SubCode=??, ErrorName=?? |
Confirm robot has entered targeting mode | |||
| << STATUS(TARGETING, DNR:??:??) << DEVICE_NAME=TARGETING C=13(DeviceNotReady), SubCode=??, ErrorName=?? |
ERROR CASE: If not able to enter targeting mode (i.e. calibration not received, reply with Code:13 (Device Not Ready) | |||
| The operator select a target, Nav software creates a 4x4 matrix for desired 6-DOF robot pose to reach the target | ||||
| >> TRANSFORM(TGT_XXXXX, 4x4 target matrix in RAS coordinates) >> | XXXX is a unique query ID (string of any ASCII letters up to 16 bytes) | |||
| << TRANSFORM(ACK_XXXXX, 4x4 target matrix) << | Acknowledge receipt of target transformation by echoing back | XXXX is the same unique query ID as the TARGETING message. | ||
| Calculate if target pose is reachable based on the kinematics, reply with status and set target | ||||
| << STATUS(TARGET, OK:??:??) << DEVICE_NAME=TARGETING C=1(OK), SubCode=??, ErrorName=?? |
Reply with OK if target was accepted | |||
| << TRANSFORM(TARGET, 4x4 target matrix) << | Send actual target pose in robot controller if one was set (corresponds to when status comes back OK) | |||
| << STATUS(TARGET, DNR:??:??) << DEVICE_NAME=TARGET C=13(DeviceNotReady), SubCode=??, ErrorName=?? |
ERROR CASE: If not in targeting mode, reply with Code:13 (Device Not Ready) | |||
| << STATUS(TARGET, CE:??:??) << DEVICE_NAME=TARGET C=10(ConfigurationError), SubCode=??, ErrorName=?? |
ERROR CASE: If not a valid target (i.e. out of workspace), reply with Code:10 (ConfigurationError) | |||
| Display the reachable target position set in robot controller. | ||||
| The operator confirms the target position set in the controller, and press "MOVE" | ||||
| >> STRING(CMD_XXXX, MOVE_TO_TARGET) >> | XXXX is a unique query ID (string of any ASCII letters up to 16 bytes) | |||
| << STRING(ACK_XXXX, MOVE_TO_TARGET) << | Echo back an acknowledgement command was received (not yet completed) | XXXX is the same unique query ID as the MOVE_TO_TARGET message. | ||
| Alert the clinician to hold footpedal to align the robot | Clinician engages interlock (footpedal in scanner room) to enable robot motion. Robot will only move when interlock is engaged following a move command. | |||
| The robot moves to the target and streams its pose during motion | ||||
| << TRANSFORM(CURRENT_POSITION, 4x4 current robot pose matrix in RAS coordinates) << | Stream current robot pose in RAS coords as moving. Can also be requested (see below). | |||
| Display the current robot position as it moves toward the target. | ||||
| Display that the robot is at the target. Send confirmation. | ||||
| << STATUS(MOVE_TO_TARGET, OK:??:??) << DEVICE_NAME=DONE_MOVING C=1(OK), SubCode=??, ErrorName=?? |
Reply with OK when robot reaches target | |||
| << TRANSFORM(CURRENT_POSITION, 4x4 current robot pose matrix in RAS coordinates) << | Push out final robot pose in RAS coords as moving. (same format as previous stream - ensures last one is at final position) | |||
| Display the current final robot position at the target. | ||||
| Needle Insertion (Manual) | ||||
| Ask to lock the robot | ||||
| The operator presses "Lock" button | ||||
| >> STRING (CMD_XXXX, MANUAL) >> | XXXX is a unique query ID (string of any ASCII letters up to 16 bytes) | |||
| << STRING(ACK_XXXX, MANUAL) << | Echo back an acknowledgement command was received (not yet completed) | XXXX is the same unique query ID as the MANUAL message. | ||
| Cut motor power to prevent motion of the robot base. This also eliminates causes of MR interference for insertion under live imaging. | ||||
| << STATUS(MANUAL, OK:??:??) << DEVICE_NAME=MANUAL C=1(OK), SubCode=??, ErrorName=?? |
Reply with OK when robot is in a safe, locked state | |||
| Insert a needle, optionally under live MR imaging. Perform intervention with the needle (biopsy or seed placement). | ||||
| Retract the needle | ||||
| Ask to unlock the robot and confirm needle is retracted | ||||
| The operator presses "Unlock" | ||||
| Return to the TARGETING phase (Slicer sends STRING(ACK_XXXXX, TARGETING) ) | ||||
| Additional Commands | ||||
| The operator presses "Stop" button | ||||
| >> STRING(CMD_XXXX, STOP) >> | XXXX is a unique query ID (string of any ASCII letters up to 16 bytes) | |||
| << STRING(ACK_XXXX, STOP) << | Acknowledge receiving targeting command | XXXX is the same unique query ID as the STOP message. | ||
| The robot stops all motion. Stays in current state/workphase. | ||||
| << STATUS(STOP, 4:??:??) << DEVICE_NAME=STOP C=1(OK), SubCode=??, ErrorName=?? |
||||
| The operator presses "Emergency" button | ||||
| >> STRING(CMD_XXXX, EMERGENCY) >> | XXXX is a unique query ID (string of any ASCII letters up to 16 bytes) | |||
| << STRING(ACK_XXXX, EMERGENCY) << | Acknowledge receiving targeting command | XXXX is the same unique query ID as the STOP message. | ||
| The robot stops all motion and disables/locks motors. Switches to Emergency state/workphase. ?? IS THIS THE DESIRED ACTION | ||||
| << STATUS(EMERGENCY, 4:??:??) << DEVICE_NAME=DONE_MOVING C=4(Emergency), SubCode=??, ErrorName=?? |
||||
| Request current robot pose (or target or calibration transforms) | ||||
| >> GET_TRANSFORM(CURRENT_POSITION) >> | ||||
| The robot transmits current pose ("CURRENT_POSITION") through IGTLink upon request. This also works for requesting "TARGET_POSITION" and "CALIBRATION" transforms stored in robot controller. | ||||
| << TRANSFORM(CURRENT_POSITION, 4x4 current robot pose matrix in RAS coordinates) << | ||||
| Request the robot status/workphase | ||||
| >> GET_STATUS(CURRENT_STATUS) >> ?? CONFIRM COMMAND STRUCTURE FOR STATUS REQUEST | ||||
| Sends current state/workphase. ?? SHOULD IT SEND OTHER INFO TOO | ||||
| << STATUS(XXXXX, YYYYY) << | XXXXX is workphase (e.g. TARGETING), YYYYY is status. | |||
| Robot controller sends errors or notifications through IGTLink. Transmitted asynchronously with error text in message body. To be used with limit events, hardware failures, invalid commands, etc. | ||||
| << STATUS(ERROR, Error Text) << | ||||
