About Micipsa
Micipsa: What Sets It Apart#
This document highlights what makes Micipsa stand out from typical DIY and hobbyist autonomous mobile robots.
Each subject mentioned here has its own dedicated documentation that goes deeper into the details.
Core Principle#
Whether it's software, hardware, or mechanical parts, modularity is Micipsa's core design principle. Every part of the robot, physical or virtual, is meant to be interchangeable with little to no reconfiguration.
This principle carries through the entire project as a set of consistent standards, launch and configuration are standardized across the whole project, documentation follows the same standardized structure for every ROS 2 package, and installer scripts are standardized as well.
Manufacturing and Assembly#
Micipsa was designed to be assembled, disassembled, and wired quickly (under 10 minutes), with any component swappable in a few seconds and, for most parts, no fasteners required at all.
This is made possible by a standard mounting system based on the dovetail joint, known for its strength and resistance to being pulled apart.
This also makes transporting Micipsa to test sites easier and safer, expensive or critical components can be removed and carried separately, with the rest packed into a suitcase, for example when travelling by plane.
Project Organization#
The project is structured for easy navigation, with the Micipsa stack, third-party libraries, common nodes, infrastructure, and documentation each kept in dedicated folders.
Software#
Modes#
The Micipsa ROS 2 stack can run in either simulation or deploy mode by changing just two values, deploy_mode and use_sim_time, in the bringup config file, making it fast to switch between the two.
Code Quality#
Micipsa software stack is divided into distinct layers, each responsible for a single concern and exposing well-defined inputs and outputs. This clean separation keeps every layer interchangeable, as long as the interfaces are respected.
ROS 2 nodes are kept separate from control logic, so algorithms can be tested by feeding known inputs and checking outputs directly, without needing to start ROS 2 or a full robot/simulation environment. This also means the logic can potentially be reused elsewhere or tested as a standalone library.
The codebase follows established practices such as DRY, KISS, YAGNI, and separation of concerns, with an emphasis on meaningful names, small and focused functions, minimal comments and consistent formatting. Object-oriented design is used to encapsulate state and behavior into well-defined components, keeping the code easy to understand, modify, test, and extend.
Launch Process#
Launch files follow a top-down structure. The top-level bringup.launch.py file retrieves the bringup config and passes parameters down to dedicated sub-launch files.
For example: drivers.launch.py calls camera.launch, which in turn calls the launch file for the selected driver:
Swapping hardware is therefore as simple as changing which driver launch file camera.launch points to.
Also adding a sublaunch file call in camera.launch to launch a new driver.
Each ROS 2 layer or package can also be launched independently. Running bringup.launch.py, localization.launch.py, or rl_ekf_launch.py all work on their own, so you can test the full pipeline, a single layer, or a specific feature in isolation.
Configuration Process#
Parameters are never duplicated, each one is defined and given a default value in exactly one place (file that consumes it). If no value is passed to the launch file, that default is used automatically.
A single bringup config file references all the layer-specific sub-configs and controls stack-level settings such as deploy_mode, localization_mode, and whether the perception and behavior layers are enabled.
System#
Micipsa's system architecture also follows clear separation of responsibilities.
The ROS 2 software stack runs on the high-level compute unit (the Jetson), while Micipsa's firmware runs on a low-level microcontroller (the Yahboom board). The two communicate over a serial link.
On power-on, the Jetson automatically starts the Micipsa systemd services, which in turn launch the ROS 2 stack inside Docker containers.
A router provides static IP addresses to both the robot and the base station, keeping communication addresses consistent and making it easy to test the robot in a new location by simply connecting the router to the local Wi-Fi.
The base station's only responsibility is to visualize, monitor, and send commands to the robot it never executes any part of the Micipsa software stack itself.
Containrenzation#
The software stack can be built, configured, tested, and deployed through Docker and Docker Compose in both simulation and deploy mode, giving a reproducible environment across machines.
Every image is a multi-stage build on a minimal base image, with pinned versions and instructions ordered to make the best use of layer caching. Each layer of the stack has its own image, and every image follows the same set of stages: base, build, dev, and deploy with the deploy stage kept as small and lightweight as possible, containing only what's needed to run that layer's code.
Docker Compose brings up the full stack across its containers. To ensure each compose file and container receives the correct launch arguments, a dedicated compose launcher script handles startup, the same script is used whether running in simulation or on the robot.
Consistency Across Environments#
Whether run natively or in containers, the Micipsa stack uses the same configuration and behaves the same way in both simulation and deploy mode. Understanding one environment means understanding the other.
Some Docker Compose–specific nuances still need to be learned, but these relate to the tool itself rather than to anything specific to Micipsa.
Provisionning & Deployement#
Micipsa ships with a set of installer scripts, udev rules, network configuration, config files, and more to simplify provisioning a new robot. Each script can be run individually for a specific piece of configuration.
A single robot setup script also exists that clones the repository and runs every installer in sequence, leaving the robot fully operational once it completes. Equivalent scripts are provided for setting up the base station and for tearing down a provisioned system to clean and start fresh.
Testing#
A CI pipeline runs on every merge, executing Micipsa's unit and integration tests to catch regressions before they land.
Documentation#
Micipsa comes with documentation covering every part of the robot: how it's built, how each component works, how to configure it, how to run it, and how to extend it.
The goal throughout is to keep information easy to digest and easy to follow surfacing only what's relevant and anticipating the reader's likely questions, so using the documentation feels as frictionless as possible.