Main Content

Get Started with the TurtleBot Support Package

This example demonstrates how to interface with the TurtleBot® robot. You can acquire sensor data from the robot's sensors and send commands to control the robot's motion.

All functionality works either with a simulated robot in Gazebo or with a physical TurtleBot.

  • If you are using a real TurtleBot, follow the hardware setup steps in Get Started with a Real TurtleBot.

  • Alternatively, you can download a virtual machine image that already has ROS and Gazebo installed. This virtual machine is based on Ubuntu® Linux® and is pre-configured to support this example. Follow the setup steps in Get Started with Gazebo and Simulated TurtleBot, and launch the Gazebo Office world to access a simulated TurtleBot.

Connect to TurtleBot

Connect to the robot by replacing the sample IP address with the IP address of the TurtleBot. This creates a turtlebot object that can be used to retrieve sensor data to control the robot's motion.

ipaddress = '192.168.192.132';
tbot = turtlebot(ipaddress)
tbot = 
  turtlebot with properties:

           Velocity: [1×1 struct]
         ColorImage: [1×1 struct]
          GrayImage: [1×1 struct]
         DepthImage: [1×1 struct]
         PointCloud: [1×1 struct]
          LaserScan: [1×1 struct]
           Odometry: [1×1 struct]
      OdometryReset: [1×1 struct]
                IMU: [1×1 struct]
    TransformFrames: {0×1 cell}
         TopicNames: {32×1 cell}

Specify the command velocity topic name.

tbot.Velocity.TopicName = '/cmd_vel';

Get Sensor Data

Get the position and orientation of the robot from its odometry sensor.

pose = getOdometry(tbot)
pose = struct with fields:
       Position: [3.0898e-05 9.9519e-05 -0.0010]
    Orientation: [6.2384e-04 0.0032 -3.3232e-06]

Every TurtleBot sensor or control command is represented by a capability property in the turtlebot class. For example, the Odometry property contains information about the robot's odometry sensor.

tbot.Odometry
ans = struct with fields:
    TopicName: '/odom'
       Active: 1

Each capability property has two fields. The TopicName field shows the ROS topic used to receive sensor data or send control commands. The Active field allows you to explicitly enable or disable the data stream.

Explicitly enable the color image subscriber. Note that for convenience, the color image subscriber is enabled automatically when you first call getColorImage.

tbot.ColorImage.Active = true;

The same behavior applies to all functions starting with get. Each capability property has an associated getPROP or setPROP function, where PROP refers to the property name.

Get a color image from the TurtleBot camera and display it. The getColorImage function waits for up to 5 seconds for a new image.

[colorImg] = getColorImage(tbot);
figure
imshow(colorImg)

You can change the maximum time that the function should wait for a color image by specifying an optional timeout value (in seconds). Wait for up to 10 seconds for a new image.

colorImg = getColorImage(tbot, 20);

Disable the color image subscriber. This can be useful if you want to save network bandwidth or process sensor data offline.

tbot.ColorImage.Active = false;

Control Robot Motion

You can also send commands to control the robot's motion. Move the robot forward at a speed of 0.3 meters per second.

setVelocity(tbot, 0.3);

Now wait until the robot finishes moving and then get a new odometry reading.

pause(1)
pose = getOdometry(tbot)
pose = struct with fields:
       Position: [0.1464 -8.5454e-04 -0.0010]
    Orientation: [-0.0057 0.0032 -3.0712e-06]

You can reset the odometry and then try the movement again. resetOdometry sets the robot position and robot orientation to [0, 0, 0] respectively.

When you move the robot forward, you can expect only the X position value to change, whereas the Y and Z values should be close to 0.

resetOdometry(tbot)
setVelocity(tbot, 0.3);
pause(1)
pose = getOdometry(tbot)
pose = struct with fields:
       Position: [1.0262 -0.0066 -0.0010]
    Orientation: [-0.0075 0.0032 -4.0146e-06]

Notice that setVelocity only sends a single command to the robot and it stops moving fairly quickly. To command the TurtleBot to continue a motion for a specified time period, you can use an alternative syntax.

Move the robot in a circular motion for 5 seconds.

setVelocity(tbot, 0.3, 0.6, 'Time', 10);

At the end of the elapsed time, a velocity of 0 is sent to the robot. At the end of the elapsed time, a velocity of 0 is sent to the robot. Get a point cloud from the robot's depth sensor to verify where the robot is.

[pcloud, pcloudmsg] = getPointCloud(tbot);
figure;
scatter3(pcloudmsg)

The second output argument pcloudmsg is optional and gives you access to the received ROS message. See Work with Specialized ROS Messages for more information. All other functions starting with get also return the ROS message as a second, optional output.

Disconnect from the Robot

Disconnect from the robot by clearing the tbot variable from the workspace.

clear tbot