emxdemo 仿真目标机使用指南
概述
emxdemo 是随 EmeyeStudio 一起发布的 Windows 仿真 XCP 从机目标机。它在没有真实硬件的情况下模拟一台电机控制器：内部运行一组模拟的电机信号（转速、三相电流、母线电压、温度等），并通过虚拟串口对外提供标准 XCP 通信接口。
借助 emxdemo，您可以在纯 PC 环境中完整体验 EmeyeStudio 的核心功能：
| 功能 | 体验内容 |
|---|---|
| Scope 实时监控 | 观察转速、三相电流、母线电压等实时波形 |
| Watch 窗口 | 实时查看与修改变量值 |
| Recorder + 触发器 | 配置触发条件，捕获转速超限、故障置位等事件 |
| 数据分析 | 对录制数据运行 PMSM 磁链观测器算法 |
| Power-on Recorder | 体验上电预录波（目标机开机前自动记录启动瞬态） |
本指南提供两条体验路径：
- 方式一：从零创建工程（推荐） —— 走一遍完整的建工程流程，学习如何在真实项目中使用 EmeyeStudio；
- 方式二：打开预置工作区（可选捷径） —— 直接打开随包发布的现成工作区，快速查看效果。
emxdemo 同时也是《emXCP 目标机库 集成说明及核心设计文档》的参考样例：其源码展示了如何在目标程序中集成 emXCP 从机库（初始化、内存分配、上电预录波配置），供二次开发参考。
工作原理简介
emxdemo 在 Windows 进程中模拟了真实 MCU 的关键要素：
- 仿真 RAM：在固定地址 0x20000000（STM32 系列 RAM 典型基址）分配 64KB 内存，全部 demo 变量定位于其中，XCP 变量地址即真实物理地址；
- 电机信号模型：转速按三角波规律在 0~3000rpm 之间循环变化（周期 20s），三相电流为随转速改变幅值的对称正弦波，母线电压含 100Hz 纹波，故障码每 60s 周期性置位一次（持续 500ms）；
- 通信接口：通过虚拟串口对与 EmeyeStudio 通信，XCP 协议与真实从机完全一致。
一、准备工作：安装虚拟串口对
emxdemo 与 EmeyeStudio 之间通过一对虚拟串口通信，需先安装 com0com（开源虚拟串口驱动）：
- 下载并安装 com0com（安装过程如提示未签名驱动，选择允许安装）；
- 安装完成后打开「Setup Command Prompt」或设备管理器，确认默认创建了串口对（通常为 COM10 ↔ COM11）；
- 如果您的电脑已有占用 COM10/COM11 的设备，可用 com0com 的
change命令将虚拟串口对改为其他空闲端口号（例如 COM13 ↔ COM14），并同步调整后文的启动参数与设备配置。
提示：在设备管理器 → 端口（COM 和 LPT）中可查看 com0com 创建的端口对名称。
二、启动 emxdemo
emxdemo.exe 位于发布包的 emxdemo-src\bin\ 目录。
基本用法（使用默认 COM10、115200）：
emxdemo.exe
指定端口和波特率：
emxdemo.exe -p COM13 -b 115200
| 参数 | 说明 | 默认值 |
|---|---|---|
-p <port> |
XCP 通信串口（虚拟串口对的一端） | COM10 |
-b <baud> |
波特率 | 115200 |
启动成功后窗口显示：
=============================================
EmeyeStudio Demo Target (emxdemo)
=============================================
[emxdemo] Simulated RAM : 0x20000000 - 0x2000FFFF (64KB)
[emxdemo] Variables : 0x20000000 - 0x20000033 (14 vars, see emxdemo.elf)
[emxdemo] Recorder buf : 0x20001000 - 0x20008FFF (32KB)
[emxdemo] XCP transport : \\.\COM10 @ 115200 baud
[emxdemo] XCP slave initialized (irq period 1ms).
[emxdemo] Power-on pre-recording started (6 vars, max duration).
保持此窗口开启，emxdemo 开始以 1ms 周期更新模拟信号。按 Ctrl+C 或关闭窗口退出。
三、方式一：从零创建工程（推荐）
以下流程模拟真实目标机的调试过程，逐步创建工程并体验各特性。全部操作只需 emxdemo 在后台运行。
第 1 步：新建工作区
- 启动 EmeyeStudio，在欢迎对话框中点击「新建工作区」（或菜单「文件」→「新建工作区」）；
- 选择保存位置（建议放在您的文档目录下，例如
MyDemo\），输入工作区名称（如emx-demo）； - 点击「确定」，资源浏览器中将出现新工作区。
第 2 步：创建工程
- 菜单「文件」→「创建工程」；
- 输入工程名称（如
motor-demo），确定； - 工程出现在工作区的工程列表中。
第 3 步：配置串口设备
- 在资源浏览器中展开「资源」→「硬件设备」，右键选择「添加设备」；
- 设备类型选择串口，配置参数：
- 端口：选择虚拟串口对的另一端（emxdemo.exe 占用一端，如 COM10，这里选 COM11）；
- 波特率：115200；数据位 8；停止位 1；校验无； - 命名设备（如
emxdemo-vcom）并保存。
端口选择口诀：emxdemo.exe 用一端，EmeyeStudio 设备用另一端。若 emxdemo 用了非默认端口（如 -p COM13），这里对应改成 COM14。
第 4 步：导入 ELF 并添加变量
emxdemo 的声明 ELF 文件位于安装目录 emxdemo\motor-demo\emxdemo.elf，其中包含全部 14 个 demo 变量的名称与地址。
- 在资源浏览器中右键「ELF资源」节点 →「添加」，选择上述 emxdemo.elf 文件；
- 等待解析完成（应显示 14 个变量）；
- 右键 ELF 文件节点 →「查找全局变量」，输入
g_过滤； - 全选 14 个变量，点击「添加到工程」；
- 变量出现在工程的「变量引用」→「ELF变量」下。
demo 变量一览
| 变量名 | 类型 | 单位 | 说明 |
|---|---|---|---|
| g_motorSpeed | float | rpm | 转速（0~3000 三角波，周期 20s） |
| g_phaseCurrentA/B/C | float | A | 三相电流（对称正弦，幅值随转速变化） |
| g_busVoltage | float | V | 母线电压（48V + 100Hz 纹波） |
| g_pwmDuty | float | % | PWM 占空比 |
| g_motorTemp | float | ℃ | 电机温度（25~65℃ 慢漂移） |
| g_idRef / g_iqRef | float | A | d/q 轴电流给定 |
| g_udVoltage / g_uqVoltage | float | V | d/q 轴电压 |
| g_runCounter | unsigned int | - | 运行计数器 |
| g_faultCode | unsigned short | - | 故障码（周期性演示置位） |
| g_ctrlMode | unsigned char | - | 控制模式 |
第 5 步：Scope 实时监控
- 在工具栏将模式切换为 Scope；
- 选中要观测的变量（建议 g_motorSpeed、g_phaseCurrentA/B/C、g_busVoltage），右键「添加到图形分析」；
- 点击「连接」按钮，状态栏显示已连接后点击「开始」（F5）；
- 波形视图将显示实时曲线：转速三角波每 20s 一个周期，三相正弦电流幅值随转速变化；
- 使用鼠标滚轮缩放、拖拽平移，用十字光标读取数值。
第 6 步：Watch 窗口
- 切换到 Watch 模式，添加 g_motorSpeed、g_faultCode、g_ctrlMode、g_runCounter；
- 采集运行时实时查看数值变化：转速爬升/回落、故障码周期性跳变、计数器递增；
- 双击变量可修改其值（demo 信号每周期重新计算，写入值会被信号模型覆盖，用于体验写入功能即可）。
第 7 步：Recorder 与触发器
- 切换到 Recorder 模式；
- 添加要录制的变量（如 g_motorSpeed、g_faultCode）；
- 在触发器配置中新建触发条件：
- 条件一：变量g_motorSpeed，比较方式「大于」，阈值1500—— 转速越限触发；
- 条件二：变量g_faultCode，比较方式「大于」，阈值0—— 故障置位触发； - 点击「开始」进入等待触发状态：转速三角波每 20s 越过一次 1500rpm，最多等待约 10 秒即可触发；
- 触发后查看录制的波形（预触发/后触发各 500ms），确认触发时刻前后数据完整；
- 录制数据可保存到工程 Data 目录，供离线分析。
第 8 步：磁链观测器数据分析
demo 的转速/电流/电压信号恰好构成一组 PMSM 运行数据，可直接作为磁链观测器的输入。
- 采集一段数据（Scope 实时数据或 Recorder 录制数据均可）；
- 打开「算法」对话框，选择 PMSM 磁链观测器；
- 配置输入映射：
| 输入端口 | 绑定变量 |
|---|---|
| id | g_idRef |
| iq | g_iqRef |
| omega_m | g_motorSpeed |
| ud | g_udVoltage |
| uq | g_uqVoltage |
- 配置参数：
| 参数 | 值 | 说明 |
|---|---|---|
| K1 | 100 | 观测器增益 1 |
| K2 | 100 | 观测器增益 2 |
| Ld / Lq | 0.001 | d/q 轴电感 (H) |
| Rs | 0.5 | 定子电阻 (Ω) |
| pole_pairs | 4 | 极对数 |
| psi_f | 0.01 | 转子磁链 (Wb) |
| sample_time | 5e-05 | 采样周期 (s) |
- 运行算法，查看估算磁链波形。
磁链观测器的原理与详细操作见 PMSM 磁链观测器快速入门。
第 9 步：Power-on Recorder（上电预录波）
emxdemo 演示了从机端上电预录波功能：emxdemo 启动时即自动在后台记录 6 个变量（转速、三相电流、母线电压、电机温度），无需上位机参与。
体验流程：
- 启动（或重启）emxdemo.exe；
- 在 EmeyeStudio 中切换到 Power-on Recorder 模式，创建配置：
- 启用「使用预录波数据」（usePreRec）；
- 记录时长 200ms、采样周期 500μs；
- 添加 6 个变量：g_motorSpeed、g_phaseCurrentA/B/C、g_busVoltage、g_motorTemp； - 连接后读取预录数据，查看目标机启动前后的变量曲线。
这是该功能相对传统 Recorder 的核心价值：真实目标机上，它能让您看到固件复位、电机上电瞬间（上位机尚未连接时）的电气瞬态。
四、方式二：打开预置工作区（可选捷径）
如果希望跳过建工程步骤直接查看效果，可打开随包发布的现成工作区：
- 菜单「文件」→「打开工作区」，选择安装目录下的
emxdemo\emxdemo.workspace； - 预置内容包括：
- 设备emxdemo-vcom（串口 COM11）；
- 工程motor-demo，已从声明 ELF 导入全部 14 个变量；
- 已配置的 Scope / Recorder / Power-on Recorder 实例；
- 已配置的 PMSM 磁链观测器（输入映射与参数齐备，直接运行即可）； - 若您的虚拟串口对不是 COM10 ↔ COM11，请在「连接设置」中修改设备端口，并以对应参数重启 emxdemo.exe；
- 连接后即可按「方式一」中第 5~9 步的相同方式体验各功能。
预置工作区仅作为快速体验入口；正式使用建议按「方式一」自行创建工程，熟悉完整流程。
五、目录与文件说明
发布包中与 emxdemo 相关的内容：
EmeyeStudio.exe 所在目录/
├── emxdemo/ # 预置 demo 工作区（方式二可选打开）
│ ├── emxdemo.workspace # 工作区文件
│ └── motor-demo/
│ ├── motor-demo.project # 工程配置（变量/采集/算法配置）
│ └── emxdemo.elf # 声明 ELF（方式一建工程时也从这里引用）
└── emxdemo-src/ # demo 源码包（供参考与重编译）
├── src/ # 仿真器源码（main.c/signals.c/target_defs.h）
├── arm/ # 声明 ELF 工程（ARM GCC 编译）
├── CMakeLists.txt # CMake 构建配置
├── build.bat # 一键构建脚本（debug/release/clean）
├── bin/
│ └── emxdemo.exe # 预编译可执行文件（可直接使用）
└── sdk/ # emXcp 从机库开发包（静态库 + 头文件）
六、从源码重编译
emxdemo-src 包含完整源码与 emXcp 开发包，可自行重编译（需安装 CMake、Ninja 及 MinGW-w64 工具链，且为 32 位 MinGW 以匹配 emXcp 静态库）：
cd emxdemo-src
build.bat # 默认 Debug 构建
build.bat release # Release 构建（自动去除符号表）
构建产物：
build\bin\emxdemo.exe— 仿真器；build\elf\emxdemo.elf— 声明 ELF（需安装 ARM GCC，未安装时自动跳过，可继续使用包内预置的 emxdemo.elf）。
关于 emXcp 从机库的完整集成方法（内存分配、初始化、上电预录波接口等），参见《emXCP 目标机库 集成说明及核心设计文档》及 emxdemo-src 源码中的注释说明。
常见问题
Q: emxdemo 启动正常，但 EmeyeStudio 连接不上？
A: 依次检查：
- com0com 是否已安装并创建串口对（设备管理器 → 端口）；
- emxdemo.exe 使用的端口与工作区设备端口是否为同一对虚拟串口的两端；
- 波特率是否一致（默认 115200）；
- 虚拟串口对是否被其他程序占用。
Q: com0com 安装失败或驱动签名警告？
A: com0com 为开源驱动，在部分 Windows 版本上安装时需要允许未签名驱动（测试模式下安装或使用新版签名安装包）。也可改用其他虚拟串口软件（只要能创建成对的互联 COM 端口即可）。
Q: 我的电脑没有 COM10/COM11（被占用或编号不够）？
A: 用 com0com 将虚拟串口对改为其他空闲端口（如 COM13↔COM14），emxdemo.exe 用 -p COM13 启动，EmeyeStudio 设备端口改为 COM14。
Q: 自建工程看不到变量或地址解析失败？
A: 确认引用的 ELF 是安装目录 emxdemo\motor-demo\emxdemo.elf（与 emxdemo.exe 版本匹配）；添加变量后执行「解析所有地址」；demo 变量从 0x20000000 起固定布局。
Q: 波形是一条直线？
A: 等待信号变化（转速三角波周期 20s，温度漂移周期 5 分钟）；或检查 Y 轴范围（右键 →「适应窗口」）。
Q: Recorder 无法触发？
A: 确认触发条件已创建并绑定（变量、比较方式、阈值），且已点击「开始」进入等待触发状态；转速条件阈值不超过 3000 才会在三角波周期内触发。
相关文档
- 快速入门概述 - 快速入门总览
- 第一个工程 - 通用的建工程流程详解
- PMSM 磁链观测器快速入门 - 算法分析详细操作
- Scope 模式 - 实时波形显示
- Recorder 模式 - 触发式录制
- Power-on Recorder - 上电自动录制
- 触发条件配置 - 触发器详解
- 变量管理 - 变量导入与解析
- 目标机集成与 Boot 部署 - 真实目标机上的 emXCP 集成指南