Separating CiA402 Logic from EtherCAT (lcec): Modular Adapter + Drive Stub Valid

Hi,

Now that we won't be getting any support from the German PLC forum, I did some searching myself and found this interesting project. In my opinion, it could serve as a good template, as all the code I've seen so far uses a similar topology.

I would also like to emphasize that there is no need to reinvent the whole concept. We already have functioning components (CIA402; homecomp.comp) that form a good basis. Many thanks to @rodw and @MobiusToast for their excellent pioneering work. What is missing now is the further development of these components.
I fear that even this thread, with its good approach, will ultimately be forgotten.

For my part, I will take a different path.
Since I continue to have homing problems and have now ruled out EMC and configuration errors, I think the problem lies with the A6 itself. Yesterday, it took 3 minutes for the x-axis to start the reference run! 
I will now try to expand my system to include battery-buffered encoders.
At least according to the documentation, this should be possible. This would make homing obsolete.

 

I want to clarify something.

My goal in this thread was never to “reinvent everything”.
It was to separate CiA402 logic from EtherCAT transport and validate it deterministically in SIM before going back to real hardware.

Rodw already showed the essential backbone:

• A proper PDS state machine gate
• Only allow homing/motion after Operation Enabled
• Explicit opmode request (6060) and confirmation (6061)
• Controlled homing start sequence

That is exactly what I am implementing — but modularized and testable without depending on a specific drive.

If someone believes this “will lead nowhere”, that is fine — but then please explain technically why isolating CiA402 logic, adding deterministic state transitions, mask/value evaluation, timeouts, and SIM validation would be a wrong direction.

Negative predictions without technical arguments do not help anyone.

Also, individual hardware purchasing decisions (A6 or anything else) are unrelated to the architectural question being discussed here.

The objective is not to fix one specific drive problem.
The objective is to build a clean CiA402 logic layer that can be validated independently and reused.

If anyone has constructive input (state diagrams, PLCopen-style Execute/Busy/Done patterns, hardware traces, mask definitions, timing constraints), that would be very welcome.

Otherwise, I will continue implementing the modular adapter + PDS manager approach and share results for review.

Quick progress update on this project.

The CiA402 semantic layer has now been fully validated in pure HAL + AXIS SIM.

Current validated behavior:

- Clean separation between PDS state machine and opmode modules
- Deterministic controlword composition (no 6040 ambiguity)
- 6060/6061 handshake confirmed
- Mask/value based statusword evaluation
- Operation Enabled gating exposed as a hard industrial gate
- Fault injection during active homing:
-> immediate abort
-> op-enabled cleared
-> no false “done”
-> clean fault-reset return to OE

All of this is transport-agnostic and does not depend on LCEC or EtherCAT internals.

The next planned step is extending this architecture to dual-axis gantry / squaring validation in SIM, keeping CiA402 logic fully modular.

At this stage I do not have EtherCAT hardware available.
If someone with LCEC + CiA402 hardware would be willing to test the modular stack on real drives, I can prepare:

- Clean HAL example configuration
- Minimal README
- Reproducible test steps
- Fault and homing test scenarios

The goal is to validate that the semantic layer behaves identically when replacing the stub with real PDOs.

Feedback on the gantry direction is also welcome before I proceed further.

I know it's a step to include motion/motmod.
Linuxcnc should be in charge of the movements, that's the whole point.
Motion should do the the homing, and control it (as best as it can).
Motion should also make possible to switch an joint from axis to spindle. 
Or make possible to use EtherCAT probing.
We don't need to invent crazy situations, but the common ones.

What we do now with these components, homecomp, etc and I have done one myself
for Profile Velocity for spindle, is to have the component decouple the real position from motion
and then re-couple it. The right thing to do would be to have motion handle all motions.

I don't expect you to go that route. I just raise the thought.

 

I understand your point about motion being the proper authority for movements.

My current focus is strictly on validating a clean and deterministic CiA402 semantic layer in isolation, before going into deeper motion integration discussions.

As suggested earlier, I think a dedicated thread about motion/motmod integration would be better for that architectural direction.

For now, I will proceed with the next step: extending this modular CiA402 stack toward dual-axis gantry/squaring validation in SIM.

Once the semantic layer is stable and multi-axis behavior is validated, it should be easier to explore tighter motion integration if needed.

Marcos wrote:

If someone with LCEC + CiA402 hardware would be willing to test the modular stack on real drives, I can prepare:

- Clean HAL example configuration
- Minimal README
- Reproducible test steps
- Fault and homing test scenarios


 

I currently have a Lichuan model OL57E-4A 4-axis drive and a Stepperonline model A6-750EC 750 watt servo drive set up on the workbench for testing, I can connect homing and limit switches without too much trouble.
Both are LCEC + CiA402.
The Lichuan manual is available here:  git.gitcoding.net/nwe/lcec_4x_stepper/src/branch/main/manual
The Stepperonline manual is  here .

I'd be willing to test drive your config. It might be a couple days till I find time.

Hi nwe,

That would be extremely helpful, thank you for offering to test.

No rush at all if it takes a couple of days — I will actually be working in the field for the next two days doing maintenance for a client. When I get back, I plan to implement the safety gate component and the decouple/recouple logic, so the timing works out well.

To prepare proper adapter templates for your two drives (the Lichuan OL57E-4A and the Stepperonline A6-750EC), I just need a few details from your setup so I can map the HAL pins correctly.

If possible, could you share:
1. Your LCEC configuration
• lcec.conf (or equivalent configuration file)
• The EtherCAT XML/ENI if you have it
• Or a snippet of the HAL where the lcec.* pins for the drives appear
2. PDO mapping
I mainly need to confirm the HAL pins for the standard CiA402 objects:
• 6040 Controlword
• 6041 Statusword
• 6060 Modes of Operation (command)
• 6061 Modes of Operation Display
If available in PDO as well:
• 6064 Position Actual Value
• 607A Target Position
3. Homing
• Which homing method (object 6098) you plan to use
• Whether the homing/limit switches are connected to the drive inputs
• The HAL pin names for those inputs (for example lcec.*.din-*)
4. Quick Stop
• Is Quick Stop (Controlword 0x0002) configured and usable on these drives?
• Or do they require a different shutdown sequence?
5. Anything unusual
• Any known quirks with enable, fault reset, or homing behavior.

With that information I can prepare two adapter templates (one for each drive) that plug into the CiA402 semantic layer we validated in simulation.

Thanks again for offering to test — having real hardware feedback will be extremely valuable.

I have lichuan too

I'm preparing a small repository for this. The current README draft describes the structure I'm experimenting with.
# linuxcnc-cia402-layer

Vendor-agnostic CiA402 (DS402) semantic layer for LinuxCNC.

Status: experimental reference implementation
Target: LinuxCNC HAL architecture
Focus: deterministic CiA402 semantic separation
License: MIT

This project provides a clean separation between drive semantics,
machine policy and fieldbus transport for CiA402 devices in LinuxCNC.


---

# Overview

This project implements a deterministic HAL architecture that separates:

- Power Drive System (PDS) state machine (6040 / 6041)
- Procedure layer (homing / operation handshake)
- Deterministic controlword composition
- Machine-level safety policy
- Fieldbus adapters (EtherCAT / CANopen / etc.)

The goal is to validate CiA402 semantics in a clean and deterministic way
before involving real fieldbus hardware.

The semantic layer is designed to remain:

- drive-agnostic
- fieldbus-agnostic
- reusable across different servo drives


---

# Motivation

Many CiA402 integrations inside LinuxCNC mix together:

- fieldbus communication
- drive state logic
- machine safety policy
- procedure logic

inside a single component.

This makes systems harder to:

- debug
- validate
- reuse
- maintain

This project separates these responsibilities into clear HAL layers.


---

# Safety Notice

This project provides software-level safety behavior such as:

- controlword gating
- quick stop policy
- fault handling
- machine enable supervision

However, it **does NOT replace hardware safety systems** such as:

- physical E-stop circuits
- STO (Safe Torque Off)
- safety PLC
- certified safety devices

Always implement proper hardware safety according to applicable safety standards.


---

# Architecture Overview

The architecture ensures that machine-level safety always has authority
over drive-level state machines.


Machine Safety Policy
│
▼
safety_gate.comp
│
▼
pds_manager.comp
│
▼
procedure layer (c402hu)
│
▼
cw_compose.comp
│
▼
Fieldbus Adapter (LCEC / CANopen)
│
▼
Drive


LinuxCNC motion interacts with the drive through the semantic layer.


---

# Core Components (Drive-Agnostic)

## safety_gate.comp

Machine-level safety policy.

Responsibilities:

- integrates with halui
- supervises machine enable state
- supervises E-stop state
- blocks procedures when unsafe
- overrides controlword when required

Typical policies:

- Machine OFF → Disable Voltage
- E-stop → Quick Stop
- Fault → block enable until reset

The safety gate sits **above the PDS layer** to guarantee machine authority.


---

## pds_manager.comp

Implements the CiA402 Power Drive System state machine.

Responsibilities:

- decode statusword (6041)
- generate base controlword (6040)
- track DS402 states
- expose HAL signals

Outputs include:

- op_enabled
- fault
- decoded state
- debug mask patterns
- cw_pds


---

## c402hu.comp (Procedure Layer)

Procedure management for CiA402 operations.

Handles:

- mode request (6060)
- mode confirmation (6061)
- homing start generation
- completion detection
- error detection

Responsibilities:

- manage operation sequences
- latch completion states
- detect abnormal conditions

All procedures are gated by:


ut.enable


which is typically controlled by the safety gate.


---

## cw_compose.comp

Single source of truth for the final controlword (6040).

Responsibilities:

- combine PDS controlword
- combine procedure bits
- apply safety overrides

Typical composition:


cw_final = cw_pds | procedure_bits


Safety overrides may replace this value when required.


---

# Coupler (Decouple / Recouple)

Planned component:


coupler.comp


Purpose:

Allow drives to perform internal motion (such as homing)
without creating position jumps in LinuxCNC.

Responsibilities:

- temporarily decouple motion feedback
- follow drive position during internal motion
- recouple after completion

Typical use cases:

- drive-based homing
- drive internal motion procedures
- avoiding position discontinuities


---

# Gantry Support

Future component:


gantry_manager.comp


Possible responsibilities:

- synchronized homing of multiple drives
- gantry squaring
- position difference monitoring
- safe recoupling after homing

This allows coordination of multiple CiA402 drives
in gantry machines.


---

# Fieldbus Adapters

Adapters are intentionally simple.

Example:


adapters/adapter_TEMPLATE.hal


Responsibilities:

- map fieldbus objects to semantic layer pins

Typical mapping:

- 6040 → drive controlword
- 6041 → statusword
- 6060 → mode of operation
- 6061 → mode display
- 6064 → position actual
- 607A → position command

Adapters should contain **no logic**.

They only wire fieldbus data to the semantic layer.


---

# Repository Layout


src/
safety/
safety_gate.comp

pds/
pds_manager.comp

procedure/
c402hu.comp

controlword/
cw_compose.comp

coupler/
coupler.comp

gantry/
gantry_manager.comp

adapters/
adapter_TEMPLATE.hal

sim/
cia402_stub.comp
opc_validation.hal

docs/
architecture.md



---

# Validation Approach

The semantic layer was initially validated using LinuxCNC AXIS simulation.

Simulation includes:

- CiA402 stub drive
- statusword generation
- homing procedure testing
- fault injection

This allows deterministic validation before connecting real hardware.


---

# Current Project Status

Validated:

- PDS state decoding
- deterministic controlword composition
- mode handshake (6060 / 6061)
- homing start/done detection
- fault handling behavior
- operation enabled gating

In progress:

- safety gate implementation
- drive motion decouple / recouple
- gantry synchronization logic
- EtherCAT adapter validation


---

# License

MIT License

Copyright (c) 2026
Marcos Duque Cesar


---

# Project Goal

Provide a clean reference implementation of CiA402 semantics for LinuxCNC HAL that is:

- deterministic
- reusable
- independent of fieldbus drivers
- suitable for different servo drives

1) It may not be a good idea to divide the architecture of a single module too much. This can cause unnecessary complications in the connections between them and race conditions between components...  For example, the state machine of the “homemode” module in some situations cyclically processes several states in one cycle, thanks to its flat structure, which would be difficult to do if it were broken down into modules.


2)

gantry_manager.comp
Possible responsibilities:
- synchronized homing of multiple drives
- gantry squaring

I think this should be handled by the built-in homing and kinematic module, regardless of the communication bus.

I recently encountered this using ethercat drives with absolute encoders - it is already partially successful. 
Alignment occurs during the homing procedure when jointY1 and joint Y2 move independently and synchronously (home sequence) by calling free_tp,
but requires a revision of the procedure for HOME_ABSOLUTE_ENCODER, which is used by cia402/ethercat (github.com/LinuxCNC/linuxcnc/pull/3774/c...be947439e20fc5da9825), to prepare it for correct communication with the cia402 state machine

as a result, squaring control should take place in the trivkins module where, when declaring KINS=XYYZ, the connection is established 
joints[1] = pos->tran.y
joints[2] = pos->tran.y

I don't see the need for another layer  “motion -> trivkins -> gantry.comp -> pid -> cia402 ->lcec”   since we already have independent joints, each of which is connected to feedback for tracking following error.