MATLAB USARSim Toolbox

The USARSim Matlab Toolbox gives users the ability to interface with USARSim and develop robot control programs in Matlab. The current version of the toolbox is developed for USARSim-2004 (v3.0 or higher) and is compatible with Matlab v7.5 or higher. The toolbox also features limited initial compatibility with USARSimUT3.

Alpha Version

Download Version 1.1, Modified 02/14/2011

Beta Version

Download Version 1.4, Modified 05/19/2010

Useful Links

Quickstart

To start place all the *.m files and the Java directory in your working Matlab directory.

  1. Start USARSim
  2. In Matlab, enter the command
    >> rob = initializeRobot('robot_name', 'robot_type', robot_Position, robot_Orientation)
    where 'robot_name' is the robot's name in UT2004, 'robot_type' is the type of robot you want to use, and 'robot_Position' and 'robot_Orientation' are 3x1 vectors containing the robot's x, y, and z position in world coordinates and roll, pitch, and yaw angles.
    Suggestion: You may want to use the same name for the Matlab variable, i.e., rob, as the robot's name. Now you are ready to send robots different commands using the other Matlab functions. A brief description of what each function does is provided below. To get help on using the functions type help function_name at the Matlab command prompt. When you are done working with the robot, make sure you call the shutdownRobot(rob) command. When you are ready to close Matlab, call the shutdownUSAR command.

Release Notes

Changes:

  • Added timestamp field to all sensor outputs.
  • Added matlab function to obtain the status of mission packages. 1/13/2011
  • Added support for aerial robots to the sendDriveCommand. 1/13/2011
  • Fixed sendDriveCommand for [0 0] commands to differential drive robots. A [0 0] command will now stop the robot. 1/13/2011
  • initializeRobot will now check to make sure if second element in robot position vector is 0 or not and make necessary adjustments. USAR has a bug such that robots cannot span at [* 0 *] positions. 1/13/2011

Matlab Function Descriptions

  • addUSARJavaPath.m - Internal command used by initializeRobot.m to add the Java Class Path.
  • getEncoderReadings.m - Returns a USAR sensor message for the encoders on a vehicle as a Matlab struct with members: Names (String vector), Ticks (number vector).
    Usage: encoders = getEncoderReadings(robot), where robot is the java class object created with initializeRobot.m.
  • getGPSReadings.m - Returns a USAR sensor message for a GPS sensor on a vehicle as a Matlab struct with members: Name (String), Latitude (double), Longitude (double), GotFix (double), NumOfSatellites (double).
    Usage: gps = getGPSReadings(robot), where robot is the java class object created with initializeRobot.m.
  • getGroundTruth.m - Returns a structure containing true robot position and orientation.
    Usage: true = getGroundTruth(robot), where robot is the java class object created with initializeRobot.m.
  • getImage.m - Returns an image from the robot's onboard camera.
    Usage: Please consult the USARSim Camera Support section.
  • getINSReadings.m - Returns a USAR sensor message for an INS sensor on a vehicle as a Matlab struct with members: Name (String), Position (1x3 vector), Orientation (1x3 vector).
    Usage: ins = getINSReadings(robot), where robot is the java class object created with initializeRobot.m.
  • getLaserSensorReadings.m - Returns a USAR sensor message for a laser range finder on a vehicle as a Matlab struct with members: Name (String), Resolution (double), FOV (double), and Scans (double vector).
    Usage: laser = getLaserSensorReadings(robot), where robot is the java class object created with initializeRobot.m.
  • getMissionState.m - Returns an array of USAR mission state messages on a robot. Each element in the array contains a Matlab struct with members: Name (String), TimeStamp (double), Link (int vector), Value (double vector), and Torque (double vector).
    Usage: state = getMissionState(robot), where robot is the java class object created with initializeRobot.m.
  • getOdometryReadings.m - Returns a USAR sensor message for an odometry sensor on a vehicle as a Matlab struct with members: Name (String), Pose (1x3 vector).
    Usage: odometry = getOdometryReadings(robot), where robot is the java class object created with initializeRobot.m.
  • getRFIDReadings.m - Returns a structure containing name of the sensor, ID's of RFID tags picked up by the sensor and their corresponding data.
    Usage: rfid = getRFIDReadings(robot), where robot is the java class object created with initializeRobot.m.
  • getSonarReadings.m - Returns a USAR sensor message for sonar sensors on a vehicle as a Matlab struct with members: Name (String), Range (double vector).
    Usage: sonar = getSonarReadings(robot), where robot is the java class object created with initializeRobot.m.
  • getTouchSensorReadings.m - Returns a USAR sensor message for touch sensors on a vehicle as a Matlab struct with members: Name (String), ContactState (double vector of 0s and 1s).
    Usage: touch = getTouchSensorReadings(robot), where robot is the java class object created with initializeRobot.m.
  • getVehicleGeometry.m - Returns a USAR geometry message for a ground vehicle as a Matlab struct with members: Name (String), Dimensions (3x1 vector), CenterOfGravity (3x1 vector), WheelRadius (number), WheelSeparation (number), WheelBase (number).
    Usage: vehicleGeo = getVehicleGeometry(robot), where robot is the java class object created with initializeRobot.m.
  • getVehicleState.m - Returns a USAR ground vehicle state message as a Matlab struct with members: TimeStamp (number), FrontSteer (number), RearSteer (number), LightToggle (0 or 1), LightIntensity (number between 0 and 100), and BatteryLife (number).
    Usage: state = getVehicleState(robot), where robot is the java class object created with initializeRobot.m.
  • initializeRobot.m - Creates a new robot in USARSim.
    Usage: rob = initializeRobot('robot_name', 'robot_type', left_motor, right_motor).
  • sendDriveCommand.m - Sends commands to drive the robot.
    Usage: sendDriveCommand(robot,command,command_Type) where command = [left_motor_value, right_motor_value] and command_type can be either 'differential' or 'ackerman' depending on the vehicle type.
  • sendMisPkgCommand.m - Sends a command to a mission package on a robot.
    Usage: sendMisPkgCommand(robot,name,joints,angles,types), where robot is the java class object created with initializeRobot.m, name is the name of the mission package as stated in USARBot.ini, joints is a vector of joint numbers corresponding to the numbers given in USARMisPkg.ini, angles is a vector of desired angles/speeds/torques corresponding to the joint numbers in joints, types is a vector of command orders corresponding to the joints argument. Type 0 is angle control. Type 1 is speed control. Type 2 is torque control. If this argument is omitted, all types default to 0.
  • setRFIDTag.m - Sends a command to the RFID sensor to change an RFID tag's memory to the given string.
    Usage: setRFIDTag(robot,ID,data), where robot is the java class object created with initializeRobot.m, ID is the unique ID of the tag you want to change, and data is the string you want to store in the tag. data can contain letters, numbers, and underscores.
  • shutdownRobot.m - Clears the robot from USARSim.
    Usage: shutdownRobot(robot), where robot is the java class object created with initializeRobot.m.
  • shutdownUSAR.m - Clears USARSim java class objects from the Matlab's workspace.

The zipped file contains the following:

  • USARSimJava directory containing the following files USARSim.java and:
    • USARSim.class, USARSim$1.class, USARSim$ParseWorker.class
    • usarStateGroundVehicle.class
    • usarMissionState.class
    • usarGroundVehicleGeometry.class
    • usarGroundTruth.class, usarSensorEncoder.class, usarSensorGPS.class, usarSensorINS.class, usarSensorLaser.class, usarSensorOdometry.class, usarSensorRFID.class, usarSensorSonar.class, usarSensorTouch.class
  • Matlab functions (more to come!):
    • addUSARJavaPath.m
    • initializeRobot.m, shutdownRobot.m, shutdownUSAR.m
    • sendDriveCommand.m, sendMisPkgCommand.m
    • setImageQuality.m, setImageResolution.m, setRFIDTag.m, spawnKarmaTag.m
    • getVehicleState.m
    • getVehicleGeometry.m
    • getEncoderReadings.m, getGPSReadings.m, getGroundTruth.m, getImage.m, getINSReadings.m, getLaserSensorReadings.m, getOdometryReadings.m, getRFIDReadings.m, getSonarReadings.m, getTouchSensorReadings.m


USARSim Camera Support

The biggest change to the toolbox in this release is the addition of camera support. This new tool uses a third party program called FRAPS http://www.fraps.com/ to capture rendered images from the GPU and saves them in a folder. A new program included in the toolbox USAR Screenshot Tool.exe) monitors the user-selectable FRAPS screenshot capture folder for new images. These new images are moved to a folder known to a location that matlab can process. The sampling rate of the system is set in the FRAPS configuration and it generally performs well with an interval of 1 second or more.

Installation:

The MATLAB library is used exactly as before. Additional steps are required for camera support. First, visit the FRAPS site http://www.fraps.com/ to download and install FRAPS. The vision code works perfectly well with the trial version of FRAPS, however the trial is limited to bitmap-type files and these can tax your hard drive. After FRAPS is installed, open it and move to the screenshot tab. Select the button that says 'Repeat screen capture every' and set the desired time interval. One second is a good idea on most modern machines. Take a note of the Screen Capture Hotkey and the folder listed.

Next, start the 'USAR Screenshot Tool.exe' and point it to the folder that FRAPS will save in. Start up MATLAB and instantiate a robot. After the robot is created in Unreal click on the viewport until it shows the robot's first-person view. Push the FRAPS hotkey to start capturing then click start on the screenshot tool. The screenshot tool should give feedback if it's working or not. After this is confirmed to be working getImage.m can be used to get the image in MATLAB. The scripts setResolution.m and setQuality.m are still being implemented.

Notes:

  • Currently only one robot per Unreal window is supported. The way this program works is that it captures exactly what the unreal window sees. Unreal and USARSim support multiview and that will be implemented in the future.
  • The current version does not support resolution scaling. The resolution giving in Matlab is equal to the game window resolution.

Outstanding known issues:

  • No multi-vehicle camera support
  • Camera resolution independence

Previous versions:

Previous changes:

  • Incorporated ground truth sensor, v1.4
  • Improved RFID support (tag writing), v1.4
  • The biggest change to the toolbox in this release is the addition of camera support. This new tool uses a third party program called FRAPS http://www.fraps.com/ to capture rendered images from the GPU and saves them in a folder. More information on this here, v1.4
  • Added Camera support through external software, v1.3
  • Added RFID support, v1.3

Return to MEM380 Course Website


Contact Us

Questions or comments, please send us an e-mail at DrexelSASLab _at_ gmail dot com. If you would like to contribute your additions/modifications/improvements, send us an e-mail at DrexelSASLab _at_ gmail dot com so we can incorporate your contributions in future releases.