GORM Rover Software Overview

Welcome to the GORM Rover Software Overview, the rover consists of these main ROS 2 packages:

• gorm_bringup - Main system launcher with robot state publisher and control nodes
• gorm_base_control - Ackermann Kinematics interface for 6-wheel, 4-steer kinematics (/cmd_vel → /motor commands)
• gorm_teleop - Manual control via joystick (teleop_twist_joy_node, joy-to-cmd_vel converter)
• gorm_sensors - Sensor drivers for RGBD cameras, IMU, etc.
• gorm_navigation - Navigation stack and RL-based navigation nodes and configs
• gorm_web_interface - Lightweight web server and web UI for monitoring and control

Table of Contents

• Installation: Provides a step-by-step guide to install the GORM Rover Software on the Rover.
• Launching: Explains how to launch the GORM Rover Software, including building and running the Docker images.

Launching the GORM Rover

The GORM rover can be launched in two modes: development mode (for active development) and production mode (for deployment). This page covers the development mode. For production deployment, see the Deployment Guide.

Quick Start with Docker (Development Mode)

1. Navigate to the Rover Software Directory: Open a terminal and navigate to the directory where the rover software (on the rover) is located.

   cd /workspace/rover-software/docker
   

2. Run the Docker Container and Attach to It: Start the Docker container that contains the rover software in development mode and attach to it.

   ./run.sh rover --dev
   
   # Attach to the running Docker container
   docker exec -it rover-software-dev bash
   

3. Build the ROS2 Packages: Inside the Docker container, build the ROS2 packages to ensure everything is set up correctly.

   colcon build
   source install/setup.bash
   

4. Launch the Rover Software: Finally, launch the rover software using the provided launch file.

   ros2 launch gorm_bringup bringup_teleop.launch.py
   

5. BEFORE YOU START DEVELOPMENT: Make sure to set up your SSH keys and Git configuration as described in the Development Setup Guide.

Quick Start (Production Mode)

1. Navigate to the Rover Software Directory: Open a terminal and navigate to the directory where the rover software (on the rover) is located.

   cd /workspace/rover-software/docker
   

2. Run the Production Deployment: Start the production deployment which runs continuously and automatically restarts if it crashes or the system reboots.

   ./run.sh rover --prod
   # or with docker-compose:
   docker-compose up -d rover-deploy
   

Useful docker inspection commands

```bash
# List running containers
docker ps
# List all containers (including stopped)
docker ps -a
# View logs of a specific container
docker logs -f <container_name_or_id>
# Access a running container's shell
docker exec -it <container_name_or_id> bash
```

Development Setup

Multi-Developer Setup (ORIN System)

When developing on the shared ORIN system (192.168.50.100) with multiple developers, follow these steps:

1. Create personal workspace and clone:

   # Replace 'abmo' with your initials/username
   mkdir -p ws/abmo_dev
   cd ws/abmo_dev
   git clone https://github.com/AAU-Space-Robotics/rover-software.git
   cd rover-software
   

2. Configure Git locally for your identity:

   git config user.name "Your Name"
   git config user.email "your.email@example.com"
   

3. SSH Agent Setup for ORIN (192.168.50.100):

   Add to your SSH config (~/.ssh/config):

    Host 192.168.50.100
        HostName 192.168.50.100
        User gorm
        ForwardAgent yes
        IdentityFile ~/.ssh/id_ed25519
   

4. Install Keychain

   sudo apt-get update
   sudo apt-get install keychain
   

5. Setup SSH key evaluation:

   Add to the bottom of your ~/.profile and ~/.xprofile:

   eval $(keychain --eval --quiet id_ed25519)
   

   create the files if they don't exist.

6. Development with Docker (Recommended):

   cd docker
   ./run.sh rover --dev
   

7. Native development:

   # Source ROS 2
   source /opt/ros/humble/setup.bash
   
   # Build packages
   colcon build
   source install/setup.bash
   

Testing

ROS 2 Packages

# Build and test a specific package
colcon build --packages-select gorm_control
colcon test --packages-select gorm_control

Docker Testing

# Test in development container
cd docker
./run.sh rover --dev

# Test production build
./build.sh
./run.sh rover --prod

Development vs Production

Development Setup (rover service)

Use for: Active development, debugging, testing

• Source code mounted as volumes (../src:/home/workspace/src)
• Manual building required (colcon build)
• Interactive environment
• Code changes immediately available

Workflow:

./run.sh rover --dev
# or attach to the running container:
docker exec -it rover bash
# inside the container:
colcon build && source install/setup.bash
ros2 launch gorm_bringup bringup_teleop.launch.py

Production Setup (rover-deploy service)

Use for: Autonomous operation, field deployment, competitions

• Source code copied during image build
• Pre-built workspace (no manual building needed)
• Runs continuously in background with restart: unless-stopped
• Production-ready and stable

Workflow:

./build.sh
./run.sh rover --prod  # starts the production deploy image in background
# or using docker compose directly:
# docker compose -f docker/docker-compose.yaml up -d rover-deploy

Key Differences

Deployment Files

Important: Production deployment runs continuously in the background and will automatically restart if it crashes, unless manually stopped.

ROS 2 Interface Guide

This page documents the ROS 2 topics, services, and message types for the GORM rover.

NOTE: Please update this documentation if you discover new topics or services, or if existing ones change.

Core Topics

Control & Navigation

Localization & Odometry

Teleoperation

Sensor Topics

ZED Camera (Front)

GNSS (if enabled)

U-blox GNSS

Services

Motor Control

Key Message Types

• geometry_msgs/Twist: Linear and angular velocity
• geometry_msgs/PoseStamped: Position and orientation with a timestamp
• sensor_msgs/Image: Raw image data
• sensor_msgs/CompressedImage: Compressed image for low-bandwidth streaming
• sensor_msgs/PointCloud2: 3D point cloud
• sensor_msgs/Joy: Joystick button and axis states
• nav_msgs/Odometry: Estimated pose and velocity
• std_srvs/srv/Trigger: Standard service for simple actions

Topic Conventions

• Global Topics: Core topics like /cmd_vel and /odom are in the global namespace.
• Namespacing: Sensors are namespaced by their position (e.g., /zed_front).
• Standardization: Follows ROS REP-105 for common topic names.

Contributing Overview

Welcome to the GORM rover project! This guide will help you understand our development practices and contribution process to ensure smooth collaboration.

🚨 Important Rules

NEVER commit directly to main or dev branches. All changes must go through the Pull Request process.

Key Points for Contributors

• System releases use Git tags with format vMAJOR.MINOR.PATCH (e.g., v1.0.0)
• ROS 2 packages version independently using MAJOR.MINOR.PATCH format in their package.xml
• All changes must be made through Pull Requests
• Follow our branching strategy and commit conventions
• Test your changes before submitting PRs
• Update documentation as needed

Version Updates

When making changes that affect versioning:

1. Breaking changes: Increment MAJOR version
2. New features: Increment MINOR version
3. Bug fixes: Increment PATCH version

Always update package.xml when changing ROS 2 package versions.

Getting Help

• Issues: Use GitHub Issues for bugs and feature requests
• Discussions: Use GitHub Discussions for questions and ideas
• Maintainers: Tag @AAU-Space-Robotics maintainers for urgent matters

Remember: Never commit directly to main or dev. Always use Pull Requests for code changes.

Branching Strategy

We follow a structured branching approach to maintain code quality and enable parallel development:

Branch Types

• main - Production-ready code. Protected branch.
• dev - Integration branch for features. Protected branch.
• feature/ - New features and enhancements
• bugfix/ - Bug fixes for existing functionality
• hotfix/ - Critical fixes that need immediate deployment
• release/ - Release preparation and versioning

Branch Naming Convention

Use descriptive names with the appropriate prefix:

feature/add-navigation-controller
feature/improve-motor-control
bugfix/fix-odometry-calculation
bugfix/resolve-docker-build-issue
hotfix/critical-localization-failure
release/v1.2.0

Workflow

1. Create feature branch from dev:

   git checkout dev
   git pull origin dev
   git checkout -b feature/your-feature-name
   

2. Work on your changes and commit regularly

3. Push your branch and create a Pull Request to dev

4. After review and approval, merge to dev

5. For releases, create a release branch from dev and merge to main

Commit Guidelines

We use Conventional Commits to maintain a clear and searchable commit history.

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

• feat: - A new feature
• fix: - A bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting, no logic changes)
• refactor: - Code refactoring without changing functionality
• perf: - Performance improvements
• test: - Adding or updating tests
• chore: - Maintenance tasks, dependency updates
• ci: - CI/CD configuration changes
• build: - Build system or external dependency changes

Scopes (Optional)

Use scopes to indicate the area of change:

• ros2: - ROS 2 packages and nodes
• docker: - Docker configuration and tooling
• control: - Control system components
• perception: - Perception system components
• teleop: - Teleoperation functionality
• nav: - Navigation stack components

Examples

feat(control): add PID controller for motor speed regulation

fix(nav): resolve timeout issue in planner server subscription

docs: update README with new installation instructions

style(ros2): format Python code according to PEP 8

refactor(docker): simplify compose service configuration

chore: update dependencies to latest stable versions

Pull Request Process

Before Creating a PR

1. Ensure your branch is up to date:

   git checkout dev
   git pull origin dev
   git checkout your-branch
   git rebase dev  # or merge dev into your branch
   

2. Test your changes:

   # For ROS 2 packages
   colcon build --packages-select <package_name>
   colcon test --packages-select <package_name>
   

PR Requirements

• Link the related issue: Use Fixes #<issue-number> or Closes #<issue-number>
• Clear title: Use conventional commit format for PR title
• Detailed description: Explain what, why, and how
• Test coverage: Include test results or explain why tests aren't needed
• Breaking changes: Clearly document any breaking changes

PR Template

## Description
Brief description of changes made.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Related Issues
Fixes #<issue-number>

## Testing
- [ ] I have run the existing tests
- [ ] I have added tests for my changes
- [ ] All tests pass locally

## Checklist
- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have updated documentation as needed
- [ ] My changes generate no new warnings
- [ ] I have tested this change in the appropriate environment (Docker/hardware)

## Additional Notes
Any additional information, deployment notes, or concerns.

Review Process

1. Automated Checks: All PRs must pass automated linting and build checks
2. Code Review: At least one maintainer review required
3. Testing: Verify changes work in relevant environments
4. Documentation: Ensure documentation is updated if needed

Code Style Guidelines

Python (ROS 2 Packages)

• Follow PEP 8 style guide
• Use type hints where appropriate
• Maximum line length: 120 characters
• Use docstrings for classes and functions
• Import order: standard library, third-party, local imports

Example

#!/usr/bin/env python3
from typing import Optional

import rclpy
from rclpy.node import Node

class MyNode(Node):
    """Brief description of the node's purpose."""
    
    def __init__(self) -> None:
        super().__init__('my_node')
        self.get_logger().info("Node initialized")

C++

• Follow Google C++ Style Guide
• Use camelCase for variables and functions
• Use PascalCase for classes and structs
• Maximum line length: 100 characters
• Use meaningful variable names

Example

#include <rclcpp/rclcpp.hpp>

class MyNode : public rclcpp::Node
{
public:
  MyNode() : Node("my_node")
  {
    RCLCPP_INFO(this->get_logger(), "Node initialized");
  }

private:
  void processData();
};

Documentation

• Update README.md for significant changes
• Add docstrings/comments for complex logic
• Update package.xml descriptions when needed
• Include examples in documentation

Installation Guide

Here is a step-by-step guide to install the ROS2 Navigation Stack on the Rover. This is mainly in the context of reinstalling the software on the rover itself after a fresh OS installation, and is not necessary for development on your own machine.

Hardware Requirements

• Computer: A Nvidia Jetson Orin with Jetpack 6.1.
• Sensors: 2x Zed 2i Cameras,

Prerequisites

1. Docker
2. Docker Compose
3. Nvidia Container Toolkit
4. Resolve Joy Driver Issues: If you encounter issues with the joystick driver, you can resolve them by opening a terminal and running the following commands: see Joy Driver Issues.

   sudo git clone https://github.com/paroj/xpad.git /usr/src/xpad-0.4
   sudo dkms install -m xpad -v 0.4
   

Installation Steps

1. Connect to the Rover: SSH into the rover's computer using the following command:

   ssh gorm@192.168.50.100 # or ssh gorm@<ROVER_IP_ADDRESS>
   

   The default password is gorm.

2. Clone the Repository: Clone the GORM Rover Software repository to the rover's computer.

    git clone https://github.com/aaU-Space-Robotics/rover-software/
    cd rover-software
   

3. Build & Run the Docker Images: Navigate to the docker directory and start the main rover service in development mode (this will build images and mount the source code).

   cd docker
   ./run.sh rover --prod