search

open-rmf / free_fleet

A free fleet management system.
Apache License 2.0
163 stars 69 forks source link

readme

Free Fleet

Contents



About

Welcome to free_fleet, an open-source robot fleet management system. Sometimes it is called the "Fun Free Fleet For Friends" (F5).

Note, this repository is under active development. Things will be quite unstable for a while. Please open an issue ticket on this repo if you have problems. Cheers.



Installation Instructions

Prerequisites

Install all non-ROS prerequisite packages,

sudo apt update && sudo apt install \
  git wget qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools \
  python3-rosdep \
  python3-vcstool \
  python3-colcon-common-extensions \
  # maven default-jdk   # Uncomment to install dependencies for message generation

[!IMPORTANT] In order to ensure messages using cyclonedds are sent, received, serialized and deserialized properly between the ROS 1 and ROS 2 systems, the version of cyclonedds used/built should be the same, this can be checked with dpkg -l | grep cyclonedds on ROS 2 systems, while ROS 1 systems will need to build cyclonedds from source. For ROS 2 versions above galactic, users will need to manage the versions of cyclonedds themselves. We are working on a newer iteration of free_fleet that does not use DDS and has access to newer features of Open-RMF, stay tuned!


Message Generation

Message generation via FleetMessages.idl is done using dds_idlc from CycloneDDS. For convenience, the generated mesasges and files has been done offline and committed into the code base. They can be found here.

./dds_idlc -allstructs FleetMessages.idl


Client in ROS 1

Start a new ROS 1 workspace, and pull in the necessary repositories,

mkdir -p ~/ff_ros1_ws/src
cd ~/ff_ros1_ws/src
git clone https://github.com/open-rmf/free_fleet -b main
git clone https://github.com/eclipse-cyclonedds/cyclonedds -b releases/0.7.x

Install all the dependencies through rosdep,

cd ~/ff_ros1_ws
rosdep install --from-paths src --ignore-src --rosdistro noetic -yr

Source ROS 1 and build,

cd ~/ff_ros1_ws
source /opt/ros/noetic/setup.bash
colcon build


Client and Server in ROS 2

Start a new ROS 2 workspace, and pull in the necessary repositories,

mkdir -p ~/ff_ros2_ws/src
cd ~/ff_ros2_ws/src
git clone https://github.com/open-rmf/free_fleet -b main
git clone https://github.com/open-rmf/rmf_internal_msgs -b main

Install all the dependencies through rosdep,

cd ~/ff_ros2_ws
rosdep install --from-paths src --ignore-src --rosdistro galactic -yr

Source ROS 2 and build,

cd ~/ff_ros2_ws
source /opt/ros/galactic/setup.bash
colcon build

# Optionally use the command below to only build the relevant packages,
# colcon build --packages-up-to \
#     free_fleet ff_examples_ros2 free_fleet_server_ros2 free_fleet_client_ros2



Examples

Barebones Example

This example emulates a running ROS 1 robot,

source ~/ff_ros1_ws/install/setup.bash
roslaunch ff_examples_ros1 fake_client.launch

This example emulates a running ROS 2 robot,

source ~/ff_ros2_ws/install/setup.bash
ros2 launch ff_examples_ros2 fake_client.launch.xml

The clients will then start subscribing to all the necessary topics, and start publishing robot states over DDS to the server. Start the server using

source ~/ff_ros2_ws/install/setup.bash
ros2 launch ff_examples_ros2 fake_server.launch.xml

# Verify that the server registers the fake clients
# [INFO] [1636706176.184055177] [fake_server_node]: registered a new robot: [fake_ros1_robot]
# [INFO] [1636706176.184055177] [fake_server_node]: registered a new robot: [fake_ros2_robot]

ROS 2 messages over the /fleet_states topic can also be used to verify that the clients are registered,

source ~/ff_ros2_ws/install/setup.bash
ros2 topic echo /fleet_states

Next, to send requests and commands, check out the example scripts and their uses here.


Turtlebot3 Fleet Server

This launches a server for a fleet of simulated turtlebot3 robots.

source ~/ff_ros2_ws/install/setup.bash
ros2 launch ff_examples_ros2 turtlebot3_world_ff_server.launch.xml

At this point, the server should register any clients running, if any of the simulations below are running.

Users can issue requests and commands through the server to the clients. Check out the example scripts and their uses here.

ROS 1 Turtlebot3 Simulation

Before starting these examples, remember to install all the prerequisites according to the official tutorials of using Turtlebot3, under noetic.

sudo apt install ros-noetic-dwa-local-planner

Launch the basic simulation of a single Turtlebot3, with a free fleet client attached to it, by sourcing the ROS 1 workspace and launching the provided example launch file,

source ~/ff_ros1_ws/install/setup.bash
export TURTLEBOT3_MODEL=burger; roslaunch ff_examples_ros1 turtlebot3_world_ff.launch

This launch file starts the simulation in gazebo, visualization in rviz, as well as the simulated navigation stack of the single turtlebot3. Once the simulation and visualization show up, the robot can be commanded as per normal through rviz with 2D Nav Goal.

If the server is already running, it should display that a new robot has been registered.

[INFO] [1636706001.275082185] [turtlebot3_fleet_server_node]: registered a new robot: [ros1_tb3_0]

Another way to check, is to listen in on the /fleet_states topic, using ros2 topic echo /fleet_states.

Next, to send requests and commands, check out the example scripts and their uses here.

ROS 2 Turtlebot3 Simulation

Before starting these examples, remember to install and build all the prerequisites,

sudo apt install ros-galactic-nav2-util ros-galactic-nav2-bringup ros-galactic-rviz2

cd ~/ff_ros2_ws/src
git clone https://github.com/ROBOTIS-GIT/turtlebot3 -b galactic-devel

cd ~/ff_ros2_ws
rosdep install --from-paths src --ignore-src --rosdistro galactic -yr

source /opt/ros/galactic/setup.bash
colcon build

Launch the basic simulation of a single Turtlebot3, with a free fleet client attached to it, by sourcing the ROS 1 workspace and launching the provided example launch file,

source ~/ff_ros2_ws/install/setup.bash
export TURTLEBOT3_MODEL=burger; ros2 launch ff_examples_ros2 turtlebot3_world_ff.launch.xml

This launch file starts the simulation in gazebo, visualization in rviz2, as well as the simulated navigation stack of the single turtlebot3. Once the simulation and visualization show up, the robot can be commanded as per normal through rviz2 with 2D Nav Goal.

If the server is already running, it should display that a new robot has been registered.

[INFO] [1636706001.275082185] [turtlebot3_fleet_server_node]: registered a new robot: [ros2_tb3_0]

Another way to check, is to listen in on the /fleet_states topic, using ros2 topic echo /fleet_states.

Next, to send requests and commands, check out the example scripts and their uses here.


ROS 1 Multi Turtlebot3 Simulation

This example launches three Turtlebot3s in simulation, and registers each robot as a client within a fleet controlled by free_fleet. The setup of this simulation is the same as the ROS 1 Turtlebot3 Simulation.

Similarly to the example, launch the provided launch file, which will start the simulation, visualization, navigation stacks of 3 turtlebot3s, and free fleet clients for each of the robots,

source ~/ff_ros1_ws/devel/setup.bash
export TURTLEBOT3_MODEL=burger; roslaunch ff_examples_ros1 multi_turtlebot3_ff.launch

Once the simulation and visualization show up, the robots can then be commanded to navigate to different parts of the map by using the tool and panels in the visualization. Fill in the fleet name and robot name, select the navigation goal using 2D Nav Goal, which will be reflected on the panel, and select Send Nav Goal.

If the server is already running, it should display that a new robot has been registered.

[INFO] [1636706001.275082185] [turtlebot3_fleet_server_node]: registered a new robot: [tb3_0]
[INFO] [1636706001.275082185] [turtlebot3_fleet_server_node]: registered a new robot: [tb3_1]
[INFO] [1636706001.275082185] [turtlebot3_fleet_server_node]: registered a new robot: [tb3_2]

Another way to check, is to listen in on the /fleet_states topic, using ros2 topic echo /fleet_states.

Next, to send more specific requests and commands, check out the example scripts and their uses here.


Commands and Requests

Now the fun begins! There are 3 types of commands/requests that can be sent to the simulated robots through free_fleet,

Destination requests, which allows single destination commands for the robots,

ros2 run ff_examples_ros2 send_destination_request.py -f FLEET_NAME -r ROBOT_NAME -x 1.725 -y -0.39 --yaw 0.0 -i UNIQUE_TASK_ID

Path requests, which requests that the robot perform a string of destination commands,

ros2 run ff_examples_ros2 send_path_request.py -f FLEET_NAME -r ROBOT_NAME -i UNIQUE_TASK_ID -p '[{"x": 1.725, "y": -0.39, "yaw": 0.0, "level_name": "B1"}, {"x": 1.737, "y": 0.951, "yaw": 1.57, "level_name": "B1"}, {"x": -0.616, "y": 1.852, "yaw": 3.14, "level_name": "B1"}, {"x": -0.626, "y": -1.972, "yaw": 4.71, "level_name": "B1"}]'

Mode requests which only supports pause and resume at the moment,

ros2 run ff_examples_ros2 send_mode_request.py -f FLEET_NAME -r ROBOT_NAME -m pause -i UNIQUE_TASK_ID
ros2 run ff_examples_ros2 send_mode_request.py -f FLEET_NAME -r ROBOT_NAME -m resume -i UNIQUE_TASK_ID

Note that the task IDs need to be unique, if a request is sent using a previously used task ID, the request will be ignored by the free fleet clients.



Plans