Skip to main content

Drive model file

This is the key reference for the YAML file (schema: cia402_drive/v1) used in Connecting a servo drive. When a message from plem drive check or plem drive run cites schema §4.1, it means section §4.1 on this page. How the bus runs, checks commands, stops and benches is in Drive bus API. Where a rule was run on hardware, the page says so. The scope of that testing is in Hardware evidence.

§1 Required keys and omissions​

Every key is required except in the places listed below. A missing key is refused, and no default stands in for a value you have to choose. Leaving a key out has a meaning only here:

Key left outMeaning
cia402_profileThe built-in CiA 402 transition table (§4.8)
dc with bus.sync_mode: drive_default, pacing with fault_reset.policy: noneA switched-off feature takes no sub-block. Writing it is refused
limits.torque_nm on a csp or csv axis, limits.acceleration_rad_s2 on a cst axisEach belongs to the other modes (§4.4). Writing it is refused
stored_sdo on a slaveNo stored value is read (§4.9)
write_cycle_time in a dc block0x1C32:02 is not written (§5)
approvalUnapproved (§6)
mode_display_timingpre_enable (§4.2a)
factors.position, and the unit of position and velocityrotary_motor_encoder, the only value (§4.2)
error_code_pdoError code (0x603F), only when the slave's mapping carries it (§4.2)
bus.nameThe loader reads the file, but plem drive check and run refuse it (§4.5)

"No value" has a fixed spelling: null (error_code_pdo, approval.record, identity fields, limits.position of an axis with no end stops) or [] (startup_sdo, pdos of a mailbox SM). A key the schema does not list is refused too, so a typo cannot pass as an omission. A feature this version does not support (§9) is refused.

§2 File format​

The loader reads a narrow subset of YAML.

ItemRule
DocumentOne per file. One leading --- is allowed. No directives (%YAML)
Forbidden syntaxAnchors and aliases (&, *), every explicit tag (!!int too), block scalars (|, >), the merge key <<. Nesting up to 16 levels
KeysString keys only. A duplicate key is refused
booltrue and false only, unquoted. yes and on are refused
nullnull only. ~ and empty values are refused
IntegerDecimal without a leading zero, or 0x hex. +, _, 0X, negative hex, 1536.0 and quotes are refused. Negative values only in signed fields (zero_offset_count, dc.sync0_shift_ns). Out of range is refused, never wrapped
RealFinite values such as -1.5 and 2e-3. .5, 1., +1.0, .inf and nan are refused. An integer literal (121) is accepted
StringQuote a value that would read as a number, bool or null (12, true, 0x1f). Control characters are refused
Encoding, sizeUTF-8 only, up to 1 MiB

Where a refusal points:

  • A syntax error gives the line and column. An encoding error gives the byte offset.
  • Every other refusal gives the key path in the file, such as slaves[1].axes[0].channel or slaves[0].axes[1].limits.position. A refusal about one drive of a ring_position list starts with for the drive at slaves[e].ring_position[copy]:.
  • plem drive check --json numbers axes flat (axes[i]). With PLEM_LOG_LEVEL=debug the loader logs the mapping axes[i] = slaves[s].axes[k] (name).

§3 Top-level shape​

schema: cia402_drive/v1 # §10 — the only accepted string
model: { name: my_drive } # §4.5 — keep the file's own revision in a comment
bus: { name: my_drive, cycle_time_ns: 1000000, sync_mode: drive_default } # §4.5, §5
fault_reset: { policy: none, pulse_ms: 0 } # §4.6
# cia402_profile: [...] # §4.8 — only for a drive that differs from the standard
slaves: # §4.1 — one entry per drive, at least one
- ring_position: 0
vendor_id: 0x00c0ffee
product_code: 0x00001001
pdo_mapping: scanned
startup_sdo: [] # §4.7
axes: # §4.2 — this drive's axes, at least one
- name: j0
channel: 1
mode: csp # §4.2b — cst | csp | csv, per axis
mode_display_timing: post_enable # §4.2a
factors:
gear_ratio: 100.0
encoder_resolution: 65536
torque: { unit: scaled_current, counts_per_amp: 50.0, torque_constant: 0.12 }
velocity: { velocity_factor: 1.0 }
flip: false
zero_offset_count: 0
error_code_pdo: null # §4.2 — required with a scanned mapping
limits: # §4.4
position: { min_rad: -3.05, max_rad: 3.05 }
velocity_rad_s: 2.6
acceleration_rad_s2: 5.0 # csp and csv axes; a cst axis writes torque_nm instead
# approval: ... # §6 — left out = unapproved; the bench writes it

The values only show the shape. They come from no real drive.

  • Joint order is the order of axes in the file. Joints cannot alternate between drives (j0 on drive A, j1 on B, j2 on A).
  • A bus carries up to 8 axes.
  • The file is read once, when the bus starts. Nothing overrides its values. To change it, stop and start again.
  • A relative path is relative to the working directory and ~ is not expanded. Use an absolute path.

§4 Drives and axes​

One entry in slaves is one physical drive (one EtherCAT slave). One entry in its axes is one CiA 402 axis, which the host sees as one joint.

§4.1 slaves: drives and PDO mapping​

KeyValue
ring_positionThe drive's position on the ring (the number ethercat slaves shows). Any order. A duplicate is refused. A list declares identical drives (below)
vendor_id, product_codeThe values ethercat slaves -v shows. 0 is refused. If the drive at that position differs, the start stops and the message shows both (the configuration declares vendor 0x… product 0x…, but the slave at that ring position is …). plem drive check warns while the example's vendor 0x00c0ffee is still there
pdo_mappinggenerated, scanned or a declared mapping (below)
dc§5
startup_sdo§4.7. [] for none
stored_sdoOptional, §4.9. For none, leave the key out ([] is refused)
axesThis drive's axes. An empty list is refused

pdo_mapping takes one of three forms.

ValueWhat PLEM doesUse it when
generatedBuilds a mapping from the axes and writes it to the drive in PREOPThe drive accepts remapping and needs only the objects PLEM reads and writes. Up to four axes per drive
scannedReads the drive's current mapping at start, checks that the required entries are there, and uses it as is. Writes nothingThe drive does not accept remapping
sync_managers: (declared)Writes this mapping to the drive in PREOPThe drive needs specific PDOs, or other objects such as touch probes or digital inputs

generated. Per axis, in channel order, each object at that axis's channel address:

PDOSMObjects
RxPDO 0x1600 + channel − 1SM 2, watchdog onControlword (0x6040), Modes of operation (0x6060), the mode's target (cst 0x6071, csp 0x607A, csv 0x60FF)
TxPDO 0x1A00 + channel − 1SM 3Statusword (0x6041), Modes of operation display (0x6061), position, velocity and torque actual value (0x6064, 0x606C, 0x6077), Error code (0x603F)

The PDO numbers per channel are PLEM's choice, not a CiA 402 rule. A drive that does not accept them refuses at PREOP→SAFEOP. For such a drive, declare a mapping its manual allows, or use scanned. On hardware, generated has run on two A6B drives (csp).

scanned.

  • A required entry that is missing is refused before activation. The message names the drive, its revision and the entry.
  • A quoted "scanned", null and an empty list are refused.
  • The start log has one INFO line with a summary of the mapping and a sha256:… value. With PLEM_LOG_LEVEL=debug it also has the full mapping. Paste that text under pdo_mapping: with matching indentation and it declares the same mapping.

Declared mapping.

pdo_mapping:
sync_managers:
- { sm: 0, direction: output, watchdog: false, pdos: [] } # mailbox SM: pdos: []
- { sm: 1, direction: input, watchdog: false, pdos: [] }
- sm: 2
direction: output # output = master→drive (Rx), input = drive→master (Tx)
watchdog: true
pdos:
- index: 0x1600
entries:
- { index: 0x6040, subindex: 0, bits: 16 }
- { index: 0x0000, subindex: 0, bits: 8 } # index 0 = a gap that takes its width
- { index: 0x6071, subindex: 0, bits: 16 }
- sm: 3
direction: input
watchdog: false
pdos: [ ... ]
  • Up to 4 SMs, 4 PDOs per SM and 16 entries per PDO. An empty sync_managers and an empty entries are refused.
  • Entry addresses are absolute (§4.3).
  • A declared mapping with no output SM set to watchdog: true is refused. The watchdog time is the drive's default (ESI), and PLEM does not set it. That this watchdog stops the drive when PLEM dies is a premise and was not measured. A scanned drive keeps its own SM settings and is not checked.

plem drive check judges, without the drives, whether a generated or declared mapping carries the required entries (common entries plus the mode's target) and whether addresses overlap. The bus judges the same at start. A scanned mapping is judged only at start.

Identical drives. When drive, motor, gearhead and settings are the same, write the positions as a list (ring_position: [0, 1]) in one entry.

  • Only an axis's name, flip and zero_offset_count differ per drive. Write each as a list as long as the positions (name: [axis0, axis1]).
  • Every other key holds for all of them. A drive that differs in any other key gets its own entry.
  • The loader expands the list, so the digests and the approval record are those of the entries written out one by one. slaves[k] in check --json and the debug log counts after the expansion.

§4.2 axes​

KeyValue
nameThe joint name in joint_states. Rules in §4.5
channelWhich CiA 402 axis inside the drive (1–8). Channel n's objects sit (n − 1) × 0x800 above channel 1's: the CiA 402 layout that splits 0x6000–0x9FFF into eight 0x800 blocks
modecst (torque), csp (position) or csv (velocity). §4.2b
mode_display_timingpre_enable (the default) or post_enable. §4.2a
factorsUnit conversion, table below
fliptrue inverts the sign between PLEM and the drive. PLEM does this itself and does not write the drive's Polarity (0x607E)
zero_offset_countThe drive's position count at joint 0 rad (signed 32-bit). The count as the drive reports it, before flip. It is not the drive's Home offset (0x607C) or Position offset (0x60B0), and PLEM writes neither
error_code_pdonull (the drive maps no error code) or { index, subindex, bits }
limitsSafety limits. §4.4

error_code_pdo:

  • Left out, it is Error code (0x603F). You may leave it out only with a generated mapping or a declared mapping that maps 0x603F at that axis's channel. A scanned mapping (read only at start) and a declared mapping without 0x603F need the key.
  • Write index as channel 1's address (0x603F), even on a channel 2 axis (§4.3).
  • index: 0 is refused. To declare none, write null.

factors. Every key is required, except the position and velocity unit, which has one value.

  • The loader checks only the unit names and that numbers are positive. A wrong value still loads.
  • Gear ratio and encoder resolution are written once per axis. The torque, position and velocity conversions all use them.
  • This conversion runs in PLEM. PLEM does not write the drive's Factor group objects (0x608F–0x60A9).
  • Inside PLEM torque is always Nm. It becomes the drive's number once, at the communication boundary, and torque.unit says what that number means.
KeyMeaning
torque.unitThe unit of the drive's torque (0x6071, 0x6077). Each unit takes its own keys, and keys of the other unit are refused. scaled_current: a vendor current count, outside CiA 402. Count = τ × counts_per_amp ÷ (torque_constant × gear_ratio). rated_per_mille: the CiA 402 unit, one count = 1/1000 of the motor rated torque (0x6076). Count = τ × 1000 ÷ (motor_rated_torque_nm × gear_ratio)
torque.counts_per_amp(scaled_current) Current counts per ampere, from the drive manual
torque.torque_constant(scaled_current) Motor torque constant in Nm/A, from the motor nameplate
torque.motor_rated_torque_nm(rated_per_mille) Motor rated torque in Nm at the motor shaft. The drive's 0x6076 is in mNm, so divide by 1000 (0x6076 = 1270 → 1.27)
gear_ratioMotor turns per output-shaft turn. 1.0 without a gearhead. Axis values (limits, commands, joint_states) are in rad, rad/s and Nm at the output shaft. Drive values (startup_sdo, stored_sdo, zero_offset_count, dc) are the drive manual's raw numbers and ignore the ratio. When you change the gearhead, change this and the axis values together
position.unit, velocity.unitrotary_motor_encoder only. Position count = rad × encoder_resolution × gear_ratio ÷ 2π
encoder_resolutionPosition (0x6064) counts per motor turn, an integer. It equals the motor's encoder resolution only while the drive's electronic gear is 1:1
velocity.velocity_factorPosition counts per velocity count (1.0 = the same unit). Take it from the 0x606C unit in the drive manual. A wrong value silently skews the velocity limit and the joint_states velocity
warning
A wrong motor_rated_torque_nm skews every torque

Every torque command and measured torque is off by the same ratio. A value too large makes commands weaker. A value too small makes them stronger, up to the end of the drive's torque range.

The bench reads 0x6076 once. If it differs from this value by more than 1 % (at least 1 mNm), the bench warns and records the warning in the approval record (conditions.notes). The bench does not stop. A missing object, 0, 0xFFFFFFFF or a failed read is not compared.

§4.2a mode_display_timing​

When the drive makes 0x6061 (mode display) follow 0x6060 (requested mode).

ValueDrive behaviour
pre_enable (left out)0x6061 follows before enable
post_enable0x6061 reads 0 until the first enable

pre_enable is the stricter one: release is admitted only once 0x6061 shows the declared mode. A drive that reads 0 at rest and shows the mode only once enabled is refused with MODES_OF_OPERATION_MISMATCH (display 0). The refusal from Bus.release and from the bench tells you to write post_enable. CiA 402 does not say when 0x6061 follows, so this is a drive characteristic, not a fault. Leaving the key out gives the same digest as writing pre_enable. Changing it voids an approval.

§4.2b mode​

mode is the axis's 0x6060 value: cst 10, csp 8, csv 9. It is set per axis, one bus may mix modes, and it is sent every cycle from the start. It does not change while running.

ModeCommand unitController in plem drive runNeutral command
cstNmstream controller0 Nm
cspradtrajectory controllerthat cycle's measured position
csvrad/sstream controller0 rad/s
  • Positions and velocities are joint coordinates relative to zero_offset_count. PLEM applies flip once at the drive boundary.
  • The bus reports the modes as modes_of_operation in info. plem drive check prints them per axis (axes[i].mode with --json).
  • A command goes to the drive only while every axis is Operation Enabled, no Protective Stop is set, and every axis's command passes its check. In any other cycle every axis gets its neutral command.
  • csp and csv commands are not clipped. A command outside the limits is a Protective Stop. A cst torque is clipped to limits.torque_nm. The checks themselves, and what happens right after a release, are in Command checks.
  • plem drive check --json prints axes[i].velocity_cap_rad_s. On a csp axis it is the velocity limit less one position count per cycle (two on an axis with no end stops). plem drive run plans trajectories at or below it.

§4.3 Three kinds of address​

WhereWriteExample: channel 2's object
pdo_mapping entries indexAbsolute addressstatusword 0x6841
error_code_pdo.indexChannel 1's address. PLEM adds the channel offset0x603F (not 0x683F)
startup_sdo, stored_sdo indexAbsolute address0x6860 for channel 2's mode

Writing 0x683F in error_code_pdo makes PLEM look for 0x703F, and the check refuses it when that address is not mapped.

§4.4 limits: safety limits​

The limits have no defaults, and the author of the file is responsible for their values. The loader checks only their form. The checks run in PLEM. PLEM does not write the drive's own limit objects: software position limit 0x607D, velocity 0x607F and 0x6080, Max torque 0x6072, stop deceleration 0x6084 and 0x6085.

KeyUnitRefused whenWhen exceeded
position: { min_rad, max_rad } or nullOutput-shaft rad, relative to zero_offset_countNot finite, or min ≥ max. null with a zero_offset_count other than 0Protective Stop and forced brake engage
velocity_rad_sOutput-shaft rad/sNot finite, or 0 or lessProtective Stop and forced brake engage
acceleration_rad_s2Output-shaft rad/s². csp and csv axes only, required thereMissing or 0 or less on a csp or csv axis. Written on a cst axisNot a limit: the deceleration of a requested stop
torque_nm: { min, max }Output-shaft Nm. cst axes onlyMissing on a cst axis, not finite, not min < 0 < max. Written on a csp or csv axisThe cst command is clipped to it
  • acceleration_rad_s2: write a value the axis can really brake at, no more than the drive's 0x6085 (Quick stop deceleration). It is in the digest, so a csp or csv file approved before this key existed needs the key and a new bench.
  • torque_nm: a csp or csv axis sends no torque command. The drive's own loop makes its torque, bounded by the drive's 0x6072.
  • An axis stopped outside its position limits is not released.
  • plem drive check warns when limits.position reaches past the angles the drive's 32-bit position can show with this zero_offset_count and flip. A limit there does not hold.
  • On an axis with finite limits, a position that cannot be shown as a 32-bit joint count (a very large zero_offset_count with the count at its end) is a Protective Stop, and reset is refused until it can. Such a position reads as one value while the axis moves, so no limit could judge it.

On hardware (A6B), stops for a position command out of range, an axis out of range at start, measured overspeed and a csv command over the limit were seen. A moving axis crossing its position limit was not checked.

Premises. The file has no key for these, so the loader cannot refuse a drive that breaks them.

PremiseWhat it rules out
The brake is power-coupled and holds the load after disableA 0x60FE output brake, an external brake, no brake
Each axis has its own brakeOne brake that releases several axes. The bench approval does not cover such a drive either
The encoder is absoluteAn incremental encoder (below)
Position limits assume an absolute encoder

PLEM has no homing. zero_offset_count and the position limits point at the right place only if the drive reports the same position after every power-on. An incremental encoder restarts its count at power-on, so the limits guard nothing. No key states the encoder type, so neither the loader nor the bench can refuse it. Do not use such a drive. An axis with no end stops (below) has no position limits to guard.

Axes with no end stops​

An output shaft that keeps turning one way writes position: null and zero_offset_count: 0. Any mode works.

zero_offset_count: 0
limits: { position: null, velocity_rad_s: 20.0 } # a cst axis writes torque_nm too

PLEM follows the drive's position frame by frame and counts the turns.

SituationLimitResult
VelocityThe velocity limit is still required and cannot be turned offExceeding it is a Protective Stop
The drive's 32-bit count wrapsNonePosition in joint_states and in commands continues without a break. Velocity and torque are unaffected
PLEM restartsNo stored originCounting starts again from the drive's value (within about ±1608 rad on a 23-bit encoder at gear 1). Command a position axis relative to where it is
Net one-way travel since PLEM started2⁴⁸ counts (23-bit encoder: about 33.5 million motor turns, about 6 days at 400 rad/s or 122 days at 20 rad/s)Protective Stop (LIMIT_STOP reason 3), and reset is refused until PLEM restarts. A position command past it is reason 7
Motion while frames are lostUnder 2³¹ counts (23-bit encoder: 256 motor turns, 2.56 s at 6000 rpm)Beyond it the reported position is off by a multiple of 2³² counts. PLEM does not detect this
Maintenance that changes coordinates (homing, multi-turn clear, drive tool operations, electronic gear or polarity changes)Do it while stopped, then restart PLEMPLEM cannot tell it from motion and counts it

The drive has to meet these conditions. PLEM does not check them.

ConditionHow
The drive's position wraps over the full 32-bit rangeDo not narrow the drive's position range 0x607B, and do not use a vendor continuous-rotation absolute mode
The drive takes a wrap of the position target 0x607A as continuous motionDrive manual
The drive's software position limit 0x607D is offPLEM does not write 0x607D. Write the expected values in stored_sdo so the start warns on a difference (A6B example below)
The drive starts again after travel past its 32-bit rangeThe warning below, and the drive manual (for the A6B: SX-DSV03242 R10.1, p.261 and p.100-101)
stored_sdo: # A6B: software position limit off (607Dh-01h >= 607Dh-02h)
- { index: 0x607D, subindex: 1, size: 4, value: 0 }
- { index: 0x607D, subindex: 2, size: 4, value: 0 }
A drive that refuses the next start

A drive with a multi-turn absolute encoder rebuilds its position from the encoder at power-on and other initializations. Once the axis has travelled one way past the 32-bit range (about ±256 motor turns on a 23-bit encoder with a 1:1 electronic gear), some drives raise a counter overflow alarm and do not start. This holds in every mode (csp, csv, cst), because the encoder always counts turns.

For such a drive, do one of these:

  1. Run the encoder in incremental mode.
  2. Turn on a setting that ignores the overflow and keeps the full 32-bit wrap. On the A6B this is Pr6.98 bit 3 = 1, in function extended version 3 and later. Depending on the electronic gear, the position after a power cycle may differ from before (manual SX-DSV03242 R10.1, p.255-256).
  3. If neither exists, give the axis position limits so it stays inside that range.

On hardware, two A6B drives crossed the 32-bit boundary repeatedly without a break in position or commands. With Pr6.98 bit 3 = 0 (the factory value), they then refused the next start with Err29.1.

At stop, PLEM warns once per axis whose count in that run (starting from the drive's value at start) ended outside the 32-bit range. It cannot see wraps from earlier runs, the drive's own offsets or an electronic gear other than 1:1, so no warning does not guarantee the next start.

§4.5 Names​

KeyRule
model.name1–31 bytes (counted in UTF-8 bytes). Not whitespace only, no control characters. Too long is refused, never cut
axes[].name[a-z_][a-z0-9_]*, at most 31 bytes, unique in the file. It becomes the joint name in joint_states
bus.nameLetters, digits and _, not starting with a digit, at most 64 bytes. plem drive run starts the bus in the namespace /<name>, and Python connects with Bus("<name>"). plem drive check and run refuse a file without it. It is not in the digest, so renaming keeps the approval

§4.6 fault_reset​

One setting for the whole bus.

policypacing
noneNot written
bounded_auto_reset{ interval_ms, max_attempts } required. interval_ms > 0, max_attempts 1–10000

max_attempts is only a count limit. It does not mean that many attempts are safe. interval_ms has to be expressible as a number of control cycles, which is checked at start.

pulse_ms (required, 0–1000) is the minimum time in ms that controlword bit 7 stays on for one fault reset.

  • It applies to every reset, the reset_error request and automatic ones alike, whatever the policy.
  • It becomes a number of frames rounded up to the cycle (at least 1), so 0 is one control cycle. If the drive manual asks for a hold time, write that.
  • In the frame where the axis leaves fault, bit 7 drops, even with time left.
  • PLEM guarantees only the shape of the controlword it sends. Whether the drive reset is shown by status.

§4.7 startup_sdo​

SDO writes made to the drive at start, in order.

startup_sdo:
- { index: 0x6098, subindex: 0, size: 1, value: 35 }
  • Up to 16 per drive. Order and repetition are kept as written. Nothing is merged or sorted.
  • size is 1, 2 or 4 bytes. value is the unsigned value of that width (0 ≤ value < 2^(8 × size)). Negative values are not accepted.
  • index is an absolute address (§4.3).
  • A parameter that takes effect only at power-on gains nothing from a write after power-on. Put the value the drive must hold in stored_sdo.

Objects PLEM writes, or that another key of the file sets, are refused:

ObjectsSet by
PDO assignment and mapping (0x1C10–0x1C2F, 0x1600–0x17FF, 0x1A00–0x1BFF)pdo_mapping
Synchronization (0x1C32, 0x1C33)sync_mode and dc. PLEM writes only 0x1C32:02, for dc.write_cycle_time
Per axis, at its channel address: controlword 0x6040, mode 0x6060, targets 0x6071, 0x607A, 0x60FFPLEM, mode
Per axis: limits 0x607D, 0x6072, 0x6080, Home offset 0x607Climits, zero_offset_count. PLEM does not write these. They are refused only so the file never has two sources for one value

Every other object is accepted, and what it does is the author's responsibility. An unapproved file writes them too, and every write is logged. When the drive refuses a write, PLEM does not point to the startup SDO as the cause.

Written values stay in the drive after PLEM ends

They stay in the drive's RAM until the next power cycle. A different file started afterwards inherits them. On an A6B, torque and position-deviation limits lowered by an earlier test file stayed, and the next file's ordinary move stopped with a position deviation alarm (Err24.0). When you switch to a file that writes fewer objects, power-cycle the drive.

§4.8 cia402_profile​

Left out, every axis uses the built-in transition table: 12 rows, a subset of the standard CiA 402 transitions, with no non-standard row.

The labels are the controlwords PLEM sends. Fault reset is a separate edge (bit 7, §4.6), so there are no fault rows. The rows out of switch_on_disabled (Shutdown) and into it (Disable voltage) come from the standard and have not been confirmed on hardware.

Only a drive that moves differently from the standard writes its own rows at the top level, one list per file for every axis. For example, a drive that takes Shutdown in not_ready_to_switch_on after power-on and goes to ready_to_switch_on writes a 13-row table: that row in front of the built-in rows.

cia402_profile:
- { from: switch_on_disabled, to: ready_to_switch_on, controlword: 0x0006 }
- { from: ready_to_switch_on, to: switched_on, controlword: 0x0007 }
# …
  • State names: not_ready_to_switch_on, switch_on_disabled, ready_to_switch_on, switched_on, operation_enabled, quick_stop_active, fault_reaction_active, fault.
  • Up to 16 rows. An empty list and null are refused. To use the built-in table, leave the key out.
  • The check covers the table's shape: duplicates, required transitions, and that each controlword leads to its target. It does not show that the drive really moves that way.
  • A csp or csv axis needs the row operation_enabled → quick_stop_active (0x0002) for the requested stop. A table without it is refused.
  • plem drive check --json shows profile_source: built_in when the key is left out. If an update changes the built-in table, approvals of files that leave it out are voided (§6).

§4.9 stored_sdo​

Values the drive should have stored (optional). At start the bus reads each once and logs a warning when one differs. PLEM never writes or saves these values, and a difference or a failed read does not stop the start. Each element has the same shape as in startup_sdo.

stored_sdo:
- { index: 0x3401, subindex: 0, size: 4, value: 0 }
- { index: 0x3015, subindex: 0, size: 2, value: 2 }
  • size and value follow startup_sdo. Write a negative value as its two's complement of that width, in hex. Up to 16 per drive. For none, leave the key out ([] is refused).
  • Refused only when malformed: the same address twice in one drive, or an address the same drive's startup_sdo writes. A value written by startup_sdo stays in RAM until the next power cycle, so reading it shows nothing. An object you move to startup_sdo leaves this list.
  • Objects mapped in an output PDO (the master sends them every cycle) and PDO mapping and assignment objects (0x1600–0x17FF, 0x1A00–0x1BFF, 0x1C10–0x1C2F) are not read, with a warning each. 0x1C32 and 0x1C33 have entries the drive fills while running, so list only their stored settings.
  • A match does not mean the value is saved or in effect. Only the current value is read. A value written but not saved matches until the next power cycle.
  • It is outside the approval. Editing stored_sdo in an approved file keeps the approval, and the approval vouches neither for this list nor for the drive's values during the bench.
  • plem drive check cannot read the bus, so it checks only the form.

When the warning says a value differs, it names both ways out:

Which side is rightWhat to do
The file (the drive manual says the object can be written and saved)With PLEM stopped: power-cycle the drive, write the value, save it with CiA 301 0x1010:01 if the drive supports it (see its manual), and power-cycle again if the object takes effect at power-on. Saving usually stores every storable value the drive holds at that moment, so power-cycle first, or an earlier start's startup_sdo writes get saved too
The drive (for example, tuned on this machine)Change stored_sdo in the file

The reads can make the start wait.

  • PLEM sets no timeout of its own. Once a transfer runs, only the EtherCAT master's CoE handling bounds it, so a drive that keeps answering with other mailbox traffic can hold the start.
  • A read that fails without an SDO abort (no answer, a drive without CoE, a mailbox error) is tried again after 0.1, 0.3 and 0.5 s. If the fourth attempt fails, the rest of that drive's values are not read.
  • A start soon after the previous stop can fail these reads. The EtherCAT master (IgH 1.6.13) reads each drive's SDO dictionary once, over the same mailbox, from 3 s after the drive enters PREOP. A read that overlaps it shows ret=-5 (mailbox error) in the warning. The start goes on. To compare, start again after the bus has been idle for a while.

§4.10 Requested stop​

On a bus without a cst axis, while released, protective_stop and the end of a run (Ctrl-C in the plem drive run terminal) first decelerate the axes at limits.acceleration_rad_s2, then engage the brakes. If the stop is not confirmed in time, the drive's own Quick stop takes over and a Protective Stop is set. Any other stop disables at once. The sequence, its times and events are in Drive bus API.

What the file has to give for this stop:

ValueWhere
Deceleration, no more than the drive's 0x6085limits.acceleration_rad_s2 of every csp and csv axis (§4.4)
The drive's Quick stop deceleration 0x6085 and option code 0x605A (a value of 1–3 the drive supports, so it goes to Switch on disabled by itself after stopping)startup_sdo. PLEM does not write them
The stop objects of an immediate stop (0x605C, 0x6084)startup_sdo. plem drive check warns, one line per axis, for each of 0x605A, 0x605C, 0x6084, 0x6085 a csp or csv axis leaves out. The drive keeps its stored value
The row operation_enabled → quick_stop_active (0x0002)cia402_profile, if written. The built-in table has it (§4.8)

The bench item stop-decel measures the average deceleration of this stop (§6.1).

§5 Cycle and distributed clocks​

KeyValue
bus.cycle_time_nsThe control cycle in ns, the same unit as EtherCAT Cycle time (0x1C32:02). 200000–1000000, a multiple of 1000. Anything else is refused, never rounded
bus.sync_modedrive_default or dc_sync0. Anything else is refused
sync_modeWhat PLEM does
drive_defaultTurns on no DC and writes no synchronization. The drive keeps its own setting. The A6B ran Free Run this way (0x1C32:01 and 0x0981 read 0 in OP)
dc_sync0Turns on DC in every drive (AssignActivate, SYNC0 cycle). Every drive writes a dc block

The value names borrow from ETG Sync mode (0x1C32:01).

dc block (only with dc_sync0):

KeyValue
assign_activateNot 0. The AssignActivate of the drive's ESI
sync0_cycle_nsNot 0, a whole multiple of the bus cycle in ns. The multiple is checked only at start
sync0_shift_nsSigned ns. The master delays SYNC0 by this much from the start of the cycle. SYNC0 shift. plem drive check warns on 0
write_cycle_timeOptional, true only (left out = not written, false is refused)

With write_cycle_time: true, PLEM writes 0x1C32:02 = sync0_cycle_ns to each drive once at start (PREOP). It does not write 0x1C32:01 or 0x1C33. Set it only when the drive's ESI or manual lists 0x1C32:02 as rw and says the master sets it. It changes the digest (re-approval).

Drive0x1C32:02write_cycle_time
A6Brw, set by the masterWrite it
MR-J4-TMrw, but the manual does not say :01 follows the DC registers (default Free Run). PLEM does not write :01Unconfirmed
Yaskawa Σ-7S, Inovance SV660N, LS L7NH, Beckhoff AX8000, Omron 1S, Kollmorgen AKDRead-only or absentLeave it out

On a drive where 0x1C32:02 is read-only or absent, the write is expected to be refused (a CoE abort on a read-only object). The drive then stays in PREOP (the kernel log shows an SDO abort on 0x1C32:02) and release is refused with SLAVE_NOT_OPERATIONAL (rt_events).

  • The DC reference clock is the drive with the lowest ring position, whatever the file order. PLEM does not read the drive's 0x1C32.
  • A cycle the drive cannot run is refused by the drive, either at start (PREOP→SAFEOP) or as a sync error that drops it out of OP while running. That is the A6B's documented behaviour and the reference model, not a guarantee for every drive.
  • dc_sync0 has run on hardware on two A6B drives only, with 0x1C32:02 written by hand and with write_cycle_time. PLEM claims no DC support for another drive until it has run there.

SYNC0 shift​

sync0_shift_ns is the master-side SYNC0 shift. PLEM sets the DC reference time when its RT loop wakes, then sends that cycle's frame. SYNC0 fires sync0_shift_ns after that reference time. It is not the drive's own Shift time (0x1C32:03), which the A6B does not support.

SYNC0 has to fire after the cycle's frame has reached the drive, with margin. Choose it relative to the cycle:

  • Above: the host's worst time from wake to send + the frame's transit to the drive + a margin.
  • Below: the cycle − the drive's own processing time (drive manual).

Too small a shift shows as occasional torque spikes or sudden following-error jumps while the targets sent are regular.

Measured on two A6B drives at a 1 ms cycle:

sync0_shift_nsResult
(timing)The frame left about 12 µs after the wake (p99 15 µs, max 55 µs)
0, 20000SYNC0 fired before the frame, and the drives now and then skipped or repeated a cycle's target
300000None in 10 runs

The 300000 in the A6B two-axis example (a6b_pair/drive.yaml) is this measurement. It does not fit a cycle of about 300 µs or less. Other cycles, other drives and the drive-side input shift (0x1C33) have not been run.

§6 approval: the approval record​

Optional. A new file has none, which means unapproved. This shape means the same:

approval:
status: unapproved
record: null

On a terminal, plem drive run offers the bench for an unapproved file and starts the bus once it is approved. Without a terminal it refuses. A run with a person beside the drives can start with --unapproved (Bench and approval). The older words unverified and verified are refused.

  • The bench writes the record into this file. It carries the whole bench evidence (claims, conditions, items), so this file is the only one to keep. How the bench writes it, and when it refuses to: Bench details. A file whose block cannot be found in place (a quoted key, for example) is reported by plem drive check as approve_blocker, and the bench refuses before it starts.
  • Do not write or edit the record by hand. The exception is stored_sdo, which is outside the approval (§4.9). The loader catches only edits that break the checks below. Edits to the evidence's conditions or item descriptions go unnoticed.

An approved file loads only when all of these hold. If any fails, loading fails (it does not fall back to unapproved), and plem drive check shows every reason on its own line (reasons with --json).

  1. The record's digests equal those of the file's settings and transition table now (§7).
  2. The record has one drive identity per drive.
  3. The claims in the embedded bench evidence equal 1 and 2 and the record's implementation_revision, and every item the current software requires is PASS (§6.1). This catches a one-sided edit, such as pasting a new digest from check into the record head only. It does not prove that a bench ran, and an edit that changes both copies goes unnoticed.

An approval survives software updates. implementation_revision records the version the bench ran on and is not compared with the current one. An approval is voided when:

ChangeNote
A value in the file changesComments, indentation, key order, bus.name and stored_sdo do not count (§7). A file without cia402_profile is also voided when an update changes the built-in table
The drive differs from the recorded identity or scanned mappingChecked at start (below)
The embedded evidence no longer matches the record headRestoring it reopens the approval
An update adds a required item or tightens oneThe CHANGELOG says "drive re-bench required" (§6.1)

Bench again with the same file. The bench replaces the record, also in a file whose record no longer holds. A file with an approval that holds is refused by the bench.

At start, before activation, the bus compares the drives with the record: SII serial, SII revision number, 0x1009 (hardware version), 0x100A (software version) and, for a scanned drive, the digest of the scanned mapping. Only recorded fields are compared, and null fields are skipped. A difference or a recorded value that cannot be read refuses the start. A mapping digest mismatch shows both values and does not narrow the cause (drive or firmware replaced, wrong record and so on). Check the nameplate and bench again. Which drives an approval then opens on (identity_scope): Bench details.

The judgment compares records with each other. It does not prove that the measurements are true.

§6.1 Bench file and required items​

The bench (offered by plem drive run for an unapproved file) writes what it measured to this file in a temporary directory, hands it to the C++ judging tool and deletes it. Everything after the schema line is copied into approval.record.bench of the model file, so the bench file is not needed afterwards. Its format is the YAML subset of §2. A record that would push the model file past 1 MiB is refused.

schema: cia402_bench/v1
claims:
config_digest: "sha256:…" # from plem drive check --json
profile_digest: "sha256:…" # same
implementation_revision: "…" # same
slaves:
- { slave: 0, serial_number: 0, revision_number: 0x00000002, hardware_version: "…", software_version: "…", pdo_mapping_digest: "sha256:…" }
conditions: { host: "…", master: "…", date: "YYYY-MM-DD", measured_by: "…", notes: "" }
items:
- { id: assembly-match, result: PASS, evidence: "…" }
# …
  • claims.slaves has one entry per drive, in slaves[] order (after a ring_position list is expanded).
    • serial_number (SII serial) and revision_number (SII revision number, the Revision number of ethercat slaves -v) are integers or null. The two versions are strings of up to 31 bytes or null.
    • Not every field may be empty. A serial of 0 counts as empty, a revision number of 0 counts as read.
    • pdo_mapping_digest: for a scanned drive, the value the benched bus published in info (plem_drive_msgs/DriveInfo), the same as the start log line using the scanned PDO mapping — … sha256:…. For a declared mapping, null.
  • items: result is PASS, FAIL or NA. A duplicate id is refused.

The axis modes decide which items are required.

idChecksRequired on
assembly-matchThe bus assembled the file's values, the axes in joint_states and the scanned mapping digestsEvery bus
idle-non-oeBefore start, no axis is Operation EnabledEvery bus
start-rtsoAfter start, every axis rests with its brake engaged (Switch on disabled or Ready to Switch On), nothing pending, no Protective Stop, inside its position limitsEvery bus
release-oeRelease makes every axis Operation Enabled, a second release does nothing, and a released axis at rest does not driftEvery bus
stale-engageStopping the stream is a stale command, then Protective Stop and forced brake engageA bus with a csv or cst axis
stop-decelA category 1 stop of moving axes: no RAMP_STOP_TIMEOUT, every axis at rest and braked, each axis's average deceleration at most 1.1 × limits.acceleration_rad_s2A bus with a csp or csv axis and no cst axis
disable-engageprotective_stop at rest: disabled, braked, nothing pending, no Protective StopEvery bus
stop-quiesceSIGINT to the controller manager while released: exit code 0, the hardware plugin logged brakes confirmed engaged on stop and not brakes were NOT confirmed engaged on stop, no process of the run left, the master Idle, no axis enabled afterwardsEvery bus

What each item does during the bench, and what the bench warns about: Bench details.

  • If a required item is missing or not PASS, the file is not approved. FAIL is refused for any item. An item the drive does not offer is written NA or left out.
  • Items not required may be NA or absent. On a bus of csp axes only, stale-engage is NA.
  • An existing approval on a bus with a cst axis still holds. On a bus with csp or csv axes and no cst axis, an approval without stop-decel needs a new bench.
  • plem drive check --json shows the current software's required items as required_bench_items.

When an update makes an item's pass criteria stricter, that item gets a new id (stale-engage → stale-engage-2). Old evidence lacks the new id, so the approval is voided, and the CHANGELOG of that update says "drive re-bench required".

Drives where one brake serves several axes are outside this approval

The judgment cannot check whether a brake is shared (§4.4).

On hardware, the bench with stop-decel has approved files on two A6B drives (csp axes and a csv copy). A bus with a cst axis has not been benched on hardware.

§7 What the digest covers​

config_digest is taken over the checked meaning of the file, not its text.

Changes the digest (voids an approval)Does not
Any value, including model.name and axis namesComments, indentation, mapping key order
The order of slaves, axes, sync_managers, pdos, entries, startup_sdo0x0600 vs 1536 (integers compare by value)
mode_display_timing, write_cycle_time: true, acceleration_rad_s2Leaving out mode_display_timing vs writing pre_enable
The resolved transition table (profile_digest too)bus.name, stored_sdo, the approval block

§8 What is checked where​

CheckedBy
Format, keys, value ranges, names, limits, SDO lists, transition table, approval recordThe loader. plem drive check and plem drive run judge the same
Required entries and overlap of a generated or declared mappingplem drive check without drives, and the bus at start
A scanned mapping, sync0_cycle_ns as a multiple of the cycle, drive identity against the record, stored_sdo valuesThe bus at start only
Whether factors, flip and the limits fit the machine, the brake and the encoder typeNobody. The bench covers part of it (§6.1)

§9 Not provided​

These are refused, whatever their value:

  • An axis's ramp block (the old in-loop ramp). The message says to delete it. The client plans motion (the trajectory controller of plem drive run, Bus.move_to of Python plem.drive), and stops decelerate at limits.acceleration_rad_s2. A file without ramp keeps the digest it had before the key was retired.
  • axes[].brake.coupling and axes[].extra_sdo.
  • unit: raw, and any mode other than cst, csp and csv.

PLEM also has no homing, no mode switch while running, no feed-forward, and no IO slaves (other slaves on the bus stay at the master default, PREOP).

§10 Version and renamed keys​

The loader accepts only schema: cia402_drive/v1. A change that every existing version 1 file still loads under, with the same values and digests, stays in version 1. What blocks motion is the approval (§6), not the version.

Files written for 0.10 use older key names. They are refused (the new key is reported missing, or the old one as unknown or not an accepted value). Rename them as below. The digests do not change, so an existing approval stays valid.

0.10Now
cia402_profile[].control_wordcontrolword
axes[].mode_displaymode_display_timing
serial in the approval record and in bench claims.slavesserial_number
pdo_mapping: standardpdo_mapping: generated
bus.sync_mode: smbus.sync_mode: drive_default