Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Ball-Balance-Rolling-Control

2026 年全国大学生电子设计竞赛 H 题「车载平衡滚球运动控制系统」完整开源实现

三端分布式 · 视觉/控制解耦 · 从仿真到实机全链路可复现


这是什么

一辆红外循迹小车,车头装着摄像头,车上架着一根 25cm 的凹槽摆杆,杆上有一颗 直径 1cm 的钢球。小车要沿着黑色环形路线跑,同时摄像头实时看球,控制摆杆 倾斜,让钢球稳稳停在指定位置(比如 +50mm、-50mm、再回到中间)——这就是 2026 电赛 H 题的全部。(对,就是那个"让球别滚下去"的题,看着简单, 调参调到你怀疑人生 😂)

本仓库是我们队伍完整的参赛工程,包含:

  • K230 视觉节点:纯 CV(HSV)检测钢球、三标线标定、位置/速度滤波、UART 下发测量
  • STM32F103 球控板:延迟预测 + PID + 轨迹规划 + 卡滞脱困 + 2804 激振器
  • MSPM0G3507 底盘:8 路红外循迹、任务状态机、OLED 计时、蓝牙无线调参桥
  • PC 调参工具:GUI / 硬件在环调参 / 无硬件仿真 / 完整流程验收脚本
  • Web 可视化平台:RTSP → WebRTC 低延迟视频、实时遥测、录像与回放
  • 部署工具链:MTP 部署 + SHA-256 回读校验 + 可回滚备份

技术栈

模块 平台 技术
视觉节点 嘉楠 K230(Yahboom CanMV) MicroPython 1.4.3 · CanMV libs.PipeLine · ulab.numpy · 硬件 VENC(H.264) · WBC RTSP
球控固件 STM32F103C8T6 STM32Cube HAL · CMake + ARM GCC · 前后台裸机
底盘固件 MSPM0G3507 TI CCS / ticlang · 8 路 IR · 编码器电机 PID
PC 工具 Windows Python 3.11+ · PySerial · Tkinter GUI · HIL 仿真
Web 平台 Windows/笔记本 FastAPI · React + TypeScript + Vite · MediaMTX · WebRTC/WHEP · SQLite
部署 Windows PowerShell + MTP · SHA-256 回读校验 · 可回滚

目录结构

.
├── README.md                  # 本文件:总览 + 快速开始(先看这个没错)
├── docs/
│   ├── TUTORIAL.md            # ★ 教学文档:从零拆解(建议先读这个,有梗有货)
│   ├── ARCHITECTURE.md        # 系统架构与数据流(正经版)
│   ├── 赛题_2026电赛H题.pdf   # 赛题原文(一切的起点)
│   ├── 交接文档_原始.md        # 团队给 AI 助手的项目上下文(含设计哲学)
│   └── 交接文档_20260801.md    # 赛前交接(调参锁定参数,抄作业入口)
│
├── ball_control/              # ★ 球控系统主线(视觉 + 控制 + 工具,核心中的核心)
│   ├── README.md              # 三端架构与上机顺序
│   ├── SERIAL_PROTOCOL.md     # 三端统一帧协议(CRC16,联调必读)
│   ├── docs/                  # 协议 / 接线 / 调参卡片 / 激振器部署
│   ├── stm32/                 # STM32F103 球控固件(CMake 工程,控制大脑)
│   │   └── Core/Src/          # app_control / app_servo / app_vibrator / app_protocol ...
│   ├── k230/                  # K230 视觉节点(感知眼睛,含 RTSP 回传)
│   ├── pc_gui/                # PC 调参工具(GUI / hil_autotune / simulator / task3_sequence)
│   ├── tests/                 # 协议与 HSV 快速路径单元测试
│   └── integration/           # MSPM0 加速度前馈集成示例
│
├── chassis/                   # MSPM0G3507 底盘(跑路担当)
│   ├── eight_ir_oled_merged/  # CCS/ticlang 工程(循迹 / 电机 / OLED / 蓝牙桥)
│   └── BT_TUNING.md           # 蓝牙无线调参链路方案(无线调参,站着就把参调了)
│
├── deployment/                # K230 设备部署(MTP + SHA-256 校验 + 回滚)
│   ├── deploy-mtp.ps1         # MTP 部署脚本(依赖优先,main.py 最后写)
│   ├── deploy.ps1 / rollback.ps1
│   ├── profiles/              # edge-control-v4 / vendor-reference 部署配置
│   └── DEPLOYMENT_RECEIPT.md  # 历次部署回执(含 SHA-256,出问题翻这里)
│
└── webui/                     # Web 可视化平台(比赛现场"数字座舱")
    ├── apps/api/              # FastAPI 后端(遥测 / 录像 / 回放)
    ├── apps/web/              # React 前端(Live / Replay 页面)
    ├── infra/                 # MediaMTX / start.ps1 / offline-qa.ps1 / WiFi 配置
    ├── contracts/             # 遥测 / 事件 / 命令 JSON Schema
    └── docs/                  # 架构 / 开发指南 / K230 集成契约

快速开始(复现路径)

没有硬件也能先跑通一半:pc_gui 带一个无硬件仿真器,Web 平台带一个 离线样片 QA 脚本。建议顺序(虚拟先行,硬件殿后,能少掉一半头发):

# 1. 无硬件:跑通 PC 调参 GUI 全流程(模拟 STM32 + K230 + 球动力学)
#    白嫖体验:不花一分钱先学会所有按钮是干嘛的
cd ball_control\pc_gui
.\run_simulator.bat

# 2. 无 K230:跑通 Web 视频链路(本地样片发布 → WebRTC → 录像 → 回放)
#    模拟 K230 营业,全链路在家就能彩排
cd webui
powershell -ExecutionPolicy Bypass -File infra\offline-qa.ps1

# 3. 有硬件:烧录 STM32(ST-Link),上传 K230 视觉,连接串口联调
#    烧完先别接舵机!先 probe 再 MANUAL,顺序错了会打手
cd ball_control\stm32
cmake --preset Release
cmake --build build\Release --target flash

# 4. 完整流程验收(球放 0 位,数据自动存 CSV)
cd ..\pc_gui
python task3_sequence.py --port COM19 --hold-s 2.5 --hold-tail-s 3.0

完整的上机顺序、接线和验收标准见 ball_control/README.md 与 webui/docs/K230_INTEGRATION.md。

硬件清单(我们实际使用的)

  • 主控:STM32F103C8T6(球控)+ MSPM0G3507(底盘)
  • 视觉:嘉楠 K230 Yahboom 开发板(CanMV 固件 1.4.3,GC2093 + ST7701 LCD)
  • 执行:SG90 舵机 ×1、2804 云台电机 + SimpleFOC Mini(激振辅助,可选)
  • 传感:8 路红外循迹模块、编码器直流电机 ×2、OLED、HC-05/JDY-31 蓝牙(可选)
  • 轨道:25cm PPR 凹槽摆杆 + 直径 ~1cm 钢球(球面平滑度是最大变量,见教学文档)

文档导航

  1. 学弟学妹看这里 → docs/TUTORIAL.md:从零拆解,讲清楚 为什么这么设计、代码在哪、坑在哪。
  2. 想看架构 → docs/ARCHITECTURE.md
  3. 想直接抄代码 → ball_control/ 三端 + webui/,各自 README 都有上机步骤。

本仓库面向 2026 电赛 H 题开源。硬件参数(舵机中位、PID、脱困角度)基于我们 的实机调参,直接照搬前请先理解每项参数的意义(教学文档第五章有逐项解释)。 热点密码、串口等默认值仅用于开发环境,比赛现场请自行修改。

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages