• Overview
• Low level
  • FPGA/QLA boards
  • AmpIO library
• C
  • Threads
  • Robot IOs
  • PID controller
  • Arm classes
  • Tele-operation
  • Console
• Qt widgets
  • Robot IOs
  • PID controller
  • Arm classes
  • Tele-operation
  • Console

The dVRK hardware and software stack is composed of:

• Firmware on FPGA/QLA interfacing IO with FireWire
• Lightweight C library on PC side to interface to FPGA via FireWire
• C++ components using the cisst/SAW libraries to implement IOs, controllers (PID, tele-operation), console, GUI, bridges to ROS, ...
• ROS wrapper around dVRK topics

Embedded firmware:

• Collects data from digital inputs data (limit/home switches)
• Controls digital outputs (ON/OFF/PWM)
• Computes encoder positions and velocities, including detecting overflow and preload
• Performs basic safety checks on motor current (consistency between requested and measured)
• Implements subset of FireWire protocol to communicate with a computer
• Maintains a watchdog to make sure the PC is still connected and communicating with the controller
• See:
  • http://jhu-cisst.github.io/mechatronics
  • https://github.com/jhu-cisst/mechatronics-firmware

C low level library:

• Runs on the PC sides on top of Linux/libraw1394
• Packs/unpacks data to/from FPGA, i.e. convert bits to usable numbers (integers)
• Handles multiple FPGA and treat them as single controller (
• Simple text based programs to test hardware (qladisp, qlatest, qlacommand, ...)
• See:
  • https://github.com/jhu-cisst/mechatronics-software/wiki
  • https://github.com/jhu-dvrk/sawIntuitiveResearchKit/wiki/Hardware

All the arm classes are part of the sawIntuitiveResearchKit library. There is a base class (mtsIntuitiveResearchKitArm) for:

• powering
• getting data from the PID and IO components
• joint and cartesian motions
• cisstMultiTask interfaces

Since each arm is slightly different, there are three classes derived from the base class:

• mtsIntuitiveResearchKitPSM
• mtsIntuitiveResearchKitECM
• mtsIntuitiveResearchKitMTM

Each of these instantiates some virtual methods to reflect each arm characteristics:

• number of joints and actuators
• arm specific parameters (encoders/potentiometers tolerance, PID tracking error)
• kinematics
• homing procedure including different states (e.g. sterile adapter and tool for PSMs)

ECM and MTM classes currently use a text based configuration file which defines the DH parameters, see dv*.rob files in sawIntuitiveResearchKit shared directory. PSMs use a different file format (JSON based) containing the DH parameters as well as actuator/joint coupling matrices, joint limits, ... This file format centralizes all the parameters specific to a given tool (e.g. large needle driver). See psm*.json in the shared directory.

Most application should communicate with the arm classes to make sure that state of the system is consistent. IO and PID components should be used in "read only" mode.

The class mtsTeleOperation is part of the sawControllers library. It provides:

• a naive position based tele-operation
• API to set orientation between the MTM and the PSM
• handles operator present and clutch
• options to lock position or orientation of the PSM
• cisstMultiTask interfaces

The console class, mtsIntuitiveResearchKitConsole is part of the sawIntuitiveResearchKit library. The main goals of the console are:

• ease of deployment using a lightweight configuration file to describe the components of the system:
  • firewire port
  • periodicity for different components
  • types of arms (MTM, PSM, ECM, derived types...)
  • configurations files for IO, PID, arms with relative paths
  • teleoperation components (optional)
  • setup joints configuration
• maintaining runtime consistency between the different components
  • collect messages from components
  • centralized error handling
  • manage state of arms and controllers
  • handle and dispatch foot pedal events to arms and controllers

The console class also manages all the connections between the cisstMultiTask components which can be tedious when done manually. The console class is used in sawIntuitiveResearchKitQtConsoleJSON and in the ROS application dvrk_robot/dvrk_console_json. Using one of these two applications and a custom console configuration file, one should be able to configure pretty much any system without any C++ programming nor compilation; e.g. just one arm, one pair of arms with or without tele-operation, all arms...

The configuration files are JSON based, see console*.json files in sawIntuitiveResearchKit shared directory. The subdirectory jhu-dVRK contains files for a research kit (i.e. just MTMs and PSMs) while the directory jhu-daVinci contains examples for a full system, including setup joints and ECM.

All the Qt widgets used for the dVRK are derived from the mtsComponent class and either QObject or QWidget. This way, they can have both cisstMultiTask interfaces and Qt slots and signals. There is a couple of things to pay attention to when developing or modifying these widgets:

• Event handlers are not queued so they must be thread safe. In most case the event handler should emit a Qt signal
• Widgets should check if they are hidden or not before performing any computation, specially timer based refreshes

The class mtsRobotIO1394QtWidget is part of the sawRobotIO1394 library. Since there is usually a single IO component for multiple robots, we use an object factory to create as many widgets as necessary (see class mtsRobotIO1394QtWidgetFactory).

The layout will be slightly different based on the robot.

• Without brakes, PSM and MTM:
• With brakes, ECM:
• Extra widget for buttons (class prmQtWidgetEventButtonsComponent, part of cisstParameterTypesQt library)

The class mtsPIDQtWidget is part of the sawControllers library.

The class mtsIntuitiveResearchKitArmQtWidget is part of the sawIntuitiveResearchKit library.

The class mtsTeleOperationQtWidget is part of the sawControllers library.

The class mtsIntuitiveResearchKitConsoleQtWidget is part of the sawIntuitiveResearchKit library.