Gazebo Simulation

Gazebo simulation integration for pykal.

This module provides utilities for launching and managing Gazebo simulations directly from Python and Jupyter notebooks.

class pykal.gazebo.GazeboProcess(process, robot, world, headless)[source]

Bases: object

Wrapper for a Gazebo subprocess with lifecycle management.

Parameters:

process (Popen)
robot (str)
world (str)
headless (bool)

process: The subprocess.Popen object

robot: Name of the robot being simulated

world: Name of the world being used

headless: Whether running in headless mode

is_running()[source]

Check if Gazebo process is still running.

Return type:: bool

terminate()[source]

Gracefully terminate the Gazebo process and all children.

Return type:: None

pykal.gazebo.quick_start(robot='turtlebot3', headless=False)[source]

Quickly start Gazebo with default settings.

Convenience function for common use case.

Parameters:

robot (str, default='turtlebot3') – Robot type (‘turtlebot3’ or ‘crazyflie’)
headless (bool, default=False) – Run without GUI

Returns:

Gazebo process instance

Return type:

GazeboProcess

Examples

>>> from pykal.utilities.gazebo import quick_start, stop_gazebo
>>> gz = quick_start('turtlebot3')
>>> # ... your code ...
>>> stop_gazebo(gz)

pykal.gazebo.restart_gazebo(gz_process, **kwargs)[source]

Restart a Gazebo simulation with the same or updated parameters.

Parameters:

gz_process (GazeboProcess) – The Gazebo process to restart
**kwargs – Any parameters to override (same as start_gazebo)

Returns:

New Gazebo process instance

Return type:

GazeboProcess

Examples

>>> gz = start_gazebo(robot='turtlebot3')
>>> # ... simulation ...
>>> gz = restart_gazebo(gz, x_pose=1.0, y_pose=1.0)  # Restart at new position

pykal.gazebo.start_gazebo(robot='turtlebot3', world=None, headless=False, x_pose=0.0, y_pose=0.0, z_pose=0.0, yaw=0.0, launch_file=None, package=None, extra_args=None, verbose=True, model='burger')[source]

Launch Gazebo simulation with a robot.

This function starts a Gazebo simulation that can be used alongside pykal ROSNode instances in Jupyter notebooks for complete self-contained robot simulations.

Parameters:

robot (str, default='turtlebot3') – Robot type to simulate. Options: - ‘turtlebot3’: TurtleBot3 (Burger or Waffle) - ‘crazyflie’: Crazyflie quadrotor - ‘custom’: Use custom launch_file and package
world (str, optional) – World/environment name. If None, uses default for robot type: - turtlebot3: ‘turtlebot3_world’ - crazyflie: ‘crazyflie_world’
headless (bool, default=False) – If True, run Gazebo without GUI (faster, less resource intensive)
x_pose (float, default=0.0) – Initial x position of robot (meters)
y_pose (float, default=0.0) – Initial y position of robot (meters)
z_pose (float, default=0.0) – Initial z position of robot (meters)
yaw (float, default=0.0) – Initial yaw angle of robot (radians)
launch_file (str, optional) – Custom launch file name (required if robot=’custom’)
package (str, optional) – ROS2 package containing launch file (required if robot=’custom’)
extra_args (dict, optional) – Additional launch arguments as key-value pairs
verbose (bool, default=True) – Print status messages
model (str, default='burger') – TurtleBot3 model type (burger, waffle, or waffle_pi). Only used when robot=’turtlebot3’

Returns:

Process wrapper that can be used to manage the Gazebo instance

Return type:

GazeboProcess

Examples

Launch TurtleBot3 with GUI:

>>> from pykal.utilities.gazebo import start_gazebo, stop_gazebo
>>> gz = start_gazebo(robot='turtlebot3', world='turtlebot3_world')
>>> # ... run your simulation ...
>>> stop_gazebo(gz)

Launch Crazyflie in headless mode:

>>> gz = start_gazebo(
...     robot='crazyflie',
...     headless=True,
...     z_pose=0.5
... )

Launch custom robot:

>>> gz = start_gazebo(
...     robot='custom',
...     package='my_robot_gazebo',
...     launch_file='my_robot.launch.py',
...     extra_args={'use_sim_time': 'true'}
... )

Raises:

ValueError – If invalid robot type or missing required arguments
RuntimeError – If Gazebo fails to start

Parameters:

robot (str)
world (str | None)
headless (bool)
x_pose (float)
y_pose (float)
z_pose (float)
yaw (float)
launch_file (str | None)
package (str | None)
extra_args (Dict[str, Any] | None)
verbose (bool)
model (str)

Return type:

GazeboProcess

pykal.gazebo.stop_gazebo(gz_process, verbose=True)[source]

Stop a running Gazebo simulation.

Parameters:

gz_process (GazeboProcess) – The Gazebo process to stop (returned by start_gazebo)
verbose (bool, default=True) – Print status messages

Return type:

None

Examples

>>> gz = start_gazebo(robot='turtlebot3')
>>> # ... simulation code ...
>>> stop_gazebo(gz)

Gazebo Launcher

Gazebo launcher utilities for pykal.

This module provides functions to launch and manage Gazebo simulations directly from Jupyter notebooks, enabling self-contained robot simulations.

class pykal.gazebo.gazebo.GazeboProcess(process, robot, world, headless)[source]

Bases: object

Wrapper for a Gazebo subprocess with lifecycle management.

Parameters:

process (Popen)
robot (str)
world (str)
headless (bool)

process: The subprocess.Popen object

robot: Name of the robot being simulated

world: Name of the world being used

headless: Whether running in headless mode

is_running()[source]

Check if Gazebo process is still running.

Return type:: bool

terminate()[source]

Gracefully terminate the Gazebo process and all children.

Return type:: None

pykal.gazebo.gazebo.quick_start(robot='turtlebot3', headless=False)[source]

Quickly start Gazebo with default settings.

Convenience function for common use case.

Parameters:

robot (str, default='turtlebot3') – Robot type (‘turtlebot3’ or ‘crazyflie’)
headless (bool, default=False) – Run without GUI

Returns:

Gazebo process instance

Return type:

GazeboProcess

Examples

>>> from pykal.utilities.gazebo import quick_start, stop_gazebo
>>> gz = quick_start('turtlebot3')
>>> # ... your code ...
>>> stop_gazebo(gz)

pykal.gazebo.gazebo.restart_gazebo(gz_process, **kwargs)[source]

Restart a Gazebo simulation with the same or updated parameters.

Parameters:

gz_process (GazeboProcess) – The Gazebo process to restart
**kwargs – Any parameters to override (same as start_gazebo)

Returns:

New Gazebo process instance

Return type:

GazeboProcess

Examples

>>> gz = start_gazebo(robot='turtlebot3')
>>> # ... simulation ...
>>> gz = restart_gazebo(gz, x_pose=1.0, y_pose=1.0)  # Restart at new position

pykal.gazebo.gazebo.start_gazebo(robot='turtlebot3', world=None, headless=False, x_pose=0.0, y_pose=0.0, z_pose=0.0, yaw=0.0, launch_file=None, package=None, extra_args=None, verbose=True, model='burger')[source]

Launch Gazebo simulation with a robot.

This function starts a Gazebo simulation that can be used alongside pykal ROSNode instances in Jupyter notebooks for complete self-contained robot simulations.

Parameters:

robot (str, default='turtlebot3') – Robot type to simulate. Options: - ‘turtlebot3’: TurtleBot3 (Burger or Waffle) - ‘crazyflie’: Crazyflie quadrotor - ‘custom’: Use custom launch_file and package
world (str, optional) – World/environment name. If None, uses default for robot type: - turtlebot3: ‘turtlebot3_world’ - crazyflie: ‘crazyflie_world’
headless (bool, default=False) – If True, run Gazebo without GUI (faster, less resource intensive)
x_pose (float, default=0.0) – Initial x position of robot (meters)
y_pose (float, default=0.0) – Initial y position of robot (meters)
z_pose (float, default=0.0) – Initial z position of robot (meters)
yaw (float, default=0.0) – Initial yaw angle of robot (radians)
launch_file (str, optional) – Custom launch file name (required if robot=’custom’)
package (str, optional) – ROS2 package containing launch file (required if robot=’custom’)
extra_args (dict, optional) – Additional launch arguments as key-value pairs
verbose (bool, default=True) – Print status messages
model (str, default='burger') – TurtleBot3 model type (burger, waffle, or waffle_pi). Only used when robot=’turtlebot3’

Returns:

Process wrapper that can be used to manage the Gazebo instance

Return type:

GazeboProcess

Examples

Launch TurtleBot3 with GUI:

>>> from pykal.utilities.gazebo import start_gazebo, stop_gazebo
>>> gz = start_gazebo(robot='turtlebot3', world='turtlebot3_world')
>>> # ... run your simulation ...
>>> stop_gazebo(gz)

Launch Crazyflie in headless mode:

>>> gz = start_gazebo(
...     robot='crazyflie',
...     headless=True,
...     z_pose=0.5
... )

Launch custom robot:

>>> gz = start_gazebo(
...     robot='custom',
...     package='my_robot_gazebo',
...     launch_file='my_robot.launch.py',
...     extra_args={'use_sim_time': 'true'}
... )

Raises:

ValueError – If invalid robot type or missing required arguments
RuntimeError – If Gazebo fails to start

Parameters:

robot (str)
world (str | None)
headless (bool)
x_pose (float)
y_pose (float)
z_pose (float)
yaw (float)
launch_file (str | None)
package (str | None)
extra_args (Dict[str, Any] | None)
verbose (bool)
model (str)

Return type:

GazeboProcess

pykal.gazebo.gazebo.stop_gazebo(gz_process, verbose=True)[source]

Stop a running Gazebo simulation.

Parameters:

gz_process (GazeboProcess) – The Gazebo process to stop (returned by start_gazebo)
verbose (bool, default=True) – Print status messages

Return type:

None

Examples

>>> gz = start_gazebo(robot='turtlebot3')
>>> # ... simulation code ...
>>> stop_gazebo(gz)