ROS Toolbox

Support Package for TurtleBot®-Based Robots User's

Guide

R2023b
How to Contact MathWorks

Latest news: www.mathworks.com

Sales and services: www.mathworks.com/sales_and_services

User community: www.mathworks.com/matlabcentral

Technical support: www.mathworks.com/support/contact_us

Phone: 508-647-7000

The MathWorks, Inc.

1 Apple Hill Drive
Natick, MA 01760-2098
ROS Toolbox Support Package for TurtleBot®-Based Robots User's Guide
© COPYRIGHT 2016–2023 by The MathWorks, Inc.
The software described in this document is furnished under a license agreement. The software may be used or copied
only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form
without prior written consent from The MathWorks, Inc.
FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through
the federal government of the United States. By accepting delivery of the Program or Documentation, the government
hereby agrees that this software or documentation qualifies as commercial computer software or commercial computer
software documentation as such terms are used or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014.
Accordingly, the terms and conditions of this Agreement and only those rights specified in this Agreement, shall pertain
to and govern the use, modification, reproduction, release, performance, display, and disclosure of the Program and
Documentation by the federal government (or other entity acquiring for or through the federal government) and shall
supersede any conflicting contractual terms or conditions. If this License fails to meet the government's needs or is
inconsistent in any respect with federal procurement law, the government agrees to return the Program and
Documentation, unused, to The MathWorks, Inc.
Trademarks
MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See
www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand names may be
trademarks or registered trademarks of their respective holders.
Patents
MathWorks products are protected by one or more U.S. patents. Please see www.mathworks.com/patents for
more information.
Revision History
March 2016 Online only New for Version 16.1.0 (R2016a)
September 2016 Online only Rereleased for Version 16.2.0 (R2016b)
March 2017 Online only Rereleased for Version 17.1.0 (R2017a)
September 2017 Online only Rereleased for Version 17.2.0 (R2017b)
March 2018 Online only Rereleased for Version 18.1.0 (R2018a)
September 2018 Online only Rereleased for Version 18.2.0 (R2018b)
March 2019 Online only Rereleased for Version 19.1.0 (R2019a)
September 2019 Online only Released for Version 19.2.0 (R2019b)
March 2020 Online only Rereleased for Version 20.1.0 (R2020a)
September 2020 Online only Rereleased for Version 20.2.0 (R2020b)
March 2021 Online only Rereleased for Version 21.1.0 (R2021a)
September 2021 Online only Revised for Version 21.2.0 (R2021b)
March 2022 Online only Revised for Version 22.1.0 (R2022a)
September 2022 Online only Revised for Version 22.2.0 (R2022b)
March 2023 Online only Revised for Version 23.1.0 (R2023a)
September 2023 Online only Revised for Version 23.2.0 (R2023b)
 Contents

ROS Toolbox Support Package for TurtleBot-Based Robots

Examples
1
Get Started with the TurtleBot Support Package . . . . . . . . . . . . . . . . . . . . 1-2

Robot Applications
2
Get Image Data from TurtleBot at a Fixed Rate . . . . . . . . . . . . . . . . . . . . . 2-2

Plot Turtlebot Odometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

Create a UI for TurtleBot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7

Track and Follow an Object Using a TurtleBot . . . . . . . . . . . . . . . . . . . . . 2-11

iii
 1

ROS Toolbox Support Package for

TurtleBot-Based Robots Examples
1 ROS Toolbox Support Package for TurtleBot-Based Robots Examples

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.

1-2
 Get Started with the TurtleBot Support Package

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)

1-3
1 ROS Toolbox Support Package for TurtleBot-Based Robots Examples

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]

1-4
 Get Started with the TurtleBot Support Package

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)

1-5
1 ROS Toolbox Support Package for TurtleBot-Based Robots Examples

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

1-6
 2

Robot Applications

• “Get Image Data from TurtleBot at a Fixed Rate” on page 2-2

• “Plot Turtlebot Odometry” on page 2-5
• “Create a UI for TurtleBot” on page 2-7
• “Track and Follow an Object Using a TurtleBot” on page 2-11
2 Robot Applications

Get Image Data from TurtleBot at a Fixed Rate

This example shows how to get image data from the TurtleBot and display it at a fixed rate. ROS
Toolbox Support Package for TurtleBot-Based Robots enables you to connect to TurtleBot
hardware and get the color, grayscale, and depth images from it. In this example, use the
getColorImage function to get color images off the TurtleBot to display them. To collect images at a
fixed rate, use rateControl.

Connect to TurtleBot

Connect to your TurtleBot robot using its specific IP address. Your simulated or real TurtleBot must
be on the same ROS network as the computer running MATLAB™. Specify the command velocity
topic name.

ipaddress = '192.168.192.130'; % IP address of your robot

tbot = turtlebot(ipaddress,11311);
tbot.Velocity.TopicName = '/cmd_vel';

Get the latest image from the TurtleBot and show it in a figure. This TurtleBot is simulated in Gazebo.
For more information on the Gazebo simulator, see “Get Started with Gazebo and Simulated
TurtleBot”.

img = getColorImage(tbot);
imshow(img)

2-2
 Get Image Data from TurtleBot at a Fixed Rate

Create a rateControl object to control the execution rate of code. The desired rate is 2 Hz.

desiredRate = 2;
rate = rateControl(desiredRate);

Reset the rateControl object and start a loop to drive the robot in a circle for 10 seconds and
capture images. In the loop, use setVelocity to command a linear and angular velocity of 0.1 m/s
and 0.5 rad/s respectively. Then capture the latest image and display it. Wait for the desired rate at
the end of each loop. The image shown is the final image after the 10 turns.

reset(rate)
for i = 1:20
setVelocity(tbot,0.01,0.5)
img = getColorImage(tbot,0);
imshow(img)
waitfor(rate);
end

2-3
2 Robot Applications

To save bandwidth on the network, disable the image subscriber now that it is no longer in use. On
the ColorImage property of the robot, set Active to false. You can also disconnect from the robot
by calling clear tbot.

tbot.ColorImage.Active = false;

See Also
turtlebot | getColorImage | setVelocity | rateControl

Related Examples
• “Plot Turtlebot Odometry” on page 2-5
• “Track and Follow an Object Using a TurtleBot” on page 2-11
• “Execute Code at a Fixed-Rate” (Robotics System Toolbox)

2-4
 Plot Turtlebot Odometry

Plot Turtlebot Odometry

This example shows how to get, store, and display odometry data from a TurtleBot® as it drives in an
environment.

Connect to TurtleBot

Description of first code block

ipaddress = '192.168.192.130'; % IP address of your robot

tbot = turtlebot(ipaddress,11311);
tbot.Velocity.TopicName = '/cmd_vel';

Get Odometry Data

Use getOdometry to get a single odometry point off the TurtleBot. The function returns the position
and orientation as [x y z] coordinates and [yaw pitch roll] angles.

odom = getOdometry(tbot)

odom = struct with fields:

Position: [4.3772 1.4580 -0.0010]
Orientation: [-2.2936 0.0032 7.8259e-06]

Send velocity commands to change the position of the robot. To note the change in position, reset the
odometry first. Use setVelocity to drive the robot forward for 2 seconds and wait for the robot to
execute this command.

resetOdometry(tbot)
setVelocity(tbot,0.5,'Time',2)

Get the odometry after the velocity command is sent. The x-coordinate of odom.Position reflects
the change in position. A velocity of 0.5 m/s for 2 seconds yields a displacement of 1m in the x
direction as expected.

odom = getOdometry(tbot)

odom = struct with fields:

Position: [3.2717 0.7216 -0.0010]
Orientation: [-2.6151 0.0032 -1.5861e-05]

Plot Odometry Data Points

You can store odometry data to get a full trajectory of a robot path as it navigates through its
environment.

Start a loop to store the odometry position and then send a velocity command. This loop runs 20
times to create a basic two-turn trajectory. Plot the trajectory.

odomList = zeros(20,2);
resetOdometry(tbot)

for i = 1:20
odom = getOdometry(tbot);

2-5
2 Robot Applications

odomList(i,:) = [odom.Position(1) odom.Position(2)];

if i < 10
setVelocity(tbot,0.25,0.15)
else
setVelocity(tbot,0.25,-0.15)
end
pause(1);
end

plot(odomList(:,1),odomList(:,2))

See Also
turtlebot | getOdometry | setVelocity

Related Examples
• “Get Image Data from TurtleBot at a Fixed Rate” on page 2-2
• “Create a UI for TurtleBot” on page 2-7

2-6
 Create a UI for TurtleBot

Create a UI for TurtleBot

This example shows how to create a UI for collecting sensor data and controlling a TurtleBot® robot.
You can use the UI to get and display odometry data and laser scan readings and to teleoperate the
robot by sending it velocity commands.

For this example, specify all code and dependent callback functions in a single MATLAB® function
file.

• Set Up the UI and Its Components on page 2-7

• Connect to Robot on page 2-8
• Specify Callback Functions for UI Buttons on page 2-8
• Run UI and Control the Robot on page 2-9

Set Up the UI and Its Components

Create a function that sets up the UI for controlling the robot. Specify the dimensions of the buttons
and the callbacks associated with each button.

Specify the function header for the UI.

function turtlebot_UI

Create the UI and hide it as you build it.

f = figure('Visible','off','Position',[50,50,900,570]);

Add the components for the different buttons and for the axes used to plot data. It is important to
specify the 'Callback' name-value pair with the correct function handles. These functions are
specified at the end.

hforward = uicontrol('Style','pushbutton',...
'String','Forward','Position',[770,440,70,25],...
'Callback',@forwardCB);
hleft = uicontrol('Style','pushbutton',...
'String','Left','Position',[730,400,70,25],...
'Callback',@leftCB);
hright = uicontrol('Style','pushbutton',...
'String','Right','Position',[815,400,70,25],...
'Callback',@rightCB);
hback = uicontrol('Style','pushbutton',...
'String','Back','Position',[770,360,70,25],...
'Callback',@backCB);
hgetOdom = uicontrol('Style','pushbutton',...
'String','Get Odom','Position',[730,320,70,25],...
'Callback',@getOdomCB);
hreset = uicontrol('Style','pushbutton',...
'String','Reset','Position',[815,320,70,25],...
'Callback',@resetCB);
hgetScan = uicontrol('Style','pushbutton',...
'String','Get Scan','Position',[730,280,70,25],...
'Callback',@getScanCB);
hclear = uicontrol('Style','pushbutton',...
'String','Clear','Position',[815,280,70,25],...

2-7
2 Robot Applications

'Callback',@clearCB);
ha = axes('Units','pixels','Position',[50,60,600,400]);

Show the UI after adding all the components by setting Visible to 'on'.

% Make UI visible
f.Visible = 'on';

Connect to Robot

Connect to your TurtleBot robot using its specific IP address. Your simulated or real TurtleBot must
be on the same ROS network as the computer running MATLAB.

ipaddress = '192.168.192.130'; % IP address of your robot

tbot = turtlebot(ipaddress,11311);
tbot.Velocity.TopicName = '/cmd_vel';

Initialize the variables needed for sensor data. Reset the odometry of the TurtleBot.

odomList = [];
scanPts = [];
resetOdometry(tbot);

Specify Callback Functions for UI Buttons

Each UI button has a callback function that activates when the button is pressed. You specify these
functions inside your turtlebot_UI function file.

Create directional button callbacks for controlling the robot.

function forwardCB(source,eventdata)
setVelocity(tbot,0.25,0)
end

function leftCB(source,eventdata)
setVelocity(tbot,0,0.25)
end

function rightCB(source,eventdata)
setVelocity(tbot,0,-0.25)
end

function backCB(source,eventdata)
setVelocity(tbot,-0.25,0)
end

The inputs to setVelocity are the interface object, turtlebot, and the linear and angular
velocities.

Create callbacks to get and clear odometry and laser scan data. plotOdom and plotScan are
convenience functions for plotting odometry and laser scan to the current axes.

function getOdomCB(source,eventdata)
plotOdom
end
function resetCB(source,eventdata)
resetOdometry(tbot);
odomList = [];

2-8
 Create a UI for TurtleBot

plotOdom
end
function getScanCB(source,eventdata)
plotOdom
hold on
plotScan
hold off
end
function clearCB(source,eventdata)
scanPts = [];
plotOdom
end

Specify the plotOdom and plotScan functions, which plot the sensor data on the current axes in the
UI.

function plotOdom
% Gets and plots current and saved odometry
odom = getOdometry(tbot);
odomList = [odomList; odom.Position(1) odom.Position(2)];
plot(odomList(:,1),odomList(:,2),'b')
hold on
quiver(odom.Position(1),odom.Position(2),...
cos(odom.Orientation(1)),sin(odom.Orientation(1)),'r',...
'LineWidth',2)
hold off
xlim([-5,5])
ylim([-5,5])
grid on
end

function plotScan
% Plots laser scan data on top of current odometry
[scan,scanMsg] = getLaserScan(tbot);
odom = getOdometry(tbot);
cart = readCartesian(scanMsg);
scanPts = [cart(:,1)+odom.Position(1) cart(:,2)+odom.Position(2)];
yaw = odom.Orientation(1);
R = [cos(yaw) -sin(yaw); sin(yaw) cos(yaw)];
scanPts = (R*scanPts')';
plot(scanPts(:,1),scanPts(:,2),'k')
xlim([-5,5])
ylim([-5,5])
grid on
end

End the turtlebot_UI function. Make sure that all the example code is between this end and the
function header.

end

Run UI and Control the Robot

Call turtlebot_UI to run the function. The UI is created and connects to the robot. Set up your
robot before running the UI.

turtlebot_UI

2-9
2 Robot Applications

Use the buttons to move the robot. Click Get Odom to plot a new odometry point (blue) or Get Scan
to plot the current laser scan data (black).

See Also
turtlebot | getOdometry | getLaserScan | setVelocity

Related Examples
• “Get Image Data from TurtleBot at a Fixed Rate” on page 2-2
• “Track and Follow an Object”

2-10
 Track and Follow an Object Using a TurtleBot

Track and Follow an Object Using a TurtleBot

This example shows how to track an object based on color using a TurtleBot® robot connected via a
ROS network. ROS Toolbox Support Package for TurtleBot-Based Robots enables you to capture
images to find an object in the environment and send velocity commands to navigate toward the
object. To follow the object, you use the getColorImage and setVelocity functions along with
image processing techniques.

• Connect to Robot on page 2-11

• Track Object on page 2-11
• Follow Object Using Velocity Commands on page 2-13
• Improvement Suggestions on page 2-15

Connect to Robot

Connect to your TurtleBot robot using its specific IP address. Your simulated or real TurtleBot must
be on the same ROS network as the computer running MATLAB®.

ipaddress = '192.168.192.130'; % IP address of your robot

tbot = turtlebot(ipaddress,11311);
tbot.Velocity.TopicName = '/cmd_vel';

Track Object

To detect the example object, a blue ball, you must specify some of its properties. You use these
properties to process the images you capture. This example uses Image Processing Toolbox™ to run
color and blob detection algorithms on each image to find the ball.

Specify the properties of the ball shown, substituting in values that are tuned for your environment.
The values given are optimal for the Gazebo simulation detailed in “Get Started with Gazebo and
Simulated TurtleBot”.

blueBallParams.blueMax = 120; % Maximum permissible deviation from pure blue

blueBallParams.darkMin = 30; % Minimum acceptable darkness value

Get an image off the TurtleBot.

latestImg = getColorImage(tbot);

Use these two example helper functions to get and plot the location of the ball in the image. These
functions use regionprops from Image Processing Toolbox to get the location and size of the ball.
The first image is the output from the TurtleBot with the object location overlaid on it. The second
image is the binary image, ballImage, for detecting blue in the image based on blueBallParams.
If the ball does not show up as white with limited background in this binary image, try tuning the
blueBallParams values.

[position,~,ballImage] = exampleHelperTurtleBotFindBlueBall(latestImg,blueBallParams,false);
exampleHelperTurtleBotPlotObject(latestImg,ballImage,position);

2-11
2 Robot Applications

2-12
 Track and Follow an Object Using a TurtleBot

Follow Object Using Velocity Commands

After you tune the tracking of the object in the image, you can set up a basic control algorithm for
sending commands to the TurtleBot. This example uses basic logic with singular linear and angular
velocity commands to get the robot to follow the ball. For a more advanced control scheme, see
“Track and Follow an Object”.

Get a new image and store the image size. Recalculate the position and size of the object.
latestImg = getColorImage(tbot);
[height,width] = size(latestImg);
[position,~] = exampleHelperTurtleBotFindBlueBall(latestImg,blueBallParams,false);

Generate angular and linear velocities based on the position and size of the ball. If no object is found,
spin and search for the ball (positive angular velocity only).

• If the ball is on the far left side of the screen, the robot needs to turn left (positive angular
velocity). The same is true for the right side (negative angular velocity).
• If the ball is too small in the image, the robot must move closer (positive linear velocity). If the ball
is too large, the robot must move farther away (negative linear velocity).

Finally, send the linear and angular velocities using setVelocity and pause to wait for the
command to send. Iterate for 100 cycles to test tracking.
% Parameters for ball position and size
horizontalTolerance = 20;
sizeGoal = 70;
sizeTolerance = 5;
for i = 1:100
% Get latest image, ball postion, and ball size.
latestImg = getColorImage(tbot);
[height,width] = size(latestImg);
[position,ballSize] = exampleHelperTurtleBotFindBlueBall(latestImg,blueBallParams,false);

% Initialize velocities to zero.

linearVel = 0;
angularVel = 0;

% Left and right controls

if isempty(position)
angularVel = 0.5;
linearVel = 0;
elseif (position(1) > (width/2)-horizontalTolerance)
angularVel = 0.2;
elseif (position(1) < (width/2)+horizontalTolerance)
angularVel = -0.2;
end

% Forward and back control

if isempty(ballSize)
angularVel = 0.5;
linearVel = 0;
elseif ballSize > sizeGoal + sizeTolerance
linearVel = - 0.1;
elseif ballSize < sizeGoal - sizeTolerance
linearVel = 0.1;
end

2-13
2 Robot Applications

% Send velocity commands and wait for commands to send.

setVelocity(tbot,linearVel,angularVel)
pause(0.2)
end

To verify the algorithm is successful, capture an image and use the help functions to track and plot
the position once more. The TurtleBot focuses on the ball, assuming it found the ball during its
search. Based on the Gazebo simulated world in this example, a final image capture shows the ball
right in front of the robot.

latestImg = getColorImage(tbot);
[c,ballSize,ballImage] = exampleHelperTurtleBotFindBlueBall(latestImg,blueBallParams,false);
exampleHelperTurtleBotPlotObject(latestImg,ballImage,c);

2-14
 Track and Follow an Object Using a TurtleBot

Improvement Suggestions

This example uses simple sensor feedback and control parameters for tracking and following an
object. It works well in a simulated environment due to its low level of risk to hardware and real
environments. However, it does not factor in the bump or clip sensors, which can help with collisions
or terrain changes. Dynamically adjusting the velocity commands and factoring in previous states can
improve the movements of the TurtleBot.

To improve this example for real-world applications, consider using more advanced methods of
sensing and control for real robots that have more robust handling of sensor data. See “Track and
Follow an Object” for a more advanced example that uses a PID controller and other robot sensors.

See Also
turtlebot | getColorImage | setVelocity

Related Examples
• “Get Image Data from TurtleBot at a Fixed Rate” on page 2-2
• “Track and Follow an Object”

2-15