← Getting Started

Installation

For robot simulation capabilities, install Gazebo. The version depends on your ROS2 distribution.

Gazebo Harmonic (for ROS2 Jazzy on Ubuntu 24.04)

# Install Gazebo Harmonic
sudo apt update
sudo apt install ros-jazzy-ros-gz

# Verify installation
gz sim --version

Gazebo Garden (for ROS2 Humble on Ubuntu 22.04)

# Install Gazebo Garden
sudo apt update
sudo apt install ros-humble-ros-gz

# Verify installation
gz sim --version

Install Robot-Specific Packages

For TurtleBot3 simulation:

# For ROS2 Jazzy
sudo apt install ros-jazzy-turtlebot3*

# For ROS2 Humble
sudo apt install ros-humble-turtlebot3*

# Set default TurtleBot3 model (add to ~/.bashrc)
echo "export TURTLEBOT3_MODEL=burger" >> ~/.bashrc
source ~/.bashrc

For Crazyflie simulation:

# Install Crazyflie ROS2 packages
# (Instructions vary by ROS2 version - consult Crazyflie documentation)
sudo apt install ros-${ROS_DISTRO}-crazyflie*

Development Installation

For contributing to pykal or running tests:

# Clone the repository
git clone https://github.com/nehalsinghmangat/pykal.git
cd pykal

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests to verify installation
pytest

# Optional: Install pre-commit hooks
pre-commit install

Documentation Build Setup

To build the documentation locally:

# Install with documentation dependencies
pip install -e ".[docs]"

# Build documentation
cd docs
make html

# View documentation (open in browser)
xdg-open build/html/index.html  # Linux
# or
open build/html/index.html      # macOS

Verification

Verify your installation with these quick tests:

# Test core functionality
python -c "from pykal import DynamicalSystem; print('✓ Core pykal works')"

# Test ROS2 integration (only if ROS2 installed)
python -c "from pykal import ROSNode; print('✓ ROS2 integration works')"

# Test Gazebo utilities (only if ROS2 installed)
python -c "from pykal.gazebo import start_gazebo, stop_gazebo; print('✓ Gazebo utilities work')"

# Test Kalman filter
python -c "from pykal.estimators import KF; print('✓ Estimators work')"

Troubleshooting

ImportError: No module named ‘rclpy’

ROS2 is not installed or not sourced. Either:

  1. Install ROS2 (see ROS2 Installation section)

  2. Source ROS2 setup: source /opt/ros/<distro>/setup.bash

  3. Only use core pykal features (avoid ROSNode)

Python version too old

# Check Python version
python3 --version

# Should show Python 3.12.x or higher
# If not, install Python 3.12+

Gazebo fails to launch

# Ensure Gazebo is installed
gz sim --version

# Check ROS-Gazebo bridge is installed
ros2 pkg list | grep ros_gz

# Verify robot packages
ros2 pkg list | grep turtlebot3

Virtual environment issues

# Deactivate current environment
deactivate

# Remove old environment
rm -rf pykal-env

# Create fresh environment
python3 -m venv pykal-env
source pykal-env/bin/activate
pip install --upgrade pip
pip install pykal

Tests fail after development installation

# Ensure all dev dependencies are installed
pip install -e ".[dev]"

# Update pytest
pip install --upgrade pytest pytest-doctestplus

# Run with verbose output
pytest -v

← Getting Started