This repository represents a submodule of the ShunkoBot project, specifically, this repository must be cloned on the Raspberry and on your pc and properly installed to ensure optimal operation.
Configuration used and tested:
- Ubuntu Server 24.04.2 LTS
- Raspberry Pi 5
- ROS2 Jazzy
- System Architecture Overview
- System Pre-Configuration on the Raspberry Pi
- Install Repository Dependencies
- Export and URDF File Generation
- Guide to use the code
- License
For this project, we use Ubuntu Server on the Raspberry Pi 5 to minimize OS resource usage, combined with SSH for remote access. Before cloning this repository, complete the following pre-configuration steps:
Edit /boot/firmware/config.txt and add:
dtoverlay=uart0,ctsrts
dtoverlay=uart4-pi5Edit /boot/firmware/cmdline.txt and remove:
console=serial0,115200
Install Docker by following the official Docker installation guide.
sudo apt install make
For Raspberry Pi 4 and Pi 5 you can set the kernel in real time mode, for personal use is free:
https://ubuntu.com/real-time
To forward graphical applications over SSH (use with caution due to GPU limitations):
- Edit
/etc/ssh/sshd_configand ensure the following lines are present:X11Forwarding yes X11DisplayOffset 10 X11UseLocalhost yes - Remove the X11 authority file (if needed):
rm -f ~/.Xauthority - Connect to the Raspberry Pi with X11 forwarding enabled:
ssh -Y <username>@<ip-address>
To use the code correctly the first time you must install the various dependencies explained as below. From the raspberry terminal with ssh and on your pc:
make build
and then:
make run
in the container type:
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
Now you can either source the code and launch the code with the launch files or exit the container and use the make code set up.
Within the plugin interface, each SolidWorks part or sub-assembly is associated with a URDF link.
Connections between links are defined through joints, specifying their type (e.g., revolute or prismatic), the orientation of the movement axis, and physical limits (such as allowable rotation range).
Where necessary, optional dynamic properties — such as mass, center of mass, and inertia matrices — can also be added.
After completing the configuration, the model is exported to the target directory.
The plugin generates the .urdf file containing the structural description of the robot, along with mesh files (in .STL or .DAE format) used for 3D visualization.
Additional support files, such as .yaml files, are also created to store auxiliary parameters useful for simulation purposes.
Note
The URDF of the 3D model refers to a previous version of the mobile robot, which does not support modularity. If the modular version is being used, the URDF file must be replaced with one that corresponds to the specific robot configuration. To achieve this, the SolidWorks assembly must be modified by adding the required modules in their correct positions. Using the dedicated plugin, it is then possible to generate the updated URDF file.
The make commands for the respective devices are presented below. Makefiles were used to speed up the launch of ROS nodes, but not all of them were explicitly distinguished between run and exec commands. Simply refer to the makefile to launch the respective terminals or check directly in the readme file in the commands folder of this repository.
Only on Raspberry Pi will the following makefiles be launched:
make run_uart
make exec_startup
The following can be run(exec) on both PC and Raspberry Pi devices:
make run_navigation
make run_slam
For PC, instead:
make exec_joy
make exec_rviz_nav
make exec_rviz_slam
Note
Starting the slam and navigation on the Raspberry inevitably increases the computational load, but on the other hand, it reduces latency. Two YAML navigation files were created for these requirements, one lighter for the Raspberry Pi and one heavier. It is recommended to have a good Wi-Fi connection.
For more details on how to use the code, below is a link to an example video for launching the packages:
If there are any problems with the makefiles, the /commands folder contains the executables and a readme file for launching the commands manually.
If you are interested in learning more, you can find detailed explanations in the READMEs, comment inline and in the full project report!
This project is distributed under a dual-license model:
Open Source License: AGPLv3
The source code is licensed under the GNU Affero General Public License v3.0 (AGPLv3).
You are free to:
- Use the software for personal, educational, or research purposes
- Modify and redistribute the code
- Use it commercially, as long as you comply with the AGPLv3 terms — including making any modifications publicly available
AGPLv3 requires you to release your source code even if the software is used over a network (e.g., SaaS).
If you wish to use this software in a commercial context without being bound by the terms of AGPLv3 (for example:
- incorporating it into a proprietary product,
- offering commercial services without disclosing source code,
- avoiding copyleft obligations),
a paid commercial license is available.
For commercial licensing inquiries, please contact: shunkobotstmv@gmail.com
Using this software without complying with the AGPLv3 or without a valid commercial license is strictly prohibited
and may result in legal action for copyright infringement.
This project includes code adapted from:
https://github.com/Slamtec/sllidar_ros2
https://x-io.co.uk/open-source-imu-and-ahrs-algorithms/
All such files retain their original license and copyright notices.