ROS 2 Humble repository for Lucy (Sentience Robotics): runtime bringup, ros2_control hardware integration, and camera tooling. This is a multi-package repo; each subdirectory under src/ in your colcon workspace is one ament package.
| Package | One-line role |
|---|---|
| lucy_bringup | Jetson system launch: micro-ROS agents, web_ros_api (rosbridge + lucy_config_pipeline), RealSense, camera_ros, delayed lucy_ros2_control bringup; lucy_*_development composes the web stack with thais_urdf RViz/Gazebo. |
| lucy_ros2_control | Hardware ros2_control plugin (LucySystemHardware), controller YAML, control.launch.py for the real robot stack (no RViz/rosbridge in that launch). |
| lucy_config_generator | Config pipeline: reads thais_urdf hardware YAML and emits RP2040 firmware C, ros2_control xacro, and controllers.yaml (see package README). |
| lucy_config_pipeline | Config store + ConfigurePipeline action: validate YAML, generate artifacts, build/flash RP2040 firmware via picotool README. |
| camera_ros | GStreamer-based MJPEG → sensor_msgs/CompressedImage; client-aware activation. |
Package names match directories (<name> in each package.xml).
- Robot model, RViz, and Gazebo live in the sibling repo thais_urdf (package name
thais_urdf).lucy_bringupowns rosbridge + hardware config (web_ros_api.launch.py) andlucy.launch.py(composition viareal,rviz,gazebo).lucy_ros2_controlexpects URDF/xacro and meshes fromthais_urdfwhen using default paths. - Web control panel and teleop semantics are not in this repo; they consume the same topics/controllers documented in lucy_ws docs.
- OS: Ubuntu 22.04
- ROS: ROS 2 Humble.
- Per-package extras: Jetson-typical USB video and audio stacks for bringup; RealSense SDK stack for
realsense2_camera; serial devices for micro-ROS. See each package README andlucy_bringup/REALSENSE.md.
The lucy_config_pipeline flash phase runs sudo picotool. Copy-paste sudoers setup (Ubuntu 22.04) lives in lucy_config_pipeline/README.md — Passwordless sudo for picotool (same repository; no ../ path).
Treat this repository as src/lucy_ros_packages (clone the contents into that folder) or clone in place so that packages are direct children of your workspace src/:
lucy_ws/
└── src/
├── lucy_ros_packages/ # this repo: lucy_bringup, lucy_ros2_control, lucy_config_generator, lucy_config_pipeline, camera_ros
└── thais_urdf/ # robot description + sim launches (separate repo)
Example build:
source /opt/ros/humble/setup.bash
cd lucy_ws
colcon build --symlink-install \
--packages-select lucy_bringup lucy_ros2_control lucy_config_generator lucy_config_pipeline camera_ros
source install/setup.bashTo include simulation/description from the other repo:
colcon build --symlink-install \
--packages-select lucy_bringup lucy_ros2_control lucy_config_generator lucy_config_pipeline camera_ros thais_urdf| Goal | Entry point |
|---|---|
Full Jetson stack (agents, rosbridge, cameras, ros2_control) |
ros2 launch lucy_bringup lucy.launch.py |
Control stack only (defaults assume thais_urdf layout in workspace) |
ros2 launch lucy_ros2_control control.launch.py |
| USB MJPEG camera node | ros2 launch camera_ros camera.launch.py |
Tmux helpers ship with lucy_bringup (system_scripts/); see lucy_bringup/README.md.
Dependencies: python3-pytest-cov (e.g. sudo apt install python3-pytest-cov on Ubuntu).
From your workspace root (e.g. lucy_ws), with packages under src/lucy_ros_packages/:
source /opt/ros/humble/setup.bash
colcon build --symlink-install \
--packages-select camera_ros lucy_bringup lucy_ros2_control lucy_config_generator \
--cmake-args -DBUILD_TESTING=ON
source install/setup.bash
colcon test --packages-select camera_ros lucy_bringup lucy_ros2_control lucy_config_generator --event-handlers console_direct+
colcon test-result --verboseCoverage (same source install/setup.bash as above; open build/coverage_html/.../index.html after --cov-report=html):
mkdir -p build/coverage_reports build/coverage_html
python3 -m pytest src/lucy_ros_packages/camera_ros/test/ \
--cov=src/lucy_ros_packages/camera_ros/scripts \
--cov-report=term-missing \
--cov-report=xml:build/coverage_reports/camera_ros.xml \
--cov-report=html:build/coverage_html/camera_ros
python3 -m pytest src/lucy_ros_packages/lucy_bringup/test/ \
--cov=src/lucy_ros_packages/lucy_bringup/launch \
--cov-report=term-missing \
--cov-report=xml:build/coverage_reports/lucy_bringup.xml \
--cov-report=html:build/coverage_html/lucy_bringup
Meaningful line coverage is mostly from camera_ros/scripts; bringup tests only byte-compile launch files.
GitHub Actions (.github/workflows/ci.yml) runs rosdep, colcon build, colcon test, then pytest-cov over Python tests, producing Cobertura XML under ws/build/coverage_reports/ for camera_ros, lucy_bringup, and lucy_config_generator. Reports are uploaded to Codecov when CODECOV_TOKEN is set on the repo, and HTML/XML are attached as workflow artifacts (coverage-lucy_ros_packages). See docs/DEVELOPER.md §5.
| Doc | Audience |
|---|---|
| This file | Anyone cloning this repository |
| docs/DEVELOPER.md | Contributors — build, CI, package internals, extension checklist |
| lucy_bringup/README.md | Operators and integrators (devices, tmux, launch args) |
| lucy_ros2_control/README.md | Control stack quick start |
| docs/ROS2_CONTROL.md | ros2_control — general concepts + Lucy (LucySystemHardware, topics, launches) |
| lucy_config_generator/README.md | Hardware YAML → firmware C, ros2_control xacro, controllers |
| lucy_config_pipeline/README.md | Config services + pipeline action (build/flash); passwordless sudo for picotool |
| camera_ros/README.md | Camera topics, parameters, troubleshooting |
If these repos live under lucy_ws, see lucy_ws/docs/developer_lucy_packages.md (index into each repo’s docs/DEVELOPER.md) and lucy_ws/docs/simulation_and_visualization.md (full-stack pipeline).
Packages in this repository are licensed under GPL-3.0 unless a subdirectory states otherwise. See each package and the repository LICENSE file if present.
Sentience Robotics Team — contact@sentience-robotics.fr (see package.xml files).