项目结构与核心模块
约 2105 字
Lumina 是面向 RoboCup Small Size League(SSL)的决策与控制系统,基于开源框架 Rocos 进行二次开发。它不是一个单独的可执行程序,而是由可视化客户端、策略模块、单车调试工具和运行时资源共同组成。
先建立整体认识
- Client 负责接入数据、展示状态、管理进程,并把策略指令发送给仿真器或机器人。
- Medusa 负责感知后的决策、战术、技能和运动规划。
- Aurora 是我们测车的工具软件,可以让车做出基本的动作,方便我们测试。
- ZBin 既保存运行时配置和 Lua 策略,也是编译后程序的统一输出与运行目录。
系统如何协作
在 SSL 的标准架构中,SSL-Vision 提供场上目标的原始检测结果,SSL Game Controller 广播比赛状态和裁判指令,参赛队伍的软件负责进一步处理数据、完成决策并与机器人通信。详细背景可参考 SSL Technical Overview 和 RoboCup-SSL 官方仓库。
当前目录结构
以下结构以当前仓库为准。为了突出主要职责,省略了模块内部的大量源文件。
.github# GitHub Actions、Issue 与 PR 模板
…
Aurora# 测车软件
…
Client# 可视化客户端,负责中转吞吐各种数据,与其他模块协作
…
cmake# CMake 公共模块和构建辅助脚本
…
Installer# Ubuntu 工作站安装器(Git 子模块)
…
McpServer# 面向 AI 工具的 Lumina MCP 服务
…
Medusa# 决策、战术、技能与运动控制核心
…
scripts# 环境配置、性能优化和 CI 脚本
…
share# 多模块共用的协议与基础代码
…
Twilight# Lumina 的 VS Code 开发辅助插件(Git 子模块)
…
ZBin# 运行目录:配置、Lua 策略与编译后的程序
…
Zrazy# 浙大测车软件的C++版本,无需使用
…
CMakeLists.txt# 项目总构建入口
README.md# 项目简介与快速开始
为什么没有看到 build/ 和 lib/?
它们不是源码目录,而是配置或编译项目后产生的构建产物:
build/保存 CMake 缓存、目标文件和由 Protobuf 生成的*.pb.h、*.pb.cc等中间文件;目录名称可以自定义,也可以安全地重新生成。lib/保存构建得到的动态库和静态库,例如 Client 使用的仿真插件。- 可执行程序会输出到
ZBin/,因此Client、Medusa和Aurora应从该目录运行。
不要把源码或需要长期保留的配置放进 build/。
核心模块
Client:数据入口与系统控制中心
Client/ 保存 Lumina 图形客户端的 C++、QML 和资源文件。它将比赛所需的多个数据源和程序连接起来,主要负责:
- 接收
SSL-Vision或仿真器的视觉数据,完成融合、滤波和状态维护。 - 接收
SSL Game Controller的裁判消息,并向 Medusa 提供当前指令、下一指令、守门员编号等比赛状态。 - 与 Medusa 双向通信:发送处理后的视觉和裁判数据,接收机器人控制与调试绘制数据。
- 将控制指令发送到内置 ZSimulator、外部 grSim 或真实机器人,并接收机器人回包。
- 提供比赛画面、参数配置、日志录制与回放、裁判协议调试等界面。
- 管理 Medusa、grSim、SSL Game Controller 和 Aurora 等辅助进程。
进一步使用方法请从 Client 使用指南 开始阅读。
Medusa:策略核心
Medusa/ 是 Lumina 的决策核心。主要代码位于 Medusa/src/,按职责划分为:
Medusa
src
Vision# 视觉数据与场上状态二次处理
…
WorldModel# 世界模型,各项数据获取
…
RefereeBox# 裁判指令处理
…
Strategy# 角色分配、战术与 Skill
…
LuaModule# C++ 与 Lua 的绑定
…
MotionControl# 运动控制,算法
…
PathPlan# 路径规划,算法
…
PointCalculation# 位置与候选点计算
…
Wireless# 下发机器人控制指令
…
Simulator# 数据类型声明,车辆控制数据发回Client
…
CUDAModule# NVIDIA CUDA 后端
…
ROCmModule# AMD ROCm/HIP 后端
…
AccelModule# GPU加速模块的统一接口
…
Medusa 的 C++ 代码负责底层算法和运行框架,比赛中的 Play、角色和 Skill 组合则主要由 ZBin/lua_scripts/ 下的 Lua 脚本组织。CUDA 与 ROCm 都是可选后端;无可用 GPU 时也可以构建 CPU-only 版本。
Aurora:测车工具
Aurora/ 是当前的上车、维修和赛前检查工具。它通过串口连接无线发射机,可选择机器人编号和通信频率,并手动测试:
- 前后、横移与旋转;
- 吸球;
- 平射与挑射;
- 单车控制或全车组控;
- 发射机连接、握手及机器人回包。
Aurora 可以由 Client 启动,也可以在 ZBin/ 中单独运行,或直接使用 Windows 预构建包免安装运行:
cd ZBin
./Aurora进一步使用方法、各部分功能说明与快捷键手册请参考 Aurora 使用指南。
实车调试安全
连接发射机前先将机器人架空或清空周围区域,并核对串口、频率和机器人编号。首次发送应使用较小速度与射门功率;组控会同时向多台机器人发送指令,只应在场地安全、车辆状态明确时启用。遇到异常立即停止发送或断开发射机。
支撑模块与工具
share/:共享协议与基础设施
这里保存 Client、Medusa 等模块共同使用的代码:
share/proto/:SSL-Vision、SSL Game Controller、grSim、Client 与 Medusa 通信、日志等 Protobuf 协议;生成的 C++ 文件位于构建目录的proto/,不要手动维护。geometry.*:点、线、圆、多边形等几何计算。parammanager.*:读写ZBin/下的 INI 配置。staticparams.*:场地、端口和机器人数量等公共常量。dataqueue.hpp、Semaphore.h、ThreadPool.h:队列、同步和线程池等基础设施。zsplugin.hpp:Client 与插件模块之间的接口。
修改这里的接口可能同时影响 Client 和 Medusa,提交前应完成全项目编译与联调。
ZBin/:运行目录
ZBin/ 中同时存在版本控制内的资源和编译生成的程序:
ZBin
config# SSL Game Controller , AutoRef 等 YAML 配置
…
lua_scripts# Lua 脚本
…
LOG# 运行日志文件,比赛录像
…
zss.ini# Client 与 Medusa 的主要配置
zss_details.ini# zss.ini 中各项的解释
zss_simulator.ini# 内置仿真器配置
kickparam*.ini# 射门标定参数
ProcessAlive.sh# Medusa 进程保活脚本
编译完成后,Client、Medusa、Aurora、Zrazy、grSim 等可执行文件也会出现在这里。运行目录会影响相对路径配置和 Lua 脚本加载,因此请在 ZBin/ 目录下启动这些程序,尤其是 Client 与 Medusa。
cmake/ 与 scripts/
cmake/提供 Qt 自动检测、依赖查找、输出目录和通用构建配置,不是可删除的构建缓存。scripts/包含环境初始化、性能检查与优化、FluentUI 获取及 CI 环境脚本。执行涉及系统配置的脚本前,应先阅读脚本内容并确认适用于当前机器。
Installer/、Twilight/ 与 McpServer/
Installer/:面向 Ubuntu 24.04 的 Lumina 工作站安装器,用于配置编译依赖、Qt、开发工具和可选 GPU 环境。Twilight/:VS Code 开发辅助插件,可连接正在运行的 Client,提供运行状态、回放控制、Lua/C++ 跨语言跳转、诊断和代码生成。McpServer/:向兼容 MCP 的 AI 工具提供受限的源码检索、架构信息和 Client 运行时能力;普通编译和比赛运行不依赖它。
Installer 和 Twilight 是 Git 子模块。首次完整克隆建议使用:
git clone --recurse-submodules https://github.com/lkhcode/lumina.git已经克隆仓库但子模块目录为空时,可执行:
git submodule update --init --recursiveZrazy/
Zrazy 是我之前用来参考开发 Aurora 的时候用的,是浙大WIFI车的测试软件的移植版,原版使用 Python 开发,被我移植到了 C++ 。不用管这个