Skip to main content

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.

modeOperating modeCommand unitCommands come from
cspPositionradTrajectory controller (Bus.move_to, FollowJointTrajectory)
csvVelocityrad/sStream controller (Bus.stream, a topic)
cstTorqueNmStream controller (Bus.stream, 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/setup.bash) and the same names work.

Open the first axis without a gravity load

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​

  1. 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.sh) registers both. Installing the drive package alone is in ROS 2 interfaces.

  2. The IgH EtherCAT master must be in /opt/etherlab. Neither the plem-drive package nor the PLEM install script includes it. If it is missing, ask your contact.

  3. Add the operating account to the realtime group and log in again. The bus loop uses real-time scheduling (SCHED_FIFO) and locked memory. The group's limits file, /etc/security/limits.d/99-plem-realtime.conf, grants priority 99 and unlimited locked memory. The plem-drive package creates the group and the file, and the install and update scripts add the account. If you installed with apt only, add it yourself:

    sudo usermod -aG realtime "$USER" # then log out and back in
    ulimit -r # 99
    ulimit -l # unlimited
  4. A PREEMPT_RT kernel and isolated CPUs are recommended. Without them plem drive run warns 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_drive.yaml 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:

  1. It reads your drives with read-only ethercat commands only. Review each command your agent asks to run.
  2. It asks for the drive, motor and gearhead, reads their documents, and writes each value with its source as a comment.
  3. It asks you for every decision: limits, stop decelerations, cycle.
  4. 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.
  5. A value with no source is left out and marked # OPEN. It runs plem drive check until 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.md as its instructions.

Check what the agent wrote

The comments say where each value came from, but a wrong value still loads.

Two-axis A6B example​

The a6b_pair 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.yaml, demo.py (moves the pair as mirror images), plotjuggler.xml (a layout with a sync tab) and README.md. 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_code and motor_rated_torque_nm change, on another gearhead gear_ratio and every axis value change, and zero_offset_count is measured on your own drives.

Choose the stop deceleration for your machine

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_position: [0, 1]) and give name, flip and zero_offset_count one value per drive (§4.1).

KeyWhere it comes fromWatch for
vendor_id, product_code, ring_positionethercat slaves -v
pdo_mappingscanned (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 startgenerated has run on hardware only on the A6B (csp)
busname (the bus runs as /<name>; letters, digits and _, not starting with a digit), cycle_time_ns (a multiple of 1000), sync_modedrive_default follows the drive's own synchronization; dc_sync0 needs a dc block on every slave
nameYour choiceLower case, digits and _, at most 31 bytes, unique in the file
channelWhich CiA 402 axis inside the drive (1 to 8)
modecst, csp or csv; check the drive manualThe mode's target object (0x6071, 0x607A, 0x60FF) must be in the mapping
mode_display_timingLeave out (pre_enable)Only a drive that shows its mode on 0x6061 after enable writes post_enable. Its release is refused until you do, and the refusal says so
factorsDrive manual and motor nameplaterated_per_mille when the manual gives 0x6071/0x6077 in 0.1 % of rated torque (with motor_rated_torque_nm), scaled_current when it gives current counts
velocity_factorThe 0x606C unit in the drive manualA wrong value still loads and silently skews the velocity limit and joint_states velocities
flip, zero_offset_countMeasure themMeaningful only with an absolute encoder (Not supported)
limitsYour responsibility. No defaultsAn axis without end stops writes position: null. Position and velocity axes also write acceleration_rad_s2, the deceleration of the requested stop: what the axis can brake at, and no more than the drive's 0x6085
startup_sdoDrive manual; [] for noneAlso set the stop objects 0x605A, 0x605C, 0x6084, 0x6085 here (Stopping)
fault_resetpolicy is your choice; pulse_ms from the drive manual0 (one cycle) when the manual states nothing
cia402_profileLeave out for a drive that follows the standardA drive that takes Shutdown in not_ready_to_switch_on after power-on needs a table with that row (cia402_profile)
approvalLeave outThe 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 codeMeaning
0The file's claimed approval state holds
1The file is refused, or its claimed approval does not hold (the reason is on stderr or under approval:)
2Wrong usage

Passing check is not passing start-up. The JSON's not_judged 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.name>: /my_drive 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_trajectory_controller for csp axes, stream_controller 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.name, --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_raw 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_drive/rt_raw/samples, 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_position, applied_command, command_position), velocity and torque, timing (loop_exec_us, loop_jitter_us), and bus (wkc_mismatch, deadline_miss, dc_sync_monitor_ns).

  • The first time PlotJuggler may ask questions: restart the previous streaming plugin (Yes), select /<bus.name>/rt_raw/samples with the header stamp on, and create empty placeholders for missing curves. Keep header.stamp 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.
  • Export CSV from PlotJuggler.
  • On a dc_sync0 bus, dc_sync_monitor_ns is the DC deviation per cycle. A point at 4294967295 means 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_drive/joint_states, no relay needed.

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_ros, --plot refuses before anything starts and prints sudo apt install ros-$ROS_DISTRO-plotjuggler-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_brake in the service, release() in Python). A released axis holds its place until a command comes.

Python​

Bus from plem.drive attaches to a running bus by its bus.name. 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() before release(). With fault_reset.policy: none, an axis in fault fails release() at once.
  • Once you have streamed, keep stream() running from a thread through release() and reset().
  • When stream() calls stop, the bus takes a protective stop about 100 ms after the last one. Keep the stream loop light.
  • Leaving the with block stops the axes, however it ends (Ctrl-C included). To leave them released, create Bus(...) without with and end with close().

What each method waits for and raises is in Python plem.drive.

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: true does not mean the release is done. Confirm it with operation_enabled and brake_engaged in status (Release responses).
  • ros2 topic pub reads YAML, where 1e-05 is not a number: write 1.0e-05.
Commands are not clipped

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.stop() or the protective_stop 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/N]), 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_drive.bench.log 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, csp and csv, fixed at start. No runtime mode switch, trajectory interpolation in the bus loop (an axis with the retired ramp block 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.drive for position axes, by your stream client for stream axes. cst does 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_drive) in the drive layer.
  • No IO slaves. The bus configures only the drives in the file and leaves the other slaves on the ring unconfigured (PREOP).
Drives the software cannot refuse

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_offset_count 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 (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.

FileChecked
The A6B exampleMoves with both profiles, stops, the bench and approval, a ten-minute run of 230 moves
A csv copy of itStreaming, a silenced stream, the bench
A cst copy of itTorque up to 1.5 N·m, the stop on a silenced stream
A copy with flip, one with pdo_mapping: generatedThe 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 cst axis
  • The requested stop's Quick stop fallback (RAMP_STOP_TIMEOUT), and the example's 0x605A = 2
  • example_drive.yaml as shipped; a refused scanned mapping; generated on any drive but the A6B
  • A protective stop of a fast csv axis, and a silenced stream on a moving cst axis
  • A protective stop on a measured position crossing a limit while moving
  • Automatic fault reset (bounded_auto_reset) and a non-zero 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