Skip to main content

Launching the stack

Launch procedure​

Run plem on the device, pick a robot profile and launch. One launch file serves one robot or several.

Right before launch, plem queries the slaves on the chosen EtherCAT master. With zero slaves it does not start the stack.

What changes your interfaces​

Choice in plemLaunch argumentDefault (plem / launch file)What it addsNeeds first
MoveItmoveiton / falseplem/plan_trajectory—
Collision avoidanceenable_cumotionoff / trueThe cuMotion planning pipeline, for supported models. ROS 2 Humble (JetPack 6) devices only (warning below)MoveIt
Cameras and perceptionperception_stackoff / falseTopics for supported cameras. The environment map (ESDF) comes up only after calibrationMoveIt, a camera that supports perception
Teaching Pendant · Plem Labteaching_pendant · plem_labon / trueThe web UI connection (not needed for ROS 2 integration)—

plem remembers your last choices. When you launch with ros2 launch yourself, set every value you need, because the launch file defaults for MoveIt and collision avoidance are the opposite of the plem defaults.

Do not turn on collision avoidance on JetPack 7 (Jazzy) devices

cuMotion runs only on ROS 2 Humble (JetPack 6) devices. It is not installed on Jazzy (JetPack 7) devices yet. Turning the option on for a supported model there makes the robot stack launch fail, because the cuMotion plugin cannot be found. There is no warning first.

  • With MoveIt off, no cuMotion, camera or perception node starts. Turning on cameras alone starts nothing. Avoiding real objects needs MoveIt, collision avoidance, cameras and calibration together.
  • COLLISION_AWARE plans avoid self-collision on supported models. They do not guarantee avoiding objects added to the planning scene, including Teaching Pendant cell objects (cell objects).
  • A COLLISION_AWARE goal can be accepted and then aborted, because model support and pipeline state are checked after acceptance. Always check the result.

Checking the stack is up​

Launch happens in stages. Robots come up 1 s apart, and the layers above attach in order.

WhenWhat comes up
Right after hardware activationplem/set_mode · plem/control_command · status_broadcaster · rt_*
About 3–4 sThe web UI connection (if Pendant or Lab is on)
About 5 sCamera and perception nodes, MoveIt
With perceptionFrom 6 s after launch, waits up to 60 s for the environment map service, then starts MoveIt

The surest sign is that the plem/set_mode action answers. It answers once the hardware interface is active. In a client, wait with wait_for_server instead of a fixed delay.

When it does not come up​

Symptom (log line)MeaningWhat to do
Blocked before launch: no EtherCAT slavesZero slaves, or the state query failedCheck the robot controller power and EtherCAT cable, then launch again
Cannot get the master (Failed to request EtherCAT master <n> … possible causes: …)Another process holds the master, the IgH master is not running, or this user cannot open /dev/EtherCAT<n>. The line lists the likely causeMake sure the previous stack is fully down (Restarting), then launch again
Perception falls back to "driver-only" (the [launch.extrinsic] WARNING line above the notice)Not a failure: the stack runs with cameras only. There is no camera calibration record, or the camera model or tool rotation changed after it was measuredUse it as is, or calibrate again for the current setup. If you changed no parts, check the camera and tool rotation in the robot settings
Launch fails on a camera calibration recordThe record the profile points to is missing, unreadable, or was measured on a different robot modelClear the calibration in the robot settings or pick a matching record, then launch again
Exits because the environment map was not readyThe perception stack did not come up in time, so the whole launch stopsCheck the camera connection (Troubleshooting), then launch again
PDO mapping refused (declared PDO layout rejected, cannot read the slave's PDO mapping and other lines with refusing to initialize; case varies)A drive's PDO mapping differs from what the robot model declares, or cannot be read. Stops before the robot movesCheck the chosen robot model and the drive firmware. If it persists, contact support
Drive identity mismatch (the configuration declares vendor 0x… product 0x…, but the slave at that ring position is …)A different drive sits at that ring position, or the wiring order differsCheck the chosen robot model and the EtherCAT wiring order
Measured kinematics refused ([measured] <robot> rejected: <reason> — <action>)The measured kinematics registered for this robot failed validation. Launch stops so the robot does not move with wrong geometryFollow the action in the log line. A normal launch logs geometry: measured record applied (measured <date>) or geometry: model nominal (<model>) instead
Launch fails on perception_overrides.yamlThe perception overrides file has an unknown section, profile or keyFix or remove the file, then launch again
A MoveIt or web connection warning, then launch continuesOnly that component is missing; the rest is upIf you need the web UI, take the stack down and launch again

Restarting​

Launch again only after the previous stack is fully down. If it is still running, the new launch cannot get the EtherCAT master, and a half-started stack leaves duplicate nodes in the same namespace. Shutting down can take a while, especially with cameras.

If you deactivate the robot hardware through controller_manager, activating it again in the same stack is refused. Restart the stack instead.

warning
plem kill is a last resort

A normal shutdown asks the robot for BRAKED before it takes the processes down. It does not confirm the request succeeded, and the SIGTERM that launch sends shortly after skips any brake confirmation (Stops and safety). plem kill sends no request at all and soon force-kills. Use it only when a normal shutdown does not work. What it stops: plem kill.

Site perception overrides​

Some perception settings depend on the site, such as the collision grid size and center, or the nvblox range and voxel size. Put them in ~/.plem/perception_overrides.yaml and PLEM applies them over the installed perception profile. If you set PLEM_HOME, the file goes under that directory. Do not edit the installed files.

common: # every profile — site geometry
cumotion:
grid_size_m: [1.8, 2.2, 1.4]
grid_center_m: [0.0, 0.0, 0.6]
profiles: # then one profile only — tuning for that profile
thin_object_precise:
nvblox:
voxel_size_m: 0.02
  • The order is installed profile → common → profiles.<name>. Put site geometry in common. Under profiles.<name> it is dropped as soon as you pick another profile.
  • Keys with children merge key by key. Any other value, lists included, is replaced whole.
  • With no file, the installed profile is used as is.
  • An unknown section, a profile name that does not exist, or a key the installed profile does not have makes launch refuse, so a typo is never silently ignored.
  • Camera and perception nodes and MoveIt (the cuMotion grid) read the same result. When it applies, the launch log has a [perception] … overridden at [...] line.
  • The Camera quality preview on the plem start screen reflects the overridden range and resolution, and lists the overridden keys on one line.

Launching directly​

Arguments to set when you run ros2 launch without plem

A missing profile, or a serial or master count that does not match, stops with an error before launch.

  • Profile directory: the parent folder that holds robots/. Passing robots/ itself fails to find the profiles. Without it, ~/.plem is used, or PLEM_HOME if set. Every robot needs robots/<robot name>.yaml there.
  • Robot names: each name becomes that robot's namespace.
  • Robot serials: same count and order as the robot names. Leave an empty slot for a robot without a serial, as in ,S2. A registered model requires a serial: its joint offsets come from the per-device joint calibration profile (~/.plem/profiles/<serial>.json), and without the serial the driver refuses the robot configuration instead of falling back to defaults.
  • EtherCAT masters: one per robot, in the same order. Fewer than the robots stops before launch. Without it, the robot index (from 0) is used.

Without a log directory, logs go to the ROS default (~/.ros/log) and old logs are never removed. To get a folder per launch under ~/.plem/log as plem does, create it and pass it as ROS_LOG_DIR. The stack keeps the 20 most recent folders, this one included.

export ROS_LOG_DIR=~/.plem/log/$(date +%Y-%m-%d_%H-%M-%S)
mkdir -p "$ROS_LOG_DIR"
ros2 launch …