跳到主要内容

Slave 属性与方法

通过 master[n] 或 master.slave(n) 访问（1-based 索引）。​

提示
  • PDO 输入输出（结构体映射、字节数组、索引访问等）请参见 PDO 输入输出 页面。
  • 从站事件请参见 事件 页面。
  • 从站诊断请参见 从站诊断 页面。

属性​

类别属性类型读写说明
基本标识slave_numint只读从站编号（1-based）
indexint只读从站索引（slave_num 别名）
namestr只读设备名称（从 EEPROM group_name 读取）
drive_namestr只读驱动/设备名称（从 SDO 0x1008 读取）
设备信息vendor_idint只读制造商 ID（从 SII EEPROM 读取）
vendor_namestr | None只读制造商名称（从 ESI 文件读取）
product_idint只读产品 ID
rev_idint只读修订版本号
serial_numberint只读序列号（从 SII EEPROM 读取）
has_mdpbool只读是否支持模块化设备配置文件（ETG.5001）
block_lrwbool只读LRW 逻辑读写操作阻止标志
地址config_addrint只读物理配置地址
alias_addressint只读别名地址
状态stateEcState只读从站当前状态
error_codeEcALState只读错误码
is_lostbool只读从站是否丢失（断开连接）
拓扑topologyint只读拓扑类型 (0=无链接, 1=端点, 2=中间, 3=分支, 4=交叉)
parent_indexint只读父从站索引 (1-based)，0=父节点是主站
parent_stationint只读父从站索引 (1-based，命名为历史遗留，实际为 index 非 station address；0=父节点是主站)
parent_portint只读父端口号
entry_portint只读入口端口号
active_portsint只读激活端口位掩码
physical_typeint只读物理端口类型
child_countint只读子模块数量
PDO 数据ibits / obitsint只读输入/输出数据位数
ibytes / obytesint只读输入/输出数据字节数
ioffset / ooffsetint只读输入/输出在 IOmap 中的偏移
istartbit / ostartbitint只读输入/输出起始位
ESI/配置has_esibool只读是否已加载 ESI 文件
esi_namestr | None只读ESI 文件名
esi_versionstr只读ESI 版本号
config_by_esiobject | None只读从 ESI 文件获取的设备配置
EEPROMeep_8byte_addressingbool只读EEPROM 寻址模式（True=8字节, False=4字节）
eep_pdiint只读物理设备接口（PDI）类型
ebus_currentint只读E-bus 电流消耗（mA）
邮箱mbx_protoint只读支持的邮箱协议类型（MailboxType 位掩码）
mbx_lengthint只读邮箱发送缓冲区大小
mbx_read_lengthint只读邮箱接收缓冲区大小
mbx_read_offset / mbx_write_offsetint只读邮箱读/写偏移
mbx_countint只读邮箱协议计数器
协议详情coe_detailsint只读CoE 协议功能标志（EcCoEDetails 位掩码）
eoe_detailsint只读EoE 协议功能标志（EcEoEDetails 位掩码）
foe_detailsint只读FoE 协议详情（来自 SII EEPROM）
soe_detailsint只读SoE 协议详情（来自 SII EEPROM）
FMMUfmmu0_functionint只读FMMU0 功能类型（bit 0=输出, bit 1=输入）
fmmu1_functionint只读FMMU1 功能类型
fmmu2_functionint只读FMMU2 功能类型
fmmu3_functionint只读FMMU3 功能类型
DChas_dcbool只读是否支持 DC，详见 DC 同步
dc_activeint只读DC 激活状态（0=禁用, 非0=已激活），详见 DC 同步
dc_cycle0int只读SYNC0 周期（纳秒），详见 DC 同步
dc_cycle1int只读SYNC1 周期（纳秒），详见 DC 同步
dc_shiftint只读相位偏移（纳秒），详见 DC 同步
dc_nextint只读DC 链中下一个从站的索引
dc_previousint只读DC 链中上一个从站的索引
dc_parent_portint只读DC 父端口号
dc_receive_time_aint只读端口 A 接收时间（纳秒）
dc_receive_time_bint只读端口 B 接收时间（纳秒）
dc_receive_time_cint只读端口 C 接收时间（纳秒）
dc_receive_time_dint只读端口 D 接收时间（纳秒）
propagation_delayint只读帧从主站到达此从站的传播延迟（纳秒），详见 DC 同步
pdelayint只读传播延迟（纳秒，propagation_delay 别名）
拓扑扩展childrenList[Slave]只读子从站列表（配合 child_count 使用，导航拓扑树）
supports_frame_repeatbool读写是否支持帧重复功能（ETG.1500 5.4.3）
冗余redundancy_activatedbool只读冗余是否已激活
primary_link_brokenbool只读主线路是否断路
secondary_link_brokenbool只读冗余线路是否断路
配置groupint读写从站分组号（0-7，0=默认组，必须在 SAFE_OP 前设置），详见 从站分组
is_optionalbool读写可选从站标记，缺席时不影响 WKC 检查、不触发组离线告警（必须在 OP 前设置）
Startupshould_write_pdo_assignmentbool读写启动时是否写入 PDO Assignment，默认 True
should_write_pdo_configurationbool读写启动时是否写入 PDO Configuration，默认 False
supports_complete_accessbool读写从站是否支持 SDO Complete Access
EcTopologyType / EcPortType 枚举值
class EcTopologyType(IntEnum):
    NO_LINK = 0     # 无链接
    END_POINT = 1   # 端点
    LINE = 2        # 中间节点（线性拓扑）
    FORK = 3        # 分支点
    CROSS = 4       # 交叉点

class EcPortType(IntEnum):
    NOT_USED = 0       # 未使用
    MII = 1            # MII
    EBUS = 2           # EBUS
    EBUS_ENHANCED = 3  # EBUS 增强型
MailboxType 常量
class MailboxType(IntEnum):
    ERROR_MAILBOX = 0x00          # 错误邮箱
    ADS_OVER_ETHERCAT = 0x01      # AoE
    ETHERNET_OVER_ETHERCAT = 0x02 # EoE
    CANOPEN_OVER_ETHERCAT = 0x03  # CoE
    FILE_OVER_ETHERCAT = 0x04     # FoE
    SERVO_OVER_ETHERCAT = 0x05    # SoE
    VENDOR_OVER_ETHERCAT = 0x0F   # VoE
EcCoEDetails 常量
class EcCoEDetails(IntFlag):
    NONE = 0x00
    SDO = 0x01              # 支持 SDO
    SDO_INFO = 0x02         # 支持 SDO Info
    PDO_ASSIGN = 0x04       # 支持 PDO Assign
    PDO_CONFIG = 0x08       # 支持 PDO Config
    STARTUP = 0x10          # 支持 Startup
    COMPLETE_ACCESS = 0x20  # 支持 Complete Access
EcEoEDetails 常量
class EcEoEDetails(IntFlag):
    NONE = 0x00
    SEND_FRAME = 0x01     # 支持发送帧
    RECEIVE_FRAME = 0x02  # 支持接收帧
    SET_IP_PARAM = 0x04   # 支持设置 IP 参数
    GET_IP_PARAM = 0x08   # 支持获取 IP 参数
Python 特有语法糖

身份四元组 (vendor / product / revision / serial) 主 SDK 返回 dict, 不能 hash / 解包. 用 SlaveIdentityKey frozen dataclass 包装可作 dict key / set 元素 + 元组解包: vendor, product, rev, serial = SlaveIdentityKey.from_slave(slave). 详见 dataclass.

子对象​

类别属性类型读写说明
数据与事件pdoSlavePdo只读PDO 数据访问器，详见 PDO 输入输出
eventsSlaveEvents只读从站级事件，详见 从站事件
diagnosticsSlaveDiagnostics只读诊断信息访问器，详见 从站诊断
startupStartupParameterList只读启动参数列表
协议实例coeCoE | None只读CANopen over EtherCAT，从站不支持时为 None
soeSoE | None只读Servo over EtherCAT，从站不支持时为 None
foeFoE | None只读File over EtherCAT，从站不支持时为 None
eoeEoE | None只读Ethernet over EtherCAT，从站不支持时为 None
aoeAoE | None只读ADS over EtherCAT，从站不支持时为 None
voeVoE | None只读Vendor over EtherCAT，从站不支持时为 None
fsoeFSoE | None只读Functional Safety over EtherCAT，从站不支持时为 None
mdpMdpDiscovery | None只读MDP 模块化设备，从站不支持时为 None
esiEsiLoader只读ESI 文件加载器实例，提供 ESI 文件加载和解析功能

枚举描述​

所有枚举统一使用 .description 属性获取中文描述：

state = slave.state
desc = state.description  # "OP"

# CiA402 通过 slave.cia402 访问 (从站不支持 CoE 时为 None)
cia = master[1].cia402
if cia is not None:
    state = cia.state  # 驱动器状态
统一规范

项目中所有枚举描述均通过 .description 属性获取，包括 EcState、EcALState、SDOError、FSoEState、FSoEError、StateCiA402、ModeCiA402 等。

硬件信息查询​

计划中

以下方法尚未实现，将在后续版本中添加：

  • get_fmmus() -> List[EcFmmu] — 获取从站 FMMU 配置数组
  • get_sync_managers() -> List[EcSm] — 获取从站 SyncManager 配置数组
  • get_sync_manager_types() -> List[int] — 获取从站 SyncManager 类型数组

诊断​

提示

从站诊断信息（通信异常率、冗余状态、DC 同步）通过 slave.diagnostics 访问，详见 从站诊断。

实时诊断镜像 (薄读零帧)​

每从站的实时诊断属性挂在 slave.diagnostics 上（Python 惯例：用属性，不用 get_xxx() 方法），都是内核 per-slave 诊断缓存的薄读：每次访问直接读 native，不收发帧（零帧），不二次缓存，读到即此刻总线现实，无需手动刷新。通讯异常时诚实返回 UNKNOWN / raw=0，不臆造。

属性类型说明
diagnostics.wc_contributedWcContribution该从站本周期对工作计数器（WKC）的贡献状态，详见 WKC 贡献语义
diagnostics.al_status_mirrorSlaveAlStatusMirrorAL 状态镜像（含 al_state / has_error / al_status_code）
diagnostics.mailbox_healthEcMailboxHealth该从站邮箱健康度（UNKNOWN/HEALTHY/DEGRADED）
diagnostics.is_free_run_demotedbool该从站是否被迫从 DC 降级到 FreeRun
diagnostics.health_degraded_countint该从站邮箱半失效连续累计计数（≈秒数）
diagnostics.recover_mailbox_health()bool手动触发邮箱半失效修复（内核通常自动修复）
WcContribution 枚举值（WKC 贡献状态）
class WcContribution(IntEnum):
    NOT_CONTRIBUTED = 0x00  # 该从站此刻没在贡献 WKC（掉站 / 无响应）
    CONTRIBUTED = 0x01      # 该从站正常贡献 WKC（在总线上响应）
    UNKNOWN = 0xFF          # 内核未填充 / 未映射 — 诚实未知，不当作没贡献
EcMailboxHealth 枚举值（邮箱健康度）
class EcMailboxHealth(IntEnum):
    UNKNOWN = 0    # 无邮箱 / 不在 OP — 邮箱健康度此时无意义
    HEALTHY = 1    # 在 OP 且邮箱可用
    DEGRADED = 2   # 在 OP 但邮箱半失效（CoE/SDO 可能阻塞）

WKC 贡献语义​

slave.diagnostics.wc_contributed 反映此刻该从站是否真的在响应：

  • CONTRIBUTED — 该从站正常贡献工作计数器（WKC），即聚合 WKC 完整（actual == expected，亦即缺口 WcDeficit == 0）时各从站逐字节比对都"满"。
  • NOT_CONTRIBUTED — 该从站此刻没在贡献 WKC（疑似掉站 / 热插拔恢复中）。这不是 master 故障，从站修复后内核镜像自然回到 CONTRIBUTED。
  • UNKNOWN — 内核未填充 / 未映射，诚实暴露，不臆造为"已贡献"。
R1 可靠性铁律

本属性仅"如实反映总线现实", 不参与任何 WKC 篡改 / 迁就逻辑。逐从站贡献位是聚合 WKC 缺口（expected - actual）的逐站分解：缺口大于 0 表示有从站此刻未贡献，应报警 + 诊断，不下调 expected、不停 OP。

示例:

for slave in master:
    if slave.diagnostics.wc_contributed == WcContribution.NOT_CONTRIBUTED:
        al = slave.diagnostics.al_status_mirror
        print(f"从站 {slave.slave_num} 此刻未贡献 WKC（疑似掉站），AL Code=0x{al.al_status_code:04X}")
    if slave.diagnostics.mailbox_health == EcMailboxHealth.DEGRADED:
        print(f"从站 {slave.slave_num} 在 OP 但邮箱半失效, 已持续 {slave.diagnostics.health_degraded_count}s")

ESI 方法​

set_esi_file(esi_file_name)​

def set_esi_file(esi_file_name: str) -> bool

设置从站使用的 ESI 文件。

返回值:

  • bool — 是否成功

过程数据看门狗​

set_watchdog(timeout_ms)​

def set_watchdog(timeout_ms: int) -> bool

设置从站过程数据看门狗超时。从站在超时时间内未收到过程数据帧时触发看门狗错误（ALStatusCode 0x001B）。

参数:

  • timeout_ms (int) — 超时时间（毫秒），0 = 禁用，最大 6553ms

返回值:

  • bool — 是否成功
备注

应在 SafeOp 或 OP 状态下调用。

set_pdi_watchdog(timeout_ms)​

def set_pdi_watchdog(timeout_ms: int) -> bool

设置从站 PDI 看门狗超时。PDI 看门狗监控从站本地应用（微控制器固件）是否正常运行。

参数:

  • timeout_ms (int) — 超时时间（毫秒），0 = 禁用

返回值:

  • bool — 是否成功

示例:

slave.set_watchdog(100)  # 100ms 超时
slave.set_watchdog(0)    # 禁用看门狗

watchdog_config​

@property
def watchdog_config(self) -> Optional[dict]

读取从站看门狗当前配置。返回 None 表示读取失败。

返回值:

  • Optional[dict] — 看门狗配置字典，包含以下键:
    • divider (int) — 看门狗分频器
    • pdi_timeout (int) — PDI 看门狗超时值（分频器单位）
    • pd_timeout (int) — 过程数据看门狗超时值（分频器单位）

示例:

config = slave.watchdog_config
if config is not None:
    print(f"PD超时: {config['pd_timeout']} × {config['divider'] * 0.04}µs")

watchdog_status​

@property
def watchdog_status(self) -> Optional[dict]

读取从站看门狗运行状态。返回 None 表示读取失败。

返回值:

  • Optional[dict] — 看门狗状态字典，包含以下键:
    • status (int) — 看门狗状态值
    • counter (int) — 看门狗计数器（过期累计次数）
    • divider (int) — 当前分频器值
    • pd_timeout (int) — 当前过程数据超时值

示例:

status = slave.watchdog_status
if status is not None and status['status'] != 0:
    print(f"看门狗触发! 计数: {status['counter']}")

状态切换​

set_state(state, timeout_ms=5000)​

def set_state(state: EcState, timeout_ms: int = 5000) -> bool

设置单个从站 EtherCAT 状态（带超时）。用于手动恢复或将单个从站切换到指定状态，整网级状态机请使用 master.set_state()。

参数类型默认说明
stateEcState—目标状态
timeout_msint5000超时时间（毫秒）

返回值：

类型说明
bool是否成功
备注

状态切换遵循 EtherCAT 标准状态机流程，协议层自动处理中间状态。例如从 INIT 切换到 OP 会自动经过 PreOp → SafeOp → OP。

示例:

# 手动恢复单个从站到 OP
if slave.state != EcState.OP:
    slave.set_state(EcState.OP)

# 将从站切换到 Init（重置）
slave.set_state(EcState.INIT, timeout_ms=5000)

实时状态查询 (2.5.x 新增)​

slave.state / slave.error_code 返回的是周期缓存值。如需绕开缓存直读总线当前的 AL 状态 (例如故障注入测试、热插拔验证), 可通过 DLL 层的实时查询接口:

DLL 接口返回说明
GetSlaveStateLive(mi, si)u8实时 AL State (bit0-3=状态, bit4=Error 标志)
GetSlaveALStatusCodeLive(mi, si)u16实时 AL Status Code

这两个接口直接发 FPRD 读 ESC 0x0130 / 0x0134, 不经周期状态缓存。

示例:

from darra_ethercat import EcState, EcALState

mi, si = master.master_index, slave.slave_num

raw = master._dll.GetSlaveStateLive(mi, si)
state = EcState(raw & 0x0F)
has_error = (raw & 0x10) != 0

code = master._dll.GetSlaveALStatusCodeLive(mi, si)
print(f"实时状态: {state.name}, Error={has_error}, AL Code=0x{code:04X}")
何时用 Live 查询
  • 常规监控 — 用 slave.state / slave.diagnostics, 走周期缓存, 开销最低
  • Live 查询 — 仅在需要确认"此刻总线上从站真实状态"的诊断 / 测试场景, 每次都发实报文, 不要在高频路径调用

ESC 寄存器访问 (高级)​

直接读写从站 ESC (EtherCAT Slave Controller) 寄存器，用于故障诊断、自定义 ESC 操作、底层调试。协议层走 FPRD/FPWR 数据报，自动 primary → secondary → APWR 三级回退。

高级 API

正常使用 SDK 时无需调用 — 状态切换 / PDO / 邮箱等流程 SDK 已自动配置寄存器。此 API 用于深度诊断和特殊场景（例如读取错误计数器、强制端口策略、调试 ESI 烧写不生效等）。

寄存器定义见 ETG.1000.4 §6 / ETG.1000.6 §5（公开标准），例如：

寄存器说明
0x0000Type / Revision / Build（设备类型）
0x0030AL Control（主站发起状态请求）
0x0130AL Status（从站当前状态）
0x0134AL Status Code（错误码）
0x0300-0x030F端口 0-3 错误计数器
0x0400-0x043F看门狗配置 / 计数

read_register(addr, length)​

def read_register(self, addr: int, length: int) -> Optional[bytes]

读取从站 ESC 寄存器（FPRD）。

参数:

  • addr (int) — 寄存器地址（例如 0x0130 = AL Status）
  • length (int) — 读取字节数（1 / 2 / 4 等）

返回值:

  • Optional[bytes] — 读取成功返回字节数据；失败（从站离线 / 超时）返回 None

write_register(addr, data)​

def write_register(self, addr: int, data: bytes) -> bool

写入从站 ESC 寄存器（FPWR）。

参数:

  • addr (int) — 寄存器地址
  • data (bytes) — 写入数据

返回值:

  • bool — 成功返回 True

示例:

slave = master[1]                 # 1-based 索引, 第 1 个从站

# 读取 AL Status (0x0130, 2 字节)
data = slave.read_register(0x0130, 2)
if data:
    state = int.from_bytes(data, 'little')
    print(f"AL Status = 0x{state:04X} (state={state & 0x0F}, err={(state & 0x10) != 0})")

# 读取 AL Status Code (0x0134, 错误码)
code_bytes = slave.read_register(0x0134, 2)
if code_bytes:
    code = int.from_bytes(code_bytes, 'little')
    print(f"AL Status Code = 0x{code:04X}")

# 写 AL Control = 0x04 (请求 SafeOp)
slave.write_register(0x0030, bytes([0x04, 0x00]))

EEPROM (SII) 访问​

读写从站 SII EEPROM (Slave Information Interface, ETG.1000.6 §6)。EEPROM 存储 vendor_id / product_code / revision_no / serial_no / SyncManager / FMMU / PDO 映射 / Strings 等设备身份与配置信息。SDK 在 config_init 阶段已自动读取，应用一般无需直接访问。

危险操作

EEPROM 写入慎用 — 写错可能导致从站身份信息错乱，严重时永久 brick 从站, 需厂家工具恢复。仅在以下场景使用：

  • 烧写 alias 地址（Hot-Connect 别名）
  • 修复出厂数据被误覆盖
  • 厂商授权的固件 / 参数烧录

EEPROM 写需要从站处于 Init / PreOp 状态，OP 状态下写入会被拒绝。

EEPROM 大小通常 1 KB - 16 KB（按 word 寻址，1 word = 2 byte）。起始 8 word 为厂商基本信息，之后是 Category 链表（Strings / General / FMMU / SyncM / TxPdo / RxPdo / DC / End=0xFFFF）。

read_eeprom(byte_offset, byte_length)​

def read_eeprom(self, byte_offset: int, byte_length: int) -> bytes

读取从站 SII EEPROM 字节区域 (按 word 循环, 内部走 SIIReadWord)。SDK 自动处理 BUSY 轮询、字对齐, 推荐应用层优先使用此高层 API。

参数:

  • byte_offset (int) — 起始字节偏移 (建议偶数对齐, 奇数自动按低字节对齐)
  • byte_length (int) — 读取字节数 (建议偶数, 奇数末尾自动取低字节)

返回值:

  • bytes — byte_length 字节数据; 失败或参数非法返回空 b""

write_eeprom(byte_offset, data)​

def write_eeprom(self, byte_offset: int, data: bytes) -> bool

写入从站 SII EEPROM 字节区域 (按 word 循环, 内部走 SIIWriteWord)。byte_offset 与 len(data) 都必须是偶数。

参数:

  • byte_offset (int) — 起始字节偏移 (必须偶数)
  • data (bytes) — 写入字节 (长度必须偶数)

返回值:

  • bool — 全部 word 成功写入返回 True

示例:

slave = master[1]                 # 1-based 索引, 第 1 个从站

# 读 vendor_id (EEPROM 字节偏移 0x10, 长度 4)
data = slave.read_eeprom(0x10, 4)
if len(data) == 4:
    vendor_id = int.from_bytes(data, 'little')
    print(f"VendorID = 0x{vendor_id:08X}")

# 读取头部 16 字节 (含 PDIControl / StationAlias 等)
header = slave.read_eeprom(0, 16)
print(f"EEPROM 头部: {header.hex()}")

# 写 alias address (EEPROM 字节偏移 0x08)
# 必须从站处于 Init/PreOp 状态!
if slave.state == EcState.INIT:
    slave.write_eeprom(0x08, bytes([0x01, 0x00]))  # alias = 1
高层 API vs 低层 SII API
  • 首选: read_eeprom / write_eeprom (按字节, 自动字对齐)
  • 次选: slave.vendor_id / product_id / serial_number 等已封装属性
  • 高级用法 (按需): 通过底层 SII 接口读写原始 EEPROM 字节,用于枚举 Category / 读 PDO 映射原始字节 / 烧写 alias 等场景

DL Port 端口控制​

直接读写 ESC 的 DL Port Control 寄存器（0x0101），用于端口故障注入测试和冗余 / 环拓扑的手动诊断。

高级 API

正常运行时无需调用。大部分用户应该通过订阅 slave_port_link_changed 事件和读取 端口错误计数器 来诊断端口状态。仅在需要主动模拟端口故障（测试冗余切换）或排查特定端口问题时使用。

ESC 有 4 个物理端口 P0 / P1 / P2 / P3，DL Port Control 寄存器的位定义如下：

DLPORT 值行为
0x00Auto — 所有端口由 ESC 自动管理（默认）
0x03关闭 P0
0x0C关闭 P1
0x30关闭 P2
0xC0关闭 P3

SDK 的 write_register / read_register 自动采用 primary → secondary → APWR 三级回退写入路径，即使 P0 关闭后仍能通过副网口 / 广播恢复。

经 read_register / write_register 访问

Python SDK 没有专用的 write_dl_port() / read_dl_port() 方法。DL Port Control 寄存器 0x0101 通过通用的 write_register(addr, data) / read_register(addr, length) 直接读写。

写入 DL Port 控制寄存器（0x0101）：

# value 见上表 (0-255), write_register 接受 bytes
slave.write_register(0x0101, bytes([value]))

读取 DL Port 控制寄存器当前值：

data = slave.read_register(0x0101, 1)
dlport = data[0] if data else 0

示例:

# 模拟 P1 端口故障 (测试冗余切换)
ok = slave.write_register(0x0101, bytes([0x0C]))
print(f"关闭 P1: {'成功' if ok else '失败'}")

# 读回确认
data = slave.read_register(0x0101, 1)
dlport = data[0] if data else 0
print(f"当前 DLPORT = 0x{dlport:02X}")

# 故障恢复后还原
slave.write_register(0x0101, bytes([0x00]))  # 恢复 Auto
配合冗余诊断

关闭一个端口后，观察 master.events.add_slave_port_link_changed() 和 master.diagnostics.break_point 验证冗余切换是否生效。

Startup 配置​

Startup 相关属性（should_write_pdo_assignment、should_write_pdo_configuration、supports_complete_access）已包含在上方属性表中。

StartupAutoConfig.set_config_source_eni() / set_config_source_deni()​

def set_config_source_eni(self) -> None
def set_config_source_deni(self) -> None

标记从站配置来源为 ENI 或 DENI 文件。调用后 has_executed 返回 True，config_source 返回对应来源字符串。

这两个方法属于 StartupAutoConfig，不是 Slave 方法

set_config_source_eni / set_config_source_deni 与 has_executed / config_source 属性均定义在 darra_ethercat.slave.startup.StartupAutoConfig 类上, 不能直接 slave.set_config_source_eni() 调用。

StartupParameterList 方法（通过 slave.startup 访问）:

  • add(index, sub_index, data, transition=StartupTransition.IP, priority=0, write_timing=None, complete_access=False, description="") — 用显式参数创建并添加启动参数, 返回创建的 StartupParameter
  • add_parameter(param) — 添加一个已创建的 StartupParameter 对象
  • remove(param) — 移除指定的 StartupParameter 对象, 返回 bool
  • clear() — 清除所有启动参数
  • apply_all(slave) — 应用全部启动参数到从站, 返回成功应用的数量 (int)
注意 add 与 add_parameter 的区别

add() 接受显式字段并在内部构造 StartupParameter; add_parameter() 接受一个已构造好的 StartupParameter 对象。

示例:

from darra_ethercat import StartupParameter
from darra_ethercat.data.types import StartupTransition

# 方式一: add() 用显式参数
slave.startup.add(
    index=0x1C12,
    sub_index=0,
    data=bytes([0]),
    transition=StartupTransition.PS,
    priority=10,
)

# 方式二: 先构造 StartupParameter 对象, 再 add_parameter()
param = StartupParameter(
    index=0x1C13,
    sub_index=0,
    data=bytes([0]),
    transition=StartupTransition.PS,
    priority=10,
)
slave.startup.add_parameter(param)

相关结构:

  • IP — Init → PreOp，默认 AfterTransition
  • PS — PreOp → SafeOp，默认 BeforeTransition
  • SO — SafeOp → Op，默认 BeforeTransition
  • OS — Op → SafeOp，默认 AfterTransition
  • SP — SafeOp → PreOp，默认 AfterTransition
  • PI — PreOp → Init，默认 BeforeTransition

Slave 子结构 (Sub-Structures)​

Phase 2-D 把 EcSlave 的平面字段重新组织为多个领域子结构, 与 C 端 master.h 一一对齐, 既可作为参数传递, 也可在 from_buffer_copy() 后做整体快照。所有子结构均通过 ctypes.Structure 实现, 自然对齐 (无 _pack_)。

Python 特有语法糖

对外暴露时除 ctypes.Structure 还可用 frozen dataclass (例: SlaveIdentityKey) 表达不可变身份, 自动获得 __eq__/__hash__/__repr__ + 元组解包. 详见 dataclass.

from darra_ethercat.data.structures import (
    SlaveIdentity, SlaveMetadata, SlaveCapabilities, SlaveRuntime,
    SlaveSmFmmu, SlaveProtoMbx, SlaveTopology, SlaveDc, SlaveMailbox,
)

SlaveIdentity​

class SlaveIdentity(Structure):
    vendor_id:  c_uint32   # 厂商 ID (eep_man)
    product_id: c_uint32   # 产品 ID (eep_id)
    revision:   c_uint32   # 修订版本 (eep_rev)
    serial:     c_uint32   # 序列号 (eep_ser)
    itype:      c_uint16   # 接口类型 (Itype)
    dtype:      c_uint16   # 设备类型 (Dtype)

身份四元组 + 接口 / 设备类型 (20 字节)。slave.verify_identity(expected) 接受本结构进行身份核对。

SlaveMetadata​

class SlaveMetadata(Structure):
    identity:     SlaveIdentity     # 身份子结构
    group_name:   c_ubyte * 41      # 组名称 (EC_MAXNAME + 1)
    device_name:  c_ubyte * 41      # 设备名称 (EC_MAXNAME + 1)
    sm_count:     c_uint16          # SyncManager 数量

聚合身份 + 组 / 设备名 + SM 数量 (≈104 字节)。

SlaveCapabilities​

class SlaveCapabilities(Structure):
    is_optional:           c_uint8   # 0=必须, 1=可选 (缺席不影响 WKC)
    supports_frame_repeat: c_uint8   # 0=不支持, 1=支持 ETG.1500 帧重复
    mailbox_side:          c_uint8   # 0=auto/dual, 1=primary, 2=secondary
    coe_details:           c_uint8   # CoE 协议位 (CoEdetails)
    foe_details:           c_uint8   # FoE 协议位 (FoEdetails)
    eoe_details:           c_uint8   # EoE 协议位 (EoEdetails)
    soe_details:           c_uint8   # SoE 协议位 (SoEdetails)

Darra 扩展能力 + 各 mailbox 协议明细 (7 字节)。

SlaveRuntime​

class SlaveRuntime(Structure):
    ebus_current: c_int16    # E-bus 电流 (Ebuscurrent)
    block_lrw:    c_uint8    # >0 时禁止使用 LRW (blockLRW)
    group:        c_uint8    # 分组编号
    is_lost:      c_uint8    # 从站是否丢失 (islost)

运行时易变状态 (≈6 字节)。slave.group / slave.is_lost 等属性即派生自此。

SlaveSmFmmu​

class SlaveSmFmmu(Structure):
    sm_type:       c_uint8 * 8    # SM 类型 (SMtype)
    sm_app_length: c_uint16 * 8   # SM 应用层长度
    fmmu_func:     c_uint8 * 4    # FMMU 0-3 功能
    fmmu_unused:   c_uint8        # 第一个未使用的 FMMU 索引

SyncManager 类型 + FMMU 功能映射 (29 字节)。

SlaveProtoMbx​

class SlaveProtoMbx(Structure):
    in_ptr:  c_void_p          # 邮箱输入缓冲区指针 (C 端字段名 in)
    in_full: ctypes.c_bool     # 邮箱输入是否满
    overrun: c_int32           # 邮箱溢出计数

每个邮箱协议 (CoE/SoE/FoE/EoE/VoE/AoE) 对应 1 个 SlaveProtoMbx (16 字节)。

ctypes 字段名 in_ptr

C 端字段名为 in, Python 关键字冲突, 改名为 in_ptr。ABI 偏移与 C 一致, 字段名不影响 layout。

SlaveTopology​

class SlaveTopology(Structure):
    has_dc:         c_uint8    # 是否支持 DC
    phy_type:       c_uint8    # 物理端口类型 (ptype)
    link_count:     c_uint8    # 拓扑类型 (topology)
    active_ports:   c_uint8    # 活动端口位图
    consumed_ports: c_uint8    # 已使用端口位图
    parent:         c_uint16   # 父从站站地址
    parent_port:    c_uint8    # 父从站端口号
    entry_port:     c_uint8    # 入口端口号

物理拓扑信息 (10 字节)。slave.parent_index / slave.parent_station / slave.active_ports 等属性派生自此。

SlaveDc​

class SlaveDc(Structure):
    recvtime:           c_int32 * 4   # 端口 A/B/C/D DC 接收时间 (ns)
    propagation_delay:  c_int32       # 传播延迟 (ns)
    next:               c_uint16      # DC 链下一个从站
    prev:               c_uint16      # DC 链上一个从站
    # ... cycle / shift / active 等字段, 详见源码

DC 时钟相关字段 (≈40 字节)。slave.propagation_delay / slave.dc_active 等属性派生自此。

SlaveMailbox​

class SlaveMailbox(Structure):
    length:          c_uint16   # 写邮箱长度 (mbx_l)
    write_offset:    c_uint16   # 写邮箱偏移 (mbx_wo)
    read_length:     c_uint16   # 读邮箱长度 (mbx_rl)
    read_offset:     c_uint16   # 读邮箱偏移 (mbx_ro)
    supported_proto: c_uint16   # 支持的邮箱协议位 ECT_MBXPROT_*
    cnt:             c_uint8    # 邮箱链路层协议计数器

主邮箱布局信息 (12 字节)。supported_proto 与 slave.coe / slave.foe 等访问器的可用性判断一致。

这些子结构不需要应用层主动构造

SDK 内部从 native 内存做 from_buffer_copy() 快照后通过 slave.identity 等属性返回字典视图, 应用层一般用字典即可; 子结构仅在需要 ABI 对齐传递 (verify_identity) 或自定义快照时显式使用。SlaveMetadata 这类聚合结构没有对应的单一 slave.metadata 访问器, 应用层经 slave.identity / slave.name / slave.sm_count 等独立属性读取等效字段。