简介面向 PLC 开发者的 Codesys 文件读写专题资料聚焦 CAA File 库帮助初学者掌握在 Codesys 中实现文件读取与写入的核心方法也适合工程人员查阅功能块参数细节。资源共 1 个文件为 docx 格式图文文档压缩包大小约 391KB内容精炼目前已有 3020 人学习下载。文档在区分 CAA File 库与 SysFile 库适用场景的基础上系统解析了 xExecute、xAbort、sDirName、sFileName、eFileMode、udiTimeOut、pBuffer、szBuffer、xOverWrite、xDone、xBusy、xError、eError 等关键功能块参数的含义与用法。针对 3.5.17 前后版本的库选择、CAA_HANDLE 与 FILE_MRDWR 等命名调整、Linux 路径写法及终端命令等易错点专门作了提醒并结合官方示例与中文参考文章让读者快速理解文件读写完整流程减少调试时间提升工程开发效率。1. PLC_CODESYS 项目里做数据落盘CAA File 库才是省心的那条路做 PLC_CODESYS 项目只要遇上配方下发、数据记录、CSV 导出这类需求就绕不开文件读写。IDE 里翻库管理器能用的无非是 CAA FileFile Access和 SysFile 两套。我的建议很直接3.5.17 之前的老工程老老实实用 CAA File 库新工程直接切 File Access。原因不复杂CAA File 封装了打开、写入、关闭、定位这一整套操作对外只暴露功能块和几个参数省掉大量底层句柄管理的工作。SysFile 库则更接近系统调用适合对文件操作有特殊控制需求的场景。这篇文章把 CAA File 库的选型、参数、版本兼容和踩坑记录拆开讲新手按步骤能跑通熟手也能对照参数检查自己的调用姿势。2. 选库先看版本CAA File 与 SysFile 的分工和调用关系文件读写这件事在 CODESYS 里从来不是“拖个功能块就能写”的简单操作。选哪个库直接决定代码能不能编译通过、运行时会不会莫名其妙报错。这一章先把两个库的关系和版本分水岭讲清楚。2.1 底层调用链CAA File 封装了什么为什么说它“高级”CAA File 库的完整名称是 Common Automation Architecture File Access Library。它和 SysFile 库不是平行关系而是上下层关系——CAA File 底层调用的正是 SysFile 库的函数。所以你在 CAA File 里执行的每一次打开、读取、写入最终都会落到 SysFile 的系统调用上。理解这层关系有什么实际意义第一CAA File 的返回值、错误码和 SysFile 是相通的调试时看 eError 错误 ID可以直接去 SysFile 的文档里查更底层的失败原因。第二CAA File 做了 SysFile 没做的“收尾工作”比如在功能块内部处理句柄的创建、释放和异常清理。直接用 SysFile这些都得自己管一旦中途出错句柄泄漏是家常便饭。第三也是最重要的CAA File 把异步操作封装成了边沿触发的功能块xExecute 上升沿启动、xDone 输出完成信号这让 PLC 扫描周期和文件 I/O 的时序能对齐不用在循环里死等系统响应。我一般把 SysFile 比作“裸钻”功能强大但扎手CAA File 是“镶好的戒指”直接戴就行。项目里没有特殊需求不要绕过 CAA File 去碰底层。2.2 版本分水岭 3.5.17老项目用 CAA新工程直接 File AccessCODESYS 3.5.17 是一个明确的版本转折点。在此之前CAA File 库是 IDE 里的标准库选项直接添加即可使用。3.5.17 及以后官方把库整理进 File Access 体系库管理器的入口和命名空间都变了。新工程里你可能会遇到这样的问题打开库管理器搜 CAA File 搜不到或者添加后报一堆类型未定义错误。这不是你的操作问题而是新版本推荐使用 File Access 库。但老工程升到新版本后工程里引用的 CAA 功能块不会自动迁移需要手动重新映射。我的习惯是老工程维持原状继续用 CAA File新工程从 File Access 开始两种库里功能块的接口参数高度相似代码迁移成本并不高。需要留意的是CAA File 即使在老版本里也不是一个“独立王国”。它的功能块包括 FILE.Open、FILE.Read、FILE.Write、FILE.Close 等全部挂在 FILE 命名空间下和 SysFile 的 F 前缀函数区分明显。你在功能块列表里看到 FILE.Open、FILE.Close那就是 CAA File 的成员。2.3 把库挂到工程里从库管理器到在线帮助的完整路径在 CODESYS 里添加 CAA File 库路径是固定的工程树右键“库管理器”在“添加库”对话框搜索“CAA File”选中后确认。老版本里这个库可能叫“CAA File Access”搜索时注意别拼错。添加完成后在线帮助按 F1 呼出搜索“CAA File”可以看到官方对每个功能块的说明和示例。官方示例有几个典型场景比如读取配置文件、写入日志文件每个示例都配了可视化界面和变量声明。官方例子的代码质量不错但有一类问题很典型——例子用的库版本和你工程里的库版本不一致。同一个功能块在 3.5.15 和 3.5.17 里的结构体引用方式不同直接复制会报类型错误。后面第三章专门讲这个。第三方博客里有比在线帮助更详细的中文拆解对功能块参数做了逐项解释新手看资料比啃英文文档效率高。但任何第三方资料都会有版本偏差看的时候留个心眼凡是用到结构体、枚举的地方都要拿自己工程里的库版本比对一遍。3. 版本兼容改造把老示例搬到当前库的四处必修点从网上下载的 CAA File 示例工程很少能直接编译通过。多数报错不是代码逻辑问题而是库版本差异导致的类型引用不一致。这一章把最常见的四处改造点列出来照着改就能过编译。3.1 句柄类型的版本差异CAA_HANDLE 到 CAA.HANDLE早期版本的 CAA File 库句柄类型命名是 CAA_HANDLE一个全局枚举。新版本把句柄收进了 CAA 命名空间改名为 CAA.HANDLE。直接复制老代码编译器会报“CAA_HANDLE 未声明”或“未知类型”。举个例子老代码声明文件句柄是这样写的VAR hFile : CAA_HANDLE; END_VAR新版本库必须写成VAR hFile : CAA.HANDLE; END_VAR判断标准是格式是否匹配当前库版本。怎么快速验证右键库管理器里的 CAA File 库选“显示库文档”搜索 HANDLE看库里定义的完整名称。库文档里写的是 CAA.HANDLE就全部改成带命名空间的形式写的是 CAA_HANDLE就保持原样。我踩过一次坑老工程从 3.5.12 升到 3.5.16工程里几十处 CAA_HANDLE 全部报错手动一个个改成 CAA.HANDLE 花了一个小时。后来学聪明了先看库文档再全局替换。3.2 枚举的命名空间迁移FILE_MRDWR 到 FIL.MODE.MRDWR第二个高频报错是文件操作模式枚举。老版本直接用 FILE_MRDWR、FILE_RDONLY 这类全大写枚举值新版本把它们收进了 FIL.MODE 命名空间变成了 FIL.MODE.MRDWR、FIL.MODE.RDONLY。看一个典型调用fbOpen( xExecute : TRUE, sFileName : /home/test.txt, eFileMode : FILE_MRDWR, // 老写法会报错 udiTimeOut : 5000000, hFile hFile, xDone xDone, xError xError );改造后fbOpen( xExecute : TRUE, sFileName : /home/test.txt, eFileMode : FIL.MODE.MRDWR, // 新写法 udiTimeOut : 5000000, hFile hFile, xDone xDone, xError xError );这类枚举在 eError 输出上也有体现。错误 ID 的老枚举是 ERROR_DEVICE_BUSY新版本是 ERROR.DEVICE_BUSY。判断方式和句柄一样打开库文档搜“MODE”看库里的定义路径。血的教训不要凭记忆写枚举名每次新建工程都先确认一次当前库里枚举的命名空间。一次手误编译报错都是小事运行时才发现模式给错了写文件时直接覆盖了不该覆盖的数据。3.3 路径分隔符Linux 下必须用正斜杠CAA File 库跨平台支持 Windows 和 Linux但路径分隔符的规矩完全不同。Windows 下你习惯写反斜杠\但在 Linux 系统上必须用正斜杠/。这一点在 SysFile 库底层也是同样的要求目录分隔符用错文件打开直接失败。正确的 Linux 路径写法sFileName : CAA.FILENAME : /home/user/data/test.txt;注意 CAA.FILENAME 类型定义的是路径字符串长度固定但实际路径不能过长。我在工程里习惯把路径写成参数不硬编码在功能块引脚上方便后续替换。调试时配合 Linux 终端确认路径存在性CtrlAltT打开终端cd /home/user/data进目录ls -l看文件是否存在pwd打印当前目录。这三板斧能排查掉八成路径问题。3.4 读缓冲区类型BYTE 数组比字符串更稳读写操作的 pBuffer 参数类型是任何类型的指针通过 ADR 获取地址。文件内容不一定能按字符串解析尤其是二进制文件或带特殊字符的文本用字符串做缓冲很容易在空字符处截断。更稳妥的方案是声明一个 BYTE 数组VAR bufData : ARRAY[0..1023] OF BYTE; szRead : UDINT; END_VAR调用读取功能块时传数组首地址fbRead( xExecute : TRUE, pBuffer : ADR(bufData), szBuffer : SIZEOF(bufData), udiTimeOut : 5000000, hFile : hFile, xDone xDone, szRead szRead );需要解析文本时先把 BYTE 数组转成字符串或者直接用数组前 N 个字节做匹配。这个习惯能少踩不少坑。4. 搭一个完整的文件写入与读取流程时序、参数、状态位理论再熟不如跑通一个完整流程。这一章以“写入一行数据、再把它读出来”为目标从头到尾搭一遍 CAA File 的调用链路。代码可以直接建工程试。4.1 功能块骨架与变量声明CAA File 库的核心功能块是 FILE.Open、FILE.Write、FILE.Read、FILE.Close。以写入为例声明部分是这样的PROGRAM PLC_PRG VAR fbOpen : FILE.Open; // 打开文件 fbWrite : FILE.Write; // 写入数据 fbClose : FILE.Close; // 关闭文件 sPath : CAA.FILENAME : /home/data.txt; hFile : CAA.HANDLE; // 文件句柄 bufData : ARRAY[0..31] OF BYTE; // 写入缓冲区 szWritten : UDINT; // 实际写入字节数 xOpenDone : BOOL; xWriteDone : BOOL; xError : BOOL; eError : CAA.ERROR; END_VAR这些变量里fbOpen、fbWrite、fbClose 是功能块实例每个实例独立维护自己的状态位。hFile 是贯穿三个功能块的桥必须在打开成功后把句柄传给后面的写操作。bufData 是数据载体文件读写的核心操作都在它上面。4.2 文件写入打开到关闭的完整时序写入流程分三步打开文件、写入数据、关闭文件。每一步都要检查上一次操作的完成位和错误位不能跳步。// 第一步打开文件 fbOpen( xExecute : TRUE, sFileName : sPath, eFileMode : FIL.MODE.MRDWR, udiTimeOut : 5000000, hFile hFile, xDone xOpenDone, xError xError, eError eError ); // 第二步打开成功后写入数据 IF xOpenDone THEN // 准备要写入的数据 bufData[0] : 16#48; // H bufData[1] : 16#65; // e bufData[2] : 16#6C; // l bufData[3] : 16#6C; // l bufData[4] : 16#6F; // o bufData[5] : 13; // 回车 bufData[6] : 10; // 换行 fbWrite( xExecute : TRUE, hFile : hFile, pBuffer : ADR(bufData), szBuffer : 7, // 写入前7个字节 udiTimeOut : 5000000, xDone xWriteDone, xError xError, eError eError, szWritten szWritten ); END_IF // 第三步写入完成并检查错误后关闭文件 IF xWriteDone OR xError THEN fbClose( xExecute : TRUE, hFile : hFile, udiTimeOut : 5000000, xDone xCloseDone, xError xCloseError, eError eCloseError ); END_IFxExecute 是上升沿触发的。每个扫描周期里只要 xExecute 还是 TRUE功能块就保持执行完成后 xDone 只维持一个周期。如果 xExecute 在功能块完成前就掉到 FALSE功能块会继续执行但 xDone、xError 也只输出一个周期。这是边沿触发的特性也是新手最容易看丢状态位的地方。要让功能块能再次触发必须把 xExecute 先置 FALSE 再重新置 TRUE。工程上常见的做法是用一个触发变量完成后再复位// 写入完成后复位触发信号 IF xWriteDone THEN bStartWrite : FALSE; END_IF这样下一个上升沿才能重新生效否则功能块会认为上一次操作还没结束。4.3 读取数据与 EOF 边界处理读取流程和写入对称核心差异在 EOF 处理。CAA File 的 FILE.Read 功能块在到达文件末尾时xEOF 输出 TRUE。很多初学者的误区是读完 xEOF 变 TRUE就认为读到了有效数据。实际上 xEOF 变 TRUE 的那次读取可能已经是一个空读。4.4 参数工程化的取值建议参数取值直接影响运行稳定性以下是实际项目里验证过的值参数推荐取值原因udiTimeOut50000005秒单位是微秒给足机械硬盘/网络文件系统的响应时间eFileModeFIL.MODE.MRDWR读写兼顾读和写避免二次打开切换模式xOverWriteTRUE覆盖模式日志场景下旧文件直接覆盖szBuffer1024字节单次读写块兼顾效率和内存占用udiTimeOut 是微秒单位这个经常被忽略。填 5000 以为是 5 秒实际只有 5 毫秒文件系统稍微慢一点就超时报错。填的时候多写三个零不丢人。5. 常见问题与避坑五条被反复拖进泥潭的记录写文件这个事坑不在 API 本身全在调用时序和平台差异上。以下记录都是真实反复出现的案例按“现象 → 原因 → 解决”的结构列出来。5.1 复制示例工程后编译报错“CAA_HANDLE 未定义”现象从网上下载的 CAA File 示例工程打开后编译报错提示 CAA_HANDLE 未定义。原因示例工程使用的库版本较老句柄类型是 CAA_HANDLE当前工程引用的库版本已经把句柄改为 CAA.HANDLE命名空间不同导致编译器无法识别。解决右键库管理器里的 CAA File 库确认库里句柄类型的完整名称。如果是 CAA.HANDLE全局替换代码里的 CAA_HANDLE 为 CAA.HANDLE。枚举类型同理FILE_MRDWR 改成 FIL.MODE.MRDWR。判断标准只有一个格式必须和当前库版本匹配。5.2 Linux 系统下文件打不开路径带反斜杠现象工程在 Windows 上运行正常部署到 Linux 控制器后FILE.Open 一直报错文件打不开。原因CAA File 底层走 SysFileLinux 系统只识别正斜杠/。代码里用了\home\data.txt这种 Windows 风格路径Linux 系统解析失败。解决路径统一改成/home/data.txt。把路径变量提取出来集中管理避免散布在多个功能块里。sPath : CAA.FILENAME : /home/data.txt;Linux 下调试配合终端确认文件存在CtrlAltT打开终端cd /home看目录内容ls -l data.txt看文件权限和路径。5.3 xDone 状态位一闪而过后面的写入漏数据现象打开文件成功xDone 输出 TRUE但下一个扫描周期再去检查 xDone 已经是 FALSE后续逻辑没有执行数据没写进去。原因功能块完成动作后xDone 只保持一个周期。如果 xDone 为 TRUE 的那个周期你的后续逻辑没有触发或者因为扫描周期太长导致漏采状态位就丢了。解决把 xDone 信号锁存下来或者用“完成后再触发”的方式组织逻辑。IF xOpenDone THEN bOpenFinished : TRUE; END_IFbOpenFinished 保持为 TRUE直到整条写入链路走完再复位。这样即使漏掉一个周期状态也不会丢。从那以后我每次做文件流程都用辅助锁存位而不是直接捕状态位。5.4 写入中文乱码现象用 CAA File 写入包含中文的字符串读出来乱码。原因默认字符编码不匹配PLC 内部字符串是 UTF-16 或本地编码写入文件时没有做编码转换。解决写入前先把字符串转成 UTF-8 的 BYTE 数组再通过 pBuffer 写入。读取时同样先读 BYTE 数组再转回字符串。文件系统层面统一用 UTF-8跨平台和上位机软件都能兼容。5.5 文件句柄泄漏连续开关文件后系统资源耗尽现象程序里反复执行打开、关闭文件运行一段时间后系统卡顿或文件操作全部失败。原因某个分支下 FILE.Close 没有执行或者执行了但 xExecute 没有复位导致文件句柄没有真正释放。CAA File 的 Close 动作需要和 Open 严格配对漏一次就会累积泄漏。解决所有打开文件的分支必须保证都有对应的关闭分支。用状态机管理流程IDLE → OPEN → WRITE/READ → CLOSE → IDLE任何错误都在 CLOSE 阶段统一收尾。每轮操作结束后检查句柄数为 0。6. 分段读写大文件用 uidPos 手动推进文件指针在前面这套流程基础上有一个场景很容易卡住处理大文件时必须分段读取文件的读写位置是怎么推进的这也是熟练使用 CAA File 与只会调 API 的分水岭。CAA File 的 FILE.Read 和 FILE.Write 都带一个 uidPos 输出表示操作完成后文件指针的位置。默认每次从文件头开始读但实际业务里往往需要跳过一段再读比如日志文件按日期分段、CSV 文件按行处理。常见做法是先调用一次 FILE.Read 或 FILE.Seek 定位然后循环读取每次用 uidPos 反馈推进。VAR bReadNext : BOOL; nOffset : UDINT; // 手动维护的偏移量 szChunkSize : UDINT : 1024; END_VAR // 每次读取前把文件指针定位到 nOffset fbRead( xExecute : bReadNext, hFile : hFile, pBuffer : ADR(bufData), szBuffer : szChunkSize, udiTimeOut : 5000000, xDone xReadDone, xEOF xEofFlag, uidPos nOffset );注意fbRead 的 uidPos 输出会返回本次读完后指针的位置这个值可以直接作为下一次读取的起点。你手动维护 nOffset每次把上次的 uidPos 写回去就能按块推进整个文件。文件末尾判断靠 xEOF读到 EOF 后停止循环。坑点在于uidPos 的单位是字节从文件头开始计算但某些文件系统对文件指针有缓冲读完之后指针不会立即落在结尾。工程上更稳的方式是每读一段后调用 FILE.Seek 显式设置下一次读取的偏移量而不是依赖 Read 自动推进。项目里做配方文件解析时我习惯把整个文件读取逻辑封装成一个功能块输入是文件路径和读取起始偏移输出是数据块和文件是否结束。这样业务层不用关心文件指针只需要不停调用这个封装块直到收到 EOF 标志。从那以后每次处理大文件都强制走一遍“先定位、再分段、查 EOF”的流程再也没出现过文件内容被截断或者越界读取的问题。希望这些经验能帮到你尤其是版本兼容和边沿触发这两块吃透了能少走不少弯路。本文还有配套的精品资源点击获取