Skip to content

Commit 4e6238a

Browse files
xbattlaxxbattlax
committed
Add Raspberry Pi runtime install scaffold
1 parent 83e222b commit 4e6238a

4 files changed

Lines changed: 493 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,21 @@ Visit [main project repo](https://github.com/makerspet/oomwoo).
99

1010
![oomwoo Open source vacuum cleaner placeholder illustration](https://github.com/makerspet/oomwoo/raw/main/assets/vacuum-no-dock-front.webp)
1111

12+
## Raspberry Pi runtime
13+
14+
The current Docker image is a desktop development environment. For onboard robot
15+
work, see the lighter Raspberry Pi runtime scaffold:
16+
17+
- [Pi 4/5 4GB runtime plan](docs/pi4_4gb_runtime_plan.md)
18+
- [Jazzy runtime install script](ubuntu/install_oomwoo_runtime_jazzy.sh)
19+
- [simulated MCU serial I/O](ubuntu/tools/oomwoo_sim_mcu_serial.py)
20+
1221
## Release history
1322

23+
### 7/8/2026
24+
- added a first Raspberry Pi 4/5 4GB runtime install plan
25+
- added simulated CPU-MCU serial I/O placeholder
26+
1427
### 7/1/2026
1528
- added oomwoo-one ROS2 robot description package (simulation only)
1629

‎docs/pi4_4gb_runtime_plan.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Raspberry Pi 4/5 4GB Runtime Plan
2+
3+
This document sketches the first runtime path for running OOMWOO onboard on a
4+
Raspberry Pi 4/5 or CM4/CM5-class module with 4 GB RAM, then measuring how far
5+
the stack can be reduced toward a 2 GB target.
6+
7+
The desktop Docker image remains useful for development and simulation. This
8+
runtime profile is for the robot computer: ROS2, SLAM, Nav2, LiDAR, high-level
9+
behavior, and a serial link to an MCU that owns motors, sensors, battery/charging
10+
supervision, watchdogs, and safety reactions.
11+
12+
## Goals
13+
14+
- Keep SLAM and navigation onboard for the consumer vacuum profile.
15+
- Start with a Pi 4/5 or CM4/CM5 4 GB runtime baseline.
16+
- Avoid Gazebo, desktop GUI tools, and development-only packages on the robot.
17+
- Add a simulated CPU-MCU serial interface until the real I/O board is ready.
18+
- Measure RSS/PSS/CPU before attempting 2 GB optimization.
19+
- Try ROS2 composition and launch/process layout before adding new language
20+
dependencies.
21+
- Keep Rust/rclrs as an optional later experiment for selected memory-heavy or
22+
latency-sensitive nodes.
23+
24+
## Non-Goals For This First Scaffold
25+
26+
- It does not replace the desktop Docker development image.
27+
- It does not provide a final production image.
28+
- It does not choose the final MCU firmware protocol.
29+
- It does not attempt Kilted, Lyrical, or Rolling yet.
30+
- It does not provide a costed hardware BOM; that belongs with the PCB design.
31+
32+
## Runtime Package Direction
33+
34+
Install ROS2 Jazzy from Debian packages, but prefer `ros-jazzy-ros-base` plus the
35+
robot packages that are actually needed:
36+
37+
- Nav2 and Nav2 bringup
38+
- slam_toolbox
39+
- robot_state_publisher and xacro
40+
- robot_localization
41+
- tf2 tools used by launch/runtime
42+
- ros2_control and controllers when hardware interfaces need them
43+
- Fast DDS RMW, matching the current development image direction
44+
- Python serial tooling for the simulated MCU link
45+
46+
Avoid in the first runtime profile:
47+
48+
- `ros-jazzy-desktop`
49+
- Gazebo / ros_gz packages
50+
- GUI joint-state tools
51+
- simulation worlds
52+
- unrelated robot model packages
53+
- telemetry or web UI pieces until a runtime measurement requires them
54+
55+
## Simulated CPU-MCU Serial Link
56+
57+
Until the OOMWOO I/O board firmware exists, run:
58+
59+
```bash
60+
python3 ubuntu/tools/oomwoo_sim_mcu_serial.py --link /tmp/oomwoo-mcu-serial
61+
```
62+
63+
The tool creates a pseudo-terminal symlink such as:
64+
65+
```text
66+
/tmp/oomwoo-mcu-serial
67+
```
68+
69+
ROS2 bridge code can open that path as if it were the MCU serial device. The
70+
simulator emits newline-delimited JSON heartbeat/sensor frames and accepts simple
71+
command lines, replying with acknowledgements.
72+
73+
This keeps the CPU-MCU contract testable while the real STM32G070 firmware and
74+
custom serial protocol are still being designed.
75+
76+
## First Install Script
77+
78+
The first scaffold is:
79+
80+
```bash
81+
ubuntu/install_oomwoo_runtime_jazzy.sh
82+
```
83+
84+
It is intentionally conservative:
85+
86+
- installs ROS2 Jazzy runtime packages
87+
- creates `~/oomwoo_runtime_ws`
88+
- clones a minimal set of OOMWOO/Kaia.ai runtime repositories
89+
- optionally builds the workspace
90+
- installs the simulated MCU serial tool to `~/.local/bin`
91+
- writes a runtime environment snippet to `~/.bashrc`
92+
93+
Run:
94+
95+
```bash
96+
bash ubuntu/install_oomwoo_runtime_jazzy.sh
97+
```
98+
99+
Use `--skip-build` when iterating on the script or testing package selection.
100+
101+
## Measurement Plan
102+
103+
After the runtime install works on a 4 GB board:
104+
105+
1. Boot cleanly and record baseline memory after login.
106+
2. Source ROS2 and the runtime workspace.
107+
3. Start the simulated MCU serial tool.
108+
4. Launch the minimal OOMWOO runtime graph.
109+
5. Record RSS/PSS/CPU for idle.
110+
6. Run SLAM with 5 Hz LiDAR input and no scan dropping.
111+
7. Run navigation on a known map.
112+
8. Repeat after ROS2 composition/process-layout changes.
113+
9. Only then decide whether a C++ or Rust/rclrs port is justified.
114+
115+
The related benchmark scaffold lives in:
116+
117+
```text
118+
makerspet/oomwoo/contributions/compute-benchmark
119+
```
120+
121+
## Path Toward 2 GB
122+
123+
The 2 GB target should be treated as an optimization target, not an assumption.
124+
125+
Suggested order:
126+
127+
1. Remove development/simulation packages from the runtime image.
128+
2. Measure the Python/C++ baseline.
129+
3. Try ROS2 composition where supported.
130+
4. Reduce launch/process count.
131+
5. Remove unused web/telemetry/UI pieces from the onboard profile.
132+
6. Consider C++ ports for memory-heavy custom nodes.
133+
7. Consider Rust/rclrs ports only after the Jazzy setup is reproducible.
134+
135+
## Future Branches
136+
137+
The maintainer mentioned interest in Kilted, Lyrical, and Rolling branches. A
138+
good later contribution is to parameterize this script or create branch-specific
139+
variants once the Jazzy runtime profile is validated.

‎ubuntu/install_oomwoo_runtime_jazzy.sh‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
WORKSPACE="${WORKSPACE:-$HOME/oomwoo_runtime_ws}"
5+
SKIP_BUILD=0
6+
INSTALL_SIM_SERIAL=1
7+
8+
usage() {
9+
cat <<'EOF'
10+
Usage:
11+
install_oomwoo_runtime_jazzy.sh [options]
12+
13+
Options:
14+
--workspace PATH Runtime workspace. Default: ~/oomwoo_runtime_ws
15+
--skip-build Clone/install packages but skip colcon build.
16+
--no-sim-serial Do not install the simulated MCU serial helper.
17+
--help Show this help.
18+
19+
This script is a first Raspberry Pi 4/5 4GB runtime scaffold for OOMWOO. It
20+
installs ROS2 Jazzy runtime packages, avoids desktop/Gazebo tooling, prepares a
21+
minimal workspace, and installs a simulated CPU-MCU serial helper.
22+
EOF
23+
}
24+
25+
while [[ $# -gt 0 ]]; do
26+
case "$1" in
27+
--workspace)
28+
WORKSPACE="${2:-}"
29+
shift 2
30+
;;
31+
--skip-build)
32+
SKIP_BUILD=1
33+
shift
34+
;;
35+
--no-sim-serial)
36+
INSTALL_SIM_SERIAL=0
37+
shift
38+
;;
39+
--help|-h)
40+
usage
41+
exit 0
42+
;;
43+
*)
44+
echo "Unknown argument: $1" >&2
45+
usage >&2
46+
exit 2
47+
;;
48+
esac
49+
done
50+
51+
if [[ -z "$WORKSPACE" ]]; then
52+
echo "--workspace must not be empty" >&2
53+
exit 2
54+
fi
55+
56+
require_ubuntu_2404() {
57+
if [[ ! -r /etc/os-release ]]; then
58+
echo "Cannot detect OS. This script currently targets Ubuntu 24.04." >&2
59+
exit 1
60+
fi
61+
. /etc/os-release
62+
if [[ "${ID:-}" != "ubuntu" || "${VERSION_ID:-}" != "24.04" ]]; then
63+
echo "Warning: expected Ubuntu 24.04 for ROS2 Jazzy, got ${PRETTY_NAME:-unknown}." >&2
64+
fi
65+
}
66+
67+
install_ros_apt_source() {
68+
sudo apt update
69+
sudo apt install -y software-properties-common curl gnupg lsb-release
70+
sudo add-apt-repository universe -y
71+
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
72+
-o /usr/share/keyrings/ros-archive-keyring.gpg
73+
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo "$UBUNTU_CODENAME") main" \
74+
| sudo tee /etc/apt/sources.list.d/ros2.list >/dev/null
75+
}
76+
77+
install_runtime_packages() {
78+
sudo apt update
79+
sudo apt install -y \
80+
build-essential \
81+
git \
82+
python3-colcon-common-extensions \
83+
python3-pip \
84+
python3-rosdep \
85+
python3-serial \
86+
python3-vcstool \
87+
ros-dev-tools \
88+
ros-jazzy-nav2-bringup \
89+
ros-jazzy-navigation2 \
90+
ros-jazzy-rmw-fastrtps-cpp \
91+
ros-jazzy-robot-localization \
92+
ros-jazzy-robot-state-publisher \
93+
ros-jazzy-ros-base \
94+
ros-jazzy-ros2-control \
95+
ros-jazzy-ros2-controllers \
96+
ros-jazzy-slam-toolbox \
97+
ros-jazzy-tf2-ros \
98+
ros-jazzy-xacro
99+
}
100+
101+
init_rosdep_if_needed() {
102+
if [[ ! -f /etc/ros/rosdep/sources.list.d/20-default.list ]]; then
103+
sudo rosdep init
104+
fi
105+
rosdep update --rosdistro jazzy
106+
}
107+
108+
clone_or_update() {
109+
local branch="$1"
110+
local url="$2"
111+
local path="$3"
112+
113+
if [[ -d "$path/.git" ]]; then
114+
git -C "$path" fetch --depth 1 origin "$branch"
115+
git -C "$path" checkout "$branch"
116+
git -C "$path" reset --hard "origin/$branch"
117+
else
118+
git clone -b "$branch" --depth 1 "$url" "$path"
119+
fi
120+
}
121+
122+
prepare_workspace() {
123+
mkdir -p "$WORKSPACE/src"
124+
125+
clone_or_update jazzy https://github.com/kaiaai/kaiaai_msgs "$WORKSPACE/src/kaiaai_msgs"
126+
clone_or_update jazzy https://github.com/kaiaai/kaiaai "$WORKSPACE/src/kaiaai"
127+
clone_or_update jazzy https://github.com/kaiaai/kaiaai_bringup "$WORKSPACE/src/kaiaai_bringup"
128+
clone_or_update jazzy https://github.com/makerspet/makerspet_vac "$WORKSPACE/src/makerspet_vac"
129+
clone_or_update jazzy https://github.com/makerspet/makerspet "$WORKSPACE/src/makerspet"
130+
clone_or_update main https://github.com/makerspet/oomwoo-one "$WORKSPACE/src/oomwoo_one"
131+
clone_or_update jazzy https://github.com/remakeai/vacuum_ros2_bridge "$WORKSPACE/src/vacuum_ros2_bridge"
132+
clone_or_update jazzy https://github.com/kaiaai/nav2_wfe "$WORKSPACE/src/nav2_wfe"
133+
clone_or_update jazzy https://github.com/kaiaai/auto_mapper "$WORKSPACE/src/auto_mapper"
134+
clone_or_update jazzy https://github.com/kaiaai/m-explore-ros2 "$WORKSPACE/src/m-explore-ros2"
135+
}
136+
137+
build_workspace() {
138+
. /opt/ros/jazzy/setup.bash
139+
cd "$WORKSPACE"
140+
rosdep install --from-paths src --ignore-src -y
141+
colcon build --symlink-install
142+
rm -rf log/
143+
}
144+
145+
install_sim_serial() {
146+
if [[ "$INSTALL_SIM_SERIAL" -eq 0 ]]; then
147+
return
148+
fi
149+
150+
local script_dir
151+
script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
152+
mkdir -p "$HOME/.local/bin"
153+
install -m 0755 "$script_dir/tools/oomwoo_sim_mcu_serial.py" \
154+
"$HOME/.local/bin/oomwoo-sim-mcu-serial"
155+
}
156+
157+
update_bashrc() {
158+
local marker="# OOMWOO runtime Jazzy"
159+
if grep -q "$marker" "$HOME/.bashrc" 2>/dev/null; then
160+
return
161+
fi
162+
163+
cat >> "$HOME/.bashrc" <<EOF
164+
165+
$marker
166+
source /opt/ros/jazzy/setup.bash
167+
if [ -f "$WORKSPACE/install/setup.bash" ]; then
168+
source "$WORKSPACE/install/setup.bash"
169+
fi
170+
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
171+
export OOMWOO_MCU_SERIAL=/tmp/oomwoo-mcu-serial
172+
export PATH="\$HOME/.local/bin:\$PATH"
173+
EOF
174+
}
175+
176+
main() {
177+
require_ubuntu_2404
178+
install_ros_apt_source
179+
install_runtime_packages
180+
init_rosdep_if_needed
181+
prepare_workspace
182+
install_sim_serial
183+
184+
if [[ "$SKIP_BUILD" -eq 0 ]]; then
185+
build_workspace
186+
fi
187+
188+
update_bashrc
189+
190+
cat <<EOF
191+
192+
OOMWOO Jazzy runtime scaffold installed.
193+
194+
Workspace: $WORKSPACE
195+
Simulated MCU serial:
196+
oomwoo-sim-mcu-serial --link /tmp/oomwoo-mcu-serial
197+
198+
Open a new shell or run:
199+
source ~/.bashrc
200+
EOF
201+
}
202+
203+
main "$@"

0 commit comments

Comments
 (0)