View source for OpenIGTLink/Protocol/JHUBRP

[[OpenIGTLink | &lt;&lt; OpenIGTLink]] | [[OpenIGTLink/Protocol | Protocol]]


<div class="redirectText">'''JHU BRP Robot protocol description'''</div>
<div class="floatright">__TOC__</div>


= System Diagram =
<div class="center">[[Image:MRI_Robot_System_Diagram2.png]]</div>

= Workflow =
# Scanner: Scout image acquisition with the landmark close to the prostate
# Navigation soft and scanner: Calculate Z-frame position, scan a slice through the Z-frame
# Repeat previous step if the Z-frame is not visible enough to register the robot
# Scanner: 3D volume acquisition of the prostate
# Navigation soft: Select (or import) the targets, show needle path, allow modification
# Navigation soft: Calculate the target and path, send it to the robot
# Robot: Execute command
# [Optional] Navigation soft: send current robot coordinates to the Real Time scanner IO for needle tracking, display image
# Navigation soft: Display robot position and status
# Scanner: Confirm robot location before biopsy
# Manual: Insert biopsy needle
# [Optional] Navigation soft: show Real time images of the needle insertion
# Manual: Fire biopsy gun

= Open IGT Link Protocol =

Some commands / queries are expecting parameters in the Body section which follows the [[OpenIGTLink/Protocol#Header_Structure | Header Structure]]. The parameter can be:
*  8 bit Byte
* 32 bit Integer
* 32 bit Float

For example the Position and Orientation parameters in SET_Z_FRAME command will be the following.
  Bytes (Body)
  58      62      66      70      74      78      82
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |   X   |   Y   |   Z   |  Ox   |  Oy   |  Oz   |  
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


= Set Workphase (Slicer -> Robot) =

There are no parameters for this commands.

==  START_UP ==
Slicer: Send "START_UP" Workphase command<br />
Robot: Initialize robot and respond with status message

== PLANNING ==
Robot: Do nothing, respond with status

== CALIBRATION ==
Robot: Do nothing, respond with status. Waiting for SET_Z_FRAME command (Z-Frame transformation).

== TARGETING ==
Robot: Fail if Z-Frame was not set. Respond with status. Waiting for targets (MOVE command).

== MANUAL ==
Robot: Engage breaks, responds with status. <br />
Slicer sends "GetCoordinate" query periodically to update the display.

== EMERGENCY ==
Robot: Responds with status


= Command / Query (Slicer -> Robot) =

== Command: INITIALIZE ==
Parameters: none<br />
Robot: Initialize, set the encoders, remember this position as "HOME". Respond with status.

== Command: SET_Z_FRAME ==
Parameters (24 byte total):
* Vector of three 32 bit floats: position X, Y, Z
* Vector of three 32 bit floats: orientation
Robot: Store Z-frame position and orientation (global RAS coordinate system) - respond with status.

== Command: MOVE_TO ==
Parameters (24 byte total):
* Vector of three 32 bit floats: position X, Y, Z
* Vector of three 32 bit floats: orientation
Robot: Go to this coordinate - position, orientation (later: speed?) (global RAS coordinate system). Respond with status.

== Command: INSERT ==
Parameters (4 byte): 32 bit float<br />
Robot: Insert the needle to this depth - float (in mm)

== Command: BIOPSY ==
Parameters: none<br />
Robot: Take biopsy (Retract Cannula)

== Command: HOME ==
Parameters: none<br />
Robot: Go to Home (collapses the robot to remove/replace needle)

== Command: STOP ==
Parameters: none<br />
Robot: Stop moving

== Command: E_STOP ==
Parameters: none<br />
Robot: Emergency Stop (stop + purges the air lines)

== Command: SET_JOINT ==
Parameters: a set of 32bit floats. The number of floats is BODY_SIZE/4.<br />
Robot: Set Joint Positions - float[max.16] - move joint here

== Command: SET_VELOCITY ==
Parameters: a set of 32bit floats. The number of floats is BODY_SIZE/4.<br />
Robot: Set Joint Velocities - float[max.16] - move joint with this speed

== Command: SET_AIR_PRESSURE ==
Parameters: TBD<br />
Robot: sets the air pressure / voltage output

== Command: LOCK ==
Parameters: none<br />
Robot: Engage brakes - all of them

== Command: UNLOCK ==
Parameters: none<br />
Robot: Unlock - disengage all the brakes so the robot can be moved manually

== Command: LOCK_AXIS ==
Parameters: one or more 32bit integers (BODY_SIZE/4)<br />
Robot: Engage brakes on a give axis

== Command: UNLOCK_AXIS ==
Parameters: one or more 32bit integers (BODY_SIZE/4)<br />
Robot: Unlock - disengage the brakes on a give axis, so it can be moved manually

== Command: LIMIT_VELOCITY==
Parameters: one 32 bit float<br />
Robot: Set entire robot velocity limit in Robot Coords. - float (like 10 mm/s) 

== Query: GET_COORDINATE ==
Parameters: none<br />
Robot: Respond with current coordinate (position and orientation in global RAS coordinate system)

== Query: GET_STATUS ==
Parameters: none<br />
Robot: Respond with status (see the packet description below)

== Query: GET_BIOPSY ==
Parameters: none<br />
Robot: Respond with Actual Insertion Depth 

== Query: GET_NR_JOINT ==
Parameters: none<br />
Robot: Get Number of Joints - integer, see the description below

== Query: GET_JOINT ==
Parameters: one or more 32bit integers (BODY_SIZE/4)<br />
Robot: Get Actual Joint Positions

== Query: GET_VELOCITY==
Parameters: one or more 32bit integers (BODY_SIZE/4)<br />
Robot: Get Actual Joint Velocities

== Query: GET_AIR_PRESSURE ==
Parameters: one or more 32bit integers (BODY_SIZE/4)<br />
Robot: Get Actual Air Pressures

== Query: GET_JOINT_TRACK ==
Parameters: one or more 32bit integers (BODY_SIZE/4)<br />
Robot: Get Actual Joint Tracking Errors

== Query: GET_BRAKE ==
Parameters: none<br />
Robot: Get Brakes status

== Query: GET_MOVING ==
Parameters: none<br />
Robot: Get Joint Moving status


= Responses sent by the robot (Robot -> Slicer) =

== Status: STATUS ==
Response from Robot: Robot done moving, Error message, Emergency stop<br />
See [[OpenIGTLink/Protocol#STATUS]] for description.

== Status: BRAKES ==
Response from Robot: Brake status - boolean[max.16] - true(locked)/false(loose) for each joint<br />
Structure: a number of bytes, defied by BODY_SIZE. 0 means false, 1 means true.

== Status: DONE_MOVING ==
Response from Robot: Done moving/joint - boolean[max.16] - true/false for each joint
Structure: a number of bytes, defied by BODY_SIZE. 0 means false, 1 means true.

== Response: COORDINATES ==
Response from Robot: Actual coordinates and insertion depth - 6DOF in global RAS coordinate system<br />
Structure (28 byte total):
* Vector of three 32 bit floats: position X, Y, Z
* Vector of three 32 bit floats: orientation
* One 32 bit float: current insertion depth

== Response: JOINTS ==
Response from Robot: Number of Joints - integer<br />
Structure: one 32 bit integer (4 bytes total)

== Response: JOINT_POS ==
Response from Robot: Actual joint positions - float[max.16] (joint positions in mm)<br />
Structure: a set of 32bit floats. The number of floats is BODY_SIZE/4.

== Response: JOINT_VEL ==
Response from Robot: Actual joint velocities - float[max.16] (joint velocities in mm/s)<br />
Structure: a set of 32bit floats. The number of floats is BODY_SIZE/4.

== Response: JOINT_TRACK ==
Response from Robot: Actual joint tracking error - float[max.16] - "actual joint position" - "set joint position"<br />
Structure: a set of 32bit floats. The number of floats is BODY_SIZE/4.

== Response: AIR_PRESSURE ==
Response from Robot: Actual air pressures - float[max.32] - '''two per joint!''' (PSI for each valve)<br />
Structure: a set of 32bit floats. The number of floats is BODY_SIZE/4.