diff --git a/README(zh-cn).md b/README(zh-cn).md index c4da07c..2006314 100644 --- a/README(zh-cn).md +++ b/README(zh-cn).md @@ -9,9 +9,9 @@ CSMScript-Lite 是一款基于 [可通信状态机（CSM）](https://github.com/ 此项目包括： - **CSMScript-Lite Library** — 轻量级 CSM 脚本执行引擎，其本身也是一个基于 CSM 实现的模块。 - - **Engine**：核心执行引擎，负责解析并运行 CSM 脚本，管理测试状态与结果。 - - **UI**：用户界面，提供脚本管理、执行控制和结果查看功能。 - - **App**：示例应用程序，展示如何使用 CSMScript 库执行脚本。 + - **[Engine](docs/Engine(CSM).md)**：核心执行引擎，负责解析并运行 CSM 脚本，管理测试状态与结果。 + - **[UI（ExecutionView）](docs/ExecutionView(CSM).md)**：用户界面，提供脚本管理、执行控制和结果查看功能。 + - **[App](docs/App.md)**：示例应用程序，展示如何使用 CSMScript 库执行脚本。 - **实例工程** — 展示如何将 CSMScript-Lite 与其他 CSM 模块结合，实现脚本驱动的自动化测试。 ![CSMScriptApp](.github/CSMScript%20UI.png) diff --git a/README.md b/README.md index 0881a7a..2812552 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,9 @@ CSMScript-Lite is a lightweight script execution engine built on the [Communicab This project includes: - **CSMScript-Lite Library** — A lightweight CSM script execution engine, itself implemented as a CSM module. - - **Engine**: Core execution engine that parses and runs CSM scripts, managing test state and results. - - **UI**: User interface for script management, execution control, and result viewing. - - **App**: A sample application demonstrating how to use the CSMScript library. + - **[Engine](docs/Engine(CSM).md)**: Core execution engine that parses and runs CSM scripts, managing test state and results. + - **[UI (ExecutionView)](docs/ExecutionView(CSM).md)**: User interface for script management, execution control, and result viewing. + - **[App](docs/App.md)**: A sample application demonstrating how to use the CSMScript library. - **Example Projects** — Demonstrate how to combine CSMScript-Lite with other CSM modules for script-driven automated testing. ![CSMScriptApp](.github/CSMScript%20UI.png) diff --git a/docs/App.md b/docs/App.md new file mode 100644 index 0000000..2a66bfe --- /dev/null +++ b/docs/App.md @@ -0,0 +1,172 @@ +# `App` — CSM 模块接口文档 + +## 功能简述 + +`App` 是 CSMScript-Lite 的顶层应用模块，将 `Engine(CSM)` 和 `ExecutionView(CSM)` 整合为一个完整的脚本执行应用程序。 + +该模块负责协调引擎与 UI 的启动顺序、关联与生命周期管理，并对外暴露简洁的脚本文件加载与设置 API，可作为将 CSMScript-Lite 嵌入更大 CSM 系统的参考实现。 + +--- + +## 模块信息 + +| 属性 | 值 | +| -------------- | ---------------------------- | +| LabVIEW 版本 | ≥ 2020 | +| 支持的操作系统 | Windows | +| 支持 RT | ❌ 不支持 | +| 支持 64-bit | ✅ 支持 | +| 所属模块组 | CSMScript-Engine(Lite).lvlib | + +--- + +## 依赖项 + +| 依赖 | 类型 | +| --------------------------------------------------------------------------------------------------- | ---- | +| [Communicable-State-Machine](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) | 必须 | +| [CSM-API-String-Arguments-Support](https://github.com/NEVSTOP-LAB/CSM-API-String-Arguments-Support) | 必须 | +| [CSM-MassData-Parameter-Support](https://github.com/NEVSTOP-LAB/CSM-MassData-Parameter-Support) | 必须 | +| [CSM-INI-Static-Variable-Support](https://github.com/NEVSTOP-LAB/CSM-INI-Static-Variable-Support) | 必须 | +| Engine(CSM) | 必须 | +| ExecutionView(CSM) | 必须 | + +--- + +## API 接口（消息接口） + +以下是外部调用者可以发送给本模块的消息。 + +### `API: Load Script File` + +加载指定的 `.csmscript` 脚本文件。内部将先调用 `TS: Load Sequence` 加载到引擎，并在加载完成后更新 ExecutionView 的步骤列表。 + +- **参数**：`API String`：脚本文件的绝对路径（如 `C:\scripts\test.csmscript`） +- **响应**：N/A + +### `API: Unload Sequence File` + +卸载当前已加载的序列文件，清空引擎内容并重置 UI 显示。 + +- **参数**：N/A +- **响应**：N/A + + + + + +### `UI: Front Panel State` + +控制本模块前面板的显示状态。 + +- **参数**：`API String` — `Enum`：`Open`、`Close` 或 `Minimize` +- **响应**：N/A + +### `UI: Cursor Set` + +设置前面板光标样式。 + +- **参数**：`API String` — `Enum`：光标类型名称（如 `Busy`、`Default`） +- **响应**：N/A + +### 参数类型说明 + +| 类型 | 说明 | +| ----------- | ------------------------------------------------------------------------------- | +| `HexStr` | 将 LabVIEW Variant 序列化为十六进制字符串，内置支持 | +| `SafeStr` | 将特殊字符编码为 `%[HEXCODE]`，内置支持 | +| `ErrStr` | 将错误信息编码为字符串，内置支持 | +| `APIString` | 支持嵌套键值对的纯文本字符串，需要 CSM API String Arguments Support 插件 | +| `MassData` | 内存映射缓冲区，传递 `Start:N,Size:M`，需要 CSM MassData Parameter Support 插件 | +| 用户自定义 | 由模块自行解析的字符串，无需额外插件，但是要说明具体的解析规则和格式 | + +> **注意**：接口文档中对 `String` 类型数据统一使用 `APIString` 标注（不直接写 `SafeStr`），因为 `SafeStr` 正是 `APIString` 针对 `String` 类型的内部实现。 + +--- + +## 内部操作接口 + +以下状态由模块内部使用，**不应**由外部调用者直接发送。 + +| 状态 | 说明 | +| ----------------------------------- | --------------------------------------------- | +| `UI: Insert CSMScript OI` | 将 ExecutionView 嵌入到主应用前面板 | +| `UI: Start CSMScript Engine Behind` | 在后台启动 Engine 和 ExecutionView 并完成关联 | +| `UI: Show Version Dialog` | 在内部触发显示版本对话框 | +| `UI: Update Title` | 更新主窗口标题（通常在加载/卸载脚本后触发） | + +--- + +## 状态广播接口 + +本模块不主动向外发出业务状态广播。 + +标准 CSM 广播： + +### `Error Occurred` + +**默认广播类型**：`Status` + +当应用模块发生未处理的错误时发出。 + +- **参数**：`ErrStr` — 错误信息 + +--- + +## 调用限制与注意事项 + +> [!IMPORTANT] +> +> - 本模块为**单例**——同一时间不可运行多个实例。 +> - 本模块在 `Macro: Initialize` 阶段会自动启动内部的 `Engine(CSM)` 和 `ExecutionView(CSM)` 子模块，无需外部手动启动这两个模块。 +> - `API: Load Script File` 与 `API: Unload Sequence File` 为互斥操作，应避免并发调用。 + +--- + +## 使用示例 + +### 基本生命周期 + +```csm +// 打开主窗口 +UI: Front Panel State >> Open -@ App + +// 加载脚本文件 +API: Load Script File >> C:\scripts\test.csmscript -@ App + +// 卸载脚本 +API: Unload Sequence File -@ App + +// 查看版本信息 +API: Information -@ App +``` + +### 嵌入到更大系统中 + +```csm +// 在系统初始化时启动 App 模块（通过 CSM - Async Start Group of CSMs.vi 启动） +// 然后直接发送 API 消息控制脚本加载与执行： +API: Load Script File >> ${scriptPath} -> App +``` + +--- + +## 备注 + +- `App.vi` 是 CSMScript-Lite 的示例应用，可参考其实现了解如何将 `Engine(CSM)` 和 `ExecutionView(CSM)` 整合进自己的应用程序。 +- 如需自定义界面或集成到现有系统，建议直接使用 `Engine(CSM)` 和 `ExecutionView(CSM)` 模块，而非直接复用 `App.vi`。 + +--- + +- _完整 CSM 语法参考：_ +- _CSM Wiki：_ diff --git a/docs/Engine(CSM).md b/docs/Engine(CSM).md new file mode 100644 index 0000000..bc19bd2 --- /dev/null +++ b/docs/Engine(CSM).md @@ -0,0 +1,191 @@ +# `Engine(CSM)` — CSM 模块接口文档 + +## 功能简述 + +`Engine(CSM)` 是 CSMScript-Lite 的核心脚本执行引擎模块，负责解析并运行 `.csmscript` 脚本文件，管理测试流程状态与结果。 + +引擎采用多线程架构，支持脚本中的同步/异步 CSM 消息、广播订阅、锚点跳转与自动错误处理，并在每个关键执行节点通过广播通知 UI 模块。 + +--- + +## 模块信息 + +| 属性 | 值 | +| -------------- | ---------------------------- | +| LabVIEW 版本 | ≥ 2020 | +| 支持的操作系统 | Windows | +| 支持 RT | ❌ 不支持 | +| 支持 64-bit | ✅ 支持 | +| 所属模块组 | CSMScript-Engine(Lite).lvlib | + +--- + +## 依赖项 + +| 依赖 | 类型 | +| --------------------------------------------------------------------------------------------------- | ---- | +| [Communicable-State-Machine](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) | 必须 | +| [CSM-API-String-Arguments-Support](https://github.com/NEVSTOP-LAB/CSM-API-String-Arguments-Support) | 必须 | +| [CSM-MassData-Parameter-Support](https://github.com/NEVSTOP-LAB/CSM-MassData-Parameter-Support) | 必须 | +| [CSM-INI-Static-Variable-Support](https://github.com/NEVSTOP-LAB/CSM-INI-Static-Variable-Support) | 必须 | + +--- + +## API 接口（消息接口） + +以下是外部调用者可以发送给本模块的消息。 + +### `TS: Load Sequence` + +加载指定的 `.csmscript` 脚本。加载完成后会广播 `SequenceLoaded Event`。 + +- **参数**：`API String` | `MassData` | `HexStr` — `String`：脚本文件的内容 +- **响应**：N/A + +### `TS: Unload Sequence` + +卸载当前已加载的脚本序列，释放相关内部资源。卸载完成后会广播 `SequenceUnloaded Event`。 + +- **参数**：N/A +- **响应**：N/A + +### `TS: SinglePass` + +以单次遍历模式执行已加载的脚本序列。执行期间依次广播 `SequenceStarted Event`、`StepStart Event`、`StepComplete Event` 及 `SequenceCompleted Event`。 + +- **参数**：N/A +- **响应**：N/A + +### `TS: Terminate` + +立即终止正在执行的脚本序列。 + +- **参数**：N/A +- **响应**：N/A + +### 参数类型说明 + +| 类型 | 说明 | +| ----------- | ------------------------------------------------------------------------------- | +| `HexStr` | 将 LabVIEW Variant 序列化为十六进制字符串，内置支持 | +| `SafeStr` | 将特殊字符编码为 `%[HEXCODE]`，内置支持 | +| `ErrStr` | 将错误信息编码为字符串，内置支持 | +| `APIString` | 支持嵌套键值对的纯文本字符串，需要 CSM API String Arguments Support 插件 | +| `MassData` | 内存映射缓冲区，传递 `Start:N,Size:M`，需要 CSM MassData Parameter Support 插件 | +| 用户自定义 | 由模块自行解析的字符串，无需额外插件，但是要说明具体的解析规则和格式 | + +> **注意**：接口文档中对 `String` 类型数据统一使用 `APIString` 标注（不直接写 `SafeStr`），因为 `SafeStr` 正是 `APIString` 针对 `String` 类型的内部实现。 + +--- + +## 状态广播接口 + +以下是本模块**发出**的消息，用于通知订阅者内部状态变化。 + +### `SequenceLoaded Event` + +**默认广播类型**：`Status` + +当 `TS: Load Sequence` 成功加载脚本文件后发出。 + +- **参数**：`API String` | `MassData` | `HexStr` — `String`：脚本文件的内容 + +### `SequenceUnloaded Event` + +**默认广播类型**：`Status` + +当 `TS: Unload Sequence` 成功卸载序列后发出。 + +- **参数**：N/A + +### `SequenceStarted Event` + +**默认广播类型**：`Status` + +当脚本序列开始执行时发出。 + +- **参数**：N/A + +### `StepStart Event` + +**默认广播类型**：`Status` + +当脚本中某一步骤开始执行时发出。 + +- **参数**：`API String` — Cluster(`Def-Thread Data.ctl`)：当前步骤的线程数据 + - index - Numeric: 步骤在序列中的索引位置 + - Arguments - String: 步骤参数字符串（原始文本） + - Error - Error Cluster: 当前步骤的错误信息 + +### `StepComplete Event` + +**默认广播类型**：`Status` + +当脚本中某一步骤执行完成时发出。 + +- **参数**：`API String` — `Def-StepComplete Event Data.ctl`：步骤完成的状态数据 + - index - Numeric: 步骤在序列中的索引位置 + - Response - String: 结果字符串 + - Error - Error Cluster: 当前步骤的错误信息 + +### `SequenceCompleted Event` + +**默认广播类型**：`Status` + +当脚本序列全部执行完毕时发出。 + +- **参数**：N/A + +### `Error Occurred` + +**默认广播类型**：`Status` + +当引擎发生未处理的错误时发出（标准 CSM 错误广播）。 + +- **参数**：`ErrStr` — `Error Cluster`：错误信息 + +--- + +## 调用限制与注意事项 + +> [!IMPORTANT] +> +> - 必须先调用 `TS: Load Sequence` 成功加载脚本后，才能调用 `TS: SinglePass`。 +> - 使用 `TS: Terminate` 可以在执行过程中强制终止序列，但不会等待当前正在执行的 CSM 消息返回。 + +--- + +## 使用示例 + +### 基本生命周期 + +```csm +// 加载脚本文件 +TS: Load Sequence >> C:\scripts\test.csmscript -@ Engine + +// 订阅加载完成事件后执行 +SequenceLoaded Event@Engine >> TS: SinglePass@Engine -> + +// 执行完毕后卸载 +SequenceCompleted Event@Engine >> TS: Unload Sequence@Engine -> +``` + +### 订阅步骤状态广播 + +```csm +// 将 Engine 的步骤完成事件路由到 UI 模块处理 +StepComplete Event@Engine >> TS: Step Complete Handler@ExecutionView -> +StepStart Event@Engine >> TS: Step Start Handler@ExecutionView -> +``` + +--- + +## 备注 + +- 脚本语法说明请参阅 [README](../README.md) 或 [CSM 语法文档](https://github.com/NEVSTOP-LAB/Communicable-State-Machine/blob/main/.doc/Syntax.md)。 +- 扩充指令（如 `WAIT`、`GOTO`、`AUTO_ERROR_HANDLE_ENABLE`）由引擎内部解析，无需额外依赖。 + +--- + +- _完整 CSM 语法参考：_ +- _CSM Wiki：_ diff --git a/docs/ExecutionView(CSM).md b/docs/ExecutionView(CSM).md new file mode 100644 index 0000000..db9fc96 --- /dev/null +++ b/docs/ExecutionView(CSM).md @@ -0,0 +1,151 @@ +# `ExecutionView(CSM)` — CSM 模块接口文档 + +## 功能简述 + +`ExecutionView(CSM)` 是 CSMScript-Lite 的 UI 显示模块，用于展示脚本执行的实时状态与结果。 + +该模块通过 `TS: Link to Engine` 与 `Engine(CSM)` 模块建立关联，自动订阅引擎广播的执行事件，并将步骤列表、执行进度、步骤结果等信息实时呈现在前面板上。 + +--- + +## 模块信息 + +| 属性 | 值 | +| -------------- | ---------------------------- | +| LabVIEW 版本 | ≥ 2020 | +| 支持的操作系统 | Windows | +| 支持 RT | ❌ 不支持 | +| 支持 64-bit | ✅ 支持 | +| 所属模块组 | CSMScript-Engine(Lite).lvlib | + +--- + +## 依赖项 + +| 依赖 | 类型 | +| --------------------------------------------------------------------------------------------------- | -------------------- | +| [Communicable-State-Machine](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) | 必须 | +| [CSM-API-String-Arguments-Support](https://github.com/NEVSTOP-LAB/CSM-API-String-Arguments-Support) | 必须 | +| Engine(CSM) | 必须（作为关联引擎） | + +--- + +## API 接口（消息接口） + +以下是外部调用者可以发送给本模块的消息。 + +### `TS: Link to Engine` + +将本 UI 模块关联到指定的 `Engine(CSM)` 实例。关联成功后，UI 模块自动订阅该引擎的执行广播事件，以更新显示状态。 + +- **参数**：`API String` — `String`：目标引擎模块的名称（如 `Engine`） +- **响应**：N/A + +### `TS: Load Sequence` + +将已加载的脚本序列的步骤信息更新到 UI 显示列表中，通常在引擎触发 `SequenceLoaded Event` 后由上层模块调用。 + +- **参数**：`API String` | `MassData` | `HexStr` — `String`：脚本文件的内容 +- **响应**：N/A + +### `UI: Front Panel State` + +控制本模块前面板的显示状态。 + +- **参数**：`API String` — `Enum`：`Open`、`Close` 或 `Minimize` +- **响应**：N/A + +### `UI: Cursor Set` + +设置前面板光标样式。 + +- **参数**：`API String` — `Enum`：光标类型名称（如 `Busy`、`Default`） +- **响应**：N/A + +### 参数类型说明 + +| 类型 | 说明 | +| ----------- | ------------------------------------------------------------------------------- | +| `HexStr` | 将 LabVIEW Variant 序列化为十六进制字符串，内置支持 | +| `SafeStr` | 将特殊字符编码为 `%[HEXCODE]`，内置支持 | +| `ErrStr` | 将错误信息编码为字符串，内置支持 | +| `APIString` | 支持嵌套键值对的纯文本字符串，需要 CSM API String Arguments Support 插件 | +| `MassData` | 内存映射缓冲区，传递 `Start:N,Size:M`，需要 CSM MassData Parameter Support 插件 | +| 用户自定义 | 由模块自行解析的字符串，无需额外插件，但是要说明具体的解析规则和格式 | + +> **注意**：接口文档中对 `String` 类型数据统一使用 `APIString` 标注（不直接写 `SafeStr`），因为 `SafeStr` 正是 `APIString` 针对 `String` 类型的内部实现。 + +--- + +## 内部处理接口 + +以下状态由本模块内部使用，或在与引擎关联后通过广播订阅自动触发，**不应**由外部调用者直接发送。 + +| 状态 | 触发来源 | 说明 | +| --------------------------- | -------------------------------- | ---------------------- | +| `TS: Test Started Handler` | `SequenceStarted Event@Engine` | 序列开始时更新 UI 状态 | +| `TS: Step Start Handler` | `StepStart Event@Engine` | 步骤开始时高亮当前行 | +| `TS: Step Complete Handler` | `StepComplete Event@Engine` | 步骤完成时显示结果 | +| `TS: Test Complete Handler` | `SequenceCompleted Event@Engine` | 序列完成时更新 UI 汇总 | + +--- + +## 状态广播接口 + +本模块不主动向外发出业务状态广播。 + +标准 CSM 广播： + +### `Error Occurred` + +**默认广播类型**：`Status` + +当 UI 模块发生未处理的错误时发出。 + +- **参数**：`ErrStr` — `Error Cluster`：错误信息 + +--- + +## 调用限制与注意事项 + +> [!IMPORTANT] +> +> - `TS: Load Sequence` 通常由上层模块（如 `App.vi`）在收到引擎 `SequenceLoaded Event` 广播后触发，无需手动调用步骤更新逻辑。 + +--- + +## 使用示例 + +### 启动并关联引擎 + +```csm +// 先启动 Engine 模块 +// ...（在代码中使用 CSM - Async Start Group of CSMs.vi 启动引擎和 UI） + +// 将 UI 关联到引擎 +TS: Link to Engine >> Engine -@ ExecutionView + +// 打开 UI 前面板 +UI: Front Panel State >> Open -@ ExecutionView +``` + +### 加载脚本并更新视图 + +```csm +// 加载脚本文件到引擎 +TS: Load Sequence >> C:\scripts\test.csmscript -@ Engine + +// 加载完成后更新 UI 视图（通常由 App 模块在订阅事件后触发） +TS: Load Sequence -@ ExecutionView +``` + +--- + +## 备注 + +- UI 显示风格（步骤列表样式、列宽等）由 `Sequence-DefaultStyle.vi` 提供的默认样式初始化。 + +--- + +- _完整 CSM 语法参考：_ +- _CSM Wiki：_ diff --git a/src/APP/App.vi b/src/APP/App.vi index 5be91c2..37e9885 100644 Binary files a/src/APP/App.vi and b/src/APP/App.vi differ diff --git a/src/Engine/Engine(CSM).vi b/src/Engine/Engine(CSM).vi index d7972b3..418c6ae 100644 Binary files a/src/Engine/Engine(CSM).vi and b/src/Engine/Engine(CSM).vi differ diff --git a/src/Engine/Typedef/Def-StepComplete Event Data.ctl b/src/Engine/Typedef/Def-StepComplete Event Data.ctl index 8803c31..c5d9d37 100644 Binary files a/src/Engine/Typedef/Def-StepComplete Event Data.ctl and b/src/Engine/Typedef/Def-StepComplete Event Data.ctl differ diff --git a/src/Engine/_Support/Working Thread.vi b/src/Engine/_Support/Working Thread.vi index 89bc575..507d145 100644 Binary files a/src/Engine/_Support/Working Thread.vi and b/src/Engine/_Support/Working Thread.vi differ diff --git a/src/UI/ExecutionView(CSM).vi b/src/UI/ExecutionView(CSM).vi index 21e2eb5..05a3f59 100644 Binary files a/src/UI/ExecutionView(CSM).vi and b/src/UI/ExecutionView(CSM).vi differ