OPEN SOURCE DEEP DIVE
科聪 UDP 协议的 openTCS 社区驱动
社区维护的 openTCS 通信适配器,通过科聪 UDP V2.0 接入 MRC/FRC 控制器;梳理已接通的导航、变量写入与初始化风险,并明确 JRC3000 支持关系尚未验证。
项目定位与证据边界
这是一个面向科聪 MRC/FRC 系列 AGV 控制器的 openTCS 通信适配器。它尝试把 openTCS 下发到车辆的运动命令转换为科聪 UDP V2.0 报文,再把控制器返回的位置、任务状态和电量写回 openTCS 的车辆进程模型。项目采用 Java 11 和 Maven 构建,明确以 openTCS 7.2.1 为测试版本。
需要先把两个容易混淆的对象分开。仓库描述的是社区维护的科聪 MRC/FRC 适配器,并不等同于商用 JRC3000 驱动。JRC3000 是闭源商业系统,现有代码和文档没有给出二者同源、兼容或逆向实现的证据,因此不能把本项目宣传成 JRC3000 支持方案。仓库当前也已归档,适合作为协议理解和现场接入的参考,不应直接视为持续维护的生产驱动。
许可证同样存在不确定性。README 宣称采用 MIT 许可,但仓库没有 LICENSE 文件,GitHub 元数据也未识别出许可证。仅凭 README 中的一句声明,无法确认复制、修改和再分发条款,实际用于商业项目前需要向作者取得明确授权。
它在 openTCS 中的位置
openTCS 内核负责任务、路线和车辆调度,通信适配器则把抽象的运动命令落到具体车辆。这个项目的工厂类负责读取车辆属性并创建适配器,适配器维护一条待执行命令、定时查询车辆状态,并在目标完成后通知 openTCS。车辆进程模型保存科聪特有的工作模式、定位状态、电量、充电状态和命令序号。
代码按职责分为协议层和适配器层。协议层包含 28 字节帧、UDP 通道、命令编码器、响应解码器以及若干数据模型,不依赖 openTCS。适配器层实现 openTCS 的车辆通信接口,把控制器状态翻译为 openTCS 的车辆状态。这样的拆分有利于单独测试报文格式,也让 CLI 或其他调度系统有机会复用协议库。
UDP 协议模型
协议帧由 16 字节授权码、1 字节协议版本、1 字节报文类型、16 位序列号、固定服务码、命令码、执行码、16 位数据长度和 28 字节头部后的负载组成。所有多字节字段采用小端序,数据区最大 512 字节。每个请求使用递增的 16 位序列号,并在发送锁内完成一次发送和一次接收。
默认网络参数为导航端 192.168.100.178:17804,二维码和变量端 192.168.100.200:17800,推荐轮询周期 100 毫秒。导航通道的超时至少为 2 秒,变量通道默认为 1 秒。两个通道各自持有一个 UDP 套接字,因此导航状态、导航命令和变量写入走的是不同的控制器入口。
协议层保留了很多命令模型和编解码能力,包括状态订阅、混合导航、暂停恢复、货叉、货物状态、多变量读写、交通管理、二维码导航和磁导航。但“仓库里有模型”不等于“适配器已经调用”。实际控制路径明显更窄,这也是阅读项目时最需要警惕的地方。
真正接通的控制闭环
当前实时路径首先使用 0x17 查询运行状态。解码结果包含双精度位置、航向、电量比例、运行模式、任务状态、定位状态和置信度。适配器以约 100 毫秒周期读取这些字段,更新车辆位姿、openTCS 车辆状态以及科聪扩展属性。
导航命令使用 0x16,负载固定为 432 字节。适配器把目标路点 ID 写入第 4 到第 11 字节,操作码设为 0,表示立即开始导航,导航模式为前往路点,交通管理标志为关闭。路点 ID 优先读取路点属性 kc:markerId,缺省时才使用 openTCS 路点名称,因此名称必须与控制器地图 ID 一致,或者显式配置正确属性。
货叉动作使用二维码端口上的 0x00 变量写入。LOAD 或 PICKUP 写 Forkup,UNLOAD 或 DROPOFF 写 Forkdown,另外还支持 Forkforward 和 Forkback。变量值置为 1 后保持 5 秒,随后写 0 停止,再等待约 2 秒假定动作结束。若停止命令连续三次失败,代码仍会继续推进,并有 30 秒全局超时兜底。这种设计能防止任务永久悬挂,却无法证明货叉真的到达目标位置,现场必须依赖限位、传感器或人工确认。
电量默认直接取 0x17 响应中的比例。项目还提供 0x01 单变量读取和 0x02 多变量读取两种可选方式,后者的报文格式依据实机 MRC 结果做了修正。它们属于配置项,不是默认状态链路。
文档能力与运行能力并不等价
README 的能力表列出了 0xAE 混合导航、0xAF 状态轮询、0xB1 状态订阅、0xB2 即时动作、0xF1 和 0xF5 二维码导航、0xE0 至 0xE3 磁导航以及 0x70 和 0x71 交通管理。协议库中确实能找到相应的数据结构或编解码器,但适配器当前没有把这些路径接入 enqueueCommand、轮询调度或故障处理。
例如,0xB1 订阅刷新函数虽然存在,却没有被调度,subscriptionFuture 也从未赋值,实际状态来源仍然是 0x17 轮询。适配器的可转移进程模型返回空对象,canProcess 对任何运输订单都返回支持,车辆暂停回调和自定义消息处理也是空实现。这些缺口不会让编译失败,却会让 openTCS 误以为适配器具备比现实更多的调度能力。
初始化顺序与现场风险
自动初始化默认关闭,工厂读取 kecong:autoInit,缺省值为 false。开启后,适配器最多重试五次读取 0x17 位置;取得坐标后切换到手动模式,发送 0x14 手动定位,再发送 0x1F 确认位置,最后切回自动模式。整个序列之间使用固定短延时。
README 描述的“等待定位完成并轮询状态”并没有完整对应到代码。当前实现不会在确认后持续检查定位状态,也没有逐项确认每个模式切换或确认命令的结果。若控制器处于非预期位置、定位尚未完成或网络丢包,代码仍可能继续执行后续步骤。这个初始化序列会改变车辆控制模式,不应在载货、有人或未隔离的车辆上直接测试。
建议先在离线仿真或空载测试台验证完整报文,再把自动初始化拆成可观察的状态机:每一步都必须收到正确执行码,确认定位达到预期状态后才能切回自动模式,任何超时都应阻止后续步骤并明确上报故障。
任务完成、失败与诊断
0x17 的任务状态包括等待、执行、暂停、完成和失败。适配器把执行中映射为 openTCS 的执行状态,把失败映射为错误状态,但完成和失败在命令队列处理上进入同一个分支,都会调用 commandExecuted 并消耗待执行命令。结果是 openTCS 能看到车辆进入错误状态,却没有从驱动层得到清晰的“本运动命令失败”结果。
状态轮询中的输入输出异常会被吞掉,部分订阅异常也没有可观察的上报路径。0x17 解码器只提取位置、电量、模式和任务状态,没有把异常事件列表填入车辆状态,因此 README 描述的错误事件上报并不能从当前实时链路得到证明。进程模型虽然提供 setErrorCodes,却没有在轮询中调用。
UDP 通道收到一个能够解码的帧后即返回。它检查执行码,却不校验授权码、序列号、命令码或发送方地址。控制器只应答的理想网络里问题不明显,但在共享工业网络、地址冲突或攻击场景下,旧响应和伪造响应都可能被当作当前命令的结果。生产化版本应至少核对序列号、命令码、发送方和授权码,并为迟到响应建立隔离策略。
配置与部署要点
车辆属性可以覆盖导航地址、二维码地址、两个端口、轮询周期、授权码、自动初始化开关和电量来源。若未配置授权码,代码会使用内置默认值,并在日志中输出完整授权码;若配置了授权码,日志还会同时显示属性值。这种做法会把访问凭据写入普通日志,不适合无人值守的生产环境。
地图映射也存在文档与代码不一致。README 建议在路点上配置 kecong:pointId,实际导航代码读取 kc:markerId,缺失时才回落到路点名称。现场如果照文档配置而未改名称,就可能把展示名称当作控制器路点 ID 发送。最低成本的规避方式是统一使用控制器数字 ID 作为 openTCS 路点名称,并在部署前逐点核对。
安装时需要把协议和适配器两个 JAR 放入 openTCS 扩展目录。项目声明 Java 11 以上、Maven 3.6 以上、openTCS 7.x 和特定版本的科聪导航程序与固件。这里的版本要求来自项目文档,仍需与实际控制器固件逐项核对。
测试、发布与维护状态
审查提交 82c7cfc 的持续集成只运行协议模块测试,Java 11、17 和 21 的构建已经通过,覆盖率门限设在 85%。这能说明协议帧和小端编解码有一定回归保护,不能说明适配器、真实 UDP 交互或车辆行为已经获得同等覆盖。适配器自身已有单元测试文件,但当前工作流没有执行它们。
发布工作流在打标签后跳过测试,只安装 openTCS api-base 依赖,而适配器模块还依赖 api-injection。这个差异可能在发布环境暴露依赖缺失,应视为需要复现的发布风险,而不是已经确认的故障。
仓库在本次审查时已归档,公开元数据为 1 个星标、0 个复刻、11 个开放议题,最后提交时间为 2026 年 7 月 22 日。项目没有图片资产,也没有许可证文件。归档意味着不能期待上游及时修复协议、并发或安全问题。
适用建议
这个项目最有价值的部分是提供了一条可读的科聪 UDP V2.0 接入样本:帧布局清楚,导航和变量写入路径短,协议库与 openTCS 解耦,适合协议核对、实验室联调和二次开发。它也能帮助开发者理解 openTCS 适配器需要补哪些状态回传和配置映射。
但在自动导引车场景里,它还不具备“拿来即上生产”的证据链。采用前应把命令完成与失败分开处理,补充 UDP 响应关联和发送方校验,恢复状态订阅或删除相关宣传,落实定位确认状态机,补齐错误码和设备状态,限制 canProcess 的能力声明,并把适配器测试纳入持续集成。授权码日志和许可证问题也要在上线前处理。
如果目标只是验证某个科聪 MRC/FRC 控制器与 openTCS 的报文是否跑通,这个仓库是一个有参考价值的起点。如果目标是让车队长期无人值守运行,更稳妥的做法是以它为协议参考,建立经过现场测试、具备明确故障语义和可审计安全边界的内部驱动。上述判断只针对科聪 MRC/FRC 社区适配器,不延伸到闭源 JRC3000。