/robot-bringup

name: robot-bringup
description: >
  Patterns and best practices for bringing up a complete ROS2-based robotics system on a robot's
  onboard computer, including systemd services, launch file composition, ordered startup, and
  production monitoring. Use this skill when configuring a robot to start ROS2 nodes on boot,
  writing systemd unit files for ROS2 launch, composing layered launch files for full robot stacks,
  setting up watchdog monitoring, configuring udev rules for deterministic device naming, or
  debugging boot-time race conditions. Trigger whenever the user mentions robot bringup, robot
  startup, systemd for ROS2, ROS2 on boot, launch file composition, robot boot sequence, udev
  rules for cameras or serial ports, watchdog for robot systems, automatic restart for ROS2 nodes,
  network configuration for multi-machine ROS2, log rotation for robots, graceful shutdown of
  robot stacks, or SSH-based remote debugging of robots. Also trigger for environment setup in
  systemd (sourcing workspaces), ordered startup with health checks, deterministic device naming,
  or any discussion of running ROS2 systems as long-running production services. Covers systemd
  on Ubuntu 22.04/24.04 with ROS2 Humble, Iron, and Jazzy.

Robot Bringup Skill

When to Use This Skill

• Configuring a robot to automatically start its full ROS2 stack on boot via systemd
• Writing systemd unit files that correctly source ROS2 workspaces and set DDS environment
• Composing layered launch files (hardware, drivers, perception, application) into a single bringup
• Setting up ordered startup with health checks to avoid race conditions between dependent nodes
• Writing udev rules for deterministic device naming of cameras, LiDARs, and serial devices
• Configuring CycloneDDS or FastDDS for multi-machine ROS2 discovery across robot and base station
• Implementing watchdog and heartbeat monitoring for production robot systems
• Setting up log rotation and structured logging for long-running robot deployments
• Writing graceful shutdown handlers that bring actuators to a safe state before exit
• Debugging boot-time failures, service ordering issues, or device enumeration races

The Robot Bringup Stack

A production robot bringup follows a layered startup sequence from hardware initialization through application-level nodes. Each layer depends on the one below it.

┌─────────────────────────────────────────────────────────────────────┐
│                        APPLICATION LAYER                            │
│  Navigation, manipulation, mission planning, HRI                    │
├─────────────────────────────────────────────────────────────────────┤
│                        PERCEPTION LAYER                             │
│  Object detection, SLAM, point cloud filtering, sensor fusion       │
├─────────────────────────────────────────────────────────────────────┤
│                         DRIVER LAYER                                │
│  Camera drivers, LiDAR drivers, motor controllers, IMU              │
├─────────────────────────────────────────────────────────────────────┤
│                        HARDWARE LAYER                               │
│  udev rules, device enumeration, USB reset, firmware check          │
├─────────────────────────────────────────────────────────────────────┤
│                      ROS2 ENVIRONMENT                               │
│  Source workspace, set RMW, ROS_DOMAIN_ID, DDS config               │
├─────────────────────────────────────────────────────────────────────┤
│                    SYSTEMD TARGETS & SERVICES                       │
│  network-online.target → robot-hw.target → robot-bringup.target     │
├─────────────────────────────────────────────────────────────────────┤
│                      LINUX BOOT (systemd)                           │
│  BIOS/UEFI → GRUB → kernel → systemd init                          │
├─────────────────────────────────────────────────────────────────────┤
│                         HARDWARE BOOT                               │
│  Power supply, onboard computer, peripherals                        │
└─────────────────────────────────────────────────────────────────────┘

systemd Service Units for ROS2

Basic ROS2 Service Unit

Place service files in `/etc/systemd/system/`. This template starts a ROS2 launch file as a long-running service with watchdog support.

# /etc/systemd/system/robot-bringup.service
[Unit]
Description=Robot ROS2 Bringup Stack
Documentation=https://github.com/my-org/my-robot
After=network-online.target robot-hw.target
Wants=network-online.target
Requires=robot-hw.target

[Service]
Type=notify
User=robot
Group=robot
WorkingDirectory=/home/robot

# Load ROS2 environment variables from a dedicated env file
EnvironmentFile=/etc/robot/ros2.env

# Pre-start check: verify critical devices exist
ExecStartPre=/usr/local/bin/robot-device-check.sh

# Start the ROS2 launch file via bash so we can source the workspace
ExecStart=/bin/bash -c '\
  source /opt/ros/${ROS_DISTRO}/setup.bash && \
  source /home/robot/ros2_ws/install/setup.bash && \
  exec ros2 launch my_robot_bringup bringup.launch.py'

# Graceful shutdown: send SIGINT first (Ctrl+C equivalent for ROS2)
ExecStop=/bin/kill -INT $MAINPID
TimeoutStopSec=30

# Restart on failure, but not on clean exit
Restart=on-failure
RestartSec=5

# systemd watchdog: service must call sd_notify(WATCHDOG=1) within this interval
WatchdogSec=30

# Process management
KillMode=mixed
KillSignal=SIGINT
FinalKillSignal=SIGKILL
TimeoutStartSec=60

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=robot-bringup

[Install]
WantedBy=multi-user.target

Environment Setup in systemd

Store environment variables in a dedicated file rather than sourcing .bashrc (which is not loaded by systemd).

# /etc/robot/ros2.env
# ROS2 distribution
ROS_DISTRO=humble

# DDS middleware selection
RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

# Domain isolation: unique per