Configuration file format for the dVRK console. See dVRK wiki.
sawIntuitiveResearchKitQtConsoleJSON and the ROS application dvrk_robot dvrk_console_jsonsawIntuitiveResearchKit/components/code/mtsIntuitiveResearchKitConsole.cppConfiguration for the input/output (IO)
No Additional PropertiesPort used communicate between the computer and the dVRK controllers. Accepted values are "fw", "fw:X" (X is FireWire port), "udp" or "udp:xx.xx.xx.xx" (xx.xx.xx.xx is the IP address of the dVRK controller. Default controller address is 169.254.0.100. Values are parsed by BasePort::ParseOptions in library Amp1394.
^fw$|^fw:[0-9]$|^udp$|^udp:[0-9]{2,3}.[0-9]{2,3}.[0-9]{2,3}.[0-9]{2,3} {
"port": "udp"
}
{
"port": "fw"
}
Protocol used for all FireWire communications. This applies wether the controllers are connected to the computer using FireWired or Ethernet (UDP with Link-Local). This is an advanced setting and most users should avoid defining it.
sequential-read-write: the PC reads data from each board (2 FPGA/QLA per controller), performs its computations (conversions, safety checks, PID, ...) and then writes sequentially to each board (N reads, N writes). This is the only protocol supported on older firmware (3 and below).sequential-read-broadcast-write: the PC reads sequentially but performs a single write for all the boards. The write message is an array of values sent to the boards, each board access the data it needs by index (N reads, 1 write). This is the default protocol for the dVRK controllers with firmware 4 and above.broadcast-query-read-write: the PC sends a single query/synchronization to all boards, read values are aggregated in single packet over the bus and there's a single write (1 query, 1 read, 1 write). This is the fastest protocol available but some FireWire cards seem to have trouble synchronizing the read packets. You will have to test it on your hardware to see if it supports this protocol or not. broadcast-read-write is the older name for this protocol and is provided for backward compatibility.IO configuration file used to define inputs from the foot pedals. See files sawRobotIO1394-*-foot-pedals.xml in directory share/io. The console use a search path that includes the sawIntuitiveResearchKit/share directory so you can specify any relative path from the share directory.
{
"footpedals": "io/sawRobotIO1394-MTMR-foot-pedals.xml"
}
{
"footpedals": "io/sawRobotIO1394-MTML-foot-pedals.xml"
}
Indicates if the console should have a foot pedal configuration file when one or more tele-operation components have been declared. If the user doesn't want the physical foot pedals but had declared some tele-operation components, set this parameter to false. The console will still need events emulating the foot pedals but these can be generated using the GUI or through ROS.
Periodicity for the IO and PID loop. Defined in seconds, i.e. interval between two iterations. The default is defined in mtsIntuitiveResearchKit.h and is set so the loop frequency is 1500Hz, ~0.66ms so 0.00066s. This is an advanced setting and most users should avoid defining it.
Value must be strictly greater than 0.0
{
"period": 0.001
}
Maximum laps of time allowed between to read/write access to the controller. It is used to detect abnormally slow IOs or disconnected cables. The value is sent to the controllers and the controllers will turn off power if the communication loop time exceeds the watchdog timeout. Defined in seconds. The default is defined in mtsIntuitiveResearchKit.h and is set to 30ms. This is an advanced setting and most users should avoid defining it. Setting it to zero disables the watchdog and should only be used by experts. The maximum value is 300ms, i.e. 0.3s
Value must be greater or equal to 0.0 and lesser or equal to 0.3
{
"watchdog-timeout": 0.05
}
Extra configuration files to configure the IO component. See examples in directory share/io.
Alternative sources for the main console inputs, "operator-present", "clutch" and "camera". Each input event normally comes from the da Vinci foot pedals connected to the dVRK controller using the attribute "io": "footpedals" but they can be replaced by other sources. To define another source, you need another component with a provided interface that has one write event named "Button".
No Additional PropertiesAlternate source for the "operator-present" sensor event
Configuration required to use the built-in da Vinci surgeon's console head sensor
No Additional PropertiesIO configuration file used to define inputs for the da Vinci head sensor. This requires a custom cable and will only work with a full da Vinci system. The head sensor component was introduced in version 1.6. See dVRK wiki.
{
"operator-present": {
"io": "io/sawRobotIO1394-MTMR-dv-head-sensor.xml"
}
}
Configuration required to use the da Vinci endoscope focus controller
No Additional PropertiesIO configuration file used to define outputs for the da Vinci endoscope focus controllers. This requires a custom cable and will only work with da Vinci focus controller. The endoscope focus component was introduced in version 1.6. See dVRK wiki.
{
"endoscope-focus": {
"io": "io/sawRobotIO1394-MTML-dv-endoscope-focus.xml"
}
}
See cisstMultiTask component manager
No Additional Properties{
"components": [
{
"shared-library": "sawForceDimensionSDK",
"class-name": "mtsForceDimension",
"constructor-arg": {
"Name": "ForceDimensionSDK"
},
"configure-parameter": "sawForceDimensionSDK-MTMR.json"
}
]
}
{
"components": [
{
"shared-library": "sawSocketStreamer",
"class-name": "mtsSocketStreamer",
"constructor-arg": {
"Name": "streamerMTML",
"Period": 0.01
},
"configure-parameter": "streamerMTML.json"
}
],
"connections": [
{
"required": {
"component": "streamerMTML",
"interface": "Required"
},
"provided": {
"component": "MTML",
"interface": "Arm"
}
}
]
}
Class name, i.e. type, to be used to dynamically create the new instance.
String passed to the component's Configure virtual method. The component manager will attempt to find a file using this parameter. If a file is found, the component manager will call the configure method with the full path. Otherwise, the component manager will call the method with the parameter as-is. This is optional. If the configure-parameter is not provided, the component manager will call component->Configure("").
Attributes required to build a single object passed to the constructor of a component. These objects depend on the type of component, e.g. mtsComponent, mtsTask, mtsTaskPeriodic... and are defined in the file cisst/cisstMultiTask/mtsParameterTypes.cdg.
Name of the component instance to be created. This name must be unique for the component manager and will be used later for connections.
Value must be strictly greater than 0.0
List of arms for the console
Configuration for a single arm
No Additional PropertiesName of the arm. For dVRK arms, use one of MTML, MTML, PSM1, PSM2, PSM3 or ECM
{
"name": "MTMR"
}
Type of arm. This determines which class should be used to instantiate the arm.
MTM, PSM and ECM correspond to the default classes provided for the dVRK arms. These are the most common ones.xxx_DERIVED corresponds to classes derived from the base classes provided in the dVRK stack. Users can derive the base arm classes to alter their behavior. In this case, the console knows that the derived class has all the features from the base class so the connections to the PID, IO, Qt widget and ROS bridge are the same as those for the base class.xxx_GENERIC corresponds to classes not derived from the dVRK base classes. The console will not create any IO, PID components for this arm. The console will use a generic Qt Widget and add ROS topics if and only if the provided interface has CRTK compatible commands and events. Examples include Force Dimension devices (sawForceDimensionSDK) and the Sensable Omni (sawSensablePhantom).PSM_SOCKET is a special case used for simple tele-operation between two processes (likely between two computers). One dVRK console will have to instantiate a PSM server and the other a PSM client.SUJ is for the Setup Jointsxxx_DERIVED and xxx_GENERIC, the console has no way to automatically create the component, so the user has to provide the proper component-manager configuration to first create the component for the arm. {
"arms": [
{
"name": "MTML",
"type": "MTM",
"serial": "22723",
"system": "jhu-dVRK"
},
{
"name": "MTMR",
"type": "MTM_GENERIC",
"component": "ForceDimensionSDK",
"interface": "MTMR"
}
]
}
Arm's serial number. To verify the serial number, locate the label on the arm itself (see dVRK wiki). The serial number and the arm's name are used to locate the arm configuration file assuming the arm configuration file name is <arm_name>-<arm_serial>.json (e.g. MTML-22723.json).
{
"serial": "22723"
}
name of your system, i.e. subdirectory under sawIntuitiveResearchKit/share where to locate the arm configuration files (sawRobotIO1394*.xml, <arm_name>-<arm_serial>.json, gravity compensation parameters (for MTMs)...). For example, setting thesystemtojhu-dVRKwill addsawIntuitiveResearchKit/share/jhu-dVRK` to the search path to locate the arm's configuration files.
{
"system": "jhu-daVinci"
}
Arm configuration file. Note that this is optional if the serial number has been provided. If the serial number has been provided, the application will assume the arm file is <name>-<serial>.json. For example PSM1-22723.json. This attribute is useful mostly if the arm is simulated ("simulation": "KINEMATIC").
Use the arm in simulation mode. In this case, the console doesn't need to create an IO component and can run without the physical arms and dVRK controllers (see examples in directory share/arm). The only simulation currently supported is KINEMATIC, i.e. the PID will set the measured positions (measured_js and setpoint_js) based on the commanded positions (servo_jp). This allows to test the kinematic but doesn't include any dynamic nor simulation of interactions with the world like Gazebo or VREP would.
Base frame prepended to the forward kinematics. The base frame is also taken into account when setting cartesian position goals
No Additional Properties{
"base-frame": {
"reference-frame": "HRSV",
"transform": [
[
-1.0,
0.0,
0.0,
0.18
],
[
0.0,
0.866025404,
0.5,
0.4
],
[
0.0,
0.5,
-0.866025404,
0.475
],
[
0.0,
0.0,
0.0,
1.0
]
]
}
}
{
"base-frame": {
"component": "ECM",
"interface": "Robot"
}
}
4 by 4 matrix, i.e. homogeneous transform
Must contain a minimum of 4 items
Must contain a maximum of 4 items
Must contain a minimum of 4 items
Must contain a maximum of 4 items
Name of the reference frame. This is used for Qt Widget and ROS tf
Name of the component that can provide the base frame at runtime. This is used for the full patient cart where the SUJ component can compute the base frame.
Name of the required interface used to set the base frame on the arm (using function set_base_frame)
Override the default periodicity of the arm class. Most user should steer away from changing the default arm periodicity. This works only for the dVRK base types ('MTM, PSM, ECM).
Value must be strictly greater than 0.0
[Deprecated] Name of the XML configuration file for the low level arm's IO (from sawRobotIO1394). The name of the IO configuration file is now inferred from the serial number attribute. Use serial instead.
[Deprecated] Name of the XML configuration file for the arm's PID (from sawControllers, mtsPID). The name of the PID configuration file is now inferred from the arm's name attribute.
[Deprecated] Name of the JSON configuration file for the arm's kinematic (from cisstRobot, robManipulator). The kinematic file should now be provided in the arm configuration file. The name of the arm configuration file can be inferred from the arm name and serial number (e.g. PSM1-28007.json) or provided using the arm attribute.
For arm of type xxx_GENERIC only. Name of the component for the generic arm. For the dVRK arms, the component is named after the arm (e.g. "MTML"). For other devices (e.g. sawSensablePhantom) the component might be able to provide multiple arms so the arm name is used for the "interface".
For arm of type xxx_GENERIC only. Name of the provided interface for the generic arm. For the dVRK arms, the component is named after the arm (e.g. "MTML") and the interface is always "Arm". For other devices (e.g. sawSensablePhantom) the component might be able to provide multiple arms so the arm name is used for the "interface".
Tell the component manager to not expose the arm commands to ROS. By default, the component manager will expose the arm to ROS using the cisst ROS CRTK bridge
Only works for PSMs. Indicates that a PSM socket server should be created. This can be used to communicate with another dVRK console process with a PSM of type PSM_SOCKET and create a tele-operation between two sites.
Only works with PSM of type PSM_SOCKET or if "socket-server" is set to true. Used to create a UDP socket to remotely access a PSM
Only works with PSM of type PSM_SOCKET or if "socket-server" is set to true. Used to create a UDP socket to remotely access a PSM
Configuration for the ECM tele-operation component
No Additional PropertiesName of the MTML. The arm must have been declared in the list of arms
Name of the MTMR. The arm must have been declared in the list of arms
Name of the ECM. The arm must have been declared in the list of arms
Override the default periodicity of the ECM tele-operation class. Most user should steer away from changing the default arm periodicity. This works only for the dVRK base class, i.e. "type": "TELEOP_ECM"
Value must be strictly greater than 0.0
List of PSM tele-operation components. Each PSM tele-operation component requires a mtm and a psm
Configuration for a single PSM tele-operation component
No Additional PropertiesName of the MTM. The arm must have been declared in the list of arms
Name of the MTM. The arm must have been declared in the list of arms
Optional base frame. This allows the tele-operation component to track changes of a potential base frame for the PSM. This can be used to allow ECM motions while tele-operating. The interface provided must have a measured_cp command
{
"mtm": "MTMR",
"psm": "PSM1",
"psm-base-frame": {
"component": "ECM",
"interface": "Robot"
}
}
Name of the component that can provide the base frame at runtime.
Name of the provided interface used to get the base frame (using command measured_cp)
Type of PSM tele-operation component. This determines which class should be used to instantiate the tele-operation component.
TELEOP_PSM corresponds to the default class provided for the dVRK arms.TELEOP_PSM_DERIVED corresponds to a class derived from the base class mtsTeleOperationPSM provided in the dVRK stack. Users can derive the base arm class to alter its behavior. In this case, the console knows that the derived class has all the features from the base class so the connections to the MTM, PSM, Qt widget and ROS bridge are the same as those for the base class.TELEOP_PSM_GENERIC correspond to classes not derived from the dVRK base class.TELEOP_PSM_DERIVED and TELEOP_PSM_GENERIC, the console has no way to automatically create the component, so the user has to provide the proper component-manager configuration to first create the component for the arm. See cisstMultiTask component manager
No Additional PropertiesScale 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 "start-roll-thresold"). 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. 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)
Angle 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)
[Deprecated] Make sure your arms are properly aligned using their "base-frame". Only use this attribute if your arms don't support "base-frame", i.e. non-dVRK arms.
Must contain a minimum of 3 items
Must contain a maximum of 3 items
Must contain a minimum of 3 items
Must contain a maximum of 3 items
Override the default periodicity of the PSM tele-operation class. Most user should steer away from changing the default arm periodicity. This works only for the dVRK base class, i.e. "type": "TELEOP_PSM"
Value must be strictly greater than 0.0
Make the console say something useless when it starts. It's mostly a way to test the text-to-speech feature.