EQIO Studio 使用文档

EQIO Studio 是 EQIO 的工程开发环境，用于创建、编辑、验证和交付控制工程。它把图形化编程、Structured Text（ST）、变量管理、设备接入、HMI 组态、本机 Runtime 验证、源码调试和运行包部署放在同一个工作流中。

本文以“先建模、再验证、最后部署”的顺序介绍常用操作。页面中的功能以当前安装版本为准；不同版本的菜单名称或可用节点可能略有差异。

0. 先做一次 15 分钟入门

下面的流程使用内置的 visual-not.eqio 示例，目标是完成“开关 → NOT → 指示灯”的第一个可运行工程。示例打开后是副本，内置文件不会被覆盖。

1. 从 Studio 启动页进入 工程总览 → 示例工程，搜索 visual-not，打开示例后立即使用 文件 → 另存为 保存到自己的工作目录。也可以把一个本地 .eqio 文件直接拖入 Studio。
2. 在左侧工程树选择 前面板，确认有一个逻辑开关和一个逻辑指示灯。需要新增控件时，在画布上方打开 关联控件，选择逻辑开关、逻辑指示灯、数值输入或数值显示；Studio 会同时创建控件、变量和终端。
3. 按 Ctrl+E 切换到 程序框图。示例已经有 NOT 时先选中它检查连线；在空工程中再从左侧函数库搜索 NOT，双击或拖入画布。先点击开关变量终端的输出端，再点击 NOT 的输入端；再从 NOT 输出端连接到指示灯变量终端。绿色连线表示布尔值，橙色连线表示数值。
4. 单击 NOT，在右侧 块属性与参数 检查名称、端口和变量绑定。若端口未连接，可直接填写常量或选择 true/false；修改后按 Ctrl+S 保存。
5. 点击顶部 运行。这个命令会构建当前工程并启动 Studio 管理的本机 Runtime；它不是源码调试快捷键。切到 变量 或 在线监视，确认变量出现已提交值、质量和时间戳。
6. 回到前面板的运行态，切换开关，观察指示灯变为相反值。设计态不会向 Runtime 写值；只有在线 Runtime 连接后，控件操作才会产生运行请求。
7. 点击 停止，再次 Ctrl+S，在交付前用 文件 → 另存为 或版本工具保留一份可恢复的工程源文件。

如果这条流程不能完成，先看“问题”“输出”和“运行诊断”面板，再继续编辑。不要把画布上显示的设计值当作 Runtime 已提交值。

当前版本能做什么

1. 认识 EQIO Studio

一个 EQIO 工程通常包含以下对象：

• 工程树：组织程序、变量、设备、处理图、HMI 页面和部署目标。
• 图形化程序：通过节点和连线表达数据流、计算、判断、定时和控制关系。
• ST 程序：用结构化文本编写适合文本表达的算法和状态逻辑。
• 变量表：集中维护变量名、数据类型、初始值、读写属性和设备映射。
• 设备与端点：描述采集点、输出点和通信参数；可先连接虚拟设备进行验证。
• HMI 页面：组态画面、报警、趋势和历史查询，交付时由播放器运行。
• 运行时目标：当前以本机 Runtime 为主要闭环；远程目标和发布能力按工具链能力位显示。工程编辑、构建和运行时执行可以分开。

推荐的工作流是：

1. 设计工程结构和变量。
2. 创建图形逻辑或 ST 程序。
3. 用虚拟设备或仿真数据检查采集、计算和控制关系。
4. 构建并部署到本机 Runtime；远程目标只有在当前工具链能力位明确开放时才使用。
5. 在线监视变量、报警、趋势和连接状态。
6. 保存版本，必要时回滚或恢复备份。

2. 安装与首次启动

2.1 安装前检查

在安装前准备以下信息：

• 目标操作系统和运行时架构。
• 工程保存位置，以及用于备份的独立目录。
• 设备通信方式（例如 Modbus TCP 或 Modbus RTU）、地址和串口参数。
• 如果版本明确开放远程目标，再准备主机地址、端口和访问凭据；未开放时先使用本机 Runtime。

工程文件、运行包、缓存和运行数据应分别保存。不要把运行时数据目录当作工程备份目录。

2.2 启动后的检查

首次打开 Studio 后，先确认：

1. 工具栏可以创建或打开工程。
2. 工程树和编辑区正常显示。
3. 运行时连接状态可查看。
4. 新建一个空工程并保存到专用目录。
5. 打开示例或模板时，先另存为自己的工程再修改。

如果编辑器能打开但部署失败，先查看运行时连接、目标地址和版本兼容性；不要反复重建工程来绕过连接问题。

2.3 从命令行启动 Studio

开发环境可在仓库根目录使用匹配版本的工具链启动：

$env:EQIO_TOOLS_DIR = (Resolve-Path .\bin).Path
.\bin\eqio-studio-qt.exe

常用启动参数如下：

• --open <工程路径>：启动后直接打开一个本地 .eqio 文件。
• --port <空闲端口>：为本次 Studio 管理的 Runtime 指定端口，多个实例并行时使用。
• --e2e <毫秒>：保存、构建并运行一段时间后退出，只能对测试副本使用。

如果工具链目录、CLI 和 Runtime 不是同一版本，Studio 会在构建或握手阶段拒绝继续。正式交付时使用与 Studio 同版本的 CLI、Runtime 和 Qt 依赖。

3. 创建工程与管理工作区

3.1 新建工程

1. 选择 新建工程，填写工程名称和保存路径。
2. 在工程树中创建程序、变量表、设备和 HMI 页面。
3. 先保存一次，让 Studio 建立工程目录和初始版本。
4. 在工程设置中确认目标运行时和构建配置。

工程名称用于显示，工程对象的稳定身份由工程内部 ID 管理。移动或重命名工程文件夹前，先关闭工程并保留备份。

3.2 工程树的使用

工程树是日常导航的入口：

• 双击对象进入对应编辑器。
• 右键对象创建同类对象、重命名或删除。
• 使用搜索定位变量、设备端点和程序节点。
• 将大型工程按功能区或设备单元分组，避免所有逻辑堆在一个页面。

删除对象前确认没有其他节点、HMI 控件或设备映射引用它。对于需要保留历史的对象，优先停用或迁移引用，而不是直接删除。

3.3 保存、版本与备份

建议在以下时机创建版本：

• 完成一组变量或设备配置后。
• 仿真通过后、准备部署前。
• 现场变更前。
• 交付和升级前。

备份至少包含工程源文件和版本说明。运行包可重新构建，不应替代源工程备份。

3.4 工作区入口怎么选

内置示例位于 qt/examples/，适合按目标选择：visual-not.eqio 练习布尔逻辑，temperature.eqio 练习比较、延时和报警，common-blocks.eqio 查看 36 类函数块，modbus-loop.eqio 验证 Modbus TCP 模拟闭环。

4. 图形化编程

4.1 放置节点与连线

在图形化编辑器中，从节点面板选择函数块并拖入画布，再按端子方向连接数据线。常见节点包括比较、逻辑、定时、数学计算和 PID 等类型。

4.1.1 用温度阈值示例理解图形逻辑

以 temperature.eqio 为例，可以按下面顺序复现一个“温度超过设定值并持续 300 ms 后报警”的逻辑：

1. 在 工程总览 → 示例工程 打开 temperature.eqio，另存为自己的副本。
2. 在 程序框图 选择温度输入、Setpoint 和报警输出对应的程序。
3. 检查或放置比较节点（例如 GT）和定时节点（TON），把 Temperature 接到比较节点的 A，把 Setpoint 接到 B。
4. 检查比较结果是否连接到 TON 的 IN，把 PT_MS 设为 300；再确认 TON.Q 连接到报警指示灯或报警变量。
5. 单击节点，在右侧 块属性与参数 检查端口、单位和绑定；未接线的输入只能在确定类型后设置常量。
6. 保存并点击 运行，在前面板把输入改为 45（默认 Setpoint 为 20），观察报警在延时后激活；改为 10，观察恢复。
7. 在 变量 或 在线监视 查看输入、比较结果、ET_MS、报警和质量/时间戳；如果只看到设计值，说明当前仍在设计态或 Runtime 尚未连接。

图形编辑器当前已核对的函数块包括 AND、OR、XOR、NOT、ADD、SUB、MUL、DIV、MIN、MAX、LIMIT、SCALE、ABS、NEG、SQRT、MOD、POW、SELECT、GT、GE、LT、LE、EQ、NE、INRANGE、THRESHOLD、TON、TOF、TP、RTRIG、FTRIG、SR、RS、HYSTERESIS、FILTERPT1 和 PID_BASIC。不同工程类型、变量类型和工具链能力位可能限制实际可插入的节点。

连线时检查：

• 输入与输出的数据类型是否一致。
• 标量、数组和结构体是否误接。
• 逻辑方向是否符合采集、处理、输出的顺序。
• 是否存在未连接的必需端子。
• 是否形成不允许的环路或重复驱动。

让每个页面只承担一个清晰职责，例如“温度采集与滤波”“联锁判断”或“报警状态生成”。页面过大时，拆成可复用的子图或功能块。

4.2 读图与维护

为节点和连线使用能表达用途的名称，关键分支旁添加简短注释。把限幅、单位换算和异常值处理放在靠近数据入口的位置，使后续逻辑使用已经校验过的数据。

对于输出控制，明确默认安全值、失联行为和手动覆盖条件。控制路径应能从输出一路追溯到输入和保护条件。

4.3 构建前检查

构建前逐项检查：

• 节点是否有错误标记。
• 变量和设备端点是否全部解析。
• 是否有未连接端子或类型转换警告。
• 定时周期和执行顺序是否符合预期。
• HMI 使用的变量是否仍然存在。

5. Structured Text（ST）

ST 适合状态机、循环、结构化计算和需要文本审查的逻辑。建议把输入读取、状态计算和输出写入分成清晰的区域，避免同一变量在多个位置被隐式改写。

5.1 .eqio 与 .eqst 的区别

• .eqio 是图形工程容器，可同时保存 HMI、变量、设备点和图程序；其中的 ST 内容取决于当前工程和工具链能力，不要把它和独立 ST 调试项目混为一谈。
• .eqst 是独立的 IEC-61131-3 ST 源工程，适合练习源码、部署和断点调试。源码修改后必须保存并重新部署，旧运行包不会自动更新。
• 图形工程的节点在线观察与 ST 源码断点是两条不同链路；当前版本不能把图形节点调试当作已经接入的断点功能。

5.2 ST 源码调试步骤

1. 打开 examples/iec-st/debugging.eqst（或从 Studio 的文件菜单打开自己的 .eqst）。
2. 在部署前勾选 调试启动，保存并部署到本机 Runtime。
3. 点击源码行号或按 F9 设置/取消行断点。
4. Runtime 命中断点后：F5 继续，F10 步过，F11 步入，Shift+F11 步出；调用栈可切换帧并查看局部工作值与提交值。
5. 修改源码后按 Ctrl+S 保存，再重新构建和部署；否则 Studio 会提示源码与运行版本不一致。
6. 暂停 ST 时会暂停整个资源，设备通信仍可能继续，输出使用工程定义的安全策略；恢复前确认现场处于维护窗口。

示例：

IF Enable THEN
    IF Temperature > HighLimit THEN
        AlarmHigh := TRUE;
    ELSIF Temperature < ResetLimit THEN
        AlarmHigh := FALSE;
    END_IF;
ELSE
    AlarmHigh := FALSE;
END_IF;

使用 ST 时注意：

• 变量名反映业务含义，并保持大小写和命名规则一致。
• 明确初始化值和断电、重启后的行为。
• 对数组下标、除数和通信返回值做边界判断。
• 把状态迁移条件写完整，避免多个分支同时写入同一状态。
• 保存后先构建，再进入在线监视；不要直接把未构建文本当作运行结果。

6. 变量、数据类型与设备映射

6.1 变量表

变量表至少应记录：变量名、数据类型、初始值、单位、读写属性、来源和用途。对外暴露给 HMI 或其他客户端的变量，名称和类型应保持稳定。

常用类型包括布尔、整数、浮点、字符串、数组和结构化数据。选择类型时考虑设备原始寄存器格式、缩放关系和精度，不要用字符串承载需要计算的数值。

选中变量后使用 来源与引用 可以定位 HMI 控件、图程序终端、报警和设备来源。删除变量前先看影响列表；有引用时，Studio 会阻止不安全删除或要求先迁移引用。

6.2 设备端点

创建设备时填写通信协议、地址、站号或寄存器信息，再把端点映射到工程变量。Modbus TCP 和 Modbus RTU 场景要分别确认：

• TCP 主机地址、端口和连接超时。
• RTU 串口、波特率、校验位、停止位和站号。
• 寄存器地址的起始编号和字节序。
• 读写权限、轮询周期和异常重试策略。

先使用仿真值检查缩放和单位，再接入真实设备。这样可以把通信问题和逻辑问题分开定位。

6.3 读写边界

采集变量应只由采集或计算路径写入，HMI 和外部客户端按权限读取或发送命令。对输出变量设置明确的联锁条件，避免一个变量同时被多个页面或程序驱动。

7. 验证、构建与调试

7.1 先分清三种验证

• 设计态：编辑页面、变量和图程序；画布上的示意值不代表 Runtime 已提交值。
• 本机 Runtime 验证：通过 Studio 的 运行 或独立命令启动 Runtime，才能观察真实扫描结果、质量和时间戳。
• 本地 HMI 交互预览：只给控件提供测试值，不执行 PLC 程序、不连接 Runtime，也不等同于正式仿真。

正式验证至少覆盖正常值、边界值、断线、超时和恢复。若涉及真实设备，先用虚拟设备或 Modbus 模拟器隔离通信问题与逻辑问题。

7.2 在 Studio 中构建和运行

1. 保存工程，打开 Runtime 与部署，确认 CLI、Runtime 和工程目标版本一致。
2. 点击 构建。构建会检查工程中的页面、控件、绑定和运行目标；有错误时不会覆盖上一份可用运行包。
3. 构建成功后点击 运行，让 Studio 启动并管理本机 Runtime。
4. 打开 在线监视，按名称筛选变量，确认值、质量、时间戳和值版本。停止或断线后，旧快照不会继续显示为实时值。

命令行等价流程使用：

.\target\debug\eqio-cli.exe build .\qt\examples\visual-not.eqio --target qt -o .\qt\build-plan-64\visual-not.eqrt
.\target\debug\eqio-runtime.exe .\qt\build-plan-64\visual-not.eqrt --port 7420

如果当前 CLI 版本未提供 -o 或 --target qt，以 eqio-cli build --help 和 Studio 的错误提示为准；不要混用不同版本的 CLI、Runtime 和控件目录。

7.3 独立 Runtime 与 HMI Player

需要把 Runtime 和界面分开验证时，在另一个已配置 Qt DLL 的终端启动 Player：

.\qt\bin-x86_64\eqio-hmi-player-qt.exe --package .\qt\build-plan-64\visual-not.eqrt --host 127.0.0.1 --port 7420

启动顺序是：构建 .eqio → 得到 .eqrt → 启动 Runtime → 启动 HMI Player → 在 Player 点击“连接”。关闭 Player 不会停止独立 Runtime；由 Studio 启动的 Runtime 则由 Studio 的停止/关闭流程管理。

7.4 Modbus TCP 模拟闭环

仓库根目录的演示脚本会准备模拟器、驱动、工程副本和端口：

.\scripts\demo\qt-modbus-loop.ps1
# 已完成构建时
.\scripts\demo\qt-modbus-loop.ps1 -SkipBuild
# 端口冲突时
.\scripts\demo\qt-modbus-loop.ps1 -ModbusPort 5502 -RuntimePort 7421

打开后点击 运行，修改温度阈值为 60 或 100，比较逻辑输出指令与设备线圈回读；IR0 按 0.1 换算，HR100 可用于手动读写。这个示例验证采集—逻辑—设备 IO 闭环，不模拟真实热过程，也不能代替现场硬件验收。

7.5 在线监视、连线观察和历史

• 在线监视只读显示 Runtime 已提交值、质量和时间戳；它不会显示尚未提交的写入草稿。
• 选中连线后使用 观察选中连线，可查看周期提交值；最多观察有限数量的连线，停止、断线或工程草稿修改后旧值会隐藏。
• 对已经启用历史记录的数值/布尔变量，打开 查询历史数据，选择最近时间或自定义时间范围；每次最多 8 个变量、每变量 100–2000 个点，结果支持质量断点、缩放、游标和 CSV。
• 报警区显示当前快照，可确认未确认报警并导出当前视图；它不是持久化审计记录。

8. HMI 组态与运行

HMI 页面用于操作、状态显示、报警、趋势和历史查询。先在 HMI 设计 创建页面和控件，再绑定变量，最后分别在本地预览和在线 Runtime 验证。

8.1 HMI 的三种状态

8.2 从设计到在线

1. 在左侧页面列表新建或打开页面，设置 分辨率；分辨率是工程逻辑像素，不会自动重排控件。
2. 从控件库拖入控件，使用右侧 属性 / 绑定 / 状态动画 / 事件权限 检查器设置属性。
3. 绑定变量时确认类型、单位、小数位、只读/可写权限和断线状态；变量旁的 定位 可以跳回变量定义。
4. 点击 交互预览，输入测试值并验证控件行为；关闭预览后测试值丢弃，工程设计和撤销历史保留。
5. 构建并启动 Runtime，再把 HMI 切换到在线状态，检查真实质量和时间戳。目标分辨率、报警确认、趋势刷新和历史查询都要在目标环境复核。

HMI Player 支持工具栏倍率 50%–200%，Ctrl+滚轮 可在 25%–400% 范围微调；F11 全屏，Esc 退出。倍率只改变显示变换，不改变工程坐标和运行包。

8.3 控件、报警和历史的边界

控件库存在已支持子集，目录中的全部类型不等于当前版本全部可部署。禁用或标记为待实现的控件不要放入正式运行包。报警导出是当前快照，操作记录是本次 Studio/Player 进程的临时记录，两者都不能替代现场审计。

9. 部署到运行时

9.1 本机部署

• 保存工程源文件并创建版本。
• 在 Runtime 与部署 先调用能力检查，再构建。
• 构建成功后发布本机运行包并启动 Runtime。
• 在 在线监视、HMI、报警和历史入口完成冒烟检查。
• 备份源工程、运行包、版本说明和回滚包。

9.2 远程目标边界

远程目标、升级、回滚和多目标协调需要独立部署服务、匹配的能力位和目标环境证据。Studio 中出现目标页或“规划中”说明，不代表已经可以对任意远程主机发布。未明确开放时，使用本机 Runtime 或独立部署工具；不要把本机启动、模拟器和离线包检查写成远程或硬件验收。

9.3 升级与回滚

升级前保留旧运行包和工程备份。若新包异常，先停止新包，恢复已验证版本，再分析日志、变量快照和设备事件。回滚不应覆盖原始工程备份，也不应在未确认输出安全状态时重启控制逻辑。

10. AI 工程助手与开放接口

当前 Studio 的 AI 面板是开发预览：它使用本地固定示例，最多保存有限的本机会话，不调用模型、不读取工程正文、不生成可应用补丁，也不会执行变量写入、部署、重启或删除。

只有当当前版本的能力位明确开放，并且界面显示真实上下文范围时，才可以使用后续的模型或 MCP 接入。未开放时，不要把面板中的示例建议当作工程分析结果，也不要声称已经完成 AI 联调。

如果未来接入开放，仍应遵守以下边界：

• 先让助手读取工程结构和变量，再决定是否执行操作。
• 对写入变量、部署、重启和删除等动作逐项确认。
• 不把生产凭据、密钥或无关个人信息放入提示词。
• 保存 AI 生成的变更说明，经过构建、验证和人工复核后再交付。

11. 常见问题排查

工程打不开

确认工程路径可读写、版本未被其他进程锁定，并从最近一次备份恢复到独立目录测试。不要直接覆盖原工程。

构建提示变量或端点不存在

检查对象是否被重命名或删除、变量类型是否改变，以及设备映射是否仍指向当前对象。修复引用后重新构建。

运行时无法连接

先确认目标地址和端口，再检查运行时进程、防火墙和账户权限。连接恢复后，确认运行的是刚刚部署的工程版本。

设备有连接但数值异常

检查寄存器地址、站号、字节序、缩放比例、单位和轮询周期。用仿真值或原始寄存器读数对照，区分通信层和逻辑层问题。

HMI 没有更新

检查控件绑定变量、变量质量状态、刷新周期和播放器连接。若变量正常而画面不更新，重新加载对应页面或播放器并记录工程版本。

报警反复触发

检查触发阈值、恢复阈值、去抖时间和输入质量。对断线、无效值和边界值分别定义策略，避免用一个阈值处理所有状态。

12. 快捷键与操作习惯

具体快捷键可能随编辑器版本和操作系统不同。使用以下习惯可以减少误操作：

• Ctrl+S：随时保存，并在关键步骤后创建版本。
• Ctrl+Z / Ctrl+Y：撤销或重做编辑操作。
• Ctrl+F：在当前编辑器查找变量、节点或文本。
• Delete：删除选中的节点、连线或工程对象；执行前确认选区。
• 运行工具栏命令：构建并启动本机 Runtime；在 ST 源码调试中，F5 是继续执行，不是启动工程。
• 使用画布缩放、对齐和框选功能保持图形逻辑可读。

图形编辑常用操作：Ctrl+E 切换前面板/程序框图，Ctrl+D 复制选区，Delete 删除节点及关联连线，Ctrl+滚轮 缩放，Esc 取消连线预览，Ctrl+Shift+F 进入或退出专注画布。

ST 编辑器常用操作：Ctrl+F 查找，F3 / Shift+F3 前后查找，Ctrl+H 替换，Ctrl+G 跳到行号或行列，Ctrl+/ 切换当前行或选区注释；源码调试使用 F9 断点、F5 继续、F10 步过、F11 步入、Shift+F11 步出。

帮助 → 键盘快捷键… 或 Ctrl+K, Ctrl+S 会打开按命令、菜单和按键筛选的快捷键参考；它从当前版本真实动作生成，优先于本页的简表。

如果快捷键与系统或输入法冲突，以 Studio 菜单中显示的快捷键为准。

13. 交付检查清单

• 工程源文件、版本说明和备份位置已记录。
• 图形逻辑和 ST 均已构建通过。
• 变量类型、单位、权限和设备映射已复核。
• 仿真覆盖正常、边界、断线和恢复场景。
• 运行时、HMI、报警、趋势和历史已在目标环境检查。
• 部署包与回滚版本可用。
• 目标 Runtime、工具链版本和外部接口边界已记录；远程能力未开放时不把本机验证写成远程验收。

如需了解其他资料，请返回文档中心或查看 EQIO Studio 专题页。