EC-Engineer SDK 核心 API 使用指南

EC-Engineer SDK 核心 API 使用指南

📘 文档导航

欢迎！你想开发 EtherCAT 主站配置工具，只使用 SDK 访问 ESI/ENI 数据结构，不使用 WPF UI。

这完全可行！ 以下文档将帮助你快速上手：

---

🚀 快速开始（5 分钟）

<QUICK_START_CORE_API.md>

快速参考卡片，包含：

• ✅ 需要哪些 DLL
• ✅ 5 个最常用的代码片段
• ✅ 核心类快速参考
• ✅ 常见问题解答

适合：想要立即开始编码的开发者

---

📖 完整指南（30 分钟）

<SDK_Core_Usage_Guide.md>

详细的使用指南，包含：

• SDK 架构分层详解
• 核心 DLL 功能说明
• 完整的 API 使用示例
• 项目配置建议
• 数据访问路径图
• 常见问题详解

适合：系统学习核心 API 的开发者

---

🔬 对比分析（15 分钟）

<UI_vs_Core_API_Comparison.md>

UI 层 vs 核心 API 的详细对比：

• Demo 的做法 vs 推荐做法（代码对比）
• 依赖对比表
• 性能和大小对比
• 决策树
• 实际项目建议

适合：想了解为什么不用 UI 层的开发者

---

💻 可运行示例（即刻体验）

<Examples/CoreAPIOnly/>

完整的控制台示例项目：

• 7 个实用示例
• 完全不依赖 UI
• 可直接编译运行
• 详细注释

运行方法：

cd Examples/CoreAPIOnly
msbuild CoreAPIOnly.csproj
cd bin/Debug
EtherCATCoreAPIDemo.exe

适合：想要看到实际运行效果的开发者

---

📂 项目结构

D:\work\50_PLCnext\01_ec_engnieer\01_demo\
│
├── 📄 README_CORE_API.md              ← 你在这里（导航页）
├── 📄 QUICK_START_CORE_API.md         ← 快速开始
├── 📄 SDK_Core_Usage_Guide.md         ← 完整指南
├── 📄 UI_vs_Core_API_Comparison.md    ← 对比分析
│
├── 📁 Examples/
│   └── 📁 CoreAPIOnly/                ← 可运行示例
│       ├── Program.cs                 ← 7 个示例
│       ├── CoreAPIOnly.csproj         ← 项目文件
│       └── README.md
│
├── 📁 Src/                            ← SDK 原始 Demo
│   ├── 📁 C#/                         ← WPF 版本（包含 UI）
│   └── 📁 MFC/                        ← MFC 版本（包含 UI）
│
├── 📚 SDK DLLs（核心 API 需要的）
│   ├── EcCore.dll              ⭐ 必需
│   ├── EcEniEngine.dll         ⭐ 必需
│   ├── EcResources.dll         ⭐ 必需
│   ├── EcWrapper.dll           ⭐ 必需
│   ├── EcWrapperDotNet.dll     ⭐ 必需
│   └── EcMaster.dll            ⭐ 必需
│
├── ❌ UI DLLs（不需要）
│   ├── EcView.dll
│   ├── EcViewControls.dll
│   ├── EcViewModel.dll         ⚠️ 可选（用于项目保存）
│   └── ...
│
└── 📘 官方文档
    ├── EC-Engineer_SDK_Core_Layer4_V3.7.11.chm
    ├── EC-Engineer_SDK_View_Layer2_V3.7.11.pdf
    └── ReleaseNotes.pdf

---

🎯 学习路径建议

路径 1：快速上手（1 小时）

1. 阅读 QUICK_START_CORE_API.md           (5 分钟)
   ↓
2. 运行 Examples/CoreAPIOnly              (5 分钟)
   ↓
3. 修改示例代码，添加自己的设备           (30 分钟)
   ↓
4. 阅读 UI_vs_Core_API_Comparison.md     (15 分钟)
   ↓
5. 开始集成到你的项目

路径 2：系统学习（半天）

1. 运行 SDK 原始 Demo (Src/C#)           (30 分钟)
   - 了解 SDK 能做什么
   ↓
2. 阅读 SDK_Core_Usage_Guide.md          (30 分钟)
   - 理解架构和 API
   ↓
3. 阅读 UI_vs_Core_API_Comparison.md     (15 分钟)
   - 理解 Demo 和核心 API 的区别
   ↓
4. 阅读 Examples/CoreAPIOnly/Program.cs  (30 分钟)
   - 学习实际代码
   ↓
5. 查阅官方文档 .chm                      (按需)
   ↓
6. 开始你的项目开发

---

💡 核心概念速记

SDK 分层

━━━━━━━━━━━━━━━━━━━━━━━━━━━
 UI 层 (WPF)        ← Demo 用
━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ViewModel 层       ← 可选
━━━━━━━━━━━━━━━━━━━━━━━━━━━
 核心 API 层        ← 你需要的！
━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Native 层 (C++)    ← 底层引擎
━━━━━━━━━━━━━━━━━━━━━━━━━━━

最小依赖（6 个 DLL）

EcCore.dll            ← 核心数据模型
EcEniEngine.dll       ← ENI 文件处理
EcResources.dll       ← 资源和日志
EcWrapper.dll         ← Native 引擎
EcWrapperDotNet.dll   ← .NET 互操作
EcMaster.dll          ← 主站管理

核心类关系

EcEmi (主站配置)
   ↓
EcDevice (主站设备)
   ├─ Slaves[]
   │    └─ EcSlave (从站)
   │         ├─ VariablesData → 过程映像
   │         ├─ ObjectDictionary → CoE 对象
   │         └─ PdoData → PDO 配置
   │
   └─ GenerateEni() → ENI 文件

---

🔧 快速代码模板

创建设备

var emi = new EcEmi();
emi.Load(Path.Combine(EcResFileIo.GetInstallDir(), "EMI/default.emi"));
var device = new EcDevice(emi);

添加从站

var slave = device.AppendSlave(
    vendorId: 2,
    productCode: 0x044c2c52,
    revision: 0
);

读取 I/O

foreach (var slave in device.Slaves)
{
    foreach (var variable in slave.VariablesData.Variables)
    {
        Console.WriteLine($"{variable.Name}: {variable.Offset}");
    }
}

导出 ENI

device.GenerateEni("output.xml");

---

❓ 常见问题速查

问题	答案	详见
必须用 WPF UI 吗？	❌ 不需要，可以只用核心 API	QUICK_START
需要引用 EcViewModel.dll 吗？	⚠️ 不需要，除非想用它的保存功能	UI_vs_Core
如何访问 ESI 数据？	使用 EcSlaveInfoManager	SDK_Core_Usage
如何读取 CoE 对象？	使用 slave.ObjectDictionary	Examples/Program.cs
支持哪些 .NET 版本？	.NET Framework 4.0+	CoreAPIOnly.csproj
需要什么平台？	x86 或 x64（匹配 SDK DLL）	SDK_Core_Usage
如何查看 API 文档？	打开 EC-Engineer_SDK_Core_Layer4_V3.7.11.chm	-

---

🎓 示例项目

Example 1: 基本设备创建

var emi = new EcEmi();
var device = new EcDevice(emi);

Example 2: 构建从站网络

var ek1100 = device.AppendSlave(2, 0x044c2c52, 0);
var el2004 = device.AppendSlave(ek1100, 2, 0x07d43052, 0x00100000);
var el1104 = device.AppendSlave(el2004, 2, 0x04503052, 0x00100000);

Example 3: 读取过程映像

var processImage = device.Slaves
    .SelectMany(s => s.VariablesData.Variables)
    .ToList();

Example 4: 导出 ENI

device.GenerateEni("config.xml");

Example 5: 访问对象字典

foreach (var obj in slave.ObjectDictionary.Objects)
{
    Console.WriteLine($"0x{obj.Index:X4}: {obj.Name}");
}

完整代码见 <Examples/CoreAPIOnly/Program.cs>

---

📞 获取帮助

官方文档

• EC-Engineer_SDK_Core_Layer4_V3.7.11.chm - 核心 API 参考
• EC-Engineer_SDK_View_Layer2_V3.7.11.pdf - 视图层文档（如果需要）

示例代码

• Src/C#/ - 官方 WPF Demo
• Examples/CoreAPIOnly/ - 核心 API 示例

本地文档

• 所有 .md 文件都包含详细说明和代码示例

---

🚀 下一步

1. ✅ 运行示例：cd Examples/CoreAPIOnly && msbuild && bin\Debug\EtherCATCoreAPIDemo.exe
2. ✅ 阅读快速开始：<QUICK_START_CORE_API.md>
3. ✅ 查看对比：<UI_vs_Core_API_Comparison.md>
4. ✅ 深入学习：<SDK_Core_Usage_Guide.md>
5. 🎯 开始你的项目开发！

---

📊 总结

	Demo (WPF UI)	你的项目 (核心 API)
UI 框架	WPF (固定)	任意（自己选）
DLL 数量	12+	6
总大小	~20 MB	~6 MB
启动速度	慢	快
学习曲线	需要学 MVVM	直接用 API
灵活性	受限于 WPF	完全自由
适用场景	桌面应用	任何场景

结论：你完全可以只使用核心 API，开发自己的 EtherCAT 配置工具！🎉

---

版本信息

• SDK 版本: EC-Engineer SDK v3.7.11
• 文档创建: 2025
• 目标平台: .NET Framework 4.0+
• 支持架构: x86 / x64

---

开始你的 EtherCAT 主站配置工具开发之旅！ 🚀