Magni Robot Simulation Documentation

Note

A comprehensive guide to running the Ubiquity Robotics Magni platform in simulation

Overview

The Ubiquity Robotics Magni is a robust differential drive mobile robot platform engineered for industrial and research applications. This guide provides step-by-step instructions for setting up and running the Magni robot in simulation using ROS and Gazebo.

Robot Specifications

Physical Characteristics

Physical Specifications
Component	Specification
Drive System	Differential drive with 2 wheels
Payload Capacity	Up to 100 kg
Chassis	Aerospace-grade aluminum construction
Motors	2 × 200W hub motors
Power Supply	12V and 5V outputs (10A each)
Battery	Up to 35 Amp hours of 24V batteries
Operating Time	Up to 8 hours of normal operation

Computing Platform

Computing Specifications
Component	Specification
Onboard Computer	Raspberry Pi 4
Operating System	Ubuntu with ROS
Connectivity	WiFi, Ethernet, 4x USB ports
Sensors	Sonar array for obstacle avoidance

Simulation Environment Setup

Prerequisites

System Requirements

Operating System: Ubuntu 24.04 LTS (recommended)
ROS Version: Jazzy (for Ubuntu 24.04)
Simulator: Gz sim harmonic (https://gazebosim.org/docs/harmonic/install/)
Graphics: NVIDIA GPU recommended for optimal performance
Memory: Minimum 8GB RAM, 16GB recommended

Tip

For best performance, ensure your system meets the recommended specifications

Installation Steps

Step 1: Install ROS2 and Dependencies

Follow the official ROS2 installation guide for your Ubuntu version. Ensure you have the necessary dependencies installed:

https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html

Step 2: Install Magni Robot Packages

Download the Magni robot package from:

https://drive.google.com/file/d/1SRjRAT85jVueIivhKSYl1sVWF8c6LNqB/view?usp=drive_link

Install the package:

sudo dpkg -i path/to/magni-description_1.0.1_all.deb

Fix any dependency issues:
```
sudo apt-get install -f
```

Step 3: Verify Installation

source /opt/ros/jazzy/setup.bash
ros2 pkg list | grep magni_description
source /opt/ros/jazzy/share/magni_description/local_setup.bash

Simulation Configuration

URDF Model Structure

The Magni robot simulation uses a Unified Robot Description Format (URDF) model that defines the following components:

Base Components

Base Link:: Main chassis with inertial properties
Wheel Links:: Left and right drive wheels with friction parameters
Caster Wheel:: Front support wheel for stability
Sensor Mounts:: Attachment points for sensors

Joint Definitions

Wheel Joints:: Continuous rotation joints for differential drive
Caster Joint:: Fixed joint for support wheel
Sensor Joints:: Fixed joints for sensor mounting

Gazebo Plugin Configuration

The simulation utilizes several Gazebo plugins for realistic robot behavior.

Differential Drive Plugin

Available Sensor Plugins

IMU Sensor:: Provides orientation feedback
Sonar Sensors:: Enable obstacle detection
Camera Sensor:: Optional visual input (configurable)
Lidar Sensor:: Optional laser scanning capability (configurable)

Running the Simulation

Basic Simulation Launch

Step 1: Start Gazebo with Magni Model

# Launch empty world with Magni robot
ros2 launch magni_description description.launch.py

Step 2: Verify Robot Spawning

After launching, verify the following:

Gazebo simulator window opens with the Magni robot visible
Robot model loads with correct visual and collision properties
All joints and sensors initialize properly

Step 3: Check ROS Topics

# List active topics
rostopic list

Expected topics include:

/cmd_vel              # Velocity commands
/odom                 # Odometry feedback
/joint_states         # Joint position/velocity states
/tf                   # Transform tree
/scan                 # Laser scan data (if lidar enabled)
/sonar_*              # Sonar sensor readings

Teleoperation Testing

Step 1: Launch Teleop Node

# Keyboard teleoperation
rosrun teleop_twist_keyboard teleop_twist_keyboard.py

Step 2: Robot Control Commands

Keyboard Control Reference
Key	Action
i	Move forward
,	Move backward
j	Turn left
l	Turn right
k	Stop
u	Move forward with left turn
o	Move forward with right turn
m	Move backward with left turn
.	Move backward with right turn

Advanced Simulation Scenarios

Multi-Robot Simulation

# Launch multiple Magni robots
roslaunch magni_gazebo multi_magni.launch robot_count:=3

Custom World Integration

# Launch with custom Gazebo world
roslaunch magni_gazebo magni_world.launch world_name:=custom_warehouse

Troubleshooting

Common Issues and Solutions

Issue 1: Robot Falls Through Ground

Problem:: Robot model falls through the ground plane
Cause:: Missing collision properties in URDF model
Solution:: Verify collision tags are properly defined in robot description files

Issue 2: Wheels Not Moving

Problem:: Robot wheels do not respond to velocity commands
Cause:: Joint controller configuration errors
Solution:: Check joint names in differential drive plugin match URDF joint definitions

Issue 3: Sensors Not Publishing Data

Problem:: Sensor topics show no data output
Cause:: Plugin configuration errors or missing parameters
Solution:: Verify sensor plugin parameters and confirm topic names are correct

Performance Optimization

Graphics Settings

For improved simulation performance:

Reduce Gazebo graphics quality settings
Disable shadows and reflections when not required
Lower physics update rate for non-real-time applications

System Resources

Resource management recommendations:

Monitor CPU and memory usage during simulation
Close unnecessary applications to free system resources
Consider headless mode for automated testing scenarios

Development Guidelines

Custom Sensor Integration

When adding new sensors to the Magni simulation:

Update URDF: Add sensor links and joints to robot description
Configure Plugins: Set appropriate Gazebo sensor plugins with correct parameters
Test Integration: Verify sensor data publication and topic connectivity
Document Changes: Update simulation documentation with new sensor capabilities

Controller Development

For developing custom motion controllers:

Interface Definition: Define clear control inputs and feedback mechanisms
ROS Integration: Create appropriate ROS nodes and topic interfaces
Simulation Testing: Validate controller behavior in Gazebo before hardware deployment
Parameter Tuning: Optimize controller gains specifically for simulation environment

Validation Procedures

Simulation Accuracy

Best practices for validation:

Compare simulated robot behavior against real hardware performance
Validate sensor readings and timing characteristics
Test edge cases and failure mode scenarios

Performance Benchmarking

Measurement guidelines:

Measure simulation real-time factor under various conditions
Profile computational requirements for different scenarios
Document system limitations and performance boundaries

Support and Resources

Official Documentation

Community Support

ROS Discourse Forum
Ubiquity Robotics Community Forums
GitHub Issues for bug reports and feature requests

Additional Resources