OpenPLC Editor 集成(英译中)

OpenPLC Editor 集成

本文档描述 OpenPLC Editor 如何与 OpenPLC Runtime v4 通信。

概述

OpenPLC Runtime v4 是一个无头服务，设计为由 OpenPLC Editor 桌面应用程序控制。没有供最终用户使用的Web浏览器界面。所有与运行时的交互都是通过 OpenPLC Editor 在端口 8443 上的 REST API 进行的。

架构

OpenPLC Editor (桌面应用) | | HTTPS (端口 8443) | JWT 认证 | v OpenPLC Runtime v4 (无头服务) - REST API 服务器 - PLC 运行时核心 - 编译引擎

工作流程

1. 用户在编辑器中创建程序

用户使用 OpenPLC Editor 的图形界面（梯形图、功能块图、顺序功能图）或基于文本的语言（结构化文本、指令列表）创建 PLC 程序。

2. 本地编译

当用户在编辑器中点击“编译”时，以下步骤在用户的本地机器上执行：

1. 编辑器将项目 JSON 转换为 XML 格式
2. 使用 xml2st 将 XML 转换为结构化文本 (ST)
3. 使用 iec2c 将 ST 转换为 C 代码
4. 生成 C/C++ 功能块
5. 创建调试文件和胶水变量
6. 对于 Runtime v4：将所有源文件压缩到program.zip
7. 对于 Runtime v3：只准备program.st

3. 认证

上传程序前，编辑器必须先向运行时认证：

首次设置：

POST /api/create-user { "username": "admin", "password": "password", "role": "user" }

登录：

POST /api/login { "username": "admin", "password": "password" } 响应： { "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc..." }

编辑器存储此 JWT 令牌，并在所有后续请求中将其包含在请求头中：

Authorization: Bearer <jwt_token>

4. 程序上传

编辑器将编译后的程序上传到运行时：

端点：POST /api/upload-file

请求：

• 方法：POST
• Content-Type: multipart/form-data
• Authorization: Bearer<jwt_token>
• 正文：包含 program.zip (Runtime v4) 或 program.st (Runtime v3) 的 file 字段

响应：

{"UploadFileFail":"","CompilationStatus":"COMPILING"}

5. 编译状态监控

运行时异步编译上传的程序。编辑器轮询其状态：

端点：GET /api/compilation-status

轮询配置：

• 间隔：1 秒
• 超时：5 分钟 (300 秒)

响应：

{"status":"COMPILING","logs":["[INFO] 开始编译","[INFO] 正在编译源文件...","..."],"exit_code":null}

状态值：

• IDLE- 无编译进行中
• UNZIPPING- 正在解压上传的 ZIP 文件
• COMPILING- 正在运行编译脚本
• SUCCESS- 编译成功完成
• FAILED- 编译失败

6. PLC 控制

编译完成后，编辑器可以控制 PLC 执行：

启动 PLC：

GET /api/start-plc Authorization: Bearer <jwt_token> 响应： { "status": "RUNNING" }

停止 PLC：

GET /api/stop-plc Authorization: Bearer <jwt_token> 响应： { "status": "STOPPED" }

获取状态：

GET /api/status Authorization: Bearer <jwt_token> 响应： { "status": "RUNNING" }

7. 调试

编辑器连接到运行时的 WebSocket 调试接口，用于实时变量监控和强制赋值：

连接：

import{io}from'socket.io-client';constsocket=io('https://runtime-ip:8443',{path:'/socket.io',transports:['websocket'],auth:{token:jwt_token},rejectUnauthorized:false// 编辑器处理自签名证书});// 连接到调试命名空间socket.on('connect',()=>{socket.emit('join',{namespace:'/api/debug'});});// 监听调试响应socket.on('debug_response',(data)=>{console.log('调试响应：',data);});// 发送调试命令socket.emit('debug_command',{command:'45 00 00'// 十六进制编码的调试命令});

详细的 WebSocket 协议文档请参阅 DEBUG_PROTOCOL.md。

TLS/证书处理

运行时默认使用自签名 TLS 证书。OpenPLC Editor 通过以下方式处理：

1. 在 HTTPS 请求中设置rejectUnauthorized: false
2. 在 HTTP 客户端库中使用等效的-k标志
3. 可选地允许用户配置RUNTIME_TLS_REJECT_UNAUTHORIZED环境变量

注意：这是编辑器侧的配置，不是运行时配置。

API 端点摘要

认证

• POST /api/create-user- 创建用户账户
• POST /api/login- 登录并获取 JWT 令牌
• POST /api/logout- 登出并撤销 JWT 令牌
• GET /api/get-users-info- 检查用户是否存在
• GET /api/get-user-info/<user_id>- 获取用户信息
• PUT /api/password-change/<user_id>- 更改密码
• DELETE /api/delete-user/<user_id>- 删除用户

PLC 操作

• POST /api/upload-file- 上传程序 ZIP 文件
• GET /api/compilation-status- 获取编译状态和日志
• GET /api/status- 获取 PLC 运行时状态
• GET /api/start-plc- 启动 PLC 执行
• GET /api/stop-plc- 停止 PLC 执行
• GET /api/ping- Ping 运行时
• GET /api/runtime-logs?id=<min_id>&level=<level>- 获取运行时日志

调试接口

• wss://host:8443/api/debug- WebSocket 调试接口

除/api/create-user（仅限第一个用户）、/api/login和/api/get-users-info外，所有端点都需要 JWT 认证。

错误处理

编辑器处理各种错误情况：

上传错误：

• 文件过大（每文件 >10 MB，总计 >50 MB）
• 无效的 ZIP 文件
• 编译已在进行中
• 路径遍历尝试
• 禁止的文件扩展名 (.exe, .dll, .sh, .bat, .js, .vbs, .scr)

编译错误：

• ST 代码中的语法错误
• 缺少依赖项
• 编译超时（5 分钟）

连接错误：

• 无法访问运行时
• JWT 令牌无效
• 证书验证错误

开发与测试

对于需要与运行时 API 集成的开发者，请参阅 API.md 以获取详细的端点文档和 curl 示例。

对于运行时开发者，请参阅 DEVELOPMENT.md 以获取本地开发设置。

安全注意事项

• 所有 API 请求都需要 HTTPS（端口 8443）
• 除初始用户创建和登录外，所有操作都需要 JWT 令牌
• 可以通过注销来撤销令牌
• 文件上传时会验证大小、压缩比和文件扩展名
• ZIP 解压过程中强制执行路径遍历保护

全面的安全文档请参阅 SECURITY.md。