Reverse-docs: PLC文档逆向生成器
在西门子 TIA Portal 项目中，大量 PLC 程序经过多年迭代后，往往存在一个非常现实的问题：程序还在运行，但文档已经找不到了。
尤其是维护历史项目时，工程师经常需要面对大量缺少注释、缺少设计说明的 OB、FB 和 FC。想要理解一个程序块的功能，只能逐行阅读梯形图或 SCL，分析变量、调用关系、状态机、联锁条件以及外部引用。
为了帮助工程师快速理解和维护这些历史 PLC 程序，我们推出了 REVERSE-DOCS 博途程序块逆向文档生成工具。
REVERSE-DOCS 可以读取 TIA Portal 中的 PLC 程序块，对程序逻辑进行分析，并自动生成结构化的技术文档，帮助工程师快速了解一个程序块“做了什么、用了什么、依赖什么”。
1、REVERSE-DOCS 解决的问题
在实际 PLC 项目维护过程中，经常会遇到以下场景：
- 老项目经过多年修改，原始设计文档已经丢失；
- PLC 程序只有代码和少量注释，新工程师很难快速理解；
- FB/FC 内部逻辑复杂，需要人工分析大量网络；
- 程序中包含状态机、联锁、许可等复杂控制逻辑；
- 需要进行项目交接，但缺少完整的程序说明；
- 需要对历史程序进行维护、重构或者二次开发；
- 希望让 AI 或其他开发工具能够更容易理解现有 PLC 程序。
传统方式下，工程师通常需要打开 TIA Portal，逐个程序块查看代码，然后手工整理变量、控制逻辑和调用关系。
对于一个规模较大的 PLC 项目，这项工作可能需要花费大量时间。
REVERSE-DOCS 的目标，就是把这个过程自动化。
它不是简单地把 PLC 代码转换成另一种格式，而是从已有程序中提取信息，分析程序逻辑，并生成面向工程师阅读的技术文档。
2、支持的 PLC 程序块
REVERSE-DOCS 支持常见的 TIA Portal 程序块：
- OB —— 组织块
- FB —— 函数块
- FC —— 函数
同时支持不同的 PLC 编程语言：
- SCL
- LAD（梯形图）
因此，无论历史项目主要使用 LAD 还是 SCL，都可以通过 REVERSE-DOCS 对程序进行逆向分析。
3、自动生成技术文档
REVERSE-DOCS 会围绕程序块的结构和控制逻辑生成技术文档。
生成的内容包括：
3.1 程序块基本信息
首先整理程序块的基本信息，包括程序块类型以及相关的程序结构信息。
这样在阅读大量程序块时，可以快速了解当前程序块的作用和定位。
3.2 功能说明
根据程序代码和控制逻辑生成程序块的功能说明。
例如一个 FB 可能包含电机控制、自动运行、故障处理等多个部分，文档会尝试从代码结构中总结其主要功能。
3.3 变量说明
整理程序块中的输入、输出、输入输出以及内部变量，并结合程序中的使用情况辅助理解变量作用。
这样可以减少工程师逐个查找变量引用的工作。
3.4 控制逻辑
对程序中的主要控制逻辑进行整理，帮助工程师从“代码”进一步理解“控制过程”。
例如：
- 启停逻辑
- 自动/手动逻辑
- 条件判断
- 顺序控制
- 故障处理
- 输出控制
3.5 状态机分析
对于包含状态机的程序，REVERSE-DOCS 会尝试识别程序中的状态以及状态之间的转换关系。
这对于分析复杂的顺序控制程序尤其有帮助。
例如：
IDLE
↓
STARTING
↓
RUNNING
↓
STOPPING
↓
IDLE通过这种方式，工程师不需要完全依赖代码阅读，也可以快速建立对程序运行过程的整体认识。
3.6 联锁与许可
PLC 程序中经常存在大量 Interlock、Permissive 和保护条件。
这些条件往往散落在不同的网络和判断逻辑中，也是维护人员最需要理解的部分之一。
REVERSE-DOCS 会对相关逻辑进行整理，帮助工程师快速了解：
- 哪些条件允许设备启动；
- 哪些条件会阻止设备运行；
- 哪些条件会触发停止；
- 哪些条件用于故障保护。
3.7 外部引用
对于程序块中使用的外部变量、其他程序块以及相关引用进行整理。
通过这些信息，可以进一步了解当前程序块与整个 PLC 程序之间的关系。
3.8 I/O 标签
对于程序中使用的 I/O 标签进行整理，帮助工程师了解程序与现场设备之间的关系。
3.9 程序总结
最后，根据前面的分析生成程序块的整体总结。
工程师可以先阅读总结，再根据需要深入查看具体的控制逻辑。
这样可以明显降低阅读历史 PLC 程序的成本。
4、自动匹配 TIA Portal 当前语言
REVERSE-DOCS 会根据 TIA Portal 当前项目语言自动选择生成文档的语言。
例如项目使用中文环境时，可以生成中文技术文档；使用其他语言环境时，则可以匹配对应的文档语言。
同时，PLC 程序中的标识符和代码保持原样，避免因为翻译变量名而影响工程师与实际程序之间的对应关系。
例如：
Motor_Start
Motor_Stop
Motor_Fault
Auto_Mode
Emergency_Stop这些程序中的标识符仍然保持原样，而文档说明可以使用当前项目对应的自然语言。
5、使用方法
REVERSE-DOCS 需要配合 TIA Portal Add-In 插件使用。
5.1 下载插件
REVERSE-DOCS工具需要配合 TIA Portal Add-In 插件使用。
首先下载插件压缩包：博途V19插件下载链接
下载完成后，将压缩包保存到本地。
5.2 安装 TIA Portal Add-In
下载完成后，解压插件安装包。
找到其中的 *.addin 文件，并将其复制到对应 TIA Portal 版本的 AddIns 目录。
例如 TIA Portal V19：
C:\Program Files\Siemens\Automation\Portal\V19\AddIns完成复制后，TIA Portal 即可识别该插件。
5.3 激活插件
启动 TIA Portal，并打开需要分析的项目。
在 TIA Portal 的 Add-ins 面板中找到 REVERSE-DOCS 插件，并按照插件菜单完成激活。
5.4 选择程序块
在 TIA Portal 项目树中选择需要分析的程序块。在目标程序块上点击鼠标右键，在弹出的菜单中选择【逆向生成程序块文档】：
工具会读取当前程序块，并生成对应的Markdown文档。
5.5 查看生成的技术文档
工具会读取当前程序块，对程序结构和控制逻辑进行分析，并生成对应的技术文档。
工程师可以利用生成的文档快速了解程序块的：
- 功能；
- 变量；
- 控制逻辑；
- 状态机；
- 联锁和许可；
- 外部引用；
- I/O；
- 整体功能。
这样就不需要从第一行代码开始逐步阅读整个程序。
6、特别适合历史 PLC 项目维护
REVERSE-DOCS 一个重要的应用场景，就是历史项目逆向分析。
很多 PLC 项目并不是从零开始开发，而是经过多年持续修改：
原始项目
↓
第一次现场修改
↓
第二次设备改造
↓
增加新的联锁
↓
增加新的运行模式
↓
增加故障处理
↓
多年后的当前版本随着项目不断演进，最初的设计文档可能已经无法准确反映当前程序。
这时候，PLC 程序本身才是最接近当前实际控制逻辑的“事实来源”。
REVERSE-DOCS 的思路就是从当前程序反向生成文档，让技术文档重新与实际代码建立联系。
7、让 PLC 程序重新变得“可读”
PLC 程序和普通软件一样，也会随着项目不断演进而变得复杂。
区别在于，很多工业项目的生命周期可能非常长，一个 PLC 项目可能会被不同工程师维护很多年。
因此，程序的可理解性和可维护性非常重要。
REVERSE-DOCS 可以把：
PLC 程序代码
↓
程序结构分析
↓
控制逻辑分析
↓
技术文档形成一个自动化的逆向流程。
对于新工程师来说，可以先通过文档了解程序，再深入代码。
对于经验丰富的工程师来说，也可以快速定位关键逻辑，减少阅读大量程序代码的时间。
8、结束语
PLC 项目最难维护的，很多时候并不是代码本身，而是没人知道代码为什么这样写。
REVERSE-DOCS 希望解决的，就是 PLC 程序与技术文档之间长期存在的断层。
通过自动分析 TIA Portal 中的 OB、FB、FC 程序，并从 LAD 和 SCL 中提取程序结构、变量、控制逻辑、状态机、联锁、外部引用和 I/O 信息，REVERSE-DOCS 可以帮助工程师快速重新理解已有 PLC 程序。
对于需要进行历史项目维护、程序交接、设备改造、程序审查和二次开发的 PLC 工程师来说，逆向生成技术文档可以成为程序分析过程中的一个实用工具。