Connect a servo drive
This page runs a CiA 402 servo drive on an EtherCAT bus without a robot arm. You describe the drive in one YAML file, the drive model file. There is no C++ to write and no UI: you work from the command line, ROS 2 and Python.
The drive must speak CiA 402 over CoE (CANopen over EtherCAT). Each axis picks one operating mode with mode in the file, and one bus may mix modes.
mode | Operating mode | Command unit | Commands come from |
|---|---|---|---|
csp | Position | rad | Trajectory controller (Bus., FollowJointTrajectory) |
csv | Velocity | rad/s | Stream controller (Bus., a topic) |
cst | Torque | Nm | Stream controller (Bus., a topic) |
csv and cst axes take a command every cycle, so these pages call them stream axes. Every key of the file is in Drive model file. Interfaces, errors, stops and the bench are in Drive bus API.
The whole procedure for your own drive:
mkdir -p "$HOME/drives" && cp "$(ros2 pkg prefix --share plem_drive)/examples/example_drive.yaml" "$HOME/drives/my_drive.yaml" # section 1
# fill in your drive's values (section 2)
plem drive check "$HOME/drives/my_drive.yaml" # section 3
plem drive run "$HOME/drives/my_drive.yaml" # bench once (section 7), then the bus runs (section 4)
plem drive has two verbs, check and run, and plem drive --help lists them. plem passes the command unchanged to the plem-drive tool. A device with only the drive package (plem-drive) still has plem, because the plem-cli package comes with it. In a source build, source the workspace (source install/) and the same names work.
The steps below release the brakes under a neutral command: 0 Nm on a torque axis. The drive layer has no gravity compensation, so a loaded torque axis falls as soon as its brake opens. Position and velocity axes are held by the drive's own loop, but that behavior differs per drive and has not been checked on hardware. Test first on an unloaded axis, with the Emergency Stop within reach.
Prerequisites
-
Install the PLEM packages, the full install or the drive package (
plem-drive) alone. They come from the Depot repository, registered with the token your license contact gave you, on a Jetson (aarch64, Ubuntu 22.04 or 24.04) that also has the ROS 2 apt repository. The full install (install.) registers both. Installing the drive package alone is in ROS 2 interfaces.sh -
The IgH EtherCAT master must be in
/opt/. Neither theetherlab plem-drivepackage nor the PLEM install script includes it. If it is missing, ask your contact. -
Add the operating account to the
realtimegroup and log in again. The bus loop uses real-time scheduling (SCHED_FIFO) and locked memory. The group's limits file,/etc/, grants priority 99 and unlimited locked memory. Thesecurity/ limits. d/99-plem-realtime. conf plem-drivepackage creates the group and the file, and the install and update scripts add the account. If you installed withaptonly, add it yourself:sudo usermod -aG realtime "$USER" # then log out and back inulimit -r # 99ulimit -l # unlimited -
A PREEMPT_RT kernel and isolated CPUs are recommended. Without them
plem drive runwarns and starts anyway.
1. Copy an example
mkdir -p "$HOME/drives"
cp "$(ros2 pkg prefix --share plem_drive)/examples/example_drive.yaml" "$HOME/drives/my_drive.yaml"
example_ is one position axis with synthetic values that fit no real drive. Keep the shape and replace every value with your drive's.
Let a coding agent fill it in
The package installs an agent skill, add-drive, that takes the copy through section 2:
- It reads your drives with read-only
ethercatcommands only. Review each command your agent asks to run. - It asks for the drive, motor and gearhead, reads their documents, and writes each value with its source as a comment.
- It asks you for every decision: limits, stop decelerations, cycle.
- It stops early when a premise of the schema does not hold: a holding brake per axis that the drive itself operates, and an absolute encoder.
- A value with no source is left out and marked
# OPEN. It runsplem drive checkuntil the file passes or fails only on its open keys.
The bench (section 7) stays yours. For Claude Code, link the skill into your skills folder:
mkdir -p ~/.claude/skills
ln -s "$(ros2 pkg prefix plem_drive)/share/skills/add-drive" ~/.claude/skills/
On a device with both plem-code and plem-drive, plem code finds the skill without this link (except in bare and safe mode). It reads skills at start, so restart plem code after installing or updating the package. Another agent takes the same SKILL. as its instructions.
The comments say where each value came from, but a wrong value still loads.
Two-axis A6B example
The a6b_ folder next to it is an example made on real drives: two Panasonic MINAS A6B (MDDLN55BE, motor MSMF102L1H5), one position axis each, on distributed clocks with a 21:1 gearhead. It holds drive., demo. (moves the pair as mirror images), plotjuggler. (a layout with a sync tab) and README.. The README has the steps, the safety rules and the source of every value. The approval is written into the file, so copy the folder somewhere writable:
cp -r "$(ros2 pkg prefix --share plem_drive)/examples/a6b_pair" "$HOME/drives/"
On another A6B model or motor product_ and motor_ change, on another gearhead gear_ and every axis value change, and zero_ is measured on your own drives.
The example's stop deceleration of 3200 rad/s² (at the motor) was chosen on an unloaded bench with the gearhead outputs free. A load raises the stopping torque and the regenerated energy. Set it for your machine and make the first stop without a load.
2. Fill in the values
A file with a missing key is refused. Write "no value" as null or []. The keys you may leave out, and what is used instead, are in Drive model file §1. Identical drives share one entry: list their ring positions (ring_) and give name, flip and zero_ one value per drive (§4.1).
| Key | Where it comes from | Watch for |
|---|---|---|
vendor_, product_, ring_ | ethercat slaves -v | |
pdo_ | scanned (the drive's power-on mapping), generated (PLEM writes the CiA 402 objects it uses in PREOP) or a declared mapping from the ESI file, ethercat pdos or the log of a scanned start | generated has run on hardware only on the A6B (csp) |
bus | name (the bus runs as /<name>; letters, digits and _, not starting with a digit), cycle_ (a multiple of 1000), sync_ | drive_ follows the drive's own synchronization; dc_ needs a dc block on every slave |
name | Your choice | Lower case, digits and _, at most 31 bytes, unique in the file |
channel | Which CiA 402 axis inside the drive (1 to 8) | |
mode | cst, csp or csv; check the drive manual | The mode's target object (0x6071, 0x607A, 0x60FF) must be in the mapping |
mode_ | Leave out (pre_) | Only a drive that shows its mode on 0x6061 after enable writes post_. Its release is refused until you do, and the refusal says so |
factors | Drive manual and motor nameplate | rated_ when the manual gives 0x6071/0x6077 in 0.1 % of rated torque (with motor_), scaled_ when it gives current counts |
velocity_ | The 0x606C unit in the drive manual | A wrong value still loads and silently skews the velocity limit and joint_ velocities |
flip, zero_ | Measure them | Meaningful only with an absolute encoder (Not supported) |
limits | Your responsibility. No defaults | An axis without end stops writes position: null. Position and velocity axes also write acceleration_, the deceleration of the requested stop: what the axis can brake at, and no more than the drive's 0x6085 |
startup_ | Drive manual; [] for none | Also set the stop objects 0x605A, 0x605C, 0x6084, 0x6085 here (Stopping) |
fault_ | policy is your choice; pulse_ from the drive manual | 0 (one cycle) when the manual states nothing |
cia402_ | Leave out for a drive that follows the standard | A drive that takes Shutdown in not_ after power-on needs a table with that row (cia402_profile) |
approval | Leave out | The bench writes it (section 7) |
3. Check the file
No drive is needed:
plem drive check "$HOME/drives/my_drive.yaml"
A refusal names the key path and says how to fix it. A schema §4.1 in the message is that section of Drive model file. check also refuses, without the drives, a file the bus would refuse at start, such as a mode whose required PDO object is missing or two axes on one channel.
A passing file prints the bus, each axis, the approval state, warnings and the next step. Warnings do not refuse the file or change the exit code. Scripts use plem drive check --json <file>. The fields and the warnings are in plem drive check output.
| Exit code | Meaning |
|---|---|
| 0 | The file's claimed approval state holds |
| 1 | The file is refused, or its claimed approval does not hold (the reason is on stderr or under approval:) |
| 2 | Wrong usage |
Passing check is not passing start-up. The JSON's not_ lists what the bus judges when it starts: a scanned slave's mapping, the live drive identity (serial number, revision number, 0x1009, 0x100A, the scanned mapping), fault-reset pacing against the cycle, and DC rules.
4. Run the bus
plem drive run "$HOME/drives/my_drive.yaml"
The bus runs in this terminal, in the namespace /<bus.: /my_ for the example. Renaming the bus keeps its approval. On a file not yet approved for motion, run offers the bench first (section 7). It warns, and starts anyway, when the kernel is not PREEMPT_RT, no CPU is isolated, or the Jetson's nvpps PTP-TSC lock is on.
Move only after this line: every slave in OP (working counter complete) … s after the loop started. A slave still outside OP after 60 s stops the bus and fails the start. Ctrl-C stops every axis before the bus lets go.
The axis mode picks the controller: joint_ for csp axes, stream_ for stream axes. Options, the start sequence and the interface names are in plem drive run and ROS interfaces.
For two buses, start one plem drive run per master, each with its own bus., --master and --rt-cpu. With only one isolated CPU, the second loop runs on a non-isolated CPU and its jitter may grow. A start fails if the robot stack or another program holds the same master.
Every cycle in PlotJuggler
plem drive run "$HOME/drives/my_drive.yaml" --plot
rt_ packs up to 40 cycles in one message, so PlotJuggler on it draws one point per message. --plot starts a relay that republishes one cycle per message on /my_, stamped with that cycle's RT time, and opens PlotJuggler on a layout built from this bus's axes. The relay runs with normal scheduling and leaves the control loop alone. Both end with the bus.
The layout has four tabs: position (one pane per axis: actual_, applied_, command_), velocity and torque, timing (loop_, loop_), and bus (wkc_, deadline_, dc_).
- The first time PlotJuggler may ask questions: restart the previous streaming plugin (Yes), select
/<bus.with the header stamp on, and create empty placeholders for missing curves. Keepname>/ rt_ raw/ samples header.as the time axis; with it off, the 40 cycles of a batch arrive together and the points bunch up. The dialog's wording may differ between PlotJuggler versions, and the header-stamp choice has not been checked on a live bus.stamp - Export CSV from PlotJuggler.
- On a
dc_bus,sync0 dc_is the DC deviation per cycle. A point atsync_ monitor_ ns 4294967295means no value that cycle. The deviation is large for the first tens of seconds and still spikes now and then afterwards; PLEM does not wait for it to settle. - Measured position, velocity and torque alone are on
/my_, no relay needed.drive/ joint_ states
PlotJuggler is installed with PLEM when the ROS apt repository (packages.ros.org) is reachable during install or update. A source build, an install with --no-install-recommends or an install without that repository may lack it. Without PlotJuggler or plotjuggler_, --plot refuses before anything starts and prints sudo apt install ros-$ROS_.
Bus timing in the terminal
plem drive run <file> --monitor prints the loop timing and the drive state beside the bus, one line a second, plus a line of its own for each state change, and the totals at Ctrl-C. The columns are in --monitor output.
5. Release and move
Releasing opens the brakes and puts every axis in Operation enabled (release_ in the service, release() in Python). A released axis holds its place until a command comes.
Python
Bus from plem. attaches to a running bus by its bus.. With no such bus it raises DriveError after the timeout, naming the bus.
from plem.drive import Bus, SCurve
with Bus("my_drive") as bus: # the file's bus.name
print(bus.axes, bus.positions) # axis names, positions (rad)
bus.reset() # clear a fault latched when the bus last stopped
bus.release() # brakes off; the axes hold where they are
start = bus.positions
bus.move_to({name: start[name] + 0.5 for name in bus.axes},
velocity_scale=0.2, acceleration_scale=0.2) # returns on arrival
bus.move_to(start, profile=SCurve())
bus.stop() # decelerate, then the brakes
Stream axes take a command each cycle from your own loop (here one axis, j0):
import threading, time
from plem.drive import Bus
with Bus("my_drive") as bus:
command = {"j0": 0.0} # per stream axis: rad/s (csv) or Nm (cst)
running = True
def control(): # your loop: each call is one cycle's command
while running:
bus.stream(command)
time.sleep(0.005)
loop = threading.Thread(target=control)
loop.start() # a bus with a torque axis releases only on a live stream
try:
bus.reset() # with the stream live (a silent stream's stop would stay)
bus.release()
command["j0"] = 0.3
time.sleep(2.0)
command["j0"] = 0.0
bus.stop()
finally:
running = False # an exception above must end the loop too
loop.join()
- Call
reset()beforerelease(). Withfault_, an axis in fault failsreset. policy: none release()at once. - Once you have streamed, keep
stream()running from a thread throughrelease()andreset(). - When
stream()calls stop, the bus takes a protective stop about 100 ms after the last one. Keep the stream loop light. - Leaving the
withblock stops the axes, however it ends (Ctrl-C included). To leave them released, createBus(...)withoutwithand end withclose().
What each method waits for and raises is in Python plem..
Command line
csp axes also move from any other FollowJointTrajectory client. MoveIt speaks it, but has not been tried on this path.
On a bus with a torque (cst) axis, order matters: start the stream first, then release. The neutral is 0 Nm on a torque axis and 0 rad/s on a velocity axis, and position axes hold their position at the release.
# ① keep a neutral on the stream axes (one value per stream axis; for one torque axis, 0 Nm)
ros2 topic pub -r 200 /my_drive/stream_controller/commands \
std_msgs/msg/Float64MultiArray '{data: [0.0]}'
# ② release in another terminal (bus.release() in Python)
ros2 service call /my_drive/plem_drive/control_command \
plem_rt_msgs/srv/SetControlCommand '{release_brake: true}'
- A command whose length is not the stream axis count, or that holds a non-finite value, is not accepted; sending only that is the same as sending nothing.
- On a bus with only position and velocity axes, the release does not wait for commands. Commands sent before it are not applied, and the 50 ms command watch starts with the first command after it.
success: truedoes not mean the release is done. Confirm it withoperation_andenabled brake_inengaged status(Release responses).ros2 topic pubreads YAML, where1e-05is not a number: write1.0e-05.
A position or velocity command beyond a limit, or a position more than one cycle's travel away, causes a protective stop. The first position command after the release that is within one cycle's travel is applied, and the axis moves. Details: Command checks.
6. Stop
Stop a moving bus with bus. or the protective_ service. Cancelling a FollowJointTrajectory goal does not stop it. What each stop does (a requested stop that decelerates, or an immediate disable), what the drive decides, and how to recover from a protective stop are in Stopping and Recover from a protective stop.
7. Bench and approval
Only the approval block inside the model file enables motion. Run an unapproved file on a terminal and plem drive run starts the bench after one line:
/home/…/drives/my_drive.yaml is not approved for motion. Starting the drive bench.
The bench asks one question ([y/), releases and engages the brakes a few times, and on a bus without a torque axis moves each position or velocity axis once, up to 0.5 rad. On success it writes the approval into the model file, and run starts the bus; that file is the only thing to keep. Otherwise it leaves my_ and the file as it was. Later starts compare the drives on the bus with the record.
The conditions, what the bench checks, what voids an approval and what an approval does not prove are in Bench and approval. --unapproved runs any file in bench mode without using its approval; use it only when you are at the drives.
Not supported
- Modes are
cst,cspandcsv, fixed at start. No runtime mode switch, trajectory interpolation in the bus loop (an axis with the retiredrampblock is refused), feed-forward (0x60B1, 0x60B2) or homing. Quick stop is used only as the fallback of a requested stop. - Trajectories are made on the host: by the trajectory controller and
plem.for position axes, by your stream client for stream axes.drive cstdoes not hold position. - Several axes on one drive are supported, up to 8, not verified on hardware: each axis writes its
channel, and the second channel's objects are at +0x800 (for example 0x6841). - No gravity compensation and no Freedrive (
free_) in the drive layer.drive - No IO slaves. The bus configures only the drives in the file and leaves the other slaves on the ring unconfigured (PREOP).
The file has no key for these, so nothing refuses such a drive. Do not use one.
- Only a holding brake the drive itself releases and engages with the servo. A brake opened by a 0x60FE digital output, an external brake or no brake is not supported.
- No brake shared by several axes. Brakes are opened and closed per axis. Sharing cannot be declared or detected, so one axis's brake action could release another axis, which may then fall without the software knowing.
- Only absolute encoders. PLEM has no homing.
zero_and the position limits locate an axis only if the drive reports the same position after every power-on; an incremental encoder restarts its count, and the limits then guard nothing. An endless axis (offset_ count position: null) has no position limits, and its position after a restart is relative anyway.
Hardware evidence
plem drive run has run on two A6B drives with position (csp) axes, on a Jetson AGX Orin with JetPack 7.2.1 and ROS 2 Jazzy, with the two gearhead outputs joined by a jaw coupling and also free.
| File | Checked |
|---|---|
| The A6B example | Moves with both profiles, stops, the bench and approval, a ten-minute run of 230 moves |
A csv copy of it | Streaming, a silenced stream, the bench |
A cst copy of it | Torque up to 1.5 N·m, the stop on a silenced stream |
A copy with flip, one with pdo_ | The bench and approval |
Not yet verified on hardware:
- Two coupled axes turning together under torque, and torque above 1.5 N·m
--rt-cpu, two buses on one Jetson- The bench on a bus with a
cstaxis - The requested stop's Quick stop fallback (
RAMP_), and the example's 0x605A = 2STOP_ TIMEOUT example_as shipped; a refuseddrive. yaml scannedmapping;generatedon any drive but the A6B- A protective stop of a fast
csvaxis, and a silenced stream on a movingcstaxis - A protective stop on a measured position crossing a limit while moving
- Automatic fault reset (
bounded_) and a non-zeroauto_ reset pulse_ms - Several axes on one drive, three or more drives, DC on any drive but the A6B
- A SYNC0 shift at any cycle other than 1 ms, and the drive-side input shift (0x1C33)
- How a position or velocity axis holds a load once its brake is open