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 plem | Launch argument | Default (plem / launch file) | What it adds | Needs first |
|---|---|---|---|---|
| MoveIt | moveit | on / false | plem/ | — |
| Collision avoidance | enable_ | off / true | The cuMotion planning pipeline, for supported models. ROS 2 Humble (JetPack 6) devices only (warning below) | MoveIt |
| Cameras and perception | perception_ | off / false | Topics for supported cameras. The environment map (ESDF) comes up only after calibration | MoveIt, a camera that supports perception |
| Teaching Pendant · Plem Lab | teaching_ · plem_ | on / true | The 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.
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_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).AWARE - A
COLLISION_goal can be accepted and then aborted, because model support and pipeline state are checked after acceptance. Always check the result.AWARE
Checking the stack is up
Launch happens in stages. Robots come up 1 s apart, and the layers above attach in order.
| When | What comes up |
|---|---|
| Right after hardware activation | plem/ · plem/ · status_ · rt_* |
| About 3–4 s | The web UI connection (if Pendant or Lab is on) |
| About 5 s | Camera and perception nodes, MoveIt |
| With perception | From 6 s after launch, waits up to 60 s for the environment map service, then starts MoveIt |
The surest sign is that the plem/ action answers. It answers once the hardware interface is active. In a client, wait with wait_ instead of a fixed delay.
When it does not come up
| Symptom (log line) | Meaning | What to do |
|---|---|---|
| Blocked before launch: no EtherCAT slaves | Zero slaves, or the state query failed | Check 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/. The line lists the likely cause | Make sure the previous stack is fully down (Restarting), then launch again |
Perception falls back to "driver-only" (the [launch. 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 measured | Use 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 record | The record the profile points to is missing, unreadable, or was measured on a different robot model | Clear the calibration in the robot settings or pick a matching record, then launch again |
| Exits because the environment map was not ready | The perception stack did not come up in time, so the whole launch stops | Check 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 moves | Check 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 differs | Check 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 geometry | Follow 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_ | The perception overrides file has an unknown section, profile or key | Fix or remove the file, then launch again |
| A MoveIt or web connection warning, then launch continues | Only that component is missing; the rest is up | If 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_, activating it again in the same stack is refused. Restart the stack instead.
plem kill is a last resortA 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 ~/. and PLEM applies them over the installed perception profile. If you set PLEM_, 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.. Put site geometry in<name> common. Underprofiles.it is dropped as soon as you pick another profile.<name> - 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
plemstart 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/. Passingrobots/itself fails to find the profiles. Without it,~/.is used, orplem PLEM_if set. Every robot needsHOME robots/there.<robot name>. yaml - 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 (~/.), and without the serial the driver refuses the robot configuration instead of falling back to defaults.plem/ profiles/ <serial>. json - 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 (~/.) and old logs are never removed. To get a folder per launch under ~/. as plem does, create it and pass it as ROS_. 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 …