AAU Rover Software Overview

Welcome to the AAU 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.

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

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

Docker
Docker Compose
Nvidia Container Toolkit
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

Connect to the Rover: SSH into the rover's computer using the following command:
```
ssh gorm@192.168.0.100 # or ssh gorm@<ROVER_IP_ADDRESS>
```
The default password is gorm.

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

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

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 --dev
```
💡 Production Deployment: For production deployment with auto-restart capabilities, see the Deployment Guide which provides a pre-built image that doesn't require manual building inside the container.

Launch the Rover Software: After the Docker images are built and running, you can attach to the running container and launch the rover software.

# Attach to the running Docker container
docker exec -it rover-software bash

# Build the ROS2 packages inside the container
colcon build
source install/setup.bash

# Launch the rover software
ros2 launch gorm_bringup bringup_teleop.launch.py

Launching the GORM Rover

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

Quick Start with Docker (Development Mode)

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
```
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 bash
```
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
```
Launch the Rover Software: Finally, launch the rover software using the provided launch file.
```
ros2 launch gorm_bringup bringup_teleop.launch.py
```
(Optional) Developing and changing the code: You can make changes to the code in the src directory on the host machine (outside the container on the Jetson Orin). The changes will be reflected inside the container because the source code is mounted as a volume. After making changes, you can rebuild the packages inside the container:
```
colcon build
source install/setup.bash
ros2 launch gorm_bringup bringup_teleop.launch.py
```

💡 Production Alternative: For production deployment with automatic restart and pre-built packages, start the deploy image (or use docker-compose).

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
```

Key Topics

/cmd_vel - Velocity commands (geometry_msgs/Twist)
/odom - Odometry feedback (nav_msgs/Odometry)
/joy - Joystick input

Here goes the code for the example.

Deployment Overview

The GORM rover software provides two deployment modes: development and production.

Development Mode

Source code mounted as volumes for live editing
Manual building inside container
Interactive development and testing

Production Mode

ROS2 Source code copied and pre-built during image creation
Runs continuously in the background with automatic restarts

Deployment Files

File	Purpose
`run.sh`	The main script for starting services in different modes (e.g., `rover --dev`, `rover --prod`).
`docker-compose.yaml`	Defines all services, e.g. `rover`, `rover-deploy`, `cameras`, etc.
`Dockerfile`	Defines the multi-stage build environment for both development and production.
`build.sh`	Script to build the production Docker image.
`stop.sh`	A simple script to stop all running services defined in `docker-compose.yaml`.
`attach.sh`	Helper script to quickly attach to the main `rover` container.
`entrypoint.sh`	The entrypoint for the development container.
`entrypoint.deploy.sh`	The entrypoint for the production container, handling startup logic.

Quick Start

# Build production image
cd docker/
./build.sh

# Deploy (runs in background continuously)
./run.sh rover --prod
# or using docker compose directly:
# docker compose -f docker/docker-compose.yaml up -d rover-deploy

The production deployment will run continuously in the background unless manually stopped.

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