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., 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.
| Field | Meaning |
|---|---|
bus_ | The file's bus.; the bus runs as /<bus_. A file without it is refused, with what to write |
| Two digests | The file's settings and its transition table. bus. is not in them, so renaming the bus keeps the approval |
implementation_ | This software's revision |
approval_, approval_ | The approval state the file claims, and the one that holds |
required_ | The bench items this file's axis modes need |
approve_ | Why the bench could not record an approval, or null |
sync_ | The file's bus.: dc_ or drive_ |
| Axis and slave addresses | Values the bench uses |
reasons | Why a claimed approval does not hold |
not_ | What check leaves to the start of the bus |
warnings | Warnings. They do not refuse the file or change the exit code |
warnings names:
- A position or velocity axis whose
startup_leaves a stop object (0x605A, 0x605C, 0x6084, 0x6085) to the value stored in the drive.sdo - A DC slave whose
sync0_is 0.shift_ ns - An axis whose
limits.reaches past what the drive's 32-bit position (0x6064) can report with itsposition zero_andoffset_ count flip. The range is printed. - A slave that still has the example's
vendor_0x00c0ffee. The next step then says to replace the example's values instead of offeringid plem drive run.
axes[i] carries what plem drive run builds from:
| Field | Meaning |
|---|---|
mode | The axis's operating mode |
position_, position_ | Position limits; null on an axis without end stops |
velocity_ | Velocity limit |
velocity_ | The 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_ | Stop deceleration; null on a cst axis |
torque_, torque_ | A cst axis's limits.; null on other axes |
slaves[i] describes one drive. axes[i]. is an index into this list.
| Field | Meaning |
|---|---|
ring_ | The drive's position on the ring |
vendor_, product_ | The identity the file declares, as integers (0x00c0ffee prints as 12648430) |
pdo_ | scanned when the bus reads the mapping from the drive at start, otherwise declared. A file's generated prints declared |
startup_ | What 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]
| Option | Meaning |
|---|---|
--master N | The IgH master number. Default 0 |
--rt-cpu N | The CPU the bus loop is pinned to. Default: the last isolated CPU (/sys/). A CPU this process may not run on is refused at start, with the isolated list; whether it is isolated is not checked |
--monitor | Bus timing in the same terminal, one line a second (--monitor output) |
--plot | Starts rt_ and PlotJuggler on this bus (PlotJuggler). Refused before anything starts when PlotJuggler or plotjuggler_ is missing |
--unapproved | Runs 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 |
--verbose | Every node's log in the terminal |
How run decides to start:
The diagram follows run. (--unapproved skips the approval branch).
- Same-name check. It looks for another
plem drive runof yours on that namespace (its controller manager orrobot_). 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.state_ publisher - 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 (
continuouson an axis without end stops) andvelocity_as the velocity limit. The controller manager's update rate is the bus cycle. Its update thread is kept off the isolated CPUs and thecap_ rad_ s --rt-cpuCPU when another CPU is available. The bus loop runs atSCHED_priority 98, with no option to change it.FIFO - Exec.
runbecomes 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 startedonce the domain's working counter is complete. On a bus with acspaxis, the trajectory controller becomes active a moment later:Bus.waits for it, and your own FollowJointTrajectory client should wait for it (release() ros2 control list_) or retry a rejected goal. A slave still out of OP after 60 s stops the bus and fails the start, pointing atcontrollers ethercat slavesand the kernel log. Ctrl-C during the wait stops the bus at once; nothing was released, so no brake waits to be confirmed.
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
| Run | What the terminal shows |
|---|---|
| Default | A 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_, keeping a PLEM_ you already set (a value that is not a level is reported and dropped) |
--verbose | Every node's log |
| The bench's run | Always verbose; the output goes to the bench log for diagnosis |
| PlotJuggler | Its output goes to plotjuggler. in the run directory, named in the summary |
Controllers and commands
| Axes | Controller | Interface |
|---|---|---|
csp | joint_ (open loop; every trajectory ends at rest) | <ns>/ (control_). Bus. uses it, and so can any other client (MoveIt has not been tried) |
csv, cst | stream_ | <ns>/ (std_, 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.
cspaxes have no such gap, because the plan is the command. - leaves no command when it is deactivated (
ros2 control switch_), so the watch stops the whole bus, every axis, about 50 ms later. To move again, activate it, stream, thencontrollers reset()andrelease(). - 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.
LIMIT_ STOP reason 5The 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_ / speed trips the check (LIMIT_ 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_, and an overrun of the previous cycle (deadline_) 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_× cycle) from the previous one.rad_ s - 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_, 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. clips the commands of cst axes only; the torque a drive produces in csp or csv is bounded by its own 0x6072.
ROS interfaces
| Interface | Type | Meaning |
|---|---|---|
<ns>/ | sensor_ | Measured position, velocity and torque from joint_, at about 100 Hz (the cycle rate when that is slower). Every cycle is on rt_. Names are the file's axis names |
<ns>/ | plem_ | Protective stop, operation_ (every axis in Operation enabled and in its declared mode), brakes, statusword (0x6041). A level report, not a timing source |
<ns>/ | plem_ | Events. An event's time is its monotonic_; header. is the publish time |
<ns>/ | plem_ | Every control cycle, up to 40 cycles or 40 ms per message, best effort. Same format as the robot's |
<ns>/ | plem_ | Published once at start and latched |
<ns>/ | plem_ | The table below |
rt_ carries every axis of the bus (up to 8; axis_ says how many): measured values, applied_ (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_ and command_ (the command given to csp and csv axes), timing, working counter, and dc_ (the DC deviation per cycle; always 0 with sync_; 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_, the 0x6060 value: 10 cst, 8 csp, 9 csv.
SetControlCommand field | Meaning |
|---|---|
release_ | Release |
protective_ | Stop: on a bus without a torque axis the requested stop, otherwise an immediate disable (Stopping) |
reset_ | Drive fault reset and protective-stop clear. Asynchronous: watch status |
free_ | Always refused |
protective_ together with release_ or free_ in one request runs the stop only. The other fields, reset_ included, are ignored, and the response is success: false naming them.
Release responses and refusal messages
An accepted release_ or protective_ answers with a message that starts with requested and names what to watch (status., status.). 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_; the bench adds the cause to its timeout messages.
A refused release says what to do with names such as reset_, status, approval. and plem drive run (bench, --unapproved). Internal names in the message read as follows:
| Name in the message | What it means |
|---|---|
DriveHost:: | The reset_ request |
DriveHost:: | The torque command of a stream axis (<ns>/) |
stopping ("a stop is still running …") | An internal value not in status. Release again once every axis's brake_ bit is set and brake_ is 0 |
rt_ events
The events a drive bus usually shows. The other constants are explained in the comments of ros2 interface show plem_. Compare against the constants (RtEvent. in Python, RtEvent:: in C++), not the numbers.
event_ | Name | Fields | What to do |
|---|---|---|---|
| 98 (0x62) | SLAVE_ | joint_ = axis, error_ = the slave's AL state (0 offline or not readable, 1 INIT, 2 PREOP, 4 SAFEOP, 8 OP with a reconfiguration pending), value = ring position | The 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_, or dc.'s 0x1C32:02) |
| 97 (0x61) | OPERATION_ | joint_ = axis, error_ = statusword | A 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_ | joint_ = axis, error_ = statusword, value = 0x6061 display | The axis has no frame yet, an unrecognized statusword, or a display other than its declared mode. Check mode and mode_. An enabled axis that leaves its mode (a protective stop) shows here too |
| 92 (0x5C) | BRAKE_ | joint_ = axis, error_ = statusword, value = the step not reached | The 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_ | joint_ = axis, error_ = reason (below), value = the offending value | A protective stop on a limit, one event per axis |
| 79 (0x4F) | RAMP_ | value = seconds since the request | A requested stop was not confirmed in time and Quick stop was commanded. Reset before the next release |
| 84 (0x54) | COMMAND_ | value = the command's age (s) | The command stream went silent and the bus stopped |
LIMIT_ 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
| Situation | What happens | Who does it |
|---|---|---|
| Commands stop arriving (silent stream, or the controller manager stops writing) | Stale command → protective stop → neutral on every axis → forced brake engage | PLEM |
| A position or velocity command breaks a limit | Protective stop in that cycle: position axes keep the previous target, the others go neutral. From the next cycle, neutral and forced brake engage | PLEM |
Ctrl-C (SIGINT) or SIGTERM to plem drive run | Controllers off, hardware deactivated, stop, brake engage confirmed, bus released. A bus without a torque axis takes the requested stop | PLEM |
| The process is killed (SIGKILL) | Communication stops and the drive's output sync manager watchdog acts | The drive |
| You want to stop | protective_ (Bus.): 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 status | PLEM |
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.
When MoveIt or a CLI cancels a goal, the trajectory controller holds the measured position at once. Stop a moving bus with protective_.
Requested stop
On a bus of position and velocity axes, protective_ and the end of a run are a requested stop. PLEM ramps each command from its current speed to rest at limits., never back past rest, and ignores your commands meanwhile.
Engagedafter 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 andrt_getsevents RAMP_; reset before the next release.STOP_ TIMEOUT - 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_ too, and keep acceleration_ 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_ and wait until status leaves Fault before stopping.
Recover from a protective stop
- 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).
- Call
reset_.error - Wait until
protective_instop statusreads 0; the request is asynchronous. - Call
release_(brake Bus.).release()
The same order applies after a requested stop that timed out.
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_, status, the control service, controller_, the trajectory action, the stream topic). It spins ROS on its own thread, so a call blocks only its caller.
| Name | Meaning |
|---|---|
Bus(name, *, timeout=10.0) | Attaches to the plem drive run whose bus. is name (a leading / is accepted). Waits for the robot description, joint_ and status; after timeout s without them, DriveError naming the bus and asking whether plem drive run is up |
bus. | Axis names (tuple, file order) |
bus., bus. | Axis name → rad, rad/s (dict) |
bus["axis"] | One axis: .position, .velocity, .move_. An unknown name raises KeyError |
bus. | The latest plem_: operation_, the bit masks brake_ and protective_, statusword |
bus. | The default move_ 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).
| Method | What it does | Returns when |
|---|---|---|
reset() | Sends reset_ 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 release | Every axis is in Operation enabled with its brake released |
move_ | 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 order | At once; nothing re-sends it, so call it every cycle |
stop() | Calls protective_, then cancels the running move | Every 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_.
release() raises DriveError:
- at once, before or after the request, when an axis is in fault under
fault_, naming the axes and statuswords. Callreset. policy: none reset()first. Many drives latch an alarm when the bus stops. The client never resets a fault itself; underbounded_the bus does, andauto_ reset 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
statusafter 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 theSLAVE_orNOT_ OPERATIONAL MODES_events received since the request (the AL state, or the 0x6061 display and statusword), or says to seeOF_ OPERATION_ MISMATCH 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_ raises before anything moves:
ValueError: a name is not acspaxis, or a planned point leaves the file's position limits, velocity (velocity_) or acceleration (at the points, and as the average speed change between them).cap_ rad_ s 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.onvelocity_ rad_ s csv, the min and max oflimits.ontorque_ nm cst, or non-finite), a position axis named, a stream axis missing, or a bus with no stream axis.KeyError: an unknown name.DriveError: acstaxis whose robot description has no torque limits (written by an olderplem drive run). Restartplem 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.
| Profile | Meaning |
|---|---|
Trapezoid() | The default (bus.) |
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_, 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_, under a header repeated every 20 lines. Each state change gets a line of its own (HH:), 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_ turns colour off). Each column name carries its unit; /s is a count in that second.
| Column | Meaning |
|---|---|
time | When the line was printed |
exec-mean[us], exec-max[us] | Loop execution time (loop_), mean and max |
pdev-p99[us], pdev-max[us] | Period deviation, |actual − nominal| wake-to-wake period (loop_), p99 and max. Not lateness against a schedule |
overrun/ | Cycles whose execution took longer than the period (deadline_) |
wkc-err/ | Cycles with a wrong working counter; every cycle while a slave is not yet in OP |
lost/ | Gaps 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_. 0 cannot tell DC off from a real 0; cycles without a value are skipped |
state | The 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_.
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/; 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
csvaxis and nocstaxis. 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_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.error - On a bus with position or velocity axes and no torque axis,
stop-decelmoves every such axis together once, toward its roomier side, up to 0.5 rad at no more than 0.3 × the speed cap, and callsprotective_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.stop
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.).
- 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
flipare 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_. Objects the file'sresolution startup_writes are judged by that value. A read failure skips the comparison and does not stop the bench.sdo - 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-decelmay turn several times through a gearhead and are not judged, so on a bus withcsporcsvaxes onlycstaxes 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
approvalblock 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.runthen 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_, 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.drive. bench. log
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.
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
nullis not compared, so the approval holds when it changes:revision_(SII revision number),number hardware_(0x1009),version software_(0x100A, the firmware), andversion pdo_(the scanned mapping of amapping_ digest scannedslave). - 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
scannedslave with a recordedpdo_must also have the same mapping. Drives that report serial 0 (Neuromeka, for example) are approved per model, not per unit.mapping_ digest