Robot OpenIGTLink Communication March 2014
From NAMIC Wiki
Home < Robot OpenIGTLink Communication March 2014
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) -- no predefined name. It will logged or show up on navigation screen as it is.
- MM: Message -- no predefined text. It will logged or show up on navigation screen as it is.
- 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. | ||
| << STATUS(CURRENT_STATUS, Code:0:Phase) << | Code=OK: Confirm that the robot is transition to START_UP mode. Phase should be "START_UP". Code=DNR: Fails to transition. Phase should be the name of the current workphase | DNR: Device not ready (13) | ||
| Start up and initialize the hardware. Run the robot homing procedure if necessary (skip if already successfully completed). Move robot to home (loading) configuration. | ||||
| << TRAJ("FIDUCIALS", fiducials) << | Send fiducial (or landmarks) information | |||
| << POLYDATA("MDL_YYYY") << | Send polydata models. See polydata message | YYYY is the name of the model (e.g. MDL_TEMPLATE). | ||
| << STATUS(START_UP, Code:??:??) << | Code=OK: Confirm when robot is initialized Code>=2: Error. See error list |
|||
| 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. | ||
| << STATUS(CURRENT_STATUS, Code:0:Phase) << | Code=OK: Confirm that the robot is transition to PLANNING mode. Phase should be "PLANNING". Code=DNR: Fails to transition. Phase should be the name of the current workphase | DNR: Device not ready (13) | ||
| 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. | ||
| << STATUS(CURRENT_STATUS, Code:0:Phase) << | Code=OK: Confirm that the robot is transition to CALIBRATION mode. Phase should be "CALIBRATION". Code=DNR: Fails to transition. Phase should be the name of the current workphase | DNR: Device not ready (13) | ||
| 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, 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, Code:??:??) << | Code=OK: Confirm that calibration was received and robot is ready for next workphase Code=CE: Error. |
CE: Configuration Error (code 10) | ||
| Show that calibration successfully sent to robot or failed. | ||||
| 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. | ||
| << STATUS(CURRENT_STATUS, Code:0:Phase) << | Code=OK: Confirm that the robot is transition to TARGETING mode. Phase should be "TARGETING". Code=DNR: Fails to transition. Phase should be the name of the current workphase | DNR: Device not ready (13) | ||
| Confirm if robot is ready for targeting; check if calibration was received; return robot to home (loading) position, if needed. | ||||
| << STATUS(TARGETING, Code:??:??) << | Code=OK: Confirm robot has entered targeting mode. Code=DNR: If not able to enter targeting mode (i.e. calibration not received) |
DNR: Device Not Ready (code 13) | ||
| 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). The unique ID may be used as a human-readable target name on the robot control software. For example, TGT_LeftApex-2 is for the second targeting attempt on a lesion in the left-apex. | |||
| << 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, Code:??:??) << | Code=OK: Reply with OK if target was accepted Code=DNR: Not in targeting mode Code=CE: Not a valid target (i.e. out of workspace) |
DNR: Device Not Ready (code 13) CE: Configuration Error (code 10) | ||
| << TRANSFORM(TARGET, 4x4 target matrix) << | Send actual target pose in robot controller if one was set (corresponds to when status comes back OK) | |||
| 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. See the note below | ||
| 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, 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, Code:??:??) << | Code=OK: Robot reaches target Code >= 3: Return error code when the device fails to move to the target. See error list |
|||
| << TRANSFORM(CURRENT_POSITION, 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. | ||
| << STATUS(CURRENT_STATUS, Code:0:Phase) << | Code=OK: Confirm that the robot is transition to MANUAL mode. Phase should be "MANUAL". Code=DNR: Fails to transition. Phase should be the name of the current workphase | DNR: Device not ready (13) | ||
| 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:??:??) << | 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) ) | ||||
| All workhpases | ||||
| 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. | ||
| << STATUS(CURRENT_STATUS, Code:0:Phase) << | Code=OK: Confirm that the robot is transition to STOP mode. Phase should be "STOP". Code=DNR: Fails to transition. Phase should be the name of the current workphase | DNR: Device not ready (13) | ||
| The robot stops all motion. Stays in current state/workphase. | ||||
| << STATUS(STOP, OK:??:??) << | Reply with OK when robot stopped safely. | |||
| All workhpases | ||||
| 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. | ||
| << STATUS(CURRENT_STATUS, Code:0:Phase) << | Code=OK: Confirm that the robot is transition to EMERGENCY mode. Phase should be "EMERGENCY". Code=DNR: Fails to transition. Phase should be the name of the current workphase | DNR: Device not ready (13) | ||
| The robot stops all motion and disables/locks motors. Switches to Emergency state/workphase. ?? IS THIS THE DESIRED ACTION | ||||
| << STATUS(EMERGENCY, Emergency:??:??) << | Reply with OK when robot stopped safely. | |||
| All workhpases | ||||
| 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, Current robot pose matrix in RAS coordinates) << | ||||
| All workhpases | ||||
| 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(CURRENT_STATUS, Code:0:Status) << | Send status code. Status should be the name of the current status e.g. "TARGETING". Code is OK, when the robot is successfully determines its workphase. Otherwise, Code should be configuration error (10) | |||
| All workhpases | ||||
| 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, Code:??:Error name) << | | align="left" | Send status code. error list | |||
NOTE: Suggested modification -- Agreed on 9/5/13
Although MOVE_TO_TARGET workphase is currently part of TARGETING, Nirav suggested to make MOVE_TO_TARGET phase an independent workhpase. If we agree, the MOVE_TO_TARGET workphase should be defined as follows:
| 3D Slicer (operator) | Message | Robot Controller | Radiologist | Note |
| Move to Target | ||||
| 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. See the note below | ||
| << STATUS(CURRENT_STATUS, Code:0:Phase) << | Code=OK: Confirm that the robot is transition to MOVE_TO_TARGET mode. Phase should be "MOVE_TO_TARGET". Code=DNR: Fails to transition. Phase should be the name of the current workphase | DNR: Device not ready (13) | ||
| 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, Current robot pose matrix in RAS coordinates) << | Stream current robot pose in RAS coords as moving. Can also be requested (see below). | |||
| << STATUS(MOVE_TO_TARGET, Code:??:??) << | Code=OK: Robot reaches target Code >= 3: Return error code when the device fails to move to the target. See error list |
|||
| << TRANSFORM(CURRENT_POSITION, 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. | ||||
