The MBot Bridge API
The MBot Bridge API is a simple interface to control the robot and read its data. The API is available in both C++ and Python.
MBot Bridge Server
The API communicates with the MBot Bridge Server, which acts as a bridge between your code and the MBot’s programs. The MBot Bridge Server should be running before you run any code that uses the API. On the full MBot images (available on the flashing an image guide), the bridge should be running automatically.
MBot C++ API
To use the API’s robot functions, you must first create a robot object. This is done as follows:
#include <mbot_bridge/robot.h>
int main(int argc, const char *argv[])
{
// Initialize the robot.
mbot_bridge::MBot my_robot;
}
All the functions in the API will use this robot object.
my_robot.drive(0.5, 0, 0);
MBot::drive(0.5, 0, 0)
will not work. The documentation is written this way to make it clear that these functions come from the MBot class.
Sending Robot Commands
The following functions can be used to send robot commands.
Functions
-
void MBot::drive(const float vx, const float vy, const float wz)
Sends a drive command to the robot.
Warning: Once
drive
is called, the robot will continue to drive at the given speed until you tell it to stop! Usestop
to stop the robot.Parameters:
- vx: The x-component of the robot’s velocity in meters per second.
- vy: The y-component of the robot’s velocity in meters per second.
- wz: The angular (turning) velocity of the robot in radians per second.
-
void MBot::stop()
Stops the robot by sending a zero velocity command.
This is the same as calling
drive(0, 0, 0)
. -
void MBot::resetOdometry()
Resets the robot odometry to zero.
-
void MBot::drivePath(const std::vector<std::array<float, 3> >& path)
Sends a path to the motion controller to follow.
This function will return right away, while the robot is still following the path. If you have code that should only run when the path is completed, you must check if the path is finished executing separately.
Parameters:
- std::vector<std::array<float, 3> > path: A vector of arrays of length 3, each of which contain a coordinate in the path to be followed in form
[x, y, theta]
, wherex
andy
are in meters andtheta
is in radians.
- std::vector<std::array<float, 3> > path: A vector of arrays of length 3, each of which contain a coordinate in the path to be followed in form
Reading Robot Data
The following functions can be used to read data from the robot.
Functions
-
void MBot::readLidarScan(std::vector<float>& ranges, std::vector<float>& thetas)
Reads the latest Lidar scan from the robot and places the resulting ranges and angles in the vectors
ranges
andthetas
.The vector
ranges
contains the length of each ray in the scan, andthetas
contains the angle (in radians) of each ray. The vectors should have the same number of elements. If there is no scan available, a warning will be printed and both vectors will have length zero.Warning: Some rays in the scan never return (for example, if there are no obstacles, or the ray bounces off a material and goes in a different direction). If the ray does not return, its range will be zero. Make sure you check for rays with zero range and ignore them.
-
std::vector<float> MBot::readOdometry()
Reads the latest robot pose computed using odometry.
The odometry pose is measured from the pose where the robot was turned on, or at which odometry was last reset. You might want to call
resetOdometry()
at the beginning of a program using odometry data.Warning: Odometry will not be accurate over long trajectories.
Returns:
A vector with three elements containing the position (in meters) and angle (in radians) of the robot (i.e.
[x, y, theta]
). If there is no odometry data available, a warning will be printed to the screen and the vector returned will have length zero. -
std::vector<float> MBot::readSlamPose()
Reads the latest robot pose computed using Simultaneous Localization and Mapping (SLAM).
SLAM must be active and the robot must be localized in a good map of its environment to use this function. See the mapping guide for instructions. The SLAM pose is measured from the pose where the robot was when the mapping process started.
Returns:
A vector with three elements containing the position (in meters) and angle (in radians) of the robot (i.e.
[x, y, theta]
). If there is no SLAM data available, a warning will be printed to the screen and the vector returned will have length zero.
MBot Python API
To use the API’s robot functions, you must first create a robot object. This is done as follows:
from mbot_bridge.api import MBot
# Initialize the robot.
my_robot = MBot()
All the functions in the API will use this robot object.
my_robot.drive(0.5, 0, 0)
MBot.drive(0.5, 0, 0)
will not work. The documentation is written this way to make it clear that these functions come from the Robot class.
Sending Robot Commands
The following functions can be used to send robot commands. None of them return data.
Functions
-
MBot.drive(vx, vy, wz)
Sends a drive command to the robot.
Warning: Once
drive
is called, the robot will continue to drive at the given speed until you tell it to stop! Usestop
to stop the robot.Parameters:
- vx: The x-component of the robot’s velocity in meters per second.
- vy: The y-component of the robot’s velocity in meters per second.
- wz: The angular (turning) velocity of the robot in radians per second.
-
MBot.stop()
Stops the robot by sending a zero velocity command.
This is the same as calling
drive(0, 0, 0)
.Returns: None
-
MBot.reset_odometry()
Resets the robot odometry to zero.
-
MBot.drive_path(path)
Sends a path to the motion controller to follow.
This function will return right away, while the robot is still following the path. If you have code that should only run when the path is completed, you must check if the path is finished executing separately.
Parameters:
- path: A list of coordinates (lists or tuples) in the path to be followed. If the coordinates have length 2, the values are assumed to be in form
[x, y]
, wherex
andy
are in meters, with an angle of zero by default. If the coordinates have length 3, the data is in form[x, y, theta]
, wherex
andy
are in meters andtheta
is in radians.
- path: A list of coordinates (lists or tuples) in the path to be followed. If the coordinates have length 2, the values are assumed to be in form
Reading Robot Data
The following functions can be used to read robot commands. None of the reading functions take parameters.
Functions
-
MBot.read_lidar()
Reads the latest Lidar scan from the robot.
Returns:
A tuple,
(ranges, thetas)
, whereranges
contains the length of each ray in the scan, andthetas
contains the angle (in radians) of each ray. The lists should have the same number of elements. If there is no scan available, a warning will be printed and both lists will have length zero.Warning: Some rays in the scan never return (for example, if there are no obstacles, or the ray bounces off a material and goes in a different direction). If the ray does not return, its range will be zero. Make sure you check for rays with zero range and ignore them.
-
MBot.read_odometry()
Reads the latest robot pose computed using odometry.
The odometry pose is measured from the pose where the robot was turned on, or at which odometry was last reset. You might want to call
reset_odometry()
at the beginning of a program using odometry data.Warning: Odometry will not be accurate over long trajectories.
Returns:
A list with three elements containing the position (in meters) and angle (in radians) of the robot (i.e.
[x, y, theta]
). If there is no odometry data available, a warning will be printed to the screen and the list returned will have length zero. -
MBot.read_slam_pose()
Reads the latest robot pose computed using Simultaneous Localization and Mapping (SLAM).
SLAM must be active and the robot must be localized in a good map of its environment to use this function. See the mapping guide for instructions. The SLAM pose is measured from the pose where the robot was when the mapping process started.
Returns:
A list with three elements containing the position (in meters) and angle (in radians) of the robot (i.e.
[x, y, theta]
). If there is no SLAM data available, a warning will be printed to the screen and the list returned will have length zero. -
MBot.read_hostname()
Reads the robot’s hostname.
Returns:
A string containing the robot’s hostname.