简介openTCS 5.9中文版用户手册是一份面向AGV调度系统工程师、物流自动化集成人员及RCS系统维护者的操作型指南系统讲解开源运输管理系统openTCS的核心机制与使用方法帮助读者掌握工厂建模、运输订单管理、车辆调度控制等关键技能适用于物流仓储、智能制造等需要AGV调度的场景。压缩包内为单个PDF文件大小13.31MB已有595人学习便于离线查阅和反复参考。手册从系统介绍、系统要求、许可说明入手逐步展开系统组件与结构、工厂模型要素点、路径、位置、位置类型、车辆、块、图层及运行要素运输订单、订单序列、外设作业并覆盖系统操作、重要属性配置、维护与故障排查等章节。对于正在部署AGV调度系统或需要理解RCS调度逻辑的用户这份手册配有清晰的章节组织和截图辅助能帮助读者从概念到实践快速建立完整知识链路降低上手门槛。1. 装 openTCS 5.9 前先泼盆冷水它是一套调度框架不是开箱即用的软件第一次接触 openTCS 5.9多半是带着“AGV 调度系统”和“RCS 系统”这类词来的。它是目前少见的开源车队调度框架制造与仓储场景里的多车导航、订单分派和交通管理都能靠它兜底。但别指望解压就能跑它默认不带你车辆的通信协议JRE 版本还卡在 13版本不符时启动脚本会一句话不说直接退出。装不好轻则几天耗在环境上重则模型建完一辆车都不动。这篇笔记写给正在搭 AGV 调度环境、要对接 RCS 系统的开发者从 JRE 准备到四进程启动再到车辆真的跑起来每一步都按我踩过的路径来。2. 拆解系统架构内核、三个客户端和工厂模型要素2.1 四个独立进程内核、模型编辑器、操作台和内核控制中心openTCS 5.9 安装完你会在 bin 目录里看到一列启动脚本它们对应四个独立进程内核Kernel、模型编辑器Model Editor、操作台Operations Desk和内核控制中心Kernel Control Center。其中内核是唯一的服务器进程负责维护工厂的抽象行驶模型、管理运输订单、为车辆规划路线其余三个都是客户端。模型编辑器用来建立和编辑工厂模型操作台用于工厂运行期间可视化模型、交互式创建运输订单内核控制中心则负责控制和监视内核比如查看车辆驱动状态、给车辆关联驱动。为什么拆成四个进程而不是一个把与车辆无关的调度逻辑全部收敛进内核之后上层客户端可以任意替换和扩展比如再接一个负责与仓库管理系统通信的自定义客户端。这也意味着安装动作不是“启动一个软件”而是“把四个进程都按顺序跑起来”。实际部署时内核所在的机器是唯一的服务器三个客户端可以都跑在同一台机器上也可以分别部署到不同机器只要网络能通。在内核内部订单的处理由三个策略模块完成。手册里它们的中文翻译容易混在一起因为 dispatcher 和 scheduler 都被译成“调度程序”我建议直接记英文职责Dispatcher决定哪台车辆执行哪个运输订单也决定车辆空闲时去哪个停车位、电量低时去哪个充电位。Router为车辆计算到达目的地的最佳路线默认策略按路径成本函数选路。Scheduler管理交通资源分配避免车辆相撞也就是交通管理里的“资源锁”。这三个模块在日志里对应三条记录线后面第 6 章验证跑通时就是靠它们各自留下的调度日志来确认安装成功。2.2 工厂模型的三类点、两类位置和路径属性在 openTCS 里工厂模型由点Point、路径Path、位置Location、位置类型Location Type、车辆Vehicle、块Block、图层Layer这些要素组成。建模时最先接触、也最容易搞混的是点和位置。点Point是行驶路线中车辆的逻辑映射分三种类型停靠位置Halt Position默认类型车辆处理订单时可以停靠到达需要报告但不得超过必要时间。报告位置Report Position车辆只需要经过并报告不被命令在此停靠也不允许停车。停车位置Park Position车辆不处理订单时可以长期停靠的位置。这里有一个新手必踩的坑只由报告位置组成的路线无法路由因为车辆没有任何可以停靠的终点。后面第 5 章的排查记录会单独展开。位置Location则标记车辆可以执行特殊操作的点比如装卸货、充电。位置本身要链接到至少一个点车辆才能到得了位置的类型Location Type定义了该位置支持哪些车辆操作和哪些外设设备操作。路径Path连接两个可导航点主要属性包括长度、最大前进速度、最大倒车速度、锁定标志以及一组外设操作。锁定标志一旦设置路由器计算路线时就不能使用这条路径这点在做检修区隔离时非常有用。车辆Vehicle映射物理 AGV属性里有四档电量阈值临界、良好、完全充电、充分充电以及最大前进/倒车速度。集成级别Integration Level只能通过操作台调整分为忽略ignored、关注noticed、尊重respected含义分别是不显示不派单、显示但不派单、完全参与调度。点类型能否被命令前往能否停靠/停车典型用途停靠位置能能临时停靠订单处理、装卸货过程中的停靠点报告位置不能不能途经点、需要上报位置的通路停车位置能能长期停靠车队空闲时的停放点2.3 布局坐标与模型坐标新手最容易忽略的设定手册里专门用了一小节讲“布局坐标系与模型坐标系”这一节在中文资料里很少被提到但实际部署时几乎必踩。每个点有两套坐标布局坐标Layout Coordinates只用于模型编辑器和操作台里的图形化显示模型坐标Model Coordinates才是车辆驱动使用、甚至发给车辆的真实导航数据。两套坐标本身不关联可以不同。这意味着你在编辑器里把点拖到一条直线排好只改变了图形展示位置AGV 收到的目标坐标可能还是老样子。如果你的 AGV 需要精确坐标导航就会出现“图上看着路线整齐真车跑过去偏得离谱”的情况。要同步两套坐标可以在菜单里选“操作 将模型值复制到布局”或“操作 将布局值复制到模型”做全局同步也可以右键单个要素在上下文菜单里只同步这一个。这一点在模型保存进内核之前一定要确认否则后面排错会非常痛苦。工厂运行要素方面还需要理解三个概念运输订单Transport Order是让车辆执行一项运输任务的最小单元订单序列Order Sequence是按顺序处理的一批运输订单外设作业Peripheral Job是外设设备需要执行的操作例如车辆经过某条路径时打开防火门。外设作业由默认外设作业调度程序管理它用预留令牌机制避免多个车辆作业同时请求同一个外设这部分配置会在第 4 章讲到。3. 安装 openTCS 5.9JRE 13、发行版解压和四进程启动3.1 JRE 版本为什么卡在 13openTCS 5.9 手册的“系统要求”写得非常明确需要 Java 运行环境JRE版本 13并且要求 JRE 的 bin 目录已经加入 PATH 环境变量否则自带启动脚本没法用。网上不少转载的摘要会把系统要求写成“Java 8 或更高版本”我对比了手册正文5.9 的要求是 13就以手册为准。版本不对的典型后果是启动脚本执行后没有任何报错窗口进程一闪就没了。原因在于 openTCS 使用的界面库 Docking Frames 对 JRE 实现有兼容限制。手册明确警告部分厂商打包的 JRE 与 openTCS 不兼容。我实践下来的经验是直接装社区维护的 OpenJDK 13 发行版具体构建版本选择带 hotspot 的标准版即可避免那些深度定制过的商业版 JRE。安装步骤# 解压 JRE 到 /opt 目录 tar -xzf OpenJDK13-jre-x64_linux.tar.gz -C /opt # 将 JRE 的 bin 目录追加到 PATH并设置 JAVA_HOME export JAVA_HOME/opt/jdk-13.0.2 export PATH$JAVA_HOME/bin:$PATH # 验证版本输出应为 openjdk version 13.0.2 左右 java -version这段配置里最关键的不是 JAVA_HOME而是 PATH。openTCS 自带的启动脚本在启动时会直接调 java 命令它并不像某些软件那样自动扫描 JAVA_HOME脚本里写死的就是 PATH 查找。所以 PATH 配好了启动脚本就能找到运行时PATH 没配上脚本会因找不到 java 而退出。Windows 上道理一样在系统环境变量里新建 JAVA_HOME再把%JAVA_HOME%\bin追加到 Path 变量保存后重开一个终端窗口再验证。3.2 解压发行版bin、config、data、log 各管什么拿到 openTCS 5.9 发行版压缩包后解压到一个不带中文和空格的路径下得到如下目录结构opentcs-5.9/ ├── bin/ # 各组件启动脚本 ├── config/ # 内核与客户端的配置文件 ├── data/ # 工厂模型、车辆驱动相关数据 ├── log/ # 运行日志 ├── lib/ # 依赖库与第三方驱动 └── LICENSE.txt # 许可证文件这个目录结构值得先记熟因为排查问题时几乎所有关键信息都在这几个目录里。config 目录存放内核、模型编辑器、操作台各自的配置文件data 目录存放工厂模型文件内核和模型编辑器都会在这里读写模型log 目录对应每个应用都有独立的日志子目录。手册在“支持”一节专门提到提交问题报告时要把 log 子目录下的日志文件和你正在使用的工厂模型一并附上缺了这两样社区基本没法帮你定位。我一般会顺手确认一下 LICENSE.txt 是否存在顺便看一眼许可证类型。手册正文写明 openTCS 在 MIT 许可协议下分发网上有些转载渠道写成 Apache License 2.0以发行版自带的 LICENSE.txt 为准别被二手信息带偏。3.3 启动顺序与启动脚本先内核再客户端四个进程的启动顺序有讲究必须先启动内核再启动客户端。客户端启动时会尝试连接内核内核没起来的话客户端通常只会记录一条连接失败日志然后继续等。Linux 下启动内核cd opentcs-5.9 ./bin/opentcs-kernel.shWindows 环境则运行同目录下的opentcs-kernel.bat。启动脚本的逻辑很简单在 PATH 里找 java读取 config 目录下的内核配置拉起内核进程把日志写到 log 目录。内核起来后再分别启动三个客户端# 启动模型编辑器用于建模型 ./bin/opentcs-modeleditor.sh # 启动操作台用于运行期可视化和发订单 ./bin/opentcs-operationsdesk.sh # 启动内核控制中心用于挂车辆驱动和监视内核 ./bin/opentcs-kernelcontrolcenter.sh三个客户端没有强制先后关系但建议先开内核控制中心因为它能看到内核的详细状态方便确认驱动加载情况。内核与客户端之间通过 Java RMI 通信同时内核还提供 Web API 用于创建和撤销运输订单、查询订单状态外部系统对接走 Web API 更干净。3.4 启动后先看三样东西日志、模型文件和进程状态启动完成不算装完我每次都会做三件事确认环境真实可用第一看 log 目录下内核的子目录确认日志文件已经生成并且里面有内核启动完成、网络接口注册成功的记录。第二看 data 目录确认至少存在一个工厂模型文件。首次启动没有自己的模型时可以打开模型编辑器加载发行版自带的示例模型保存后 data 目录里就会出现对应的模型文件。第三确认四个进程都还活着。启动脚本闪退是最常见的问题如果启动后几秒内只剩两个进程大概率是 JRE 版本问题直接回到 3.1 节排查。这套检查流程走完环境才算是真的立住了接下来才能进入配置阶段。4. 配置内核与客户端订单池、车辆驱动和连接参数4.1 内核配置项订单池、调度器、路由器和外设作业调度openTCS 5.9 的内核配置集中在 config 目录下手册第 5.2 节从订单池、默认调度程序、默认路由器、默认外设作业调度程序、Web API、RMI 接口、SSL 加密、虚拟车辆等维度列了一批配置项。配置文件是文本格式修改后用启动脚本重启内核生效。挑选几个最影响行为的配置组说明配置组关键作用应用场景订单池配置项运输订单的过期清理策略生产计划变更频繁时避免死订单占着车队资源默认调度程序Dispatcher配置项停车位置选择、停车优先级、充电位置选择车辆空闲时的行为策略默认路由器配置项成本函数、路由组决定车辆选哪条路的计算依据默认外设作业调度程序配置项预留令牌机制多车争用同一外设时避免冲突虚拟车辆配置项启动时是否启用虚拟车辆没有真实 AGV 时的联调验证以示意性的配置片段说明写法实际文件里的键名以发行版自带的 cfg 文件为准# 订单池启用自动清理避免无效订单堆积 # 具体键名以 config 目录下实际文件为准 orderpool.cleanup.enabledtrue orderpool.cleanup.interval600 # 调度车辆空闲时优先选择停车位 dispatcher.vehicle.idletrue我一般不会一次性改动所有配置而是先跑通默认配置确认车队行为符合预期后再逐项调整。比如默认路由器按路径成本选路路径长度、最大行驶速度都会进入成本函数计算如果你想引导车辆走某条固定路线而不是最短路线可以通过设置路由组或者调整路径属性来实现而不是盲目改成本公式。4.2 车辆驱动与集成级别AGV 从“存在”到“可调度”openTCS 本身不直接控制某款具体 AGV它把车辆通信协议隔离在“车辆驱动”OpenTCS 中叫通信适配器这一层。安装驱动的做法是把驱动 jar 包放到 lib 目录或指定加载目录然后在内核控制中心里把驱动关联到对应的车辆。这一步不做内核面对的只是一堆没有通信能力的抽象车辆对象订单派下去也没人执行。驱动关联好之后还需要在操作台里调整车辆的集成级别。前面说过三个级别ignored 是完全忽略车辆不显示也不参与任何订单noticed 是车辆会显示位置但系统不会在它所在位置分配任何资源respected 才允许车辆参与运输订单。实际部署时常犯的错是车辆驱动挂好了、位置也上报了但订单一直分不出去打开操作台一看集成级别还在 noticed这就是典型的“能看见但没被纳入调度”。4.3 客户端连接配置RMI 地址、SSL 和跨主机部署三个客户端默认都往本机内核连只要内核和客户端在同一台机器上默认配置就能跑通。真正要改配置的场景是跨主机部署内核跑在服务器上操作台放在中控室电脑上模型编辑器在工程机里。这种情况下三个客户端各自的应用程序配置里要指明内核主机地址和 RMI 接口配置。手册第 6.4 节专门给了“在不同的系统上运行内核和客户端”的示例核心思路是内核所在机器固定 IP客户端配置里的连接地址从默认的本机地址改成内核 IP。如果跨公网或跨安全域部署还需要启用 SSL 加密手册 5.2.9、5.3.2、5.4.2、5.5.2 分别对应内核、内核控制中心、模型编辑器、操作台四个应用的 SSL 服务端加密配置项。我的建议是局域网内部署可以先不开 SSL本地跑通再开一旦涉及跨网络SSL 必须开否则车辆控制指令在网络上裸奔风险太大。# 跨主机场景下假设内核在 192.168.1.10 # 客户端机器的配置文件中修改内核连接地址指向该 IP # 具体键名以发行版配置文件为准 kernel.registry.host192.168.1.104.4 应用语言与模型命名方案openTCS 5.9 的应用语言配置在手册 5.1 节模型编辑器、操作台、内核控制中心各自有语言设置项默认界面以英文为主。中文用户可以把模型编辑器和操作台的语言切到中文减少现场操作人员的理解成本。模型编辑器还有一个容易被忽略的配置要素命名方案5.4.3 节。它决定你在画布上新增点、路径、位置时系统自动生成的名字规则。项目前期我习惯把命名方案配置成“前缀 序号”的格式例如 Point-001、Path-001、Loc-001这样内核日志里出现 Point-042 时能直接对应到图纸编号。如果不配置默认命名很快会让日志变得没法读尤其车辆多、路径多的时候日志里全是无名代码。5. 常见问题排查五个安装与调试阶段的典型踩坑记录5.1 启动即闪退JRE 与界面库的兼容性问题现象执行opentcs-kernel.sh或客户端启动脚本后终端里没有任何输出进程几秒内消失log 目录下要么没有日志要么只有一条不完整的初始化记录。原因openTCS 使用的 Docking Frames 界面库对 JRE 实现有兼容限制部分厂商深度打包的 JRE 会触发不兼容问题导致界面框架初始化失败。手册里已经把这个问题写得很直白属于已知坑。解决卸载当前 JRE换装社区维护的 OpenJDK 13 发行版重新配置 PATH 后再次执行java -version确认当前生效的确实是新装的版本。这里有个细节Windows 上改完系统环境变量后一定要重开终端窗口再启动旧窗口里 PATH 还是老值很容易误判问题没有解决。5.2 模型能建但路由失败报告位置不能作为终点现象模型画好了点、路径、位置都齐全但 dispatcher 一直派不出订单日志提示找不到可行路线或目的地不可达。原因把路线上的点全部建成了报告位置。报告位置不允许车辆停靠车辆也不会被命令前往报告位置只由报告位置组成的地图从根本上就无法路由因为车辆永远没有可停靠的终点。解决把需要车辆停靠处理订单的点改成停靠位置长期停放的改成停车位置报告位置仅保留给纯途经点。修改后保存模型并在模型编辑器里重新加载到内核。5.3 车辆坐标不对动的是布局坐标发出去的是模型坐标现象操作台视图上路径整齐、位置精确但真实车辆收到的目标坐标和预期不符甚至出现车辆朝着错误方向行驶的情况。原因建模时拖动的是布局坐标只改了图形显示模型坐标没有同步变化而车辆驱动最终使用的是模型坐标。解决在模型编辑器里执行“将模型值复制到布局”或反方向的全局同步再单独检查可能需要微调的要素。完成同步后保存工厂模型重新加载到内核。从那以后我建完模型必定检查两套坐标的一致性不再只盯着画面看。5.4 车辆不接单集成级别停留在 noticed现象车辆出现在操作台界面上位置也在实时上报但创建运输订单后订单状态一直停在等待分配没有车辆响应。原因车辆集成级别还处于“关注noticed”状态。该状态下系统接收车辆位置报告但不会在车辆所在位置分配任何资源车辆也不参与订单分配。解决在操作台客户端找到车辆详情把集成级别调整为“尊重respected”。调整后观察内核日志应能看到该车辆开始参与资源分配和订单评估的记录。5.5 反馈支持没人理日志和模型文件没带全现象在讨论区发布了问题帖很久没人回复或者回复第一句就是“请提供日志文件和工厂模型”。原因openTCS 是开源社区的免费支持模式维护团队没有无限免费支持义务问题定位必须靠数据。手册明确要求提供两类材料各应用 log 子目录下的日志文件以及 data 子目录下的工厂模型文件。解决提问前把内核、内核控制中心、模型编辑器、操作台四个应用的日志子目录打包连同当前使用的工厂模型文件一起上传。日志里带上时间点、操作步骤描述和预期结果问题被定位的概率会高很多。6. 验证跑通用虚拟车辆走一张完整运输订单6.1 三要素核对清单配置完成先别急着接真实 AGV我用虚拟车辆做端到端验证。第一步是在模型编辑器里建一个最小模型两个停靠位置点 A 和 B用一条路径连接B 点旁边放一个位置并链接到 B 点。对照三个要素检查模型是否可运行点必须是停靠位置或停车位置不能是报告位置路径不能带有锁定标志位置至少链接一个点。三样确认无误后保存模型。6.2 跑一张虚拟车辆运输订单看三段日志打开内核配置里的虚拟车辆开关重启内核然后在操作台里能看到一台虚拟车辆上线。给它创建一张从 A 到 B 的运输订单观察这个过程操作台视图里虚拟车辆会从起点出发沿路径移动到达终点这个过程中位置上报、停靠、行驶状态变化都会显示出来。更重要的是内核日志里会出现三段关键记录dispatcher 完成订单与车辆的匹配、router 计算并输出路径、scheduler 依次分配和释放沿途资源。三段记录齐全说明内核核心链路是活的。如果订单发出后没有任何日志反应先检查虚拟车辆是否处于 respected 状态如果只有 dispatcher 记录而 router 没有输出优先怀疑模型里存在不可路由的点类型问题回到 5.2 节排查。从那以后我每次装完 openTCS都强制自己用虚拟车辆走一遍完整订单流程再往下推进确认 dispatcher、router、scheduler 三个模块都在日志里留下记录才开始接真实 AGV。这套方法帮我避开了很多“环境看着没问题、一上真车就翻车”的尴尬场面。希望帮到你。本文还有配套的精品资源点击获取