ECAN-Lite Docs

Reading Guide

This manual is written for users who need to integrate ECAN-Lite, not only for readers who want to understand the firmware internals. After reading it, you should be able to identify the device capabilities, configure EtherCAT PDO/SDO, enter OP, send CAN/CAN FD frames through RxPDO, read CAN/CAN FD frames through TxPDO, and diagnose common problems.

The manual is organized as "integration first, implementation details second, diagnostics last". The first half explains the EtherCAT/PDO/SDO boundary. The second half explains IgH examples, secondary development, and field troubleshooting.

From bring-up to CAN frame exchange

Read by task

Chapter division of labor

When not using IgH at all, read 5.4 and 5.4.3 first. When using the IgH master-side library but not directly running the demo package, read 15.4 and 15.5 first.

1. Product positioning

ECAN-Lite is an EtherCAT to CAN/CAN FD real-time gateway module. The device operates as an EtherCAT slave. The master sends CAN/CAN FD transmit requests through RxPDO, and the device uploads received CAN/CAN FD frames, transmit results, and compact channel status through TxPDO.

This version adopts a new dynamic PDO protocol: TxPDO and RxPDO are independently configured in units of 128B * N, N=1..24, with a maximum of 3072B in one direction. PDO content no longer uses the old layout of fixed channels and fixed slots, but uses a unified "two-layer structure":

FixedPdoFrameHeader[24B] + FramePacketStream[ActivePDOBytes - 24]

The 24B fixed header carries the version/header length, double sequence commit, frame area length, payload CRC16, layout identifier, channel mask, frame count, overflow count, and 4-channel compact status. The following frame area is a continuous stream of CAN/CAN FD frame packets. Each packet uses a 2B control word to describe its CAN ID, timestamp, and data length, so the master does not need the old fixed-slot layout.

2. Core features

3. Direction definition

TxPDO and RxPDO are completely independent directions. PDO size multiples, channel masks, packaging profiles, budget strategies and direction options can be independently selected for each direction. Channel opening and PDO size are two orthogonal dimensions: closing a CAN channel will not change the SM2/SM3 length, but will only change the active channel mask and scheduling budget.

It is useful to read the protocol in three layers:

For a first bring-up, follow 5.4.3 and 5.4.4.1 to send one frame. When implementing your own parser or writer, return to Chapters 6..12 for the field-by-field definition.

3.1 Document markup description

The following tables in this article use the following notation:

Access in the PDO table refers to the master's access method for process data: RxPDO/SM2 is written by the master and read by the slave; TxPDO/SM3 is written by the slave and read by the master.

4. System architecture

EtherCAT Master
  |
  |  SM2 RxPDO: Fixed Header + FramePacketStream
  |  SM3 TxPDO: Fixed Header + FramePacketStream
  v
+------------------------------+
| ECAN-Lite EtherCAT Slave     |
|  SSC + CoE + FoE             |
|  Dynamic PDO Parser/Packer   |
|  Byte Budget Scheduler       |
+-----+-----+-----+-----+------+
      |     |     |     |
     CAN0  CAN1  CAN2  CAN3

5. EtherCAT PDO mapping and size

5.1 128B Chunk Mapping

PDO mapping is assembled from 128B chunks. Each chunk is split into 8 STRING(16) mapping units in the object dictionary to avoid the bit-length limit of a PDO mapping entry.

RxPDO chunk maps: 0x1600..0x1617
TxPDO chunk maps: 0x1A00..0x1A17
SM2 assignment: 0x1C12 selects the first N RxPDO chunks
SM3 assignment: 0x1C13 selects the first N TxPDO chunks

Chunk is the EtherCAT mapping and length selection unit, not the protocol parsing layer. FramePacketStream can span 128B chunk boundaries, and the receiving end only parses the valid frame area according to payload_len in the fixed header.

5.1.1 How the master assembles multiple chunks

On the master side, do not treat 0x1600..0x1617 / 0x1A00..0x1A17 as multiple independent protocols. They are only 128B mapping blocks used to satisfy EtherCAT PDO mapping limits. The application should combine the first N chunks in the same direction into one continuous byte buffer in assignment order:

RxPDO/SM2 output buffer:
  chunk0[128B] + chunk1[128B] + ... + chunkN-1[128B]
  "..." means the omitted chunks continue in the same order, 128B each

TxPDO/SM3 input buffer:
  chunk0[128B] + chunk1[128B] + ... + chunkN-1[128B]
  "..." means the omitted chunks continue in the same order, 128B each

Each 128B chunk contains 8 STRING(16) mapping units. If the master exposes them as separate variables, copy them in the following order:

for chunk = 0 .. N-1:
  for unit = 0 .. 7:
    dst_offset = chunk * 128 + unit * 16
    copy 16 bytes to/from process image entry

The following table expands the 8 mapping units of chunk=0 and shows the first unit of chunk=1. All later chunks follow the formula below.

Complete mapping rules:

General formula:

unit_index = chunk * 8 + unit
offset     = unit_index * 16

RxPDO data object index = 0x7000 + unit_index * 0x10
TxPDO data object index = 0x6000 + unit_index * 0x10

So chunk=1 is not only unit=0. For example, RxPDO 0x1601 contains eight 16B units: 0x7080, 0x7090, ..., 0x70F0. TxPDO 0x1A01 contains 0x6080, 0x6090, ..., 0x60F0. In both examples, ... only omits the middle objects that increase by 0x10.

For example, when N=3, the continuous buffer in each direction is 384B:

chunk0: offset   0..127
chunk1: offset 128..255
chunk2: offset 256..383

The fixed 24B header is located at offset 0 of the continuous buffer. The frame area starts at offset 24 and ends at 128*N-1. CAN_FRAME / TX_RESULT packets may cross 128B chunk boundaries. When parsing, the master must use payload_len and CRC in the fixed header to determine the valid area; it must not restart parsing at a 128B boundary.

In TwinCAT, CODESYS, or a custom master, if the tool can map PDO data to a continuous byte array, create ARRAY[0..128*N-1] OF BYTE. If the tool exposes each STRING(16) as a separate variable, assemble and split the data in the application layer using the offset formula above.

5.2 PDO size multiple

ActivePDOBytes = 128 * PdoSizeMultiplier
ActiveFrameAreaBytes = ActivePDOBytes - 24
PdoSizeMultiplier: 1..24

Choose the recommended value by CAN mode and load instead of using one value for every case. Classic CAN carries at most 8B per frame, so normal motor control, CANopen/CiA402, and small classic CAN traffic should start from N=3. CAN FD carries up to 64B per frame, so four-channel use or burst traffic should start from N=8. N=1/N=2 are intended for minimum-PDO capability checks, single-channel low-speed diagnostics, or very small classic CAN traffic. The maximum value is N=24, which is 3072B/direction.

5.3 SII/EEPROM SyncManager Requirements

Current product EEPROM/SII should maintain a large PDO single buffer layout:

The actual PDO length used by the master is determined by the first N chunks selected by the 0x1C12/0x1C13 assignment, and must be consistent with the active profile of 0x8010/0x8011.

5.4 Without IgH: Third-party EtherCAT master configuration PDO

If the customer does not use the IgH sample package demo, but uses TwinCAT, CODESYS, Acontis, or a self-developed EtherCAT master, it is necessary to explicitly complete the PDO assignment, PDO profile apply, and MCAN channel configuration in the master project. The automatic configuration in the IgH sample package demo essentially corresponds to the following general CoE configuration process.

5.4.1 Select PDO size

The PDO length of ECAN-Lite is determined by the 128B chunk number N:

ActivePDOBytes = 128 * N
N = 1..24

The master must select the first N chunks for both directions:

Example: Select N=3, that is, SM2/SM3 are both 384B:

0x1C12:00 = 0
0x1C12:01 = 0x1600
0x1C12:02 = 0x1601
0x1C12:03 = 0x1602
0x1C12:00 = 3

0x1C13:00 = 0
0x1C13:01 = 0x1A00
0x1C13:02 = 0x1A01
0x1C13:03 = 0x1A02
0x1C13:00 = 3

Example: Select N=8, that is, SM2/SM3 are both 1024B:

0x1C12:00 = 0
0x1C12:01..08 = 0x1600..0x1607
0x1C12:00 = 8

0x1C13:00 = 0
0x1C13:01..08 = 0x1A00..0x1A07
0x1C13:00 = 8

01..08 and 0x1600..0x1607 / 0x1A00..0x1A07 here represent continuous ranges, not jump selections; they are equivalent to writing the 8 assignment sub-items from :01 to :08 one by one.

The SM2/SM3 process data length in the master project should be equal to 128 * N. If the master needs to manually select PDO after importing ESI, please ensure that you select the first N consecutive chunks and do not skip or rearrange chunks.

5.4.2 Application firmware PDO profile

0x1C12/0x1C13 determines the actual mapping length of the master; 0x8010/0x8011 determines the active profile within the firmware. Both sides must be consistent, otherwise the firmware will reject the application or continue to maintain the old profile.

Recommended startup SDO sequence:

1. The slave remains in INIT/PREOP/SAFEOP, do not modify the PDO size in OP
2. Configure 0x1C12/0x1C13 and select the first N chunks
3. Write 0x8010:03 = N
4. Write 0x8011:03 = N
5. Write 0x8010:04 = tx_channel_mask
6. Write 0x8011:04 = rx_channel_mask
7. Write 0x8010:01 = 1, apply TxPDO profile
8. Write 0x8011:01 = 1, apply RxPDO profile
9. Read the active readback of 0x8010/0x8011 and confirm the length and layout
10. Configure 0x8001..0x8004 MCAN channel parameters and apply
11. Enter OP and send and receive CAN/CAN FD frames through PDO during operation.

At minimum, read back and check:

5.4.3 Complete initialization process example: without using IgH / third-party master

This section gives a set of configuration processes that can be directly transplanted to TwinCAT Startup SDO, CODESYS startup parameters, Acontis or self-developed master. Example goals are:

For conservative bring-up, it is recommended to change N to 3, change the channel mask to 0x01, and only enable CAN0. Use N=1 when explicitly verifying the minimum PDO capability.

Option flags is the bitwise configuration value of 0x8010:07 (0x07) and 0x8011:07 (0x07). Commonly used values are as follows, see Section 9.1 for the complete bit table:

Phase A: Read the device capabilities and determine the upper limit of the master configuration.

Phase B: Configuring the EtherCAT PDO assignment. The master writes in the PREOP/SAFEOP phase and selects the first N consecutive PDO chunks.

0x1C12:01..08 = 0x1600..0x1607 means writing 8 sub-items continuously, not a one-time writing range. If N=3, only write :01=0x1600, :02=0x1601, :03=0x1602, and finally :00=3; similarly for TxPDO, write 0x1A00..0x1A02.

Phase C: Configuring the firmware PDO profile. 0x8010 controls the TxPDO/SM3 upload direction, and 0x8011 controls the RxPDO/SM2 delivery direction. Both sides must be configured, and PDO size multiplier must be consistent with the number of assignments in phase B.

If 4-byte alignment is required, write 0x8010:07 (0x07) or 0x8011:07 (0x07) as 0x02 and then apply; if TxPDO is required to send the result packet, set 0x8010:07 (0x07) bit0 to 1.

Phase D: Read the active profile back and confirm that the firmware accepted the requested profile.

In the example, the active profile word is calculated as follows:

bits 0..4   = N - 1 = 7
bits 5..12  = channel_mask = 0x0F
bits 13..18 = profile = 0
bits 19..20 = budget = 0
bits 21..28 = option_flags = 0

ActiveProfileWord = 7 | (0x0F << 5) = 0x000001E7

Therefore, D7/D8 in the above table should be checked according to the actual calculated value: 0x000001E7 when N=8, mask=0x0F, profile=0, budget=0, options=0. If ALIGN4 is enabled, OptionFlags=0x02, the active profile word will additionally contain (0x02 << 21).

Phase E: Configure the MCAN channel. The following example configures CAN0 as CAN FD ISO, with a 1Mbps nominal bit rate, a 5Mbps data bit rate, and a 64B CAN FD Message RAM layout. The example assumes that the peer CAN/CAN FD device uses an 87.5% sample point for both the nominal and data phases, so the sample point range is constrained to 875..875. CAN1..CAN3 use 0x8002, 0x8003, and 0x8004 respectively with the same subindices. In this table, the subindex after the colon in SDO is written as decimal SI, and the hexadecimal SI is shown in parentheses. If your master tool displays subindices in hexadecimal, use the value in parentheses directly.

0x8001:21..24 do not define a fixed sample point for a given bit rate. They constrain the automatic timing solver so that this device uses sample points compatible with the peer CAN/CAN FD device. If the peer sample points are known, set both min and max to the peer target value. For example, if the peer uses 80.0% in the nominal phase and 87.5% in the data phase, write 0x8001:21=800, 0x8001:22=800, 0x8001:23=875, and 0x8001:24=875. If the peer sample points are unknown, start from the peer driver, tool, or device manual recommendation, then verify with CAN error counters and closed-loop frame exchange. Avoid keeping a very wide sample point range as the final production setting for CAN FD+BRS, because the solver may choose a valid timing that is not well matched to the peer.

If only CAN0 is enabled, configure only 0x8001 and set 0x8010/0x8011:04 to 0x01. For classic CAN, set 0x8001:15=0, keep or omit 0x8001:20/23/24/33/34, and set 0x8001:65/66/68/72 to 0 (8B) to save Message RAM.

Stage F: After entering OP, the master periodically writes RxPDO/SM2 and reads TxPDO/SM3. If the slave cannot enter OP, first check the SM2/SM3 length and the number of assignments in stage B; if it enters OP but CAN does not send, check the channel mask and channel apply status of stage C/E first.

5.4.4 PDO packaging and process data writing

The master ultimately operates on the continuous PDO buffer in the EtherCAT process data. Take N=8 as an example:

Generally, the master program operates the RxPDO/TxPDO start pointer in the master process image instead of directly writing the ESC physical address. If the debugging tool directly exposes the ESC DPRAM address, the fixed header of RxPDO is located at 0x1100 + 0, and the first frame of RxPDO is located at 0x1100 + 24; the fixed header of TxPDO is located at 0x1D00 + 0, and the first frame of TxPDO is located at 0x1D00 + 24.

If using TwinCAT/CODESYS, the tool may split the process data into multiple STRING(16) variables; the application needs to first assemble it into a continuous buffer according to Section 5.1.1, and then write or parse according to the offset below. If the master provides a continuous PDO pointer, operate the pointer directly.

The continuous PDO buffer has the layout below. The 24B fixed header describes the frame area state for the current cycle; the actual CAN_FRAME / TX_RESULT packets are stored continuously from offset 24.

5.4.4.1 Build an RxPDO transmit frame from scratch

The following example shows how the master requests ECAN-Lite CAN0 to transmit one standard classic CAN data frame through RxPDO/SM2. The reading order follows the actual write order: write the frame area first, calculate the payload information, then fill the 24B fixed header and commit the PDO image.

This example assumes N=8, RxPDO active channel mask 0x0F, and TX_RESULT, ALIGN4, and scheduled timestamp options disabled.

Step 1: Write the CAN_FRAME at offset 24.

Control word bit combination:

ctrl = channel
     | (dlc << 3)
     | (ide << 7)
     | (fdf << 8)
     | (brs << 9)
     | (x << 10)
     | (tsf << 11)
     | (kind << 13)

In this example:

channel = 0
dlc     = 8
ide     = 0
fdf     = 0
brs     = 0
x       = 0
tsf     = 0
kind    = 0

ctrl = 0x0040
StdIdField = 0x0123
raw_packet_bytes = 2 + 2 + 8 = 12

The bytes starting at offset 24 are:

40 00 23 01  11 22 33 44 55 66 77 88

Step 2: Calculate payload information for this cycle.

CRC-16/CCITT-FALSE parameters are poly=0x1021, init=0xFFFF, xorout=0x0000, with non-reflected input and output.

Step 3: Fill the 24B fixed header. For master-to-slave RxPDO delivery, write the fields below; seq_end must be written last.

Recommended layout_id calculation:

layout_word = ((N - 1) & 0x1F)
            | ((channel_mask & 0xFF) << 5)
            | ((profile & 0x3F) << 13)
            | ((budget & 0x03) << 19)
            | ((option_flags & 0xFF) << 21)

layout_id = (layout_word ^ (layout_word >> 16)) & 0xFFFF

Step 4: Write in commit order to prevent the slave from parsing a half-updated PDO image.

1. Clear the RxPDO buffer, or at least clear the unused frame area.
2. Write all CAN_FRAME packets starting at offset 24.
3. Calculate payload_len, frame_count and payload_crc16.
4. Write fixed header offsets 0..3 and 6..23.
5. Write offset 4..5 seq_end last, with seq_end == seq_begin.

For multiple frames, repeat only the CAN_FRAME packet layout from Step 1: the first packet starts at offset 24, the second packet follows the first packet's packet_bytes, and so on. payload_len is the sum of all packet lengths, and frame_count is the packet count. If ALIGN4 is enabled, the next offset advances by align4(raw_packet_bytes) for each packet; padding bytes must be 0 and are included in payload_len.

TxPDO reads are processed in the opposite direction:

1. Read the 24B fixed header from offset 0 of the SM3/TxPDO continuous buffer.
2. Check seq_begin == seq_end, crc_alg == 1, and payload_len <= ActiveFrameAreaBytes.
3. Calculate CRC16 over offset [24, 24 + payload_len) and compare it with payload_crc16.
4. Starting from offset 24, parse each packet according to the CAN_FRAME packet length.
5. If ALIGN4 is enabled, advance the next packet offset using align4(raw_packet_bytes).
6. If overflow_sat != 0 or STREAM_TRUNCATED=1, the TxPDO data of this cycle may be incomplete.

5.4.5 Common configuration methods of third-party EtherCAT masters

If the master does not support online modification of PDO mapping, N should be fixed during the project configuration phase and avoid switching the PDO size during operation. During runtime, only SM2/RxPDO output data is updated and SM3/TxPDO input data is read.

5.4.6 Quick judgment of configuration errors

Up to this point, Chapter 5 has shown how the master selects the PDO size, applies the firmware profile, and writes one minimal RxPDO frame. Chapters 6..12 define the bytes used by that example: the 24B fixed header, channel status, frame packets, direction options, TX_RESULT, CRC, and multi-channel budget. Readers using the official IgH API can skim these chapters; readers implementing their own parser should follow them field by field.

6. PDO fixed header

TxPDO and RxPDO share the same 24B fixed header. The header uses little-endian fields. In ver_ihl, the high 4 bits are the header version and the low 4 bits are the number of 4B words. The current version is 1 and ihl=6, so the frame area starts from offset 24.

The fixed header is not an SDO object and does not have the RO/RW attribute; its master access direction follows the PDO direction: the RxPDO header is written by the master and parsed by the slave, and the TxPDO header is written by the slave and parsed by the master.

Publishing rules: The sender first constructs the complete frame encapsulation area and header field, and finally writes seq_end = seq_begin; the receiver only parses the payload when seq_begin == seq_end, payload_len <= ActiveFrameAreaBytes, crc_alg=1 and the CRC check passes. This design is used to avoid the master or slave from reading a half-updated PDO.

6.1 Key field explanation and reception judgment

seq_begin, seq_end, layout_id, crc_alg, overflow_sat are not parameters that require separate SDO configuration of the master. They are running status fields carried in the fixed header in each PDO cycle. The master needs to write them according to rules in the RxPDO delivery direction; the master needs to check them according to rules in the TxPDO upload direction.

Notes:

• layout_id is a short identifier in the PDO header. It lets the master quickly detect whether the current PDO layout has changed. For full configuration readback, read 0x8010/0x8011:12 Active profile word and :11 Active layout CRC.
• If overflow_set appears in the document or debugger, it corresponds to this header field overflow_sat: it is not a switch, but "the saturation count after overflow/truncation in this cycle."
• The calculation range of payload_crc16 is the frame encapsulation area, that is, PDO offset [24, 24 + payload_len), which does not include the 24B fixed header.
• payload_len is the actual number of valid frame encapsulation bytes in this cycle, not the total length of PDO. Unused frame areas must be filled with 0.

Recommended judgment sequence for the receiving end:

1. Read fixed header A.
2. Check seq_begin == seq_end; if not equal, ignore the PDO of this cycle.
3. Check crc_alg == 1.
4. Check payload_len <= ActiveFrameAreaBytes.
5. Calculate CRC-16/CCITT-FALSE for payload_len bytes starting at offset 24.
6. Read the fixed header B again; if the key fields of A and B are inconsistent, it means that the PDO was updated during the reading, and this cycle is ignored.
7. Parse CAN_FRAME / TX_RESULT.
8. If overflow_sat != 0 or STREAM_TRUNCATED=1, mark this cycle as incomplete data.

Configuration example: When the master wants both TxPDO/RxPDO to use N=8, CAN0..CAN3, profile 0, Balanced, and disable the direction option:

0x1C12 / 0x1C13: Select the first 8 128B chunks
0x8010:03 = 8     TxPDO PDO size multiplier
0x8010:04 = 0x0F  TxPDO channel mask
0x8010:05 = 0     TxPDO profile 0
0x8010:06 = 0     TxPDO Balanced budget
0x8010:07 = 0x00  TxPDO option flags
0x8010:01 = 1     apply TxPDO profile

0x8011:03 = 8     RxPDO PDO size multiplier
0x8011:04 = 0x0F  RxPDO channel mask
0x8011:05 = 0     RxPDO profile 0
0x8011:06 = 0     RxPDO Balanced budget
0x8011:07 = 0x00  RxPDO option flags
0x8011:01 = 1     apply RxPDO profile

Read 0x8010/0x8011:09..12 after apply. If Active PDO bytes, Active frame area bytes, Active layout CRC, Active profile word are as expected, layout_id in subsequent PDO headers should remain stable.

header_flags：

7. Channel status word

Each channel status is compressed to 16 bits and placed in the PDO header. PDO only carries fast status, detailed reasons are read through SDO.

When warn/bus_off/rx_pressure/tx_pressure/detail_pending is set, the master should read 0x9000..0x9003 to obtain a detailed register and count snapshot. If the error comes from the PDO encapsulation layer, LastPDOError / PDOErrorCounter / PDOOverflowCounter of 0x8010/0x8011 should be read.

8. Frame encapsulation package

Each frame encapsulation packet starts with a 2B control word, which determines the length of subsequent CAN ID, timestamp and data.

The frame encapsulation package follows the PDO direction: CAN_FRAME in RxPDO is the master's request from the slave to send to the CAN bus; CAN_FRAME in TxPDO is received by the slave from the CAN bus and uploaded to the master; TX_RESULT in TxPDO is the slave's transmission result of the frame sent by RxPDO.

Unless otherwise specified, multi-byte values in PDO fixed headers, frame packets, TX_RESULT and SDO use little-endian. On the master side, do not cast unaligned byte buffers directly to host structures. Read and write fields explicitly from the byte stream.

Byte0:
  bit0..2 CH CAN channel id, currently using 0..3
  bit3..6 DLC original CAN DLC, 0..15
  bit7     IDE      0=11bit standard id，1=29bit extended id

Byte1:
  bit0     FDF      0=classic CAN，1=CAN FD
  bit1     BRS      CAN FD bit rate switch
  bit2 X When FDF=0, it is RTR, when FDF=1, it is ESI
  bit3..4  TSF      0=no timestamp，1=delta16，2=delta32，3=full64
  bit5..6  KIND     0=CAN_FRAME，1=TX_RESULT，2=STREAM_META，3=reserved
  bit7     D64      0=data length by DLC，1=fixed 64B data window

The current main process uses KIND=0 CAN_FRAME. KIND=1 TX_RESULT is optionally generated by TxPDO. KIND=2 STREAM_META is reserved for extended capabilities such as whole-stream CRC. KIND=3 must currently be considered illegal.

8.1 CAN_FRAME format

Standard ID:
  Ctrl[2] + StdIdField[2] + Timestamp[0/2/4/8] + Data[0..64] + Padding

Extended ID:
  Ctrl[2] + ExtIdField[4] + Timestamp[0/2/4/8] + Data[0..64] + Padding

StdIdField:

ExtIdField：

ID_AUX suggested semantics:

When not used, the sender must write 0 and the receiver ignores it.

8.2 DLC and data length

DLC<=8, BRS=0, D64=0 in classic CAN. If FDF=0 && X=1, the frame is RTR, and the data length must be 0. X in CAN FD represents ESI, and there is no RTR.

8.3 Packet length calculation

id_bytes = IDE ? 4 : 2
ts_bytes = TSF == 0 ? 0 : (TSF == 1 ? 2 : (TSF == 2 ? 4 : 8))
data_bytes = (FDF == 0 && X == 1) ? 0 :
             (D64 ? 64 : can_dlc_to_len(DLC))
raw_packet_bytes = 2 + id_bytes + ts_bytes + data_bytes
packet_bytes = ALIGN_4_ENABLE ? align4(raw_packet_bytes) : raw_packet_bytes

The unused frame area must be filled with 0. If 4-byte alignment is enabled, the padding byte must be 0 and counted as payload_len.

8.3.1 Enable 4-byte alignment

4-byte alignment is controlled by the direction option ALIGN_4_ENABLE, not the 0xF000 read-only capability object that is turned on directly. 0xF000:15 (0x0F) is used to confirm whether the device claims to support this capability; the real switch is 0x8010/0x8011:07 (0x07) Option flags bit1.

Turn on steps:

1. Read 0xF000:15 and confirm that bit1 ALIGN4 option mask is 1.
   You can also read 0xF000:16 and confirm that bit5 ALIGN4 feature is 1.
2. Write 0x8010/0x8011 requested profile in PREOP/SAFEOP.
3. Set 0x8010:07 or 0x8011:07 bit1 of the target direction to 1.
4. Write 0x8010:01 = 1 or 0x8011:01 = 1 apply.
5. Read 0x8010/0x8011:02 and confirm Status = 0.
6. Read 0x8010/0x8011:12 and confirm that bit1 of OptionFlags in the Active profile word has taken effect.

Example: Leave other direction options unchanged and only turn on RxPDO 4-byte alignment:

old = read_u8(0x8011:07)
write_u8(0x8011:07, old | 0x02)
write_u8(0x8011:01, 1)
check read_u8(0x8011:02) == 0

Example: Turn off TxPDO 4-byte alignment:

old = read_u8(0x8010:07)
write_u8(0x8010:07, old & ~0x02)
write_u8(0x8010:01, 1)
check read_u8(0x8010:02) == 0

After ALIGN4 is enabled, the sender must pad each frame packet to a 4-byte boundary. Padding bytes must be 0 and must be included in the fixed header payload_len. The receiver must also advance by the aligned packet_bytes when parsing the next packet, not by the raw CAN data length alone.

Length example:

8.4 Timestamp field

TSF determines whether CAN_FRAME carries the timestamp field. In the ordinary TxPDO upload direction, the timestamp is used to describe the time when the slave receives the CAN frame; in the RxPDO delivery direction, TSF_NONE means immediate transmission, and TSF_FULL64 can be multiplexed by the reserved transmission format.

delta16/delta32 within the same Packet sequence in TxPDO is referenced to the first available time base of the cycle. The master should handle wrap as an unsigned difference when used for sorting and diagnostics. If the master does not need timestamps, it is recommended to use profile 0/4 to reduce the overhead of each frame.

RxPDO reservation sending only uses the 8B field of TSF_FULL64, and the required format is as follows:

format:u8 = 1
flags:u8 = 0
tag:u16
offset_ns:u32

offset_ns represents the target phase relative to the starting point of the next SYNC0 cycle. This format is not an absolute timestamp; if the target phase has been missed, the firmware will not delay the frame until the next cycle and the master should reserve sufficient phase margin.

9. Encapsulation Profile and direction options

0x8010 controls the TxPDO profile, and 0x8011 controls the RxPDO profile. Currently, the following profiles are supported out of the factory:

Direction options are controlled by 0x8010/0x8011:07 Option flags. 0x8010 acts in the TxPDO/SM3/Input upload direction, and 0x8011 acts in the RxPDO/SM2/Output delivery direction.

9.1 Option flags bit table

Option flags is an 8 bit bitmap. After the master writes the requested value, it must then write 0x8010:01=1 or 0x8011:01=1 apply. Only by reading 0x8010/0x8011:02=0 and :12 Active profile word can it truly take effect.

Commonly written values:

Ability judgment:

The current capability mask is based on 0xF000. The master should read the capability object first and then select the profile and option flags.

9.2 Default switch state when not configured

If the master does not write the profile-related SDO of 0x8010/0x8011, the default value of requested in the device object dictionary is as follows. Note: 0xF000 means "support capability" and does not mean enabled by default; the actual enabled status is determined by the requested profile of 0x8010/0x8011 and the active readback after apply.

It is recommended that masters not rely on the assumption that implicit defaults are in effect. When starting up, you should explicitly configure 0x1C12/0x1C13, write 0x8010/0x8011:03..07, then write 0x8010/0x8011:01=1 apply, and read :09..12 to confirm the active status.

10. TX_RESULT

TX_RESULT is an optional frame packet used to return the transmission result of the RxPDO frame in TxPDO.

TX_RESULT:
  Ctrl[2] + RefPacketSeq[2] + RefFrameIndex[1] + ResultCode[1]

Ctrl has KIND=1, and CH identifies the CAN channel that produced the result. RefPacketSeq refers to the committed RxPDO publish sequence in the fixed header, that is, the sequence where seq_begin == seq_end. RefFrameIndex identifies which KIND=0 CAN_FRAME packet in that RxPDO payload is being reported, counting from 0. This lets the master match each TX_RESULT to the original transmit request.

ResultCode：

TX_RESULT only represents the result of the slave handing the frame to the MCAN transmission path, which does not mean that the target CAN node has completed business processing. If TX FIFO/Queue is used, queued indicates that it has entered the local transmission queue, and the actual bus transmission is still affected by arbitration, bus off, and TX FIFO space.

If the master does not require frame-by-frame ACK, it can turn off TX_RESULT and only observe congestion through the PDO header channel status and SDO counter.

11. CRC and integrity strategy

By default, CRC32 is not added to each CAN_FRAME.

Reason:

• The CAN/CAN FD bus itself already has CAN CRC.
• EtherCAT frame has link FCS and working counter.
• per-frame CRC32 will increase 4B/frame, and the classic 8B standard frame overhead increases from 12B to 16B, about 33%.
• Frame-by-frame CRC32 adds jitter to the packet calculation in 1ms periods.

By default, ActiveLayoutCrc is used to verify the PDO layout contract. This CRC is only calculated when profile apply. payload_crc16 in the fixed header is used to protect FramePacketStream in each PDO cycle during runtime. The algorithm is CRC-16/CCITT-FALSE; it is used to identify half-update or error payload, not CAN frame-level business CRC. If additional runtime integrity checks are indeed required in the future, STREAM_CRC32_ENABLE with capability bit declaration should be used, and whole-stream CRC32 should be carried in STREAM_META packets instead of adding CRC to each CAN_FRAME.

12. Multi-channel shared budget

PDO no longer provides fixed slots for each CAN channel. The scheduler works on a frame area byte budget:

frame_area = ActivePDOBytes - 24
reserved_bytes = enabled_channel_count * policy_reserved_bytes
shared_bytes = frame_area - reserved_bytes

Budget strategy:

A CAN_FRAME must be put into the frame area of this cycle as a whole, and splitting across cycles is not allowed. If there is insufficient space, set the device to STREAM_TRUNCATED, add overflow_sat and SDO PDOOverflowCounter.

13. SDO object dictionary

The previous chapters describe periodic PDO data, which is exchanged every EtherCAT cycle after OP. The SDO object dictionary is the configuration and diagnostics entry point: use it before OP to configure PDO profiles and MCAN channels, and use it during operation to read capabilities, error counters, and detailed status. If you only need to look up an object, start from this chapter. For bring-up, read 13.1, 13.2, 13.4, and 13.8 first.

All SDO subindex tables in this chapter include a "Type" column. The type uses common EtherCAT CoE notation: U8 is unsigned 8 bit, U16 is unsigned 16 bit, and U32 is unsigned 32 bit. If a signed 32-bit type appears later, it can be marked as D32/I32. The current ECAN-Lite object dictionary mainly uses U8/U16/U32.

13.1 Object Overview

13.2 0x8010/0x8011 PDO Profile Control

0x8010 controls the TxPDO/Input direction, and the data flow is S2M; 0x8011 controls the RxPDO/Output direction, and the data flow is M2S. SI1/3/4/5/6/7/8 is the requested configuration or command written by the master, and SI2/9..16 is the status and active readback returned by the slave.

Status Common values:

Active profile word packaging format:

Command bit definition:

Last PDO error common values:

PDO error counter counts encapsulation layer errors such as parsing, CRC, and illegal fields; PDO overflow counter counts overflow or discarding caused by insufficient frame area in this cycle and TX/RX back pressure. During on-site inspection, first check Status, and then check LastPDOError and whether the two counters continue to increase.

13.2.1 0x8020 Data Path Global Control

0x8020 is the global data-path control object. It does not change the EtherCAT SM/PDO mapping length. It is used for runtime compatibility policy, diagnostic options, and service budget control. Write Apply command=1 after changing fields; Apply status=0 means the request was accepted.

13.2.2 0x8021..0x8024 MCAN Data Path Control

0x8021..0x8024 correspond to MCAN0..MCAN3. These objects expose each MCAN data-path policy as explicit fields instead of packing everything into the legacy policy word. They do not configure MCAN bit timing, filters, or Message RAM; those remain in 0x8001..0x8004.

RX budget policy:

RX cache depth:

RX overflow policy:

Critical frame policy:

TX overflow policy:

Bus-off recovery policy:

Active control word packing:

13.2.3 0x8030 PDO Diagnostic Test Control

0x8030 is intended for engineering and field performance isolation. It is not recommended to keep it enabled in production. Before writing any non-zero test policy, write Test enable key = 0x4543414E (ASCII ECAN). If the key is 0, all test policies must also be 0 or the write is rejected.

TxPDO bypass flags:

RxPDO bypass flags:

Legal combination mask:

13.2.4 0x9011 Cycle Performance Diagnostics

0x9011 observes cycle stability and firmware hot-path timing. All entries are read-only except Clear command. Cycle fields are CPU cycles; use 0x8000:4 CPU clock hz to convert them to time.

13.2.5 0x9020..0x9023 MCAN Data Path Diagnostics

0x9020..0x9023 correspond to MCAN0..MCAN3. They expose the runtime result of 0x8021..0x8024 policies and help distinguish excessive CAN input, insufficient PDO space, TX FIFO backpressure, bus-off, and service-budget limits.

13.3 0x8000 System Config

CAN pin rotation only allows rotation of logical channels between fixed sets of CAN pins at the chip/board level and does not provide arbitrary GPIO muxing configurations.

13.4 0x8001..0x8004 MCAN Channel Config

Each channel has the same structure. 0x8001 corresponds to CAN0, and 0x8004 corresponds to CAN3.

The subindices are grouped by function below. Most applications only need to configure SI15/16/19/20 and the required FIFO/Queue parameters; filters, TSU, and timeout settings are advanced options.

Channel commands and status:

Node mode value:

Manual bit timing only takes effect at SI7 Bit timing mode = 1. In automatic mode, the master configures Nominal/Data bitrate and the sample point range, and the firmware solves BRP/TSEG/SJW according to the MCAN source clock. The sample point range should follow the peer device configuration: when the peer sample point is known, set both min and max to the target sample point; otherwise start from the peer documentation recommendation and verify frame exchange quality. In manual mode, SI25..32 is used.

Filter global fields:

Filter editing window:

Entry cmd：

Entry status：

Typical filter configuration process:

1. Read Std list max / Ext list max to confirm the capacity.
2. Write Std filter count or Ext filter count.
3. Write current index.
4. Write filter type/action/sync/id1/id2.
5. Write entry cmd = 2 to save the current index.
6. Repeat to configure multiple entries.
7. Write Apply command = 1 to make the channel configuration take effect.
8. If you need to save when power off, write Flash command bit0 = 1.

RAM/FIFO/Buffer fields:

Note: the SI column below is decimal. Many master tools display subindices in hexadecimal. The commonly mentioned 0x41/0x42/0x44 are decimal 65/66/68, corresponding to the RX FIFO0, RX FIFO1, and RX Buffer element data sizes. These fields only define the maximum data bytes stored in one MCAN Message RAM element. They do not define the CAN FD DLC inside a PDO packet; the actual DLC is still carried by the frame packet in RxPDO/TxPDO.

data size uses the HPM MCAN driver enumeration and is not the byte value itself. Common values are:

The Message RAM budget is determined by both element counts and data size. The general CAN FD default is RXFIFO0=48, RXFIFO1=12, RXBUF=12, TXFIFO=32, TXBUF=0, TXEVENT=32, data size=7. Classic CAN may reduce data size to 0 to save RAM for more elements. If the configuration is illegal or exceeds the per-channel Message RAM budget, Apply status reports an error and the runtime channel does not switch to the new layout.

Timestamp/TSU/Timeout fields:

TDC Strategy:

• CAN FD default TDC enable=1.
• When the data segment is less than 5M, the master can turn off TDC through SDO.
• When the data segment reaches 5M or more, the firmware ignores TDC enable=0 and forcibly turns on TDC.
• TDC offset/filter defaults to 0, which means it is automatically calculated by the HPM MCAN driver according to the actual data segment timing.
• TDC offset/filter that is not 0 is still retained by the firmware and distributed to the MCAN driver for debugging by on-site experts.
• It is recommended to configure offset/filter in pairs when manually overwriting.

13.5 0x9000..0x9003 MCAN Channel Information

These objects are RO and use the S2M direction. The master reads them when it needs detailed channel status beyond the compact PDO header state.

13.6 0xA000..0xA003 MCAN Register Service

0xA000..0xA003 respectively correspond to the register access services of MCAN0..MCAN3. This object is used for on-site diagnosis and expert debugging, and it is not recommended for ordinary applications to access it periodically. Writing registers will be protected by a whitelist to avoid accidentally writing key addresses and causing bus abnormalities.

Status：

Write whitelist offset:

Read register process:

1. Write Offset.
2. Write Command = 1.
3. Read Status, and when it is 0, read Read value.

Write register process:

1. Verify that the device is in a state that allows debug access.
2. Write Offset and Write value.
3. Write Command = 2.
4. Read Status. If it is 2, it means that the register can only be read or it is not recommended to write through SDO.

13.7 0xB000 Device Maintenance

Access mode request/status:

Maintenance command is a bit mask. bit0..4 are traditional maintenance commands. bit5/bit6 are standalone commands and must be written alone, not combined with other bits.

Legacy maintenance diag flags:

Maintenance status Common values:

Maintenance sequence is incremented after the maintenance command is completed. When the master executes a maintenance command, it should first record the old sequence, and then poll the sequence changes and status after writing the command.

13.8 0xF000 Device Objects

The master must read the 0xF000 capability object before selecting the PDO profile.

The object is RO and the direction is S2M. It is used by the master to identify the device capabilities, version and protocol upper limit.

PDO capabilities and upper limits:

Encapsulation profile mask：

PDO option flags mask：

PDO feature flags：

Device service flags：

RxPDO reserves the TSF_FULL64 field of the multiplexed dynamic frame and does not change the ordinary CAN frame packet structure:

format:u8 = 1
flags:u8 = 0
tag:u16
offset_ns:u32

TSF_NONE is still sent immediately; TSF_FULL64 format=1 means offset_ns phase sending is reserved for the next SYNC0 cycle. The same phase is queued in PDO frame order.

Reservation delivery implementation constraints:

• The master must first confirm the RxPDO TSF reserved transmission capability bit in 0xF000:16 (0x10).
• offset_ns takes the current EtherCAT DC/SYNC0 cycle as a reference. It is recommended to use 100000ns or a larger conservative phase for bring-up first.
• The device schedules reserved frames according to the SYNC0 phase; frames that have exceeded the target phase will not be retransmitted across cycles, and the master should reserve sufficient offset_ns margin.
• Scheduled sending and direct sending share the CAN sending path; when the channel is congested or sending is abnormal, feedback is provided through PDO status and SDO diagnostic count.
• When the master is stopped, the ESC process data area may keep the last frame of RxPDO image; the firmware treats the exact same repeated image as idempotent no-op and does not record it as a real parsing error.

13.9 Comparison of real-time performance between scheduled delivery and direct delivery

The reservation sending effect depends on the certainty of the master cycle itself. If the master application uses ordinary usleep() relative delay, the 1ms/2ms cycle will accumulate application execution time and Linux wake-up jitter, and a long tail will appear in the CAN side packet capture. IgH example igh_mcan_gateway_tx_probe has been changed to absolute time period and supports:

--rt-priority 80 --spin-us 100

Among them, --rt-priority sets the periodic thread to SCHED_FIFO, and --spin-us indicates the short spin alignment target time after sleeping N microseconds before the deadline. master_period will be output at the end of the example. You should first confirm that the master cycle is stable, and then evaluate the real-time performance of the CAN side.

The following data comes from a lab reference test: a physical Linux IgH master, one ECAN-Lite slave, one MCAN channel connected to a CAN analyzer, PDO=3, which is 384B, CAN FD+BRS, payload 16B, sending 1000 frames, and the CAN analyzer saves the timestamps of the first 1200 frames.

Conclusion: Direct transmission is suitable for ordinary functional testing. The CAN transmission time will follow the PDO arrival and firmware processing time; when the master cycle converges, reserving 100us can stabilize the CAN release phase to the fixed window after SYNC0. When stable real-time output is required, it is recommended to use scheduled sending and record the master master_period and CAN analyzer timestamps at the same time.

14. Configuration process

14.1 Recommended startup process

1. The master enters PREOP/SAFEOP.
2. Read the 0xF000 capability object.
3. Configure 0x1C12/0x1C13 and select the first N 128B chunks.
4. Write 0x8010/0x8011 requested profile.
5. Write 0x8010:1 = 1 and 0x8011:1 = 1 application profiles.
6. Read ActivePDOBytes / ActiveFrameAreaBytes / ActiveLayoutCrc / ActiveProfileWord.
7. Write 0x8001..0x8004 CAN parameters and Apply command=1 for each enabled channel.
8. Enter OP.
9. In the OP, data is only sent and received through PDO; if an error is encountered, SDO details are read as needed.

14.2 Switch PDO size

PDO size affects SM2/SM3 length and must be completed during INIT/PREOP/SAFEOP. Changing active PDO size, channel mask, profile, budget or option flags is not allowed in the OP.

1. Return SAFEOP/PREOP from OP
2. Modify 0x1C12/0x1C13 assignment chunk count
3. Write 0x8010/0x8011 PDO size multiplier
4. Apply profile
5. Verify active readback
6. Re-enter OP

If the assignment chunk count is inconsistent with PdoSizeMultiplier, the device returns Status=5 master mapping reload required and keeps the old active profile.

14.3 CAN FD 5M configuration recommendations

FD enable       = 1
Nominal bitrate= 1000000
Data bitrate   = 5000000
TDC enable     = 1
TDC offset     = 0
TDC filter     = 0
RX/TX data size= 64B
Apply command  = 1

IgH demo writes TDCEnable=1, TDCOffset=0, TDCFilter=0 to the CAN FD channel by default. 5M and above, even if the master writes TDCEnable=0, the firmware will be forced to open.

15. IgH master integration guide

The IgH master sample package can directly reuse the PDO protocol layer, or run the 10-axis CiA402 demo for system bring-up. The sample commands are based on relative paths after entering the extracted IgH sample package directory.

15.1 Code level

The IgH sample package is split into three layers based on responsibilities. Customer applications usually only need to select a top-level entry, and the lower levels are continued to be reused within the library.

The sample program is only used for bring-up and regression testing. It is not recommended that customer business programs directly copy the demo main function. Recommended reuse library interface:

15.2 Linux environment preparation

It is recommended to run IgH on a physical Linux host. If a virtual machine is used, it is only recommended for early enumeration and function bring-up; the stable cycle and DC behavior should be based on the physical machine results.

Basic dependencies:

sh
sudo apt update
sudo apt install -y git build-essential cmake autoconf automake libtool \
  pkg-config linux-headers-$(uname -r)

IgH EtherCAT master needs to enable generic driver and hrtimer:

sh
git clone https://gitlab.com/etherlab.org/ethercat.git
cd ethercat
./bootstrap
./configure --prefix=../ethercat-install \
  --sysconfdir=../ethercat-install/conf \
  --enable-generic \
  --enable-hrtimer
make -j$(nproc) all modules
sudo make modules_install install
sudo depmod

Configure the EtherCAT dedicated network port according to the IgH installation instructions, for example, bind master0 to enp4s0 and use the generic driver module. After the configuration is complete, restart the master and confirm that the slaves can be enumerated:

sh
sudo systemctl restart ethercat
sudo ethercat slaves

15.3 Building the IgH sample package

Basic build commands:

sh
cmake -S . -B build
cmake --build build

Default ECAN_IGH_BUILD_DEMO=AUTO. If CMake finds ecrt.h and libethercat, it will build libecan_mcan_host.a, libecan_igh_host.a, igh_simple_loop, igh_canopen_sdo_probe, igh_cia402_single_axis_demo, and igh_cia402_10axis_demo; if no IgH development files are found, it will just build ecan_mcan_host protocol static library, the configuration process will not fail.

If using the local IgH build directory:

sh
cmake -S . -B build \
  -DECRT_INCLUDE_DIR=../ethercat/include \
  -DECRT_LIBRARY=../ethercat/lib/.libs/libethercat.so
cmake --build build -j$(nproc)

If you only need the protocol static library, do not build the IgH demo:

sh
cmake -S . -B build -DECAN_IGH_BUILD_DEMO=OFF
cmake --build build

If you need to force the demo to be built:

sh
cmake -S . -B build -DECAN_IGH_BUILD_DEMO=ON
cmake --build build

15.3.1 Firmware update using IgH FoE OTA

ECAN-Lite supports EtherCAT FoE writing packaged application firmware. The FoE target file name on the device side is fixed to ecan_lite_app, and the default password is 0. The master can complete the update using the ethercat command that comes with IgH, and does not rely on the demo in this directory.

Preparation conditions:

Read the current version before updating:

sh
sudo /opt/etherlab/bin/ethercat upload -p 0 0x100A 0 --type string
sudo /opt/etherlab/bin/ethercat upload -p 0 0xF000 5 --type uint16
sudo /opt/etherlab/bin/ethercat upload -p 0 0xF000 6 --type uint16

Write firmware:

sh
sudo /opt/etherlab/bin/ethercat foe_write \
  -p 0 \
  -o ecan_lite_app \
  /tmp/ecan_lite_v140494.bin

-p 0 in the above command is the FoE password, and -o ecan_lite_app is the target file name on the device side. If the on-site IgH tool version uses different options for slave position, password or remote file name, ethercat foe_write --help should prevail; the core parameters remain unchanged: target slave, password=0, remote file name ecan_lite_app, local packaged firmware path.

Common mistakes:

After a successful update, the firmware writes to the free APP partition and requests a reset. After waiting for the slave to come back online, rescan and confirm the version:

sh
sudo systemctl restart ethercat
sudo /opt/etherlab/bin/ethercat slaves
sudo /opt/etherlab/bin/ethercat upload -p 0 0x100A 0 --type string
sudo /opt/etherlab/bin/ethercat upload -p 0 0xF000 5 --type uint16
sudo /opt/etherlab/bin/ethercat upload -p 0 0xF000 6 --type uint16

15.4 Secondary development interface

During secondary development, choose the abstraction layer first, and do not expose all functions to business code. For complete instructions, see API.md in the example package:

Conventional CAN/CAN FD gateway applications preferentially use the MCAN Port layer. Business code should give priority to calling flat interfaces igh_mcan_port_send_can(), igh_mcan_port_send_canfd(), igh_mcan_port_schedule_can() and igh_mcan_port_receive() without constructing igh_mcan_tx_frame_t first. In this way, the call chain is the shortest. User data is only copied once when writing to the RxPDO frame area. At the same time, details such as PDO header, CRC, frame boundary, TxPDO parsing errors, etc. are still encapsulated by the library:

c
igh_mcan_tx_frame_t tx;
igh_mcan_rx_frame_t rx[32];
size_t rx_count = 0;
uint8_t data[8] = {0, 1, 2, 3, 4, 5, 6, 7};

igh_mcan_tx_frame_set_can(&tx, 0, 0, 0x123, 0, data, sizeof(data));
igh_mcan_port_exchange(&mcan, &tx, 1, rx, 32, &rx_count);

When periodic real-time control is required, it is recommended to use igh_mcan_port_cycle_begin(), igh_mcan_port_receive(), igh_mcan_port_send_can/canfd(), igh_mcan_port_schedule_can/canfd(), and igh_mcan_port_cycle_end() to form a fixed period. igh_mcan_tx_frame_set_*(), igh_mcan_port_send() and igh_mcan_port_exchange() are reserved only for batch sending, bring-up, test scripts or legacy code compatibility.

Minimal CAN transceiver example:

sh
sudo ./build/igh_simple_loop

CANopen SDO probing example:

sh
sudo ./build/igh_canopen_sdo_probe \
  --node 1 \
  --index 0x1000 \
  --sub 0 \
  --bitrate 1000000

15.5 IgH integration process without demo

If the customer does not run igh_simple_loop or igh_cia402_*_demo, but integrates ECAN-Lite in its own master application, it is recommended to still reuse the three-layer interface in the IgH sample package. The demo is just a runnable sample. The process that really needs to be transplanted into the client program should be divided into four parts: "master configuration, MCAN channel configuration, periodic send/receive, and business protocol processing".

15.5.1 Recommended access method

For general projects, MCAN Port API is preferred. In this way, even if you don't use the demo, you can avoid copying the long process of the demo into the business code.

15.5.2 Configuring an IgH application from scratch

Step 1: Scan the EtherCAT topology to confirm the slave location of ECAN-Lite.

sh
sudo ethercat slaves

Step 2: Select PDO size, period and channel. For first debugging, start with 1 slave, 1 MCAN channel, and cycle_us=10000. Use pdo-n=3 for classic CAN or CiA402/CANopen motor scenarios, and use pdo-n=8 for CAN FD, especially 64B payloads or multi-channel bursts. After OP and CAN transceiver are stable, increase the slave count, channel count and cycle pressure.

Step 3: Create IgH generic configuration.

c
ecan_igh_config_t igh_config;
ecan_igh_default_config(&igh_config);
ecan_igh_config_set_slave_count(&igh_config, 1);
ecan_igh_config_set_cycle_us(&igh_config, 10000);
ecan_igh_config_set_pdo_multiplier(&igh_config, 3); /* 3 * 128B */

When there are multiple slaves and the PDO sizes are different, use ecan_igh_config_set_slave_pdo_multiplier() to configure them separately. For example, the first two slaves use N=6, and the third slave can use N=3 when only two channels of MCAN are enabled.

Step 4: Create the MCAN channel configuration and write to the startup SDO queue.

c
igh_mcan_port_config_t mcan_config;
igh_mcan_port_default_config(&mcan_config);
igh_mcan_port_set_channel_mask(&mcan_config, 0, 0x01, 0x00);
igh_mcan_port_set_classic_channel(&mcan_config, 0, 0, 1000000);
igh_mcan_port_apply_config(&igh_config, &mcan_config);

The IgH general layer will register the first N PDO chunks according to PDO multiples and configure 0x1C12/0x1C13. igh_mcan_port_apply_config() will append the startup SDO required for ECAN-Lite operation, including the PDO profile, channel mask, PDO length of 0x8010/0x8011, and the MCAN baud rate and CAN FD parameters of 0x8001..0x8004.

Step 5: Initialize the master and MCAN Port, and wait for the slave to enter OP.

c
ecan_igh_context_t igh;
igh_mcan_port_t mcan;

ecan_igh_init(&igh, &igh_config);
igh_mcan_port_init(&mcan, &igh, &mcan_config);
ecan_igh_wait_op_timeout(&igh, 10000);

Step 6: Complete an EtherCAT/CAN exchange during the application cycle.

c
uint8_t data[8] = {0};
igh_mcan_rx_frame_t rx[32];
size_t rx_count = 0;

igh_mcan_port_cycle_begin(&mcan);
igh_mcan_port_receive(&mcan, rx, 32, &rx_count);
igh_mcan_port_send_can(&mcan, 0, 0, 0x123, 0, data, sizeof(data));
igh_mcan_port_cycle_end(&mcan);

Step 7: Add real-time configuration to the periodic thread. On Linux, it is recommended to set up at least SCHED_FIFO, mlockall(), fixed running CPU, and place the IgH main service and network card interrupt on the planned RT core. The period can be used first as 5ms or 2ms, and then evaluated as 1ms after stabilization.

Step 8: Add runtime checks. Domain working counter, ecan_igh_domain_is_complete(), slave OP status, MCAN Port parsing error and TxPDO header should be monitored every cycle. When domain_complete=0 appears, do not continue to advance the motion target. Keep the output of the previous cycle or enter the safe stop logic.

15.5.3 Manual configuration when not using MCAN Port API

In Raw PDO mode, the application needs to complete two types of work by itself:

1. PDO mapping selection: According to the rules in Chapter 5, add the RxPDO/TxPDO chunk to 0x1C12/0x1C13. Each chunk is 128B, pdo-n=N means selecting 0x1600..0x160(N-1) and 0x1A00..0x1A(N-1).

2. ECAN-Lite operating parameters: write 0x8010/0x8011 and 0x8001..0x8004. The minimum configuration should include channel mask, PDO length, profile and nominal/data bitrate for each MCAN channel. After the configuration is completed, read the active profile and status through 0x8010:02 (0x02), 0x8011:02 (0x02) or 0x9000 to confirm that the firmware has taken effect as expected.

During Raw PDO periodic exchange, use the following interface to get the buffer:

c
uint8_t *rxpdo = NULL;
const uint8_t *txpdo = NULL;
size_t rxpdo_size = 0;
size_t txpdo_size = 0;

ecan_igh_get_rxpdo_buffer(&igh, slave_index, &rxpdo, &rxpdo_size);
ecan_igh_get_txpdo_buffer(&igh, slave_index, &txpdo, &txpdo_size);

rxpdo is the data output by the master to ECAN-Lite, and txpdo is the data returned by ECAN-Lite to the master. It is recommended to still use igh_mcan_pdo_writer_* and igh_mcan_pdo_parse_frames_ex() to assist in encapsulation/parsing to avoid repeated implementation of PDO header, CRC, offset and frame boundary processing by customer applications.

15.5.4 Control the motor without using CiA402 demo

The motor project also does not have to run igh_cia402_single_axis_demo or igh_cia402_10axis_demo directly. Client applications can reuse protocol layers:

1. First press 15.5.2 to complete IgH and MCAN Port initialization.
2. Use igh_cia402_axis_init() to create an axis table, describing the slave, MCAN channel, NodeID and target step of each motor.
3. Use igh_cia402_context_init() to bind MCAN Port and axis table.
4. In the startup phase, call igh_cia402_send_nmt_all(), igh_cia402_configure_csp_all_timeout(), igh_cia402_request_actual_position_all_timeout(), igh_cia402_enable_all() to complete NMT, CSP mapping, actual position reading and CiA402 enablement.
5. In the motion cycle, call igh_cia402_process_rx() to process TPDO/SDO/heartbeat, and then call igh_cia402_send_targets_all() or igh_cia402_send_target_step() to send the target position.
6. If you need to schedule sending, enable DC Sync0 first, and then call igh_cia402_set_scheduled_tx(); the RPDO target and SYNC can be scheduled independently.

In this way, the demo is only used as a bring-up and regression testing tool, and the customer's own program can still use the same startup, sending and receiving, diagnosis and reservation capabilities.

15.6 Run CiA402 demo

The single-motor bring-up example uses slave 0, MCAN0, NodeID 1, and 1Mbps by default; for the first bring-up, it is recommended to explicitly use --step 0 to avoid active movement:

sh
sudo ./build/igh_cia402_single_axis_demo \
  --bitrate 1000000 \
  --cycle-us 10000 \
  --cycles 20 \
  --step 0

For single-board CAN FD or full-capacity bring-up, explicitly use a 1024B PDO, a longer period and 1 slave. For classic CAN/CiA402 bring-up, normally keep --pdo-n 3:

sh
sudo ./build/igh_cia402_10axis_demo \
  --slaves 1 \
  --pdo-n 8 \
  --cycle-us 10000 \
  --cycles 10000

After the system is stable, shorten the period, for example 1ms:

sh
sudo ./build/igh_cia402_10axis_demo \
  --slaves 1 \
  --pdo-n 3 \
  --cycle-us 1000 \
  --cycles 10000 \
  --dc-sync0 \
  --dc-cycle-us 1000 \
  --dc-shift-us 700

Commonly used parameters:

During the startup phase, the demo will write the PDO profile, channel configuration and CAN FD TDC default value. TDCOffset=0 and TDCFilter=0 indicate that the firmware automatically calculates according to the data segment timing; when the data segment reaches 5M or more, the firmware forcibly enables TDC.

15.6.1 IgH Three-slave Reference Stable Points

The following points are current reference long-test results with the productized IgH adapter using per-slave domains, three slaves, CRC16 enabled by default, base mode, root execution, SCHED_FIFO, and CPU affinity. Short tests should only be used to screen candidate phases; product configurations should be based on 2-minute or longer runs.

These results are reference boundaries rather than guarantees for every host, NIC, and cable combination. When expanding to a larger PDO or heavier real CAN traffic, monitor WKC, OP state, TxPDO header, 0x9011 cycle diagnostics, and 0x9020..0x9023 per-channel data-path diagnostics together.

15.7 SII/EEPROM and SM layout check

The device EEPROM/SII must maintain a large PDO single buffer layout, otherwise IgH OP/DC operation will be disrupted by incorrect SM configuration:

Manual checking available with scripts:

sh
sudo scripts/ecan_sii_sm_layout.sh check \
  --ethercat ../ethercat-install/bin/ethercat \
  --position 0 \
  --pdo-bytes 3072

When repair is required, manual confirmation must be performed before execution:

sh
sudo scripts/ecan_sii_sm_layout.sh fix \
  --ethercat ../ethercat-install/bin/ethercat \
  --position 0 \
  --pdo-bytes 3072

16. Debugging and Diagnostics

16.1 OP exception

Priority checks:

• Whether SM2/SM3 in EEPROM/SII is 0x1100/0x1D00, 3072B, 0x66/0x22.
• Whether the 0x1C12/0x1C13 assignment quantity is consistent with 0x8010/0x8011 PDO size multiplier.
• Whether the IgH adapter uses the per-slave domain/FMMU segmentation strategy; consider the large PDO/FMMU patch only for old examples or old masters.
• Is DC shift too small? If the output data does not arrive before Sync0, it will cause WC miss or OP loss.

16.2 PDO parsing error

Check out:

• 0x8010/0x8011 Status
• LastPDOError
• PDOErrorCounter
• PDOOverflowCounter
• IgH protocol layer parse_diag, including offset, packet_end, ctrl, seq, payload_len, payload_crc16, layout_id, ch, dlc, tsf, kind.