Architecture
Architecture#
MICIPSA's Docker architecture splits the robot software stack into independent layers, each running as its own container.
Both flows are triggered the same way, bringup_config.yaml is read by compose_launcher.py, which then invokes Docker Compose to bring up the relevant containers.
Tip
Once you have finished reading this documentation, it is recommended that you continue with the Docker Compose, Docker File and Compose Launcher documentation. They provide a detailed explanation of:
- How Docker Compose overlays are structured
- What Docker Compose profiles do
- How Docker files stages are defined
- How the
compose_launcherscript works
Deploy Startup#
Simulation Startup#
Container Isolation#
Every layer in the stack runs as its own container. Keeping subsystems separated means a fault in one layer (a crash, a hang, a restart) stays contained instead of taking down unrelated subsystems. Each container gets its own healthcheck, its own resource footprint, and its own restart lifecycle.
The drivers layer is the clearest example of this principle. It is split into independent containers, one per sensor type, so each hardware component keeps its own isolated lifecycle.
front_camera and base_lidar both use the same micipsa/drivers image, but they run as two separate containers rather than a single "drivers" container handling both. If the camera driver crashes, hangs, or needs a restart, it should not take the lidar down with it, and vice versa.
Misssion Layer#
The behavior layer is the Mission Layer, and as such depends on the entire autonomy stack (navigation service) not because it directly interacts with each layer's internals, but because achieving its mission requires the robot to be in a fully healthy state first. If any lower layer (localization, navigation, perception, etc.) is down, the mission has no reliable ground to execute on, so behavior should not start.
That dependency set isn't fixed, though, it's a function of what the current mission actually requires, not a static architectural rule. This is what sets behavior apart from every other layer, every other layer's dependencies come from a fixed pipeline (e.g. navigation always needs localization), while behavior's dependencies are dictated by the mission logic itself.
Containers#
Deploy#
| Layer | Container | Image | Depends On |
|---|---|---|---|
| L2 | front_camera_driver |
micipsa/drivers |
/ |
| L2 | base_lidar_driver |
micipsa/drivers |
/ |
| L3 | micipsa_description |
micipsa/description |
/ |
| L4 | micipsa_actuation |
micipsa/actuation |
description |
| L5 | micipsa_localization |
micipsa/localization |
actuation |
| L6 | micipsa_slam |
micipsa/slam |
localization, base_lidar |
| L7 | micipsa_navigation |
micipsa/navigation |
localization |
| L8 | micipsa_perception |
micipsa/perception |
front_camera |
| L9 | micipsa_behavior |
micipsa/behavior |
navigation |
Simulation#
| Layer | Container | Image | Depends On |
|---|---|---|---|
| L3 | micipsa_description |
micipsa/description |
/ |
| L4 | micipsa_actuation |
micipsa/actuation |
description gazebo |
| L5 | micipsa_localization |
micipsa/localization |
actuation |
| L6 | micipsa_slam |
micipsa/slam |
localization |
| L7 | micipsa_navigation |
micipsa/navigation |
localization |
| L8 | micipsa_perception |
micipsa/perception |
gazebo |
| L9 | micipsa_behavior |
micipsa/behavior |
navigation |