Drive model file
This is the key reference for the YAML file (schema: cia402_) 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 out | Meaning |
|---|---|
cia402_ | The built-in CiA 402 transition table (§4.8) |
dc with bus., pacing with fault_ | A switched-off feature takes no sub-block. Writing it is refused |
limits. on a csp or csv axis, limits. on a cst axis | Each belongs to the other modes (§4.4). Writing it is refused |
stored_ on a slave | No stored value is read (§4.9) |
write_ in a dc block | 0x1C32:02 is not written (§5) |
approval | Unapproved (§6) |
mode_ | pre_ (§4.2a) |
factors., and the unit of position and velocity | rotary_, the only value (§4.2) |
error_ | Error code (0x603F), only when the slave's mapping carries it (§4.2) |
bus. | The loader reads the file, but plem drive check and run refuse it (§4.5) |
"No value" has a fixed spelling: null (error_, approval., identity fields, limits. of an axis with no end stops) or [] (startup_, 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.
| Item | Rule |
|---|---|
| Document | One per file. One leading --- is allowed. No directives (%YAML) |
| Forbidden syntax | Anchors and aliases (&, *), every explicit tag (!!int too), block scalars (|, >), the merge key <<. Nesting up to 16 levels |
| Keys | String keys only. A duplicate key is refused |
| bool | true and false only, unquoted. yes and on are refused |
| null | null only. ~ and empty values are refused |
| Integer | Decimal without a leading zero, or 0x hex. +, _, 0X, negative hex, 1536.0 and quotes are refused. Negative values only in signed fields (zero_, dc.). Out of range is refused, never wrapped |
| Real | Finite values such as -1.5 and 2e-3. .5, 1., +1.0, .inf and nan are refused. An integer literal (121) is accepted |
| String | Quote a value that would read as a number, bool or null (12, true, 0x1f). Control characters are refused |
| Encoding, size | UTF-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].oraxes[0]. channel slaves[0].. A refusal about one drive of aaxes[1]. limits. position ring_list starts withposition for the drive at slaves[e]..ring_ position[copy]: plem drive check --jsonnumbers axes flat (axes[i]). WithPLEM_the loader logs the mappingLOG_ LEVEL=debug 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
| Key | Value |
|---|---|
ring_ | The drive's position on the ring (the number ethercat slaves shows). Any order. A duplicate is refused. A list declares identical drives (below) |
vendor_, product_ | The 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_ | generated, scanned or a declared mapping (below) |
dc | §5 |
startup_ | §4.7. [] for none |
stored_ | Optional, §4.9. For none, leave the key out ([] is refused) |
axes | This drive's axes. An empty list is refused |
pdo_ takes one of three forms.
| Value | What PLEM does | Use it when |
|---|---|---|
generated | Builds a mapping from the axes and writes it to the drive in PREOP | The drive accepts remapping and needs only the objects PLEM reads and writes. Up to four axes per drive |
scanned | Reads the drive's current mapping at start, checks that the required entries are there, and uses it as is. Writes nothing | The drive does not accept remapping |
sync_ (declared) | Writes this mapping to the drive in PREOP | The 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:
| PDO | SM | Objects |
|---|---|---|
RxPDO 0x1600 + channel − 1 | SM 2, watchdog on | Controlword (0x6040), Modes of operation (0x6060), the mode's target (cst 0x6071, csp 0x607A, csv 0x60FF) |
TxPDO 0x1A00 + channel − 1 | SM 3 | Statusword (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",nulland an empty list are refused. - The start log has one INFO line with a summary of the mapping and a
sha256:…value. WithPLEM_it also has the full mapping. Paste that text underLOG_ LEVEL=debug pdo_with matching indentation and it declares the same mapping.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_and an emptymanagers entriesare refused. - Entry addresses are absolute (§4.3).
- A declared mapping with no output SM set to
watchdog: trueis 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. Ascanneddrive 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_) in one entry.
- Only an axis's
name,flipandzero_differ per drive. Write each as a list as long as the positions (offset_ count 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]incheck --jsonand the debug log counts after the expansion.
§4.2 axes
| Key | Value |
|---|---|
name | The joint name in joint_. Rules in §4.5 |
channel | Which 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 |
mode | cst (torque), csp (position) or csv (velocity). §4.2b |
mode_ | pre_ (the default) or post_. §4.2a |
factors | Unit conversion, table below |
flip | true inverts the sign between PLEM and the drive. PLEM does this itself and does not write the drive's Polarity (0x607E) |
zero_ | The 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_ | null (the drive maps no error code) or { index, subindex, bits } |
limits | Safety limits. §4.4 |
error_:
- Left out, it is Error code (0x603F). You may leave it out only with a
generatedmapping or a declared mapping that maps 0x603F at that axis's channel. Ascannedmapping (read only at start) and a declared mapping without 0x603F need the key. - Write
indexas channel 1's address (0x603F), even on a channel 2 axis (§4.3). index: 0is refused. To declare none, writenull.
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.says what that number means.unit
| Key | Meaning |
|---|---|
torque. | The unit of the drive's torque (0x6071, 0x6077). Each unit takes its own keys, and keys of the other unit are refused. scaled_: a vendor current count, outside CiA 402. Count = τ × counts_ ÷ (torque_ × gear_). rated_: the CiA 402 unit, one count = 1/1000 of the motor rated torque (0x6076). Count = τ × 1000 ÷ (motor_ × gear_) |
torque. | (scaled_) Current counts per ampere, from the drive manual |
torque. | (scaled_) Motor torque constant in Nm/A, from the motor nameplate |
torque. | (rated_) 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_ | Motor turns per output-shaft turn. 1.0 without a gearhead. Axis values (limits, commands, joint_) are in rad, rad/s and Nm at the output shaft. Drive values (startup_, stored_, zero_, 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., velocity. | rotary_ only. Position count = rad × encoder_ × gear_ ÷ 2π |
encoder_ | Position (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. | Position 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_ velocity |
motor_ rated_ torque_ nm skews every torqueEvery 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.). 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).
| Value | Drive behaviour |
|---|---|
pre_ (left out) | 0x6061 follows before enable |
post_ | 0x6061 reads 0 until the first enable |
pre_ 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_ (display 0). The refusal from Bus. and from the bench tells you to write post_. 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_. 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.
| Mode | Command unit | Controller in plem drive run | Neutral command |
|---|---|---|---|
cst | Nm | stream controller | 0 Nm |
csp | rad | trajectory controller | that cycle's measured position |
csv | rad/s | stream controller | 0 rad/s |
- Positions and velocities are joint coordinates relative to
zero_. PLEM appliesoffset_ count fliponce at the drive boundary. - The bus reports the modes as
modes_inof_ operation info.plem drive checkprints them per axis (axes[i].withmode --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.
cspandcsvcommands are not clipped. A command outside the limits is a Protective Stop. Acsttorque is clipped tolimits.. The checks themselves, and what happens right after a release, are in Command checks.torque_ nm plem drive check --jsonprintsaxes[i].. On avelocity_ cap_ rad_ s cspaxis it is the velocity limit less one position count per cycle (two on an axis with no end stops).plem drive runplans trajectories at or below it.
§4.3 Three kinds of address
| Where | Write | Example: channel 2's object |
|---|---|---|
pdo_ entries index | Absolute address | statusword 0x6841 |
error_ | Channel 1's address. PLEM adds the channel offset | 0x603F (not 0x683F) |
startup_, stored_ index | Absolute address | 0x6860 for channel 2's mode |
Writing 0x683F in error_ 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.
| Key | Unit | Refused when | When exceeded |
|---|---|---|---|
position: { min_ or null | Output-shaft rad, relative to zero_ | Not finite, or min ≥ max. null with a zero_ other than 0 | Protective Stop and forced brake engage |
velocity_ | Output-shaft rad/s | Not finite, or 0 or less | Protective Stop and forced brake engage |
acceleration_ | Output-shaft rad/s². csp and csv axes only, required there | Missing or 0 or less on a csp or csv axis. Written on a cst axis | Not a limit: the deceleration of a requested stop |
torque_ | Output-shaft Nm. cst axes only | Missing on a cst axis, not finite, not min < 0 < max. Written on a csp or csv axis | The cst command is clipped to it |
acceleration_: 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 arad_ s2 csporcsvfile approved before this key existed needs the key and a new bench.torque_: anm csporcsvaxis 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 checkwarns whenlimits.reaches past the angles the drive's 32-bit position can show with thisposition zero_andoffset_ count 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_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.offset_ count
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.
| Premise | What it rules out |
|---|---|
| The brake is power-coupled and holds the load after disable | A 0x60FE output brake, an external brake, no brake |
| Each axis has its own brake | One brake that releases several axes. The bench approval does not cover such a drive either |
| The encoder is absolute | An incremental encoder (below) |
PLEM has no homing. zero_ 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_. 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.
| Situation | Limit | Result |
|---|---|---|
| Velocity | The velocity limit is still required and cannot be turned off | Exceeding it is a Protective Stop |
| The drive's 32-bit count wraps | None | Position in joint_ and in commands continues without a break. Velocity and torque are unaffected |
| PLEM restarts | No stored origin | Counting 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 started | 2⁴⁸ 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_ reason 3), and reset is refused until PLEM restarts. A position command past it is reason 7 |
| Motion while frames are lost | Under 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 PLEM | PLEM cannot tell it from motion and counts it |
The drive has to meet these conditions. PLEM does not check them.
| Condition | How |
|---|---|
| The drive's position wraps over the full 32-bit range | Do 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 motion | Drive manual |
| The drive's software position limit 0x607D is off | PLEM does not write 0x607D. Write the expected values in stored_ so the start warns on a difference (A6B example below) |
| The drive starts again after travel past its 32-bit range | The 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 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:
- Run the encoder in incremental mode.
- 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).
- 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
| Key | Rule |
|---|---|
model. | 1–31 bytes (counted in UTF-8 bytes). Not whitespace only, no control characters. Too long is refused, never cut |
axes[]. | [a-z_][a-z0-9_]*, at most 31 bytes, unique in the file. It becomes the joint name in joint_ |
bus. | Letters, 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.
policy | pacing |
|---|---|
none | Not written |
bounded_ | { interval_ required. interval_ > 0, max_ 1–10000 |
max_ is only a count limit. It does not mean that many attempts are safe. interval_ has to be expressible as a number of control cycles, which is checked at start.
pulse_ (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_request and automatic ones alike, whatever the policy.error - It becomes a number of frames rounded up to the cycle (at least 1), so
0is 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.
sizeis 1, 2 or 4 bytes.valueis the unsigned value of that width (0 ≤ value < 2^(8 × size)). Negative values are not accepted.indexis 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:
| Objects | Set by |
|---|---|
| PDO assignment and mapping (0x1C10–0x1C2F, 0x1600–0x17FF, 0x1A00–0x1BFF) | pdo_ |
| Synchronization (0x1C32, 0x1C33) | sync_ and dc. PLEM writes only 0x1C32:02, for dc. |
| Per axis, at its channel address: controlword 0x6040, mode 0x6060, targets 0x6071, 0x607A, 0x60FF | PLEM, mode |
| Per axis: limits 0x607D, 0x6072, 0x6080, Home offset 0x607C | limits, zero_. 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.
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_ (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_ after power-on and goes to ready_ 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
nullare 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
csporcsvaxis needs the rowoperation_→enabled quick_(0x0002) for the requested stop. A table without it is refused.stop_ active plem drive check --jsonshowsprofile_when the key is left out. If an update changes the built-in table, approvals of files that leave it out are voided (§6).source: built_ in
§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_.
stored_sdo:
- { index: 0x3401, subindex: 0, size: 4, value: 0 }
- { index: 0x3015, subindex: 0, size: 2, value: 2 }
sizeandvaluefollowstartup_. 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 (sdo []is refused).- Refused only when malformed: the same address twice in one drive, or an address the same drive's
startup_writes. A value written bysdo startup_stays in RAM until the next power cycle, so reading it shows nothing. An object you move tosdo startup_leaves this list.sdo - 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_in an approved file keeps the approval, and the approval vouches neither for this list nor for the drive's values during the bench.sdo plem drive checkcannot read the bus, so it checks only the form.
When the warning says a value differs, it names both ways out:
| Which side is right | What 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_ writes get saved too |
| The drive (for example, tuned on this machine) | Change stored_ 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_ and the end of a run (Ctrl-C in the plem drive run terminal) first decelerate the axes at limits., 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:
| Value | Where |
|---|---|
| Deceleration, no more than the drive's 0x6085 | limits. 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_. PLEM does not write them |
| The stop objects of an immediate stop (0x605C, 0x6084) | startup_. 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_ → quick_ (0x0002) | cia402_, 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
| Key | Value |
|---|---|
bus. | The 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. | drive_ or dc_. Anything else is refused |
sync_ | What PLEM does |
|---|---|
drive_ | Turns 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_ | Turns 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_):
| Key | Value |
|---|---|
assign_ | Not 0. The AssignActivate of the drive's ESI |
sync0_ | Not 0, a whole multiple of the bus cycle in ns. The multiple is checked only at start |
sync0_ | Signed ns. The master delays SYNC0 by this much from the start of the cycle. SYNC0 shift. plem drive check warns on 0 |
write_ | Optional, true only (left out = not written, false is refused) |
With write_, PLEM writes 0x1C32:02 = sync0_ 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).
| Drive | 0x1C32:02 | write_ |
|---|---|---|
| A6B | rw, set by the master | Write it |
| MR-J4-TM | rw, but the manual does not say :01 follows the DC registers (default Free Run). PLEM does not write :01 | Unconfirmed |
| Yaskawa Σ-7S, Inovance SV660N, LS L7NH, Beckhoff AX8000, Omron 1S, Kollmorgen AKD | Read-only or absent | Leave 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_ (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_has run on hardware on two A6B drives only, with 0x1C32:02 written by hand and withsync0 write_. PLEM claims no DC support for another drive until it has run there.cycle_ time
SYNC0 shift
sync0_ 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_ 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_ | Result |
|---|---|
| (timing) | The frame left about 12 µs after the wake (p99 15 µs, max 55 µs) |
| 0, 20000 | SYNC0 fired before the frame, and the drives now and then skipped or repeated a cycle's target |
| 300000 | None in 10 runs |
The 300000 in the A6B two-axis example (a6b_) 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 checkasapprove_, and the bench refuses before it starts.blocker - Do not write or edit the record by hand. The exception is
stored_, 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.sdo
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).
- The record's digests equal those of the file's settings and transition table now (§7).
- The record has one drive identity per drive.
- The claims in the embedded bench evidence equal 1 and 2 and the record's
implementation_, and every item the current software requires isrevision PASS(§6.1). This catches a one-sided edit, such as pasting a new digest fromcheckinto 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_ records the version the bench ran on and is not compared with the current one. An approval is voided when:
| Change | Note |
|---|---|
| A value in the file changes | Comments, indentation, key order, bus. and stored_ do not count (§7). A file without cia402_ is also voided when an update changes the built-in table |
| The drive differs from the recorded identity or scanned mapping | Checked at start (below) |
| The embedded evidence no longer matches the record head | Restoring it reopens the approval |
| An update adds a required item or tightens one | The 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_): 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. 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.has one entry per drive, inslaves slaves[]order (after aring_list is expanded).position serial_(SII serial) andnumber revision_(SII revision number, the Revision number ofnumber ethercat slaves -v) are integers ornull. The two versions are strings of up to 31 bytes ornull.- Not every field may be empty. A serial of 0 counts as empty, a revision number of 0 counts as read.
pdo_: for amapping_ digest scanneddrive, the value the benched bus published ininfo(plem_), the same as the start log linedrive_ msgs/ DriveInfo using the scanned PDO mapping — … sha256:…. For a declared mapping,null.
items:resultisPASS,FAILorNA. A duplicateidis refused.
The axis modes decide which items are required.
| id | Checks | Required on |
|---|---|---|
assembly-match | The bus assembled the file's values, the axes in joint_ and the scanned mapping digests | Every bus |
idle-non-oe | Before start, no axis is Operation Enabled | Every bus |
start-rtso | After start, every axis rests with its brake engaged (Switch on disabled or Ready to Switch On), nothing pending, no Protective Stop, inside its position limits | Every bus |
release-oe | Release makes every axis Operation Enabled, a second release does nothing, and a released axis at rest does not drift | Every bus |
stale-engage | Stopping the stream is a stale command, then Protective Stop and forced brake engage | A bus with a csv or cst axis |
stop-decel | A category 1 stop of moving axes: no RAMP_, every axis at rest and braked, each axis's average deceleration at most 1.1 × limits. | A bus with a csp or csv axis and no cst axis |
disable-engage | protective_ at rest: disabled, braked, nothing pending, no Protective Stop | Every bus |
stop-quiesce | SIGINT 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 afterwards | Every 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.FAILis refused for any item. An item the drive does not offer is writtenNAor left out. - Items not required may be
NAor absent. On a bus ofcspaxes only,stale-engageisNA. - An existing approval on a bus with a
cstaxis still holds. On a bus withcsporcsvaxes and nocstaxis, an approval withoutstop-decelneeds a new bench. plem drive check --jsonshows the current software's required items asrequired_.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".
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_ is taken over the checked meaning of the file, not its text.
| Changes the digest (voids an approval) | Does not |
|---|---|
Any value, including model. and axis names | Comments, indentation, mapping key order |
The order of slaves, axes, sync_, pdos, entries, startup_ | 0x0600 vs 1536 (integers compare by value) |
mode_, write_, acceleration_ | Leaving out mode_ vs writing pre_ |
The resolved transition table (profile_ too) | bus., stored_, the approval block |
§8 What is checked where
| Checked | By |
|---|---|
| Format, keys, value ranges, names, limits, SDO lists, transition table, approval record | The loader. plem drive check and plem drive run judge the same |
Required entries and overlap of a generated or declared mapping | plem drive check without drives, and the bus at start |
A scanned mapping, sync0_ as a multiple of the cycle, drive identity against the record, stored_ values | The bus at start only |
Whether factors, flip and the limits fit the machine, the brake and the encoder type | Nobody. The bench covers part of it (§6.1) |
§9 Not provided
These are refused, whatever their value:
- An axis's
rampblock (the old in-loop ramp). The message says to delete it. The client plans motion (the trajectory controller ofplem drive run,Bus.of Pythonmove_ to plem.), and stops decelerate atdrive limits.. A file withoutacceleration_ rad_ s2 rampkeeps the digest it had before the key was retired. axes[].andbrake. coupling axes[]..extra_ sdo unit: raw, and any mode other thancst,cspandcsv.
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_. 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.10 | Now |
|---|---|
cia402_ | controlword |
axes[]. | mode_ |
serial in the approval record and in bench claims. | serial_ |
pdo_ | pdo_ |
bus. | bus. |