console json 1.x

Introduction

Configuration file format for the dVRK console, version 1.x. See dVRK wiki. This format is used by the application sawIntuitiveResearchKitQtConsoleJSON and the ROS application dvrk_robot dvrk_console_json.

Parsing is performed by the Configure method in mtsIntuitiveResearchKitConsole: https://github.com/jhu-dvrk/sawIntuitiveResearchKit/blob/main/code/mtsIntuitiveResearchKitConsole.cpp

The Configure method calls:

• ConfigureArmJSON to configure each arm
• ConfigurePSMTeleopJSON to configure the PSM teleoperation components
• ConfigureECMTeleopJSON to configure the ECM teleoperation components (from 1.4.0)

All files referenced within the console-<your_setup>.json file can be defined by an absolute path (not recommended) or a path relative to the console configuration file itself. We recommend to keep all the files shared across systems in the provided sawIntuitiveResearchKit/share directory. Then create a sub-directory for your system (e.g. jhu-dVRK) for all your files, e.g. sawRobotIO1394 XML files and console JSON files. In your console configuration files, you can refer to the shared configuration files (PID, kinematics) without any path. By default, the console looks for files in the following directories:

• Current directory, i.e. directory in which the application was started
• Directory of the console file itself, this is how your IO files are usually found
• Shared source directory for the dVRK, this is how the default PID and kinematics files are found
• Shared source directory '/io'. This folder is used to store share IO files without any system specific settings (foot pedals, camera focus, head sensor...)

Once you've created and populated your system specific directory, you can send us a github pull request or a zip. We'll merge it with the main branch and sync the devel branch.

Arms

List of arms to be configured in your system. Each arm needs a unique name, type and configuration file for kinematics.

Name

The name of the arm. In most cases this will be one of MTML, MTMR, PSM1, PSM2, PSM3, ECM or SUJ. The name will be used to create all the interfaces for the component connections, Qt GUI and ROS topics. For a dVRK arm, this will create a cisst/SAW component with the arm name. For some other devices, e.g. sawForceDimensionSDK, the arm name will match a provided interface name (see Component and interface below).

Type

The arm can be a dVRK arm: ECM, PSM, MTM or SUJ. These are the predefined classes in sawIntuitiveResearchKit and the most commonly used. For these base dVRK arms, the console class will create all the required components (IO, Qt Widgets and ROS topics).

One can also declare a derived arm using the types ECM_DERIVED, PSM_DERIVED or MTM_DERIVED. For all derived types, the console will assume that the user has already created and added the arm to the component manager (see https://github.com/jhu-cisst/cisst/wiki/cisstMultiTask-concepts). To create and add the component, one can either write their own main.cpp or use dynamic loading (see example of component-manager below). For all derived classes, the console will automatically add the IO connections as well as the Qt GUI widgets and ROS topics.

Finally, one can use ECM_GENERIC, PSM_GENERIC or MTM_GENERIC. In this case the console will not create any IO component, Qt widget nor ROS topics. The only requirement is that this generic arm has all the required commands and events in its provided interfaces. For example, a device supported by the ForceDimension SDK can be used as a generic master arm with the following configuration:

    "component-manager": {
        "components":
        [
            {
                "shared-library": "sawForceDimensionSDK",
                "class-name": "mtsForceDimension",
                "constructor-arg": {
                    "Name": "ForceDimensionSDK"
                },
                "configure-parameter": "sawForceDimensionSDK-MTMR.json"
            }
        ]
    }

The above configuration tells the console class to:

• Load a shared library names sawForceDimensionSDK (cisst/SAW wrapper for the Force Dimension SDK)
• Create an object of type mtsForceDimension under the name ForceDimensionSDK
• The configuration file contains the name of the interface to be created, i.e. MTMR

Then in the arms section, we can create a generic MTM using:

    "arms":
    [
        {
            "name": "MTMR",  // created previously using custom components
            "type": "MTM_GENERIC",
            "component": "ForceDimensionSDK", // name of component
            "interface": "MTMR" // name of interface
        }
    ]

Period

You can override the default periodicity of the arm class for all the classes . For example adding "period": 0.001 will set the periodicity to 0.001 (in seconds). This works only for the dVRK and derived arm types.

IO

This is required for all arms connected to the hardware using the component from sawRobotIO1394, i.e. all the dVRK arms and derived (unless you're using the simulation mode). These files are specific to each arm since the contain the calibration information, i.e. sawRobotIO1394-<your_arm>.xml.

PID

This is required for all the dVRK and derived arms, either in simulation mode or not. It is strongly recommended to use the configuration files provided along the source code. Since the console class has a search path that includes the directory where the default PID configurations files are, there is no need to copy the files from the source directory.

Simulation

If the arm is simulated, one need to add "simulation": "KINEMATIC". In this case, "io" field is ignored (see https://github.com/jhu-dvrk/sawIntuitiveResearchKit/blob/main/share/console-PSM1_KIN_SIMULATED.json). The only simulation currently supported is "kinematic", i.e. the PID will set the measured positions based on the commanded positions. This allows to test the kinematic but doesn't include any dynamic nor simulation of interactions with the work like Gazebo or VREP would.

Base frame

There are two possible syntaxes to define the base frame for the arm, one for a static configuration and one for a moving base frame. The syntax for a static configuration has been introduced in version 1.6. It requires two fields:

• "reference-frame": name of the reference frame, i.e. string used for display as well as ROS tf broadcast
• "transform": a 4x4 transformation matrix

    {
        "name": "MTMR",
        "type": "MTM",
        "io": "sawRobotIO1394-MTMR-28247.xml",
        "pid": "sawControllersPID-MTMR.xml",
        "kinematic": "mtm.json",
        "base-frame": {
            "reference-frame": "HRSV",
            "transform": [[ -1.0,  0.0,          0.0,         -0.180],
                          [  0.0,  0.866025404,  0.5,          0.400],
                          [  0.0,  0.5,         -0.866025404,  0.475],
                          [  0.0,  0.0,          0.0,          1.0]]
        }
    }

In the example above, we define the base frame of the MTMR using the ISI convention, i.e. the origin is just in the middle of the eye piece of the stereo display ("HSRV"), the Z axis is aligned with the display depth (hence the 30 degrees rotation) and shifted to the right (translation by -0.180 in X).

For a moving frame, the base-frame is retrieved in runtime using a cisst/SAW component and interface. Therefore it requires two fields:

• "component": name of the component providing the base frame
• "interface": name of the provided interface with the command to retrieve the base frame

    {
        "name": "PSM1",
        "type": "PSM",
        "io": "sawRobotIO1394-PSM1-49695.xml",
        "pid": "sawControllersPID-PSM.xml",
        "kinematic": "psm-large-needle-driver.json",
        "base-frame": {
            "component": "SUJ",
            "interface": "PSM1"
        }
    }

In the above example, the PSM1 base frame is provided at runtime by the SUJ component. This component has one provided interface per SUJ arm, appropriately named after the arm it carries (in this case PSM1).

Component and interface

These two fields are only required for "generic" arms so the console knows which component/interface to connect to. For example:

    "arms":
    [
        {
            "name": "MTMR",  // created previously using custom components
            "type": "MTM_GENERIC",
            "component": "ForceDimensionSDK",
            "interface": "MTMR"
        }
   ]