Skip to main content

Drive bus API

Reference for a drive bus started as in Connect a servo drive. The file's keys are in Drive model file.

On this page <ns> is the bus namespace /<bus.name>, from the file's bus: { name: … }. plem drive <verb> works on any device, because the drive package brings the plem command with it.

plem drive check output​

The format of a refusal (the key path in the file, and the debug-level line that maps axes[i] to it) is in Drive model file §2.

A passing file prints a summary: the bus, each axis with its mode, ring position and channel, the approval state (each reason a claimed approval does not hold, on its own line), the warnings and the next step.

plem drive check --json <file> prints the same judgment as one JSON document ("format": "plem-drive-check/1"). The exit code does not change with --json.

FieldMeaning
bus_nameThe file's bus.name; the bus runs as /<bus_name>. A file without it is refused, with what to write
Two digestsThe file's settings and its transition table. bus.name is not in them, so renaming the bus keeps the approval
implementation_revisionThis software's revision
approval_claimed, approval_effectiveThe approval state the file claims, and the one that holds
required_bench_itemsThe bench items this file's axis modes need
approve_blockerWhy the bench could not record an approval, or null
sync_modeThe file's bus.sync_mode: dc_sync0 or drive_default
Axis and slave addressesValues the bench uses
reasonsWhy a claimed approval does not hold
not_judgedWhat check leaves to the start of the bus
warningsWarnings. They do not refuse the file or change the exit code

warnings names:

  • A position or velocity axis whose startup_sdo leaves a stop object (0x605A, 0x605C, 0x6084, 0x6085) to the value stored in the drive.
  • A DC slave whose sync0_shift_ns is 0.
  • An axis whose limits.position reaches past what the drive's 32-bit position (0x6064) can report with its zero_offset_count and flip. The range is printed.
  • A slave that still has the example's vendor_id 0x00c0ffee. The next step then says to replace the example's values instead of offering plem drive run.

axes[i] carries what plem drive run builds from:

FieldMeaning
modeThe axis's operating mode
position_min_rad, position_max_radPosition limits; null on an axis without end stops
velocity_limit_rad_sVelocity limit
velocity_cap_rad_sThe speed a planner may command. On a csp axis, the velocity limit less one position count per cycle (two on an axis without end stops), so a rounded target stays inside the one-cycle step check. A csp axis whose cap would not be positive is refused. Other axes: the velocity limit
acceleration_limit_rad_s2Stop deceleration; null on a cst axis
torque_min_nm, torque_max_nmA cst axis's limits.torque_nm; null on other axes

slaves[i] describes one drive. axes[i].slave is an index into this list.

FieldMeaning
ring_positionThe drive's position on the ring
vendor_id, product_codeThe identity the file declares, as integers (0x00c0ffee prints as 12648430)
pdo_mappingscanned when the bus reads the mapping from the drive at start, otherwise declared. A file's generated prints declared
startup_sdoWhat the file writes to the drive at start, as a list of integer [index, subindex, value] entries. Empty when there are none

plem drive run​

plem drive run <file> [--master N] [--rt-cpu N] [--monitor] [--plot] [--unapproved] [--verbose]
OptionMeaning
--master NThe IgH master number. Default 0
--rt-cpu NThe CPU the bus loop is pinned to. Default: the last isolated CPU (/sys/devices/system/cpu/isolated). A CPU this process may not run on is refused at start, with the isolated list; whether it is isolated is not checked
--monitorBus timing in the same terminal, one line a second (--monitor output)
--plotStarts rt_raw_relay and PlotJuggler on this bus (PlotJuggler). Refused before anything starts when PlotJuggler or plotjuggler_ros is missing
--unapprovedRuns any file in bench mode without the bench procedure. The approval record is not used, so no drive identity is checked. A BENCH MODE warning comes at start and at every release, and the run's evidence is bench evidence only. Use it only when you are at the drives
--verboseEvery node's log in the terminal

How run decides to start:

The diagram follows run.py (--unapproved skips the approval branch).

  • Same-name check. It looks for another plem drive run of yours on that namespace (its controller manager or robot_state_publisher). Another user's bus, or one on another host of the ROS domain, is not seen. A file whose claimed approval no longer holds (edited after its bench) counts as unapproved.
  • Real-time warnings. 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. The nvpps lock slews the host clock, and the drives' DC drift follows. Each warning says the fix.
  • Description and parameters. One joint per axis, in the file's order and named after the axis, with the file's position limits (continuous on an axis without end stops) and velocity_cap_rad_s as the velocity limit. The controller manager's update rate is the bus cycle. Its update thread is kept off the isolated CPUs and the --rt-cpu CPU when another CPU is available. The bus loop runs at SCHED_FIFO priority 98, with no option to change it.
  • Exec. run becomes the controller manager, so Ctrl-C reaches it directly. The bus stops every axis before it lets go (Stopping).
  • Waiting for OP. The bus logs every slave in OP (working counter complete) … s after the loop started once the domain's working counter is complete. On a bus with a csp axis, the trajectory controller becomes active a moment later: Bus.release() waits for it, and your own FollowJointTrajectory client should wait for it (ros2 control list_controllers) or retry a rejected goal. A slave still out of OP after 60 s stops the bus and fails the start, pointing at ethercat slaves and the kernel log. Ctrl-C during the wait stops the bus at once; nothing was released, so no brake waits to be confirmed.
The master decides the wait for OP

IgH configures the slaves one at a time and holds a DC slave short of OP until its clock is within 10 µs of the reference clock, for up to 5 s. The wait depends on how far each slave's clock starts from the reference. One measured start began at 42 µs and converged at about 20 µs/s; the whole wait was 2 to 11 s on the two reference drives.

Terminal output​

RunWhat the terminal shows
DefaultA short summary before the start (bus name, axes and modes, cycle, master, approval), then warnings, errors, the bus node's own lines (waiting for OP, bench evidence) and the spawners' lines. run sets --log-level warn and PLEM_LOG_LEVEL=warn, keeping a PLEM_LOG_LEVEL you already set (a value that is not a level is reported and dropped)
--verboseEvery node's log
The bench's runAlways verbose; the output goes to the bench log for diagnosis
PlotJugglerIts output goes to plotjuggler.log in the run directory, named in the summary

Controllers and commands​

AxesControllerInterface
cspjoint_trajectory_controller (open loop; every trajectory ends at rest)<ns>/joint_trajectory_controller/follow_joint_trajectory (control_msgs/action/FollowJointTrajectory). Bus.move_to uses it, and so can any other client (MoveIt has not been tried)
csv, cststream_controller<ns>/stream_controller/commands (std_msgs/Float64MultiArray, best effort). One value per stream axis, in the order of the controller's joints parameter, in the axis's unit (rad/s, Nm)

The stream controller:

  • stops writing 50 ms after the last message, and the bus's own 50 ms command watch then latches a protective stop: about 100 ms after the last message. csp axes have no such gap, because the plan is the command.
  • leaves no command when it is deactivated (ros2 control switch_controllers), so the watch stops the whole bus, every axis, about 50 ms later. To move again, activate it, stream, then reset() and release().
  • on a bus without a torque axis, is watched only while the bus is released. Before the release nothing latches.
  • on Jazzy, fails to deactivate if every command interface is locked at that moment, logs it and leaves the last commands. Stop the bus then.
  • before its first message commands 0 rad/s on a velocity axis and nothing on a torque axis. That is why a bus with a torque axis streams before the release.

A cycle writes the bus only when every axis has a command, so on a mixed bus a silent stream holds back the position axes too.

note
Late samples and LIMIT_STOP reason 5

The controller manager runs on its own clock beside the bus loop, so the loop can read a sample late. A csp command written with its planned velocity is advanced by that velocity × the sample's age, so a late sample does not trip the one-cycle step check. The advance follows when the loop actually woke, while the check uses the nominal cycle. On a fast axis, a wake gap longer than cycle × velocity_rad_s / speed trips the check (LIMIT_STOP reason 5). An axis at 90 % of its velocity limit trips at a gap of about 1.1 cycles, roughly 111 µs late at 1 ms. That frame carries the whole move and the drive takes it in one cycle, so stopping is the safe outcome. Late wakes show in loop_jitter_us, and an overrun of the previous cycle (deadline_miss) is one cause. With the realtime group and isolated CPUs (Prerequisites) this is rare.

Command checks​

Position and velocity commands are not clipped. Instead of being applied, these cause a protective stop:

  • A position command outside the position limits, or farther than one cycle's travel (velocity_rad_s × cycle) from the previous one.
  • A velocity command larger than velocity_rad_s.

Both are judged after conversion to drive counts, so a value right at a limit can fall either side by rounding. velocity_cap_rad_s, the limit run writes into the robot description, leaves room for that rounding: a trajectory planned below it stays inside the check.

The first position command after a release is compared with the position held since the release (the measured position on a bus with a torque axis). Farther than one cycle's travel is a stop; closer is applied, and the axis moves. limits.torque_nm clips the commands of cst axes only; the torque a drive produces in csp or csv is bounded by its own 0x6072.

ROS interfaces​

InterfaceTypeMeaning
<ns>/joint_statessensor_msgs/JointStateMeasured position, velocity and torque from joint_state_broadcaster, at about 100 Hz (the cycle rate when that is slower). Every cycle is on rt_raw. Names are the file's axis names
<ns>/plem_drive/statusplem_drive_msgs/DriveStatusProtective stop, operation_enabled (every axis in Operation enabled and in its declared mode), brakes, statusword (0x6041). A level report, not a timing source
<ns>/plem_drive/rt_eventsplem_rt_msgs/RtEventEvents. An event's time is its monotonic_ns; header.stamp is the publish time
<ns>/rt_rawplem_rt_msgs/RtRawBatchEvery control cycle, up to 40 cycles or 40 ms per message, best effort. Same format as the robot's
<ns>/plem_drive/infoplem_drive_msgs/DriveInfoPublished once at start and latched
<ns>/plem_drive/control_commandplem_rt_msgs/srv/SetControlCommandThe table below

rt_raw carries every axis of the bus (up to 8; axis_count says how many): measured values, applied_command (the target actually sent that cycle, in the mode's unit, after clamping and rounding; NaN for a position word that cannot be represented), command_position and command_velocity (the command given to csp and csv axes), timing, working counter, and dc_sync_monitor_ns (the DC deviation per cycle; always 0 with sync_mode: drive_default; 4294967295 = no value that cycle).

info carries the scanned PDO mapping digests in the file's slave order (an empty string for a declared mapping) and each axis's modes_of_operation, the 0x6060 value: 10 cst, 8 csp, 9 csv.

SetControlCommand fieldMeaning
release_brakeRelease
protective_stopStop: on a bus without a torque axis the requested stop, otherwise an immediate disable (Stopping)
reset_errorDrive fault reset and protective-stop clear. Asynchronous: watch status
free_driveAlways refused

protective_stop together with release_brake or free_drive in one request runs the stop only. The other fields, reset_error included, are ignored, and the response is success: false naming them.

Release responses and refusal messages​

An accepted release_brake or protective_stop answers with a message that starts with requested and names what to watch (status.operation_enabled, status.brake_engaged). Scripts judge by success, not by the text.

An accepted release can still be refused a cycle later at the readiness gate: the response says success: true while the brakes stay engaged. Confirm the release on status and read the cause on rt_events; the bench adds the cause to its timeout messages.

A refused release says what to do with names such as reset_error, status, approval.status and plem drive run (bench, --unapproved). Internal names in the message read as follows:

Name in the messageWhat it means
DriveHost::resetThe reset_error request
DriveHost::writeThe torque command of a stream axis (<ns>/stream_controller/commands)
stopping ("a stop is still running …")An internal value not in status. Release again once every axis's brake_engaged bit is set and brake_operation_pending is 0

rt_events​

The events a drive bus usually shows. The other constants are explained in the comments of ros2 interface show plem_rt_msgs/msg/RtEvent. Compare against the constants (RtEvent.SLAVE_NOT_OPERATIONAL in Python, RtEvent::SLAVE_NOT_OPERATIONAL in C++), not the numbers.

event_typeNameFieldsWhat to do
98 (0x62)SLAVE_NOT_OPERATIONALjoint_id = axis, error_code = the slave's AL state (0 offline or not readable, 1 INIT, 2 PREOP, 4 SAFEOP, 8 OP with a reconfiguration pending), value = ring positionThe bus starts only once every slave is in OP, so a slave has usually left OP since. Look in the kernel log (sudo dmesg | grep -i ethercat) for an AL status code or a refused startup SDO (startup_sdo, or dc.write_cycle_time's 0x1C32:02)
97 (0x61)OPERATION_ENABLED_LOSTjoint_id = axis, error_code = statuswordA released axis left Operation enabled (a drive fault, for example). A protective stop latches and every brake is forced to engage. Recover
95 (0x5F)MODES_OF_OPERATION_MISMATCHjoint_id = axis, error_code = statusword, value = 0x6061 displayThe axis has no frame yet, an unrecognized statusword, or a display other than its declared mode. Check mode and mode_display_timing. An enabled axis that leaves its mode (a protective stop) shows here too
92 (0x5C)BRAKE_SEQUENCE_STALLEDjoint_id = axis, error_code = statusword, value = the step not reachedThe brake sequence did not progress. It does not say why: a transition missing from the table, a drive that does not answer and exhausted automatic fault resets all end here. Read the drive state from statusword
78 (0x4E)LIMIT_STOPjoint_id = axis, error_code = reason (below), value = the offending valueA protective stop on a limit, one event per axis
79 (0x4F)RAMP_STOP_TIMEOUTvalue = seconds since the requestA requested stop was not confirmed in time and Quick stop was commanded. Reset before the next release
84 (0x54)COMMAND_STALEvalue = the command's age (s)The command stream went silent and the bus stopped

LIMIT_STOP reasons: 1 position, 2 velocity, 3 position not representable, 4 position command range, 5 position command one-cycle step, 6 velocity command, 7 command not representable.

Stopping​

SituationWhat happensWho does it
Commands stop arriving (silent stream, or the controller manager stops writing)Stale command → protective stop → neutral on every axis → forced brake engagePLEM
A position or velocity command breaks a limitProtective stop in that cycle: position axes keep the previous target, the others go neutral. From the next cycle, neutral and forced brake engagePLEM
Ctrl-C (SIGINT) or SIGTERM to plem drive runControllers off, hardware deactivated, stop, brake engage confirmed, bus released. A bus without a torque axis takes the requested stopPLEM
The process is killed (SIGKILL)Communication stops and the drive's output sync manager watchdog actsThe drive
You want to stopprotective_stop (Bus.stop()): the requested stop on a bus without a torque axis, otherwise an immediate disable. Neither latches a protective stop unless the requested stop times out. The service answers at once; watch the brakes in statusPLEM
A SIGKILL stop is not a guarantee

It is a drive setting, outside PLEM. A declared mapping must enable the output watchdog to pass, but its time is the drive's default, and a scanned slave is not checked at all.

Cancelling a FollowJointTrajectory goal is not a stop

When MoveIt or a CLI cancels a goal, the trajectory controller holds the measured position at once. Stop a moving bus with protective_stop.

Requested stop​

On a bus of position and velocity axes, protective_stop and the end of a run are a requested stop. PLEM ramps each command from its current speed to rest at limits.acceleration_rad_s2, never back past rest, and ignores your commands meanwhile.

  • Engaged after the ramp: the brakes close and no protective stop latches, so the bus can be released again without a reset.
  • QuickStop: every drive in Operation enabled gets Quick stop, slows at its own 0x6085 and ends in the state its 0x605A selects (2 = Switch on disabled). A protective stop latches and rt_events gets RAMP_STOP_TIMEOUT; reset before the next release.
  • After the 2 s, a drive still in Quick stop active gets Disable voltage. If its 0x6085 has not stopped the axis by then, the axis loses power while moving.

Set 0x6085 and 0x605A in startup_sdo too, and keep acceleration_rad_s2 no higher than 0x6085 (Drive model file §4.10). The Quick stop step and 0x605A = 2 have not run on hardware.

Immediate disable​

A protective stop on a limit, a command gap or lost communication, and every stop on a bus with a torque axis, use the standard CiA 402 disable sequence, not Quick stop.

  • PLEM does not slow a moving axis down before the disable. The drive decides: on Disable operation by its option code 0x605C and deceleration (typically 0x6084), on lost communication by its fault reaction 0x605E (typically at 0x6085). Set them in startup_sdo.
  • With slow factory values an axis stopped at speed keeps turning for a long time. The A6B's factory value was measured at about 0.75 rad/s².
  • Deceleration, brake timing and how a gravity-loaded axis behaves differ per drive.
  • A position axis's neutral is that cycle's measurement, not a promise to hold a fixed position. 0 rad/s on a velocity axis is no evidence of zero torque or an engaged brake.

Brake engage confirmation​

The controller manager's exit code does not tell whether the brakes engaged. An engage the bus cannot confirm is logged as an ERROR with each axis's statusword. An axis still in Fault at the end of the stop is listed separately: PLEM could not take it through the disable sequence, so its engage could not be confirmed. Whether the drive engaged its brake on its own (servo off, alarm action) is not watched. Next time, send reset_error and wait until status leaves Fault before stopping.

Recover from a protective stop​

  1. On a bus with a torque axis, stream again first; a reset without commands trips again at once. Resending the command that broke a limit trips again too (on a bus of position and velocity axes, once it is applied after the next release).
  2. Call reset_error.
  3. Wait until protective_stop in status reads 0; the request is asynchronous.
  4. Call release_brake (Bus.release()).

The same order applies after a requested stop that timed out.

An axis stopped outside its position limits does not recover this way

Reset is refused while it is outside, and the drive layer cannot move it back. Recover the axis outside PLEM.

Python plem.drive​

from plem.drive import Bus, SCurve

Bus uses only the bus's standard ROS interfaces (robot description, joint_states, status, the control service, controller_manager/switch_controller, the trajectory action, the stream topic). It spins ROS on its own thread, so a call blocks only its caller.

NameMeaning
Bus(name, *, timeout=10.0)Attaches to the plem drive run whose bus.name is name (a leading / is accepted). Waits for the robot description, joint_states and status; after timeout s without them, DriveError naming the bus and asking whether plem drive run is up
bus.axesAxis names (tuple, file order)
bus.positions, bus.velocitiesAxis name → rad, rad/s (dict)
bus["axis"]One axis: .position, .velocity, .move_to(x). An unknown name raises KeyError
bus.statusThe latest plem_drive_msgs/DriveStatus: operation_enabled, the bit masks brake_engaged and protective_stop, statusword
bus.default_profileThe default move_to profile, Trapezoid()

timeout also bounds the waits below. Errors are DriveError (the bus refused or failed; the message is the bus's reason), ValueError (a check before sending) and KeyError (an unknown axis name).

MethodWhat it doesReturns when
reset()Sends reset_error for drive faults and the protective stop. Logs the axes in fault as a ROS warning first (statusword, and the error code when the bus reported one)The bus reports neither
release()On a bus with position axes, waits for the trajectory controller to be active, then re-activates it so it holds where the axes are, not where an earlier goal left them. Then requests the releaseEvery axis is in Operation enabled with its brake released
move_to(goals, *, velocity_scale=1.0, acceleration_scale=1.0, profile=None)Plans one move of every position axis to goals ({axis: rad}) and sends it. Axes not named stay. Scales are in (0, 1]Every axis is within 1 mrad of its goal
stream(commands)Sends one cycle's command to every stream axis: rad/s on csv, Nm on cst. Puts them in the stream controller's orderAt once; nothing re-sends it, so call it every cycle
stop()Calls protective_stop, then cancels the running moveEvery brake is engaged

After release() the axes hold until moved: a velocity axis on a bus without a torque axis holds 0 rad/s until the first stream command, and on a bus with a torque axis the live stream's command applies at the release.

reset() raises DriveError when something remains, naming the protective stop's source and the axes in fault. INTERNAL is a limit still broken; EXTERNAL is the bus, the command stream, or a drive leaving Operation enabled or its declared mode. The cause itself is on rt_events.

release() raises DriveError:

  • at once, before or after the request, when an axis is in fault under fault_reset.policy: none, naming the axes and statuswords. Call reset() first. Many drives latch an alarm when the bus stops. The client never resets a fault itself; under bounded_auto_reset the bus does, and release() waits for it.
  • when the bus refuses the release or it trips (a slave not in OP, an axis not in its declared mode). From the second status after the service answers, brakes engaged with no brake operation pending is taken as the outcome. While an earlier brake operation is still pending, it may wait out the timeout. The message names the SLAVE_NOT_OPERATIONAL or MODES_OF_OPERATION_MISMATCH events received since the request (the AL state, or the 0x6061 display and statusword), or says to see rt_events.
  • when the trajectory controller cannot be restarted.

Once this client has streamed, keep stream() running from a thread through release() and reset() (0 rad/s holds a csv axis). If after the request the bus still reports the EXTERNAL stop while this client's stream is silent (more than 0.1 s since the last stream()), both raise DriveError at once instead of waiting out the timeout. Revive the stream thread and call the method again.

move_to() raises before anything moves:

  • ValueError: a name is not a csp axis, or a planned point leaves the file's position limits, velocity (velocity_cap_rad_s) or acceleration (at the points, and as the average speed change between them).
  • KeyError: an unknown name.
  • DriveError: the axes are not released.

During the move it raises DriveError with the bus's reason when the controller refuses or fails the move, stop() cancels it, the bus stops on its own before arrival, the bus sends no status or joint states for a second, or the axes are not within 1 mrad of their goals by the timeout (a coarse encoder may not settle that close). After a silent second during the move, check that plem drive run is up; if it is, the move continues, so call stop().

stream() sends nothing and raises:

  • ValueError: a value outside the file's limits (limits.velocity_rad_s on csv, the min and max of limits.torque_nm on cst, or non-finite), a position axis named, a stream axis missing, or a bus with no stream axis.
  • KeyError: an unknown name.
  • DriveError: a cst axis whose robot description has no torque limits (written by an older plem drive run). Restart plem drive run.

Each value is checked alone; a csv axis's acceleration is not. When the calls stop, the bus takes a protective stop about 100 ms after the last one (50 ms for the stream controller + 50 ms for the command watch, plus a cycle and the delivery); on a bus without a torque axis, only while released. stream() may be called before release(), and on a bus with a torque axis it must be.

Leaving a with block calls stop(), then closes the client, however the block ends (Ctrl-C included). On a normal exit a failing stop raises DriveError; on an exception the original exception propagates. close() alone only detaches the client: released axes stay released, holding.

ProfileMeaning
Trapezoid()The default (bus.default_profile)
SCurve(jerk=None)Jerk-limited. The default jerk makes each axis reach its acceleration limit in 0.1 s

A move of several axes is one straight line in joint space, so the axes start and stop together. Only the segment boundary points are sent, and the trajectory controller's spline follows each segment between them. For your own profile, subclass Profile and implement plan(start, goal, limits, scale) -> trajectory_msgs/JointTrajectory, starting at start at t = 0 and ending at rest at goal. Its points get the same limit check.

--monitor output​

One line a second from rt_raw, under a header repeated every 20 lines. Each state change gets a line of its own (HH:MM:SS -> <state>), and Ctrl-C prints the totals for the whole run, the wait for OP included: samples, lost, execution max, period deviation max, p99 and p99.9, overruns and working-counter errors. On a terminal, lines with overruns, working-counter errors or lost samples are yellow, and a fault, a protective stop or a brake not confirmed on is red (NO_COLOR turns colour off). Each column name carries its unit; /s is a count in that second.

ColumnMeaning
timeWhen the line was printed
exec-mean[us], exec-max[us]Loop execution time (loop_exec_us), mean and max
pdev-p99[us], pdev-max[us]Period deviation, |actual − nominal| wake-to-wake period (loop_jitter_us), p99 and max. Not lateness against a schedule
overrun/sCycles whose execution took longer than the period (deadline_miss)
wkc-err/sCycles with a wrong working counter; every cycle while a slave is not yet in OP
lost/sGaps in the sample sequence, from publisher overflow and DDS loss alike. A restarted bus, seen when the sequence goes back, starts a new count
dc-max[ns]Max of dc_sync_monitor_ns. 0 cannot tell DC off from a real 0; cycles without a value are skipped
stateThe last status in words: no status yet, every statusword 0 (drives not reporting yet), held, brakes on (every brake confirmed engaged), brake operation pending, released; in red protective stop INTERNAL|EXTERNAL (…), axisN fault (statusword 0x…, error 0x…), axisN brake not confirmed on

Percentiles use 0.1 µs bins up to 1000 µs and report the bin's upper edge, never above the exact max. Values above 1000 µs show the exact max.

Bench and approval​

Only the file's approval block enables motion, and the software judges that record. The bench comes with the plem-drive package; plem drive run offers it for an unapproved file, and for an approved file whose drives differ from its record. The required items and their pass criteria are in Drive model file §6.1; plem drive check --json prints the file's required_bench_items.

Before it starts​

It refuses before touching the bus or the drives when the robot stack or another drive bus holds the master, or the master is not Idle. Every axis must start inside the file's position limits, and the model file must be yours, with it and its directory writable. A file whose approval no longer holds, or an approved file benched again, is benched like an unapproved one and its record replaced; the confirmation says why. check's warnings are shown first and do not stop it.

The confirmation​

One question ([y/N]; no, end of input or Ctrl-C touches nothing). It states how many releases follow and asks whether you are at the drive with the Emergency Stop in reach, gravity-loaded axes are propped, axes not in the file are held by their own brakes or mechanics, and no brake is shared by several axes. On a bus with a position or velocity axis and no torque axis, it also says each such axis moves once, up to 0.5 rad either way: clear the workspace on both sides.

During the bench​

  • It starts the same chain as plem drive run --unapproved, as its child, on the same --master.
  • It releases and engages the brakes three times, four on a bus with a csv axis and no cst axis. A release holds every axis: a position axis at its position, a velocity axis at 0 rad/s, a torque axis at the 0 Nm the bench streams.
  • A released axis held at rest that moves more than 0.005 rad aborts the bench and engages the brakes.
  • A drive fault already present before the bench (an alarm a previous run left; its cause is not examined) is cleared with one reset_error once every axis reports its state, logged as a WARN and kept in the approval record. A drive still in Fault stops the bench; clear the drive alarm and run again.
  • On a bus with position or velocity axes and no torque axis, stop-decel moves every such axis together once, toward its roomier side, up to 0.5 rad at no more than 0.3 × the speed cap, and calls protective_stop during the cruise to measure the deceleration. On a bus with a torque axis the stop is an immediate disable, so this item is NA.

On two axes coupled as mirror images, the bench moves are mirrored only when the limits and the rest positions make them so; otherwise the two drives push against each other through the coupling. Uncouple them for the bench, or narrow one axis's limit so the moves mirror.

Drive comparison and warnings​

Warnings do not block the approval and are kept in the record (conditions.notes).

  • Before starting the bus it reads the drive's supported modes (0x6502). A file mode the drive does not support stops the bench before any brake opens.
  • It warns when the drive's polarity (0x607E) and the file's flip are both set.
  • It warns when the drive's scaling objects (0x6092, 0x6091, 0x608F) report one motor turn as a whole count other than the file's encoder_resolution. Objects the file's startup_sdo writes are judged by that value. A read failure skips the comparison and does not stop the bench.
  • For position and velocity axes it shows the stop values the file does not declare, as the drive holds them now, in lines you can paste into startup_sdo.
  • At the end it reports whether an encoder position changed by a turn or more across the bench. Axes moved by stop-decel may turn several times through a gearhead and are not judged, so on a bus with csp or csv axes only cst axes are.
  • It reports whether the drive's internal limit (statusword bit 11) was active during the bench. Following error (bit 13) is not reported: PLEM does not use it, and it can be on in normal running.

Result​

  • On success the approval, with the bench evidence inside it, is written into the model file. The approval block is replaced in place, or added at the end; every other byte is kept, and the write is atomic (a temporary file in the same directory, then a rename, permissions kept). The recording step judges the approval; the bench only carries measurements. run then starts the bus.
  • If the file changed during the bench (another digest), recording is refused.
  • Any other outcome leaves the model file as it was and writes my_drive.bench.log, whose path is printed. The log is rewritten on every confirmed run; a refusal or decline before the confirmation prints one line and writes nothing. Move a log you need before running again.

Later starts​

An approved file starts without a question. Before every start the drives on the bus (serial number, revision number, 0x1009, 0x100A, the scanned mapping) are compared with the record; nothing is configured or moved. Another unit of the same model, or a changed identity value, is offered the bench on a terminal and refused without one. Another model, a missing drive, or drives in another order than at the bench (restore the cabling) are refused with the bus's message.

What voids an approval

An approval survives software updates. It is voided by changing a value in the file, replacing a drive, or an update that raises the bench requirements (the CHANGELOG says so). Benching the same file again replaces the record.

What an approval proves​

It judges that the records agree: the file, the bench evidence it carries and the live drive. It does not judge that the measurements are true. At start only the recorded fields are compared:

  • A field recorded as null is not compared, so the approval holds when it changes: revision_number (SII revision number), hardware_version (0x1009), software_version (0x100A, the firmware), and pdo_mapping_digest (the scanned mapping of a scanned slave).
  • A serial number of 0, or none recorded, leaves no unit to bind to. The approval then applies to every drive with the same vendor and product code, within the recorded fields; a scanned slave with a recorded pdo_mapping_digest must also have the same mapping. Drives that report serial 0 (Neuromeka, for example) are approved per model, not per unit.