Freedom Robotics

Freedom Robotics Developer Hub

Welcome to the Freedom Robotics developer hub!

You'll find comprehensive guides and documentation to help you start working with Freedom Robotics as quickly as possible, as well as support if you get stuck. Let's jump right in!

For guides to setting up a device and using Freedom's core features, choose Get Started. If you'd prefer to jump in by yourself, choose Reference for detailed interface specifications.

Get Started    API Reference

Pilot: Navigate with a Map

Time to complete: 10 minutes

In this section, we'll set up map-based navigation for your robot. Freedom Robotics provides top-down and 3D views of your robot in its surroundings, enabling you to view your robot's position, visualize current and future paths, and set navigation waypoints. These features require a (simple) navigation stack to be running on the robot and accepting goal commands.

To enable you to identify issues and intervene in real-time, we'll walk through the following steps:

1. Set up transformations
2. Add map and path data
3. Navigate to a waypoint
4. Relocalize your robot

Uploading transformation data is required, and we recommend that you also set up all other elements that are relevant to your robot and its operations.

Set up transformations

Transformations define the three-dimensional relationships between various parts of your robot. For ROS-based systems, we upload data from the /tf and /tf_static topics by default. These topics contain all of the transformation information from the robot, so no additional set up is required.

Non-ROS users should review the schema for our transformation messages and how we interpret them here.

Visualizing 3D transformations

To view transformations in 3D, select your robot and navigate to SETTINGS → PILOT → ENVIRONMENT. Under the TRANSFORMATIONS section, enable the options to show the links, axis, and names. Next, return to the PILOT tab, select the map view and click the 3D button. These transformations are updated as the robot moves around.

Add map and path data

Map and path data provide important context for your robot as it navigates in its environment.

Upload map data

To add a map, select your robot and navigate to SETTINGS → PILOT → ENVIRONMENT. Under the MAP section, add the topic name for each of the maps you would like to view. If you add multiple map topics, the data will be overlaid on top of one another.

Map data should be formatted as the ROS type nav_msgs/OccupancyGrid. See here for more information.

Upload path data

This will allow visualization of the path the robot is following. To add path data, select your robot and navigate to SETTINGS → PILOT → ENVIRONMENT. Under the PATH section, add the path topic name.

Path data should be formatted as the ROS type nav_msgs/Path.

Tune upload bandwidth

We recommend an upload rate of 1-10 Hz depending on the path or map size for dynamic maps. For static maps, set the upload rate to 'once'. See the guide to tuning bandwidth for information on how to change a topic's upload frequency.

View map and path data

Next, return to the PILOT tab. If you haven't yet selected the map view, click on the map in the top right corner of the screen. You'll now see your robot with the current map and path data displayed. If you have multiple maps, you can toggle them on and off by clicking SELECT MAPS in the bottom left corner of the screen.

Set up navigation

Freedom Robotics provides an intuitive click-and-drag interface that lets you send navigation goals to your robot.

Add a navigation goal

Navigate to SETTINGSPILOT and select the MOVEMENT tab. Add your navigation goal topic name (e.g. /move_base_simple/goal and set the pose injection frame (e.g. map).

When you provide a navigation goal, Freedom will publish a message formatted as the ROS type geometry_msgs/Pose on the navigation topic name you provided (see here for more information on the message schema).

If you are using ROS, the standard move_group navigation node will accept this message. Non-ROS users will need to create a callback (see here to learn more about creating a callback).

Try it out

Next, head back to the PILOT tab, click TAKE OVER, and enter map mode by clicking on the map in the top right corner.

Click the NAVIGATE button on the righthand side of the screen, then click on the robot and drag it to the desired location. Adjust its orientation as desired, then click CONFIRM. If your robot's navigation stack is ready to accept a navigation goal, your robot will begin navigating to the waypoint!

Add a waypoint on the map and follow along in real-time as your robot navigates towards it.

Add a waypoint on the map and follow along in real-time as your robot navigates towards it.

Stopping your robot

While your robot is navigating, you can click the red MANUAL CONTROL button at any point to take over. This will send a zero velocity command to the wheels and send an empty message to the /move_base/cancel topic. You can change this default behavior in
SETTINGSPILOTCONTROLS under the NAVIGATION STOP BUTTON section.

'P' to copy pose

At any time in map view, press 'p' to copy the robot's current location to clipboard, or when in relocalization or navigation mode, to copy the current intended position.

Relocalizing your robot

Freedom makes it easy to intervene when a robot becomes "lost" or mis-localized. You can click and drag to move the robot to the correct position using LiDAR as a guide, then send a message to the robot to update its confirmed pose and position.

The relocalization tool can be used to adjust the robot position until the LiDAR (shown in blue) matches the appropriate position on the map.

The relocalization tool can be used to adjust the robot position until the LiDAR (shown in blue) matches the appropriate position on the map.

Add the relocalization topic

Navigate to SETTINGSPILOTMOVEMENT. Under the RELOCALIZE section, add the topic name and set the pose injection frame (e.g. map). If you're using amcl with ROS as your localization solution, the topic is /initialpose by default.

Freedom will publish the pose with covariance data on the indicated topic for your localization algorithm to use as an adjustment. The message will be formatted as the ROS type geometry_msgs/PoseWithCovarianceStamped (see here for more information about the message type).

For ROS users that use particle filter-based localization like amcl, this works out of the box. Non-ROS users will need to create a callback to accept the message (see here to learn more about creating a callback).

Try it out

Head to the PILOT tab and click TAKE OVER. If you haven't yet selected the map view, click on the map in the top right corner of the screen.

Click the localization button on the righthand side of the screen. Click and drag to reposition your robot appropriately, using the live LiDAR stream as a guide. You can adjust the robot's orientation by clicking and dragging farther away from the robot (the cursor will become a curved arrow).

Once the robot is positioned correctly, click CONFIRM. The robot's new pose will be published for your localization algorithm to accept and use to generate updated transformations. The robot's position will then be updated to reflect the new, correctly localized position on the map.

Updated about a month ago

Pilot: Navigate with a Map


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.