Basic Usage

To get started with PyRoboSim, you can run the following examples.

Standalone

First, go to the pyrobosim subfolder under the repository root.

cd /path/to/pyrobosim/pyrobosim

Then, run the example.

python3 examples/demo.py

This serves the UI at http://localhost:8050 and opens it in your default browser.

You can now interact with the UI through the buttons and text boxes. For example, enter “bedroom desk” in the Goal query text box and then click the Navigate button. Once at the destination, click Pick.

Basic standalone demo.

With ROS 2

First, build and setup your ROS 2 workspace (or use one of our provided Docker containers).

cd /path/to/ros_workspace
colcon build
. install/local_setup.bash

You can run a ROS 2 enabled demo and interact with the UI:

ros2 run pyrobosim_ros demo.py

In a separate Terminal, you can send an action goal with a task plan or a single action:

ros2 run pyrobosim_ros demo_commands.py --ros-args -p mode:=action
ros2 run pyrobosim_ros demo_commands.py --ros-args -p mode:=plan

Or, you can run both of these nodes together using a provided launch file:

ros2 launch pyrobosim_ros demo_commands.launch.py mode:=plan
ros2 launch pyrobosim_ros demo_commands.launch.py mode:=action

The first command will start a world as a ROS 2 node, and the second one will execute a plan (or set of actions) to the node.

Basic ROS 2 demo.

Creating Worlds

Worlds can be created either with the Python API, or loaded from a YAML file using the pyrobosim.core.yaml_utils.WorldYamlLoader utility.

By default, demo.py creates a world using the API, but you can alternatively try a demo YAML file using the --world-file argument. For example:

# Standalone
python3 examples/demo.py --world-file test_world.yaml

# ROS 2
ros2 launch pyrobosim_ros demo.launch.py world_file:=test_world.yaml

Refer to the YAML Schemas documentation for more information.

Web UI

The PyRoboSim UI is browser-based and built with Plotly Dash. The examples serve it at http://localhost:8050 and open it in your default browser.

To use the web UI in your own scripts, call start_ui with a world:

from pyrobosim.web import start_ui

start_ui(world, host="127.0.0.1", port=8050, auto_open=True)

To keep the browser from opening automatically (e.g., on a headless machine), pass auto_open=False.

Note that the web server is unauthenticated, so only bind to a non-localhost address (host) on networks you trust.

Exporting Worlds to Gazebo

To export worlds to Gazebo, there is a pyrobosim.core.gazebo.WorldGazeboExporter utility. You can try this with the following commands.

# Standalone
python3 examples/demo_world_save.py

# ROS 2
ros2 run pyrobosim_ros demo_world_save.py

Then, follow the steps displayed on the console to see the generated world.

Example world exported to Gazebo.