Running the Lab

This page explains how the CPM Lab is executed day to day: which launch file to start, what the control flow does in the background, and in which order an experiment is set up. The step-by-step guides First Simulation and External Motion Planner show the same workflow with screenshots.

The Control Flow

The central component of the lab is the control flow (package cpm_lab_control_flow). It runs in the lab domain (ROS_DOMAIN_ID=21) and starts and stops all other components on request:

  • the map server with the selected Lanelet2 map,

  • the indoor positioning system (IPS) with the selected lab configuration,

  • one simulated vehicle per selected vehicle ID,

  • the bridge and the selected motion planner in the planner domain (ROS_DOMAIN_ID=1) when an experiment is deployed,

  • the experiment recorder if the experiment is recorded, see Recording and Evaluating Experiments.

The Control Center panel in RViz and the CPM control dashboard panel in Lichtblick are only user interfaces for the control flow. They call the control flow services and show its state, so the control flow must always be running.

RViz with the Control Center panel next to the map and the vehicles

RViz with the Control Center panel (left) during an experiment

Starting the Lab

Start the control flow together with one of the user interfaces. All launch files start the control flow and the map visualization:

Command

Use case

ros2 launch cpm_lab cpm_lab_rviz.launch.xml

RViz with the Control Center panel and the CPM Lab RViz configuration.

ros2 launch cpm_lab cpm_lab_foxglove.launch.xml

Foxglove bridge for Lichtblick, see Visualization with Lichtblick. Recommended for a headless deployment on the central workstation.

ros2 launch cpm_lab cpm_lab_headless.launch.xml

Control flow and map visualization only, for example to control the lab from the command line. Accepts recording_root:=<path> and use_sim_time:=true.

Always start the lab in the lab domain:

source /opt/ros/jazzy/setup.bash
export ROS_DOMAIN_ID=21
ros2 launch cpm_lab cpm_lab_rviz.launch.xml

Note

If you built the workspace from source, source <path-to-ros2-workspace>/install/setup.bash instead of /opt/ros/jazzy/setup.bash.

Stop the lab with Ctrl+C in the terminal of the launch file. This also stops all components started by the control flow, but not planners or other nodes you started yourself in other terminals.

The control flow shows a warning in the user interface if ROS_DOMAIN_ID is not 21 or if FastDDS is used as middleware. Use Zenoh, which the real lab requires, or CycloneDDS for simulations only, see Middleware.

Experiment Workflow

An experiment is always set up in the same order. Simulated and real vehicles can be mixed.

  1. Map server: select a map and start the map server. The maps starting with Lab match the lab track.

  2. IPS (real vehicles only): select the configuration of your lab, for example munich2.yaml, and start the IPS.

  3. Vehicles: start simulated vehicles for the vehicle IDs you need, or switch on the muCars. A vehicle is online as soon as its state reaches the lab domain. Start the map server before the simulated vehicles so they can use the spawn points of the map.

  4. Deploy: select the motion planner and its update period, optionally enable Record experiment, and deploy. The control flow deploys all vehicles that are online at that moment, starts the bridge and, if selected, the internal motion planner. With an external motion planner, start it yourself in ROS_DOMAIN_ID=1, see Understanding the Motion Planner.

  5. Start: as soon as the bridge reports that the planner and all vehicles are ready, start the experiment.

  6. Stop: stopping the experiment stops the vehicles, the bridge and the internal motion planner. The map server, the IPS and the simulated vehicles keep running, so you can deploy the next experiment right away.

The bridge stops the experiment automatically if a vehicle state times out. A stop requested by any other component on /lab/system_trigger also stops the experiment.

Deploy Checks

After clicking Deploy, the control flow and the bridge run the following checks. Start is only enabled once all of them pass. The red boxes show the most common reasons why Start never becomes available. The events on /lab/control_flow/status show which step failed.

        ---
config:
  layout: elk
  startOnLoad: false

---
flowchart TD
   DEPLOY([Deploy]) --> IDLE(Control flow idle?)
   IDLE -->|no| E1[Deploy refused:<br/>experiment still deployed or<br/>recording still finalizing]
   IDLE -->|yes| ONLINE(At least one<br/>vehicle online?)
   ONLINE -->|no| E2[Deploy refused:<br/>no vehicle state in domain 21<br/>within the last second]
   ONLINE -->|yes| REC(Record<br/>experiment?)
   REC -->|yes| RECSTART(Recorder started<br/>and armed?)
   RECSTART -->|no| E3[Recorder failed:<br/>another recorder in the domain,<br/>no map within 5 s,<br/>less than 100 MB free disk space]
   RECSTART -->|yes| BRIDGE
   REC -->|no| BRIDGE[Bridge started in domain 1<br/>with all online vehicles]
   BRIDGE --> HLC(Internal<br/>motion planner?)
   HLC -->|yes| SPAWN[Control flow starts the planner<br/>in domain 1]
   HLC -->|no| EXT[User starts the external planner<br/>in domain 1]
   SPAWN --> REQ
   EXT --> REQ[Bridge sends READY_REQUEST<br/>every period]
   REQ --> PREADY(Planner READY for<br/>every deployed vehicle?)
   PREADY -->|no| E4[Planner not ready:<br/>not running or crashed,<br/>wrong ROS_DOMAIN_ID,<br/>vehicle IDs differ from the online vehicles,<br/>source_id not planner_&lt;id&gt;]
   PREADY -->|yes| VONLINE(All deployed vehicles<br/>still online?)
   VONLINE -->|no| E5[Vehicle lost:<br/>vehicle switched off or crashed,<br/>no network or wrong domain]
   VONLINE -->|yes| BREADY[Bridge reports READY]
   BREADY --> START([Start enabled])

   classDef error fill:#fde2e1,stroke:#c0392b,color:#111
   class E1,E2,E3,E4,E5 error

Checks between Deploy and Start

Note

The control flow deploys all vehicles that are online when you click Deploy. A common reason for a missing Start is an external motion planner started with fewer vehicle IDs, for example because an additional muCar was switched on or a simulated vehicle was still running. Use the IDs from online_vehicle_ids of /lab/control_flow/state for the planner.

If Start does not appear, click Abort Waiting, fix the cause and deploy again.

Controlling the Lab from the Command Line

Every step of the workflow is a ROS2 service of the control flow, so the lab can also be operated without a user interface, for example over SSH on the central workstation. Run the commands in ROS_DOMAIN_ID=21:

# Show the available maps, IPS configurations and motion planners
ros2 topic echo --qos-durability transient_local /lab/control_flow/catalog

# Show the current state (deploy_state: 0 idle, 1 waiting, 2 ready, 3 running)
ros2 topic echo --qos-durability transient_local /lab/control_flow/state

# Start / stop the map server
ros2 service call /lab/control_flow/map_server cpm_lab_control_flow_msgs/srv/MapServer "{action: 0, map_name: 'Lab Full.osm'}"
ros2 service call /lab/control_flow/map_server cpm_lab_control_flow_msgs/srv/MapServer "{action: 1}"

# Start / stop the IPS
ros2 service call /lab/control_flow/ips cpm_lab_control_flow_msgs/srv/Ips "{action: 0, ips_config: 'munich2.yaml'}"
ros2 service call /lab/control_flow/ips cpm_lab_control_flow_msgs/srv/Ips "{action: 1}"

# Start / stop a simulated vehicle
ros2 service call /lab/control_flow/simulation cpm_lab_control_flow_msgs/srv/Simulation "{action: 0, vehicle_id: 1}"
ros2 service call /lab/control_flow/simulation cpm_lab_control_flow_msgs/srv/Simulation "{action: 1, vehicle_id: 1}"

# Deploy with an internal motion planner (package and launch file as listed in the catalog)
ros2 service call /lab/control_flow/deploy cpm_lab_control_flow_msgs/srv/Deploy "{action: 0, use_internal_hlc: true, hlc_package: 'cpm_lab_central_routing', hlc_node: 'default.launch.xml', period_ms: 400, record_experiment: false}"

# Deploy for an external motion planner
ros2 service call /lab/control_flow/deploy cpm_lab_control_flow_msgs/srv/Deploy "{action: 0, use_internal_hlc: false, period_ms: 400, record_experiment: false}"

# Abort the deployment
ros2 service call /lab/control_flow/deploy cpm_lab_control_flow_msgs/srv/Deploy "{action: 1}"

# Start / stop the experiment once deploy_state is 2
ros2 service call /lab/control_flow/experiment cpm_lab_control_flow_msgs/srv/Experiment "{action: 0}"
ros2 service call /lab/control_flow/experiment cpm_lab_control_flow_msgs/srv/Experiment "{action: 1}"

The control flow also publishes a readable event log on /lab/control_flow/status.

Maps and Spawn Points

The available maps are installed with the cpm_lab_maps package:

  • Lab Full.osm, Lab Reduced.osm, Lab Outer Circle.osm and Lab Traffic Rules.osm for the lab track,

  • A61 Lanelet2.osm and A61 Lanelet2 SFB.osm.

A simulated vehicle starts at the spawn point of the map with its vehicle ID. A spawn point is a linestring with the attribute spawn_point=<vehicle_id>; the vehicle starts at its first point, heading towards its last point. Without a spawn point, vehicles 1 to 20 use a predefined start pose on the lab track.