Preser

A Matlab Framework For Professional Education in Service Robotics.

About Preser

The object of the project is to develop and test the new area of Professional Education in Service Robotics. The main motivation comes from the fact that there is a significant gap between research education and professiontal education, i.e. addressing the needs of inegrators of service robots.

PRESER will provides lectures for addressing the practical aspects of using a service robot in a domestic environment and a simulation framework based on MATLAB www.mathworks.com and the simulator V-REP www.coppeliarobotics.com for testing your knowledge during the lessons.

Download Preser

Our framework is available for OSX, Windows and Debian based distros.You can download the binary included in Preser for free following the button below, or you can get the source code via our public repositories.

Download Binaries Download Source code

User manual

Before start using Preser you need to setup your computer, if you have already setup the system, you can go to the Sketch section and find a complete list of examples build with the built-in algorithms. The user manual is available for the download here User manual.

Install

Step-by-step instructions for setting up Preser on your computer (Mac OS X, Windows, Linux) and connecting it to the simulator.

Setup

Clone the repository with the flag --recursive for getting the other dependencies (i.e gmapping c++ core):
git clone --recursive -b master https://bitbucket.org/altairlab/preser.git

Then download Peter Corke Toolbox here and unzip it in the base folder. Matlab 2014a or later and the following toolboxes are required:

  • Simulink Toolbox
  • Aerospace Toolbox

Mexfile

To compile a mexfile you will need a c++ compiler installed on your system, then for each algorithm written in c++ that you need to use run the compile script.

Java

If you need to compile the simulation runner, remember to append to the java classpath the path to jmi.jar. For linux user add this command to the bashrc file and adjust the path if needed export CLASSPATH=$CLASSPATH:matlab-root/java/jar/jmi.jar. The runner must be compiled with the same or later version of java embed in Matlab, and to get the Matlab java version use the following command version -java.

Simulator

To get the simulator download the latest version of V-REP from Coppelia Robotics (http://www.coppeliarobotics.com/). The simulator standard configuration is ready to be used with remote Api. In case you want to customize port number and debug console you have to edit the remoteApiConnections.txt placed in the base folder of the simulator.

Usage

Procedures

For defining a procedure (i.e your program) you have to create two scripts: a initialization one (invoked only one time before the first simulation step) and the main procedure (invoked every simulation step). These scripts must be written in Matlab code and placed inside the procedures folder.

These phase is also abstracted by an automated code generation with a simple user interface available inside the control panel.

Anyway if you want to write your own procedure the standard workflow for the main procedure is:

  • Define components port interconnections
  • Call update components function

This is an example for a main procedure that use SLAM GMapping, laser scan, the robot class and a joypad for drive the robot with a twist command.

robot.Base(1).m_twist_cmd = joypad.out_twist_cmd;
slam.in_odometry = robot.Base(1).out_odometry;
slam.in_laser_data = laser.out_laser_points;

path_planner.in_odometry = robot.Base(1).out_odometry;
path_planner.in_occupacy_grid = slam.out_occupacy_grid;

joypad.update();
slam.update();
laser.update();
robot.update();

In other hand for the initial procedure doesn't exist a standard workflow, mainly this procedures it's used only for the non-standard object instantiation. Below there's an example for an initial procedure: robot, robot_kine and cartesian_ctrl objects are automatically created by the start_me_up script.

api.armSetCtrlModes(1,4);
api.baseSetCtrlModes(1,5);

joypad = XBoxJoypad();
laser = Hokuyo(vrep,id);
slam = GMapping();

path_planner = AStar();

Configuration

Preser is fully configurable via .ini file that are stored in the config folder. The main configuration file is Preser.ini and each section is described below:

Section hilas:

Parameter Value Content
start_thread true/false Start the simulation loop after the first step
thread_sleep 1-n Set the sleep time between each simulation step (ms)
init_procedure string Set the name of the initialization procedure (usefull for object instantiate, robot setup etc...). This name reflect the Matlab script name your_init_procedure.m
procedure string Set the name of the procedure executed every simulation step (set component ports connection, invoke update component etc...) This name reflect the Matlab script name your_procedure.m
matlab_warning true/false Enable the warning in the Matlab console
java_log true/false Enable log for simulation runner
matlabcontrol_log true/false Enable debug console for jmi.jar

Section simulator:

Parameter Value Content
socketaddr ip address Set the ip address where the simulator resides
socketport number Set the port number for the socket connection
scene string Set the name of the scene to be loaded at startup (the scene name doesn't include file extension your_scene_name.ttt)
startScene true/false Set if the scene is loaded via Preser

Section robot:

Parameter Value Content
name string Set the name of the robot used in the simulation. The robot name reflect the real robot name

Command

Once the system is setted up, the simulation driver is wrapped in a workspace variable called hilas with a couple of usefull functions:

  • hilas.suspend Suspend the execution of the runner thread.
  • hilas.resume Resume the execution of the runner thread.
  • hilas.stopRun Stop the execution of the runner thread, stop the simulator and exit the loop (the command doesn't clean the Matlab workspace).

Api

The General API have a couple of functions usefull for plotting data:

  • plotRobotKine() Plot the kinematic chain.
  • plotRobotKineWorkspace(cube_size) Plot the kinematic chain with a workspace dimention ( needed for prismatic joint).
  • plotLaserPoints(laser) Plot the 2D laser points in the laser reference frame.
  • plotMap(slam, robot, amcl) Plot the occupacy grid from slam as an image. Slam, amcl and robot pose are displayed in overlay with circles of different colour (red = slam correction, green = amcl correction, blue = robot odometry).
  • plotStaticMap(static_map, robot, amcl) Plot the occupacy grid from a static map. Amcl and robot pose are displayed in overlay with circles of different colour (green = amcl correction, blue = robot odometry).
  • saveMap(slam) Save the occupacy grid in .mat file. Filename is map_yymmddHHMMSSFFF of your system.
  • loadMap(filename) Load the occupacy grid from a file and store the grid in a workspace variable called static_map.

With the Robot API is possible to modify the robot control loop parameters and joint target:

  • armSetCtrlModes(index, k) Set the specified control mode for the arm service.
  • armSetPos(index,joint_pos) Set the control mode to PLANE_ANGLE and set the target positions.
  • armSetVel(index,joint_vel) Set the control mode to ANGULAR_VELOCITY and set the target velocities.
  • armSetTor(index,joint_tor) Set the control mode to TORQUE and set the target torques (not yet implemented).
  • baseSetCtrlModes(index, k) Set the control mode for the base service.
  • baseSetPos(index,joint_pos) Set the control mode to PLANE_ANGLE and set the target positions (deprecated).
  • baseSetVel(index,joint_vel) Set the control mode to ANGULAR_VELOCITY and set the target velocities.
  • baseSetTor(index,joint_tor) Set the control mode to TORQUE and set the target torques (not yet implemented).
  • baseSetTwist(index,twist) Set the control mode to TWIST and set the specified twist command.
  • gripperSetCtrlModes(index, k) Set the specified control mode for the gripper service.
  • gripperSetStat(index,isToBeOpened) Set the specified target state for the gripper.

The control modes parameter set the type of loop controller. I.e Setting the control mode to PLANE_ANGLE the control loop will only apply the joint position target. The MOTOR_STOP mode is different for the other ones. Specifying it a joint position controller is activated which keeps fixed the instantaneous joints position. The control modes can be specified via enumeration or integer values:

PLANE_ANGLE (1)
ANGULAR_VELOCITY (2)
TORQUE (3)
MOTOR_STOP (4)
TWIST (5)

i.e armSetCtrlModes(1,MOTOR_STOP) is equal as armSetCtrlModes(1,5).

Remarks

Due to concurrent workspace access sometimes (mainly for long take time functions) is possible to have error messages in the console.

The simulation is driven by Matlab via the runner java thread, so the simulation time increase only when the runner is executed.

Sketch

The Sketch section gives you a brief description for the built-in examples of what you can do with Preser. If you want to get some information about the principles, techniques and how to setup the framework read the User manual.

Slam (Simultaneous localization and mapping)

Localization

  • Localization Move and localize your robot on a static map.

Planning

  • Planning Plan a route to a specific destination on a static map.
  • Trajectory Plan a route to a specific destination and move the robot to a specific destination on a static map.

Extra

  • Planimetry Build a simulator scene from a provided planimetry of the environment.
  • Trajectory 2 Use together trajectory generator and free robot navigation.

The Sketch section gives you a brief description for the built-in examples of what you can do with Preser. If you want to get some information about the principles, techniques and how to setup the framework read the User manual.

OBJECT RECOGNITION AND IDENTIFICATION

GRASP PLANNING

  • Geometry Use inverse kinematic to grasp from a point given by segmentation.
  • Agile Grasp Use agile grasp algorithm.

VISUAL SERVOING

  • Camera calibration Use matlab camera calibration and load parameters.
  • Visual Navigation and servoing. Define trajectory.

Extra

  • Navigation and grasping Build a simulator scene in office environment which use navigation algorithm and object grasping.

The Sketch section gives you a brief description for the built-in examples of what you can do with Preser. If you want to get some information about the principles, techniques and how to setup the framework read the User manual.

TELEOPERATION

  • Four Channel Teleoperation architecture.
  • Two Layer Energy tank teleoperation algorithm.
  • TDPA Time Domain Passivity Approach.

Lessons

The structure of the course is divided in two main sections: theory and practice. Click on a element in the list to show the relative topic.

Contact Us

Feel free to email us to provide some feedback on our project, give us suggestions for improve the project, report any bug or to just say hello!

preser@altairlab.scienze.unvir.it