Configuration file format for a dVRK console.
sawIntuitiveResearchKit/core/components/code/console_configuration.cdgArbitrary name given to the console. Usually console, console1...
General configuration for the console's inputs. All surgeon's consoles are expected to provide at least 3 signals: clutch pedal, camera pedal and operator present.
To allow users to reposition their hands while teleoperating, original da Vinci systems provide a "clutch" pedal. Later systems (Xi) also provide a slider button on each MTM so one can clutch each MTM individually.
The "camera" pedal is used to determine if the MTMs should be used to teleoperate the PSMs or the ECM.
To enable any teleoperation, the dVRK needs to know if the operator is present and holding the MTMs. On the clinical systems, there is a sensor at the level of the stereo display to detect if the operator's head is facing the display. On the first versions of dVRKs, we didn't have a head sensor so we used one of the foot pedals as a deadman switch. The operator was considered present if and only if the "COAG" pedal was pressed. Having to press the pedal continuously is quite inconvenient, so we came up with a few alternatives.
The different options are:
PEDALS_ONLY: this can be used by all dVRK sites as long as you have the original (or compatible) foot pedals connected to the dVRK controller. If you're using the foot pedals, you must specify which IO configuration file to use based on the type of controller with IO_pedals.PEDALS_GOOVIS_HEAD_SENSOR: if you're using the Goovis HMD, you can use the USB connection to detect if the operator is present. When using this option, you must also provide the HID_file.PEDALS_ISI_HEAD_SENSOR: assuming you built the custom cable to connect the original ISI head sensor (Classic and S) to the dVRK controllers (QLA1 or DQLA), you can use this option. In this case, you also need to specify which controller is used by setting the IO_head_sensor (this assumes the head sensor is connected to DOF 1 on the dVRK controller)PEDALS_DVRK_HEAD_SENSOR: cheap head sensor designed in the early days of the dVRK, see PEDALS_ISI_HEAD_SENSOR for configuration.SIMULATED: used when no physical sensor is available. The events can be emulated using either the GUI in "direct mode" or ROS topics.COMPONENTS: this is the most flexible option. Any cisst/SAW component can be used but the user has to make sure the components are properly created and provide the names of components and interfaces for the clutch, camera pedal and operator present: clutch_component, clutch_interface, camera_component, camera_interface, operator_present_component, operator_present_interface.WARNING: dVRK Si controllers can't be used to connect pedals and head sensors, you need a Classic controller (QLA1 or DQLA) since these controllers are the only one with some extra IOs.
IO file used to specify the IOs for the foot pedals. Use one of the existing files in the share/io directory.
Make sure you use the correct IO configuration file based on the name of the controller (e.g. MTML vs MTMR). The controller's name is used to identify the Id of the FPGA board connected to the pedals. You must also make sure you use specific files for DQLA based controllers.
This is required if the input_type starts with PEDALS_.
{
"input_type": "PEDALS_ONLY",
"IO_pedals": {
"IO": "IO1",
"IO_file": "io/sawRobotIO1394-MTMR-foot-pedals-DQLA.json"
}
}
{
"input_type": "PEDALS_ONLY",
"IO_pedals": {
"IO": "IO1",
"IO_file": "io/sawRobotIO1394-MTML-foot-pedals-DQLA.json"
}
}
Optional name for the IO, can be used to provide slightly more helpful error messages.
Name of the IO declared in the IOs section of the overall system configuration file.
File used to configure the IO.
IO file used to specify the IOs for the head sensor. Use one of the existing files in the share/io directory
This is required if the input_type is PEDALS_ISI_HEAD_SENSOR or PEDALS_DVRK_HEAD_SENSOR.
{
"input_type": "PEDALS_ISI_HEAD_SENSOR",
"IO_pedals": {
"IO": "IO1",
"IO_file": "io/sawRobotIO1394-MTMR-foot-pedals-QLA1.json"
},
"IO_head_sensor": {
"IO": "IO1",
"IO_file": "io/sawRobotIO1394-MTMR-dv-head-sensor.json"
}
}
{
"name": "console",
"input_type": "PEDALS_DVRK_HEAD_SENSOR",
"IO_pedals": {
"IO": "IO1",
"IO_file": "io/sawRobotIO1394-MTMR-foot-pedals-QLA1.json"
},
"IO_head_sensor": {
"IO": "IO1",
"IO_file": "io/sawRobotIO1394-MTMR-dVRK-head-sensor.json"
}
}
Optional name for the IO, can be used to provide slightly more helpful error messages.
Name of the IO declared in the IOs section of the overall system configuration file.
File used to configure the IO.
File used to specify HID (Human Interface Device) parameters for the Goovis head sensor. Use one of the existing files in the share/hid directory
This is required if the input_type is PEDALS_GOOVIS_HEAD_SENSOR.
{
"input_type": "PEDALS_GOOVIS_HEAD_SENSOR",
"IO_pedals": {
"IO": "IO1",
"IO_file": "io/sawRobotIO1394-MTML-foot-pedals-QLA1.json"
},
"HID_file": "hid/goovis-hd.json"
}
Name of the CISST component used to provide the clutch pedal signal.
This should be specified if and only if the input_type is set to COMPONENTS.
Component name
Component name
Name of the CISST component used to provide the camera pedal signal.
This should be specified if and only if the input_type is set to COMPONENTS.
Component name
Component name
Name of the CISST component used to provide the operator_present signal.
This should be specified if and only if the input_type is set to COMPONENTS.
Component name
Component name
List of PSM tele-operation components. Each PSM tele-operation component requires a MTM and a PSM
No Additional ItemsConfiguration for a single PSM tele-operation component
No Additional PropertiesName of surgeon's side MTM arm to be used (MTML, MTMR, MTML1...). The arm must have been declared in the main system configuration file under "arms".
Name of patient's side PSM arm to be used (PSM1, PSM2...). The arm must have been declared in the main system configuration file under "arms".
Type of teleoperation. This determines which class should be used to instantiate the PSM teleoperation.
TELEOP_PSM corresponds to the default class provided for the dVRK. This is the most commonly used.TELEOP_PSM_DERIVED corresponds to classes derived from the base class provided in the dVRK stack. Users can derive the base PSM teleoperation class to alter its behavior. In this case, the system knows that the derived class has all the features from the base class so the connections to the Qt widget and ROS bridge are the same as those for the base class.TELEOP_PSM_GENERIC corresponds to classes not derived from the dVRK base.Override the default periodicity of the teleoperation class.
Most user should steer away from changing the default periodicity.
Value must be strictly greater than 0.0
Component and interface used to provide the base frame of the PSM.
This is used if the reference frame of the teleoperation might change during the teleoperation. For example, with automated or manual motion of the ECM while the operator is teleoperating. This feature is not available on clinical systems but sometime used with the dVRK for research putposes. This is useful for groups with setup joints (even fixed ones) and an ECM
No Additional Properties{
"teleop_PSMs": [
{
"MTM": "MTMR",
"PSM": "PSM1",
"PSM_base_frame": {
"component": "ECM",
"interface": "Arm"
}
}
]
}
Component name
Component name
Configuration passed to the teleoperation component after its creation. It is used by the component's Configure method.
Scale factor applied to translations from the MTM to the PSM
Value must be strictly greater than 0.0 and lesser or equal to 1.0
Ignore PSM jaws and incidentally the MTM gripper.
This can be used for PSM tools (or generic PSM arms) without jaws and/or MTM arms without a gripper.
Start the tele-operation component with the rotation locked, i.e. the PSM orientation will not change and the MTM wrist will be locked (for MTMs with motorized wrist such as the da Vinci MTM).
This can be overwritten at runtime using the GUI or ROS topics.
Start the tele-operation component with the translation locked, i.e. the PSM position will not change.
This can be overwritten at runtime using the GUI or ROS topics.
Maximum orientation difference between the MTM and PSM allowed before starting the tele-operation.
The error is computed by converting the difference of orientation to an axis-angle. This threshold is ingnored if "align-mtm" is set to false.
Most users should steer away from this setting. The default is defined in components/include/sawIntuitiveResearchKit/mtsIntuitiveResearchKit.h: `mtsIntuitiveResearchKit::TeleOperationPSM::OrientationTolerance
Value must be greater or equal to 0.0
This is one of two parameters used to detect hand motion from the operator to determine if their hand is on the MTM (see also "startrollthresold").
To prevent accidentally getting in follow mode, the tele-operation component tries to detect some motion on the MTM, using a combination of thresholds on the gripper and roll motion. In any of these motions exceed the corresponding thresholds, the tele-operation component assumes the operator have their hand on the MTM and tele-operation can start. If any of these threshold is set to zero, the tele-operation will start without any motion the on the MTM. This can be used for testing with a simulated MTM where emulating gripper and roll motion would be complicated (see "arm": "simulation").
Most users should steer away from this setting. The default is defined in components/include/sawIntuitiveResearchKit/mtsIntuitiveResearchKit.h: `mtsIntuitiveResearchKit::TeleOperationPSM::GripperThreshold
Value must be greater or equal to 0.0
See "start-gripper-threshold" for description.
Most users should steer away from this setting. The default is defined in components/include/sawIntuitiveResearchKit/mtsIntuitiveResearchKit.h: `mtsIntuitiveResearchKit::TeleOperationPSM::RollThreshold
Value must be greater or equal to 0.0
Enforce absolute orientation between the MTM and PSM.
On clinical da Vinci systems this is always true, i.e. the orientation of the operator's hands with respect to the display always matches the orientation of the tooltip with respect to the endoscopic camera.
For research purposes, it can be interesting to allow relative orientation between the MTM and PSM. This can also be useful for alternate MTMs (e.g. ForceDimension devices) with a smaller SO3 space which might require orientation "clutching". To note, the application publishes the error in orientation between the MTM and PSM when the tele-operation is in Following mode. This can be overwritten at runtime using the GUI or ROS topics.
Maximum rate (velocity) for the PSM jaw angle in radians per seconds.
Most users should steer away from this setting. The default is defined in components/include/sawIntuitiveResearchKit/mtsIntuitiveResearchKit.h: `mtsIntuitiveResearchKit::TeleOperationPSM::JawRate
Value must be strictly greater than 0.0
Maximum rate (velocity) for the PSM jaw angle in radians per seconds when returning from clutch. When the user returns from clutch mode and back in follow mode, the PSM jaw angle might not match the MTM gripper angle. To prevent sudden changes in jaw angle, the PSM jaws moves at a slower rate until it "recovers" and matches the MTM gripper angle. Most users should steer away from this setting. The default is defined in components/include/sawIntuitiveResearchKit/mtsIntuitiveResearchKit.h: `mtsIntuitiveResearchKit::TeleOperationPSM::JawRateBackFromClutch
Value must be strictly greater than 0.0
Scaling applied to the MTM gripper angle. All angles are in radians! This angle is then used to control the PSM jaw angle.
By default, the tele-operation component assumes that the MTM gripper maximum angle is 60 degrees (as defined in the gripper calibration and the angle 0 corresponds to the PSM jaws being closed. When closed (angle set to 0), the PSM jaws don't apply any significant torque (just enough for the PID control to maintain a zero angle) so to apply a stonger grip, the tele-operation component sends a negative jaw angle to the PSM. Since the jaws can't have a negative angle, this will lead to a higher tracking error and by direct consequence, the PID will apply a strong torque. The "gripper-scaling" parameters are used to linearly interpolate the MTM gripper angles to the default convention, i.e. [0, 60] for positive range and some room for negative angles. For example, if your MTM has an effective range of [0, 30], set the "max" to 30 and the "zero" to 5. This way the values between 5 and 30 will be mapped to [0, 60] and values below 5 will generate negative angles for the PSM jaws (i.e. applying extra torque)
No Additional PropertiesAngle in radians on the MTM corresponding to just closed jaws on the PSM
Maximum angle in radians the MTM can send. By default, 60 degrees (by convention for dVRK MTMs)
Use the MTM cartesian linear velocity, scale it and send it to the PSM along the position to define the setpoint used by servo_cp.
This is turned on by default on the dVRK. For this to work with alternate arms (e.g. ForceDimension for MTM, UR for PSM), you need to make sure the MTM velocities are not too noisy and the PSM can receive setpoints with both positions and velocities (twists).
Use the MTM cartesian angular velocity and send it to the PSM along the position to define the setpoint used by servo_cp.
This is turned off by default on the dVRK. For this to work with alternate arms (e.g. ForceDimension for MTM, UR for PSM), you need to make sure the MTM angular velocities are not too noisy and the PSM can receive setpoints with both positions and velocities (twists).
List of ECM tele-operation components. Each PSM tele-operation component requires a MTML, MTMR and a PSM
No Additional ItemsConfiguration for a single ECM tele-operation component
No Additional PropertiesName of surgeon's left side MTM arm to be used (MTML, MTML1...). The arm must have been declared in the main system configuration file under "arms".
Name of surgeon's right side MTM arm to be used (MTMR, MTMR1...). The arm must have been declared in the main system configuration file under "arms".
Name of patient's side ECM arm to be used (ECM, ECM1...). The arm must have been declared in the main system configuration file under "arms".
Type of teleoperation. This determines which class should be used to instantiate the ECM teleoperation.
TELEOP_ECM corresponds to the default class provided for the dVRK. This is the most commonly used.TELEOP_ECM_DERIVED corresponds to classes derived from the base class provided in the dVRK stack. Users can derive the base ECM teleoperation class to alter its behavior. In this case, the system knows that the derived class has all the features from the base class so the connections to the Qt widget and ROS bridge are the same as those for the base class.TELEOP_ECM_GENERIC corresponds to classes not derived from the dVRK base.Override the default periodicity of the teleoperation class. Most user should steer away from changing the default periodicity.
Value must be strictly greater than 0.0
Configuration passed to the teleoperation component after its creation. It is used by the component's Configure method.
Scale factor applied to insertion motion
Value must be strictly greater than 0.0 and lesser or equal to 1.0