主站对象字典 (Master OD)

符合 ETG.1510 标准的主站对象字典，提供主站身份信息、从站配置/状态/诊断数据，供外部诊断工具和 HMI 通过标准 SDO 接口访问。

通过 master.master_od 访问。

ETG.1510 标准

主站对象字典按照 ETG.1510 规范实现。配合邮箱网关使用，可实现远程诊断工具对主站的标准访问。

对象索引总览

索引	类别	名称	子索引数	读写	说明
0x1000	设备标识	Device Type	0	只读	0x00001389（EtherCAT Master）
0x1008	设备标识	Manufacturer Device Name	0	只读	"Darra EtherCAT Master"
0x1009	设备标识	Manufacturer Hardware Version	0	只读	x64
0x100A	设备标识	Manufacturer Software Version	0	只读	原生库版本号（major.minor.build）
0x1018	设备标识	Identity Object	4	只读	主站身份信息
0x8nnn	从站配置	Configuration Data	40	只读	第 n 个从站的配置数据
0x9nnn	从站信息	Information Data	32	只读	第 n 个从站的检测信息
0xAnnn	从站诊断	Diagnosis Data	19	只读	第 n 个从站的诊断数据
0xF002	扫描	Detect Modules Command	3	只读	从站扫描状态
0xF120	主站诊断	Master Diag Data	16	只读	主站诊断数据
0xF200	诊断控制	Diag Interface Control	16	读写	诊断接口控制

备注

nnn = 从站编号（1-based），索引根据 master.slave_count 动态生成。例如 3 个从站时，0x8001 ~ 0x8003、0x9001 ~ 0x9003、0xA001 ~ 0xA003 均可访问。

0x1018 — 主站身份 (Identity Object)

子索引	类别	名称	类型	值	读写	说明
0	身份	Number of Entries	int	4	只读	固定
1	身份	Vendor ID	int	0x00001164	只读	ETG 分配，固定值
2	身份	Product Code	int	0x00000001	只读	固定值
3	身份	Revision Number	int	自动	只读	自动从原生库版本派生（高字=主版本，低字=次版本）
4	身份	Serial Number	int	自动自增	只读	每个实例自动分配 0, 1, 2...，用于多主站实例区分

0x8nnn — 从站配置数据

每个从站对应一个 0x8nnn 对象（nnn = 从站编号），包含 ENI 中配置的静态信息。

子索引	类别	名称	类型	读写	说明
0	结构	Number of Entries	int	只读	固定 40
1	地址	Fixed Station Address	int	只读	站地址（当前实现返回从站索引 slave.index）
2	标识	Type	str	预留	设备类型字符串（DriveName）
3	标识	Name	str	预留	设备名称
4	标识	Device Type	int	预留	设备类型编码
5	标识	Vendor ID	int	只读	厂商 ID
6	标识	Product Code	int	只读	产品代码
7	标识	Revision Number	int	只读	修订号
8	标识	Serial Number	int	只读	序列号
33	邮箱	Mailbox Out Size	int	预留	SM0 邮箱输出大小
34	邮箱	Mailbox In Size	int	预留	SM1 邮箱输入大小
35	链路	Link Status	int	预留	端口链路状态（低4位：端口连接，高4位：物理链路）
36	链路	Link Preset	int	预留	端口链路预设（根据拓扑设置）
37	链路	Flags	int	预留	从站标志（Bit3: 热连接组成员）
38	链路	Port Physics	int	预留	端口物理类型
39	邮箱	Mailbox Protocols	int	预留	支持的邮箱协议（CoE=0x04, FoE=0x08 等）
40	诊断	Diag History Supported	int	预留	是否支持 0x10F3 诊断历史对象

实现范围

read_object 对 0x8nnn 当前只实现子索引 0、1、5–8；标注「预留」的子索引是 ETG.1510 布局占位，读取返回 None。

0x9nnn — 从站检测信息

每个从站对应一个 0x9nnn 对象，包含运行时检测到的实际信息。

子索引	类别	名称	类型	读写	说明
0	结构	Number of Entries	int	只读	固定 32
1	地址	Station Address	int	只读	站地址（当前实现返回从站索引 slave.index）
5	标识	Vendor ID	int	只读	检测到的厂商 ID
6	标识	Product Code	int	只读	检测到的产品代码
7	标识	Revision Number	int	只读	检测到的修订号
8	标识	Serial Number	int	只读	检测到的序列号
32	链路	DL Status	int	预留	DL Status 寄存器（ESC 0x0110-0x0111）

实现范围

read_object 对 0x9nnn 当前只实现子索引 0、1、5–8；子索引 32 为 ETG.1510 布局占位，读取返回 None。

0xAnnn — 从站诊断数据

每个从站对应一个 0xAnnn 对象，包含诊断数据。子索引 18 每次读取时实时取自从站 CoE 最近一次 SDO Abort Code；其余子索引为 SDK 侧诊断缓存（初始 0，计数器可经 0xF200:16 复位），当前不随从站实时刷新。

子索引	类别	名称	类型	读写	说明
0	结构	Number of Entries	int	只读	固定 19
1	状态	AL Status	int	只读	当前 AL 状态
2	控制	AL Control	int	只读	AL 控制字（写入未实现，write_object 返回 False）
3	状态	Last AL Status Code	int	只读	最近一次 AL 错误码（ESC 0x0134）
4	链路	Link Conn. Status	int	只读	端口链路连接状态
5	链路	Link Control	int	只读	链路控制（DL Control 寄存器 0x0101）
6	链路	Fixed Addr Conn. Port 0	int	只读	Port 0 连接的从站配置地址
7	链路	Fixed Addr Conn. Port 1	int	只读	Port 1 连接的从站配置地址
8	链路	Fixed Addr Conn. Port 2	int	只读	Port 2 连接的从站配置地址
9	链路	Fixed Addr Conn. Port 3	int	只读	Port 3 连接的从站配置地址
10	链路	Frame Error Port 0	int	只读	Port 0 帧错误计数
11	链路	Frame Error Port 1	int	只读	Port 1 帧错误计数
12	链路	Frame Error Port 2	int	只读	Port 2 帧错误计数
13	链路	Frame Error Port 3	int	只读	Port 3 帧错误计数
14	计数	Cyclic WC Error Counter	int	只读	周期性工作计数器错误
15	计数	Slave Not Present Counter	int	只读	从站不在线计数
16	计数	Abnormal State Change Counter	int	只读	异常状态变化计数
17	链路	Disable Auto Link Control	int	只读	自动链路控制禁用标志
18	协议	Last CoE/SoE Protocol Error	int	只读	最近一次 CoE/SoE 协议错误码（实时取自 slave.coe.last_sdo_error）
19	诊断	New Diag Messages	int	只读	是否有新诊断消息（通过 0x10F3 检测）

0xF002 — 扫描命令

安全保护

0xF002 扫描命令禁止外部写入。运行中执行扫描可能导致配置丢失和设备异常，因此该对象为只读。 从站扫描仅在主站初始化阶段由内部逻辑执行。 更多功能请等待未来更新。

子索引	类别	名称	类型	读写	说明
0	结构	Number of Entries	int	只读	固定 3
1	扫描	Scan Command Request	int	只读	扫描命令请求（禁止外部写入）
2	扫描	Scan Command Status	int	只读	1=完成无错误， 3=完成有错误， 255=执行中
3	扫描	Scan Command Response	bytes	只读	状态 + 错误码 + 检测到的从站数

实现范围

Python 侧从站扫描不经此对象，当前实现中子索引 2 恒为 1（完成无错误）、子索引 3 中的检测从站数恒为 0。

0xF120 — 主站诊断数据

子索引	类别	名称	类型	读写	说明
0	结构	Number of Entries	int	只读	固定 16
1	统计	Cyclic Lost Frames	int	只读	周期帧累计丢失计数（真实计数值，不做百分比放大）
2	统计	Acyclic Lost Frames	int	只读	非周期性丢帧计数（本实现固定返回 0）
3	统计	Cyclic Frames/Second	int	只读	每秒周期帧数（取自内核总线周期，拿不到真实周期时返回 0）
4	统计	Acyclic Frames/Second	int	只读	每秒非周期帧数（本实现固定返回 0）
16	状态	Master State	int	只读	主站当前 EtherCAT 状态

0xF200 — 诊断接口控制

子索引	类别	名称	类型	读写	说明
0	结构	Number of Entries	int	只读	固定 16
16	控制	Reset Diag Info	int	可写	写入 1 复位所有从站诊断计数器（上升沿触发）

方法

read_object()

def read_object(self, index: int, subindex: int) -> Optional[bytes]

读取主站对象字典中指定索引的数据。

参数：

• index (int) — 对象索引（如 0x1018、0x8001、0xA001）
• subindex (int) — 子索引

返回值：

• Optional[bytes] — 读取的原始数据，未知对象返回 None

示例：

import struct

vid = master.master_od.read_object(0x8001, 5)
if vid is not None:
    vendor_id = struct.unpack('<I', vid)[0]
    print(f"厂商ID: 0x{vendor_id:08X}")

write_object()

def write_object(self, index: int, subindex: int, data: bytes) -> bool

写入主站对象字典。当前仅 0xF200:16（Reset Diag Info）支持写入，其余对象写入返回 False（见上方各对象表格的读写列）。

参数：

• index (int) — 对象索引
• subindex (int) — 子索引
• data (bytes) — 要写入的数据

返回值：

• bool — 写入成功返回 True

get_object_name()

def get_object_name(self, index: int) -> str

获取对象的名称。

参数：

• index (int) — 对象索引

返回值：

• str — 对象名称，未知索引返回 "Unknown"

get_subindex_count()

def get_subindex_count(self, index: int) -> int

获取对象的子索引数量。

参数：

• index (int) — 对象索引

返回值：

• int — 子索引数量（未知索引返回 0）

get_supported_object_indices()

def get_supported_object_indices(self) -> List[int]

获取当前支持的所有对象索引列表（固定索引 + 按从站数量动态生成的 0x8nnn/0x9nnn/0xAnnn）。

返回值：

• List[int] — 支持的索引列表

读写主站对象字典

读写统一经 master.master_od:

# 读取主站对象字典
data = master.master_od.read_object(0x1018, 1)

# 写入主站对象字典 (仅部分对象可写)
ok = master.master_od.write_object(0xF200, 16, bytes([1]))

完整示例

import struct

od = master.master_od

# 遍历所有从站的诊断数据
for i in range(1, master.slave_count + 1):
    cfg_idx = 0x8000 | i
    diag_idx = 0xA000 | i

    # 读取从站名称
    name_data = od.read_object(cfg_idx, 3)
    name = name_data.decode("ascii") if name_data else "N/A"

    # 读取 AL Status 和错误码
    al_status = od.read_object(diag_idx, 1)
    al_code = od.read_object(diag_idx, 3)

    # 读取各端口帧错误计数
    port_errors = []
    for p in range(4):
        err = od.read_object(diag_idx, 10 + p)
        port_errors.append(struct.unpack('<I', err)[0] if err else 0)

    al_val = struct.unpack('<H', al_status)[0] if al_status else 0
    code_val = struct.unpack('<H', al_code)[0] if al_code else 0

    print(f"从站{i} [{name}]: "
          f"AL=0x{al_val:04X}, Code=0x{code_val:04X}, "
          f"Errors={port_errors}")

# 复位所有诊断
od.write_object(0xF200, 16, bytes([1]))