MA培训文档

本书的一些符号和标注

• <XXX> 表示命令里你需要根据实际情况替换的内容. 例如你要clone team-training仓库，git clone <url>，你需要替换成git clone git@github.com:mechanical-ancestor/team-training.git.

GitHub

简介

GitHub是一个基于Git的开源代码托管平台，提供各种版本控制功能，包括代码托管、协作开发、项目管理、代码审查、问题跟踪等。

开始使用GitHub

开始使用Git

核心概念

• 仓库

• 问题跟踪

开始使用 GitHub

网络问题

可以尝试以下方法解决网络问题：

• Windows建议用，下载Watt Toolkit免费加速GitHub，但是Linux里基本用不了。
• 科学上网，不方便细说

注册

点此注册 根据提示填写相关信息即可。

设置ssh密钥

为什么要设置ssh密钥

我们知道，要推送修改到GitHub仓库，首先肯定要验证你是谁，这样才能知道你有没有权限。

下面介绍三种GitHub支持的验证方式

• 密码认证
• ssh密钥认证
• 双因素(Two-factor)认证

由于GitHub在2021年8月13日以后不再支持密码登录，而是推荐双因素认证。

由于https协议在推送提交时用的就是密码认证，导致用https协议Clone下来的仓库，在推送修改时如果没有设置远程推送URL， 由于无法通过密码认证，导致无法推送。

但是如果使用ssh协议进行clone下来的仓库，就不需要输入用户名和密码，因为ssh协议使用你提前上传的ssh公钥进行认证。

为此我们可知，要使用ssh密钥认证，你需要：

• 生成ssh密钥对
• 将公钥上传到GitHub
• 用ssh协议Clone仓库，或者设置远程推送URL

生成ssh密钥对

在终端输入以下命令，生成ssh密钥对：

ssh-keygen

然后如果没有特殊要求, 一路回车，默认即可。

这时候会在~/.ssh目录下生成两个文件：

• id_ed25519: 私钥
• id_ed25519.pub: 公钥

这时可以复制公钥内容，准备上传到GitHub。

将公钥上传到GitHub

在GitHub点击头像，依次点击Settings，SSH and GPG keys，New SSH key按钮

• Title: 随便起名
• Key: 粘贴之前生成的ssh公钥(id_ed25519.pub)的内容

加入组织

• 申请考核之前，是需要进入mechanical-ancestor组织的。

• 提供你的github账号，我们即可邀请你进入mechanical ancestor(MA视觉组织)

你的github账号如下图所示：

Git

1. Git 与 GitHub

Git 是工具：负责本地代码的版本控制（如记录修改、分支管理）。 GitHub 是平台：基于 Git 提供远程托管和协作功能，让分布式开发更便捷。

简单来说：使用git可以管理代码，并将代码托管到github，而github可以分享代码。

关于Git的使用可以看文档

当然，git的官方文档也是不错的，有兴趣的自行观看

仓库

介绍

仓库

组成

1. Git仓库
2. Issues
3. Pull requests

问题跟踪

分支

工作流

其他文档

看看这个： Git简易指南

详细的有吗（有的兄弟有的）： Git入门教程(宝宝巴士版)

分支

分支是git版本控制系统中重要的概念

remote仓库

remote仓库是指托管在远程服务器上的仓库, 你本地的git仓库可以指定多个远程仓库

远程仓库可能包含多个分支, 如remote/main, remote/dev, 等.

添加仓库

git remote add <仓库名称> <url> 

origin远程仓库

origin 一般表示默认的远程仓库,

添加origin远程仓库

git remote add origin <url> 

默认上游分支

默认上游分支是分支的属性， 当在某个分支执行例如push等命令时的默认远程分支。

设置远程推送URL

git remote set-url --push origin <url>

local仓库

local仓库是指你本地的仓库

local仓库基本是remote仓库的一个镜像版本,

例如你如果有远程分支remote/main, 那么你本地仓库的main分支就是remote/main的一个镜像版本.

之后你所有关于main分支的修改本地的修改和提交都发生在本地仓库的main分支上

所以你push命令实际上是把本地的分支同步到远程仓库的对应分支上.

Git 工作流

克隆

git clone <url>

查看状态

查看当前分支状态

这会输出当前分支的状态和暂存区状态等状态.

git status

注意查看当前位于的分支，如果是刚克隆的仓库，默认是main分支。

有时你不被允许修改main分支，这时你需要切换到其他分支

查看提交历史

这一般用来查看历史提交记录.

git log

切换分支

切换到指定分支

git checkout <branch>

暂存区

暂存区是存放待提交的修改的地方. 类似于一个未封装的快递盒.

添加文件到暂存区

git add <file1> <file2> ...

类似于将东西放入盒子.

添加文件夹到暂存区

git add <folder>

类似于将一堆东西放入盒子.

.gitignore文件

有时你不想让git管理某些文件，比如临时文件, 编译生成的文件或者占用很大的视频文件， 又或者你不想让别人看到你的密码文件.

你可以在.gitignore文件中添加一些忽略规则，这样git就不会管理这些文件.

更多关于.gitignore文件的用法请参考官方文档.

以下是最简单的.gitignore文件:

# 忽略a.txt文件
a.txt
# 忽略所有.mp4后缀的文件
*.so
# 忽略build文件夹里的所有文件
build/

💡: #开头的行是注释, 可以去掉

提交

把暂存区的修改和提交信息封装为一个commit. 类似将快递盒贴上封条，并贴上相关便条.

快速提交

如果第一次提交，见配置用户名和邮箱

git commit -m "<message>"

可视化提交

这会在当前终端用$EDITOR¹打开一个临时文件来输入提交信息.

git commit

配置用户名和邮箱

如果你从未配置过用户名和邮箱, git 会不知道你是谁，会在提交时报错, 并提示你像如下进行配置.

类似于封装快递时，要求你填上寄件人和你的联系地址.

git config --global user.name "<name>"
git config --global user.email "<email>"

配置好后请再次提交

拉取

从远程仓库拉取最新代码和变更到本地.

git pull

推送

进行代码推送前，请先进行查看状态和拉取操作, 确保在正确的分支并先同步了别人的更改.

推送到默认上游分支

把本地的提交推送到默认上游分支.

如果你从未设置过默认上游分支，请换用推送时设置默认上游分支

git push

详细推送到指定分支

有时你的仓库可能不只一个remote仓库, 或者你没有设置默认上游分支. 你可以指定推送到哪个远程仓库和分支.

如果你不指定<remote>和<branch>，那默认是提交到默认上游分支， 就像推送到默认上游仓库

git push <remote> <branch>

推送时设置默认上游分支

这一般发生在首次推送代码时， 这会提交代码到指定远程仓库的指定分支，并同时设置该分支默认上游分支.

git push -u <remote> <branch>

设置后，当前分支会记住你上一次推送的位置， 下次你只需要使用git push就可以推送到默认上游分支.

1. $EDITOR 是当前环境变量指定的文本编辑器, 通常是 nano 或 vi . ↩

流程

完整的考核的流程为申请考核，本地完成考核和提交考核。

申请

为什么考核要申请

这是为了方便追踪每个人的考核进度，提高考核效率， 也帮助每个人提前熟悉分工明确的开发流程。

申请考核

查找考核issue

要完成一个考核，你需要在考核文档仓库的Issue里找到对应的考核Issue,

在这个issue中的介绍有一个链接，指向考核几的仓库

创建问题

• 尝试创建问题

点击New issue按钮，再选择申请考核

• 填写问题标题和姓名

根据模板提示填写即可

最后点击Create

加入MA的Github组织

等待管理员创建分支

等待管理员为你创建开发分支，管理员创建后，一般会在你的Issue里留言，并留下创建的分支的链接，并且Github会通过邮件自动通知你，管理员的留言如下图：

进入分支，完成考核

进入这个branch，在这里完成你的考核

上传代码

如何使用Git上传代码，请参考Git 工作流

关闭问题，完成考核

完成后，先进入问题，然后在Add a comment中写下你的考核完成情况，例如完成了什么

然后点击Close with comment，即关闭问题。

编程语言

ma所用的编程语言

c++ –>自瞄

rust –>导航

python –>雷达&&脚本

路线

c++(c) –> rust/python

c++

代码规范

为什么要代码规范

• 提高可读性，降低理解成本

• 便于维护和迭代

• 减少团队协作冲突

• 降低错误风险

怎么规范代码

交爷给了我们一份《C++编码规范》，可以作为参考：
上海交龙的C++编码规范

上海交龙的超多教程： 上海交龙的视觉教程

核心知识

暂时会前两个就行了

• 基本语法

与C语言相同

• 类与对象

• 多线程与并发编程

• 学习资源

c++官网

入门：b站上有很多教程(大差不差)

可以看这个（详细）（捡自己感兴趣的看） c++参考手册

有兴趣的可以了解c++的新特性

cmake管理c++项目

CMake 官方文档

CMake 入门

Rust

入门： rust圣经

Python

入门：

b站有很多教程(大差不差)

markdown

markdown

什么是markdown？

markdown 是一种编写文档的语言

十分钟学会 Markdown: 学习 markdown

linux

ubuntu

1. 安装ubuntu

串口无法识别为tty设备

见brltty

ubuntu 安装指南

这里会介绍ubuntu的基本安装的步骤，

对于不同的电脑会有不同的细节（问题），也会有相应的解决方案汇总

推荐双系统安装

双系统安装

1. 下载 Ubuntu 镜像

首先：我们需要一个U盘（8GB足够） 下载地址
官网

推荐镜像下载 清华镜像 注：如何找镜像： 游览器直接搜，如 清华大学开源软件镜像站
进入镜像站后直接搜, 如ubuntu-releases

ubuntu镜像在官网也有链接

2. 制作启动盘

需要一个烧录软件，推荐使用下面这个：

balenaEtcher官网

其他烧录软件： 待补充

3. 划分空闲磁盘分区

a.在 Windows 系统中，右键点击 “此电脑”，选择 “管理”，进入 “磁盘管理”；​

b.找到有空闲空间的磁盘（如 D 盘），右键点击该磁盘，选择 “压缩卷”，输入压缩空间大小（建议 100GB 以上，单位为 MB，1GB=1024MB，如 100GB 需输入 102400）；​

c.压缩完成后，会出现一块 “未分配” 空间，无需进一步操作，关闭磁盘管理。​

4. 进入bios系统

a. 重启电脑，在开机画面出现时，快速按下启动快捷键（不同品牌电脑快捷键不同，常见的有 F2、F10、F12、Del，开机画面通常会提示）,进入bios系统（每个人的电脑不同，bios系统界面也不同）

b. 打开bios高级设置界面，关闭安全启动（Secure boot）

c. 把电脑显卡模式改为混合模式或者或内显模式(因为装系统过程没有显卡驱动，会直接黑屏)

d. 更改优先启动，把原本的Window改为系统盘usb启动

5. 安装ubuntu系统

a.在U盘界面选择try or install ubuntu

b.

后续部分默认继续即可

选择你上面分出来的空区域，一般是空闲，看旁边的大小来判断,点击“+”号进行分区

c.★EFI系统分区

EFI分区通常位于磁盘的前部，因此我们需要第一创建。并且刚刚我们通过BIOS中的Boot得知，使用的是UEFI引导模式，因此创建EFI分区是必须的！大小通常设置为100MB到500MB即可

d.★ 根分区

根分区是整个文件系统的根目录，所有的系统文件和用户数据都在这个文件系统下，因此主要的空间应该留给根分区.（主分区）

e.进入ubuntu系统:

在引导项选择第一个是ubuntu系统，第三个是windows系统，第二个是恢复ubuntu系统，第四个是bios系统，

6. 安装显卡驱动（可选，目前除5060显卡均可成功安装）

a. 进入ubuntu系统，打开终端，输入查看是否有显卡驱动

sudo apt update

sudo nvidia-smi

b. 如果没有的话，就输入

ubuntu-drivers devices

c.找到带recommended后缀的显卡驱动并且复制，输入

sudo apt install(推荐的显卡驱动)

sudo reboot 

Ubuntu Environment

1. 目录

• 1.环境配置的一些经验
• 2.自瞄环境配置

2.环境配置的一些经验

1.ubuntu中c++环境配置遇到的坑 90% 是各个库版本不兼容

2.如何安装c++库

如果你学过cmake，就应该知道c++项目都是(应该80%以上的吧)通过cmake编译和管理的。如果你不了解cmake，可以参考这里。

所以，如果你想安装c++库：

1.源码安装：

思路和你编译运行c++程序一样，只是要先下载源码

一般来说，c++库都有github仓库，你可以直接下载源码，然后编译安装。

git clone '库的github地址'

例子：

git clone https://github.com/opencv/opencv.git

进入源码目录，执行

mkdir build
cd build
cmake .. 
make -j8 # 编译，-j8表示使用8个线程并行编译
sudo make install # 安装到系统目录

2.包管理器安装：

如果你使用的是Ubuntu，你可以直接使用apt-get安装。

sudo apt-get install '库在apt-get中的名字'

注：apt-get安装的库一般都比较老，版本比较低，如果想用最新版本，可以参考源码安装。
名字不知道的话，可以问ai

例子：

sudo apt-get install libopencv-dev

3. 如何跑开源项目

一般来说，开源项目都有详细的安装说明，你可以参考。 在开源项目(github上)的readme中，一般都会有编译和运行的命令。

思考： 在跑开源项目的时候，以及下面配置自瞄环境的时候 有各种不同的命令, 他们的作用是什么？，有其他方法吗？，相比于其他方法有什么优势(区别)

3.自瞄环境配置

下面是老学长的环境配置（一点史，请见谅），可以参考：
老学长的环境配置

brltty

brltty 是一个用于盲文设备的屏幕阅读器

它会自动识别某些串口设备, 占用其作为屏幕阅读器,

从而阻止其被识别为普通tty设备.

删除并停止 brltty

sudo apt purge brltty

MA 导航

概述

导航是指在一个环境中，从一个点（称为起点）到另一个点（称为终点）的路径规划。 在实际应用中，导航系统需要根据环境的复杂性、障碍物、地形等因素，制定出一条安全、有效、舒适的路径。

1. 在哪里

建图，定位，感知

1. 去哪里

决策

1. 如何到达

路径规划，轨迹优化，避障，路径跟踪

• 建图定位感知
• 路径规划
• 决策

建图定位感知

路径规划

总体思路

目录

• 全局规划
• 路径优化
• 局部规划

决策

视觉

1.硬件IO

2.MiniPC相关部分

3.自瞄算法

硬件IO通信相关问题

11.10 串口无权限问题

[2025-11-10 20:33:16.928] [error] [Gimbal] Failed to open serial: IO Exception (13): Permission denied, file /home/ma/code/MA_2026/io/serial/src/impl/unix.cc, line 151.

解决方案

1.列出所有设备

ls -l /dev/ttyUSB* /dev/ttyACM*

2.给予权限

sudo usermod -aG dialout ma

11.12 电控遇到无故限位以及抖动问题

视觉发送的数据无异常

1.分电板信号传输有问题，底盘电机控制can信号若有若无

2.限位问题来源于-180度到180度的切换导致甩头不跟随

3.11.15补充，电控云台抖动，多路can集中在一路，FiFo容量过多，优先级没有设定

11.30 串口通信问题

1.在雷神上读取串口数据稳定正常无crc报错，在我y7000p电脑上一半数据能正确读取，一半报crc错误（1.27已解决，问题来源1.串口硬件信号传输不稳定，2.头帧与中间数据重复导致读取错误）

小电脑相关问题

11.10 雷神卡顿问题

雷神新装的电脑遇到跑代码明显掉帧问题，降低电脑分辨率帧率明显提神，初步判断是网口线输出远程屏幕的数据严重占用电脑性能

11.12 远程桌面连接时会断连

问题描述

1.首先RDP服务器断连接，但SSH服务器没问题，重启小电脑可以连接

2.RDP和SSH均无法连接，重启小电脑也不行，本机电脑重启可解决

问题原因

1.初步判断是由于云台抖动导致网线松了，插拔之后可连接SSH，但RDP服务器无法连接

解决方案(无用)

sudo apt update
sudo apt install xrdp -y
sudo systemctl enable xrdp

暂无

此文档为自瞄算法相关文档（开源来源于同济25自瞄开源）

代码结构

sp_vision_25
├── assets         // 包含demo素材、网络权重等
│   └── ...
├── calibration    // 标定相关程序
│   ├── calibrate_camera.cpp             // 相机内参标定程序
│   ├── calibrate_handeye.cpp            // 手眼标定程序
│   ├── calibrate_robotworld_handeye.cpp // 手眼标定程序（同时计算标定板位置）
│   └── capture.cpp                      // 相机标定数据采集程序
├── CMakeLists.txt // CMake配置文件
├── configs        // 每台机器人的YAML配置文件
│   └── ...
├── io             // 硬件抽象层，见3.4软件架构
│   └── ...
├── src            // 应用层，见3.4软件架构
│   └── ...
├── tasks          // 功能层，见3.4软件架构
│   ├── auto_aim       // 自瞄相关算法实现
│   │   └── ...
│   ├── auto_buff      // 打符相关算法实现
│   │   └── ...
│   └── omniperception // 全向感知相关算法实现
│   │   └── ...
├── tests
│   ├── auto_aim_test.cpp         // 自瞄录制视频测试程序
│   ├── auto_buff_test.cpp        // 打符录制视频测试程序
│   ├── camera_detect_test.cpp    // 识别器测试程序（工业相机）
│   ├── camera_test.cpp           // 相机测试程序
│   ├── camera_thread_test.cpp    // 相机线程测试程序
│   ├── cboard_test.cpp           // C板测试程序
│   ├── detector_video_test.cpp   // 识别器测试程序（视频）
│   ├── dm_test.cpp               // 达妙IMU测试程序
│   ├── fire_test.cpp             // 开火测试程序
│   ├── gimbal_response_test.cpp  // 云台响应测试程序
│   ├── gimbal_test.cpp           // 云台通信测试程序
│   ├── handeye_test.cpp          // 手眼标定测试程序
│   ├── minimum_vision_system.cpp // 最小视觉系统测试程序
│   ├── multi_usbcamera_test.cpp  // 多USB摄像头测试程序
│   ├── planner_test_offline.cpp  // 规划器测试程序（离线）
│   ├── planner_test.cpp          // 规划器测试程序（实车）
│   ├── publish_test.cpp          // ROS发送测试程序
│   ├── subscribe_test.cpp        // ROS接收测试程序
│   ├── topic_loop_test.cpp       // ROS话题循环测试程序
│   ├── usbcamera_detect_test.cpp // 识别器测试程序（USB相机）
│   ├── usbcamera_test.cpp        // USB相机测试程序
│   └── ...
└── tools          // 工具层，见3.4软件架构
    ├── crc.hpp                    // CRC校验
    ├── exiter.hpp                 // 退出检测
    ├── extended_kalman_filter.hpp // 扩展卡尔曼滤波器
    ├── img_tools.hpp              // 图像处理工具
    ├── logger.hpp                 // 日志记录器
    ├── math_tools.hpp             // 数学工具
    ├── plotter.hpp                // 曲线图绘制工具
    ├── recorder.hpp               // 视频录制器
    ├── thread_safe_queue.hpp      // 线程安全队列
    ├── trajectory.hpp             // 弹道解算
    ├── yaml.hpp                   // YAML配置文件解析器
    └── ...

1.相关测试程序

1.Cboard_cboard_test硬件通信测试程序（后续会改名字）

1.Can口通信测试，需在Cboard.cpp中默认初始化SocketCAN的实例，在yaml文件配置canid

2.串口通信测试

2.标定

3.相机连接

4.硬件通信

5.自瞄代码运行

6.调试问题

10.26

1.

修复无开火指令问题：上位机给下位机发的是角度，获取的云台姿态来源于陀螺仪，是弧度，修改后可正常发送

11-12月

1.

新增前哨站算法，修改卡尔曼滤波部分，利用矩阵的l和h两个维度作为前哨站两个不同高低差，雅可比矩阵增加dz_dl,dz_dh,扩展卡尔曼会自适应不同高低差变化

2.

删除同济冗余代码，ROS2,多线程，多余测试等，修复一些warning警告问题，如数据类型不统一等

3.

增加哨兵脱锁算法，目前置于Cboard.cpp中，当锁定一帧目标时脱锁会延迟3秒后再进入扫描模式

4.

修改crc高地位，适应电控校验数据

5.

问题：目前已测试GPU推理加速在Y7000p中，效果不如cpu，暂未查询到原因，准备更改OPENVINIO为ORT

6.

使用SSH连接远程终端时，跑无debug程序终止原因是因为在yolo识别部分有imshow，目前已注释

2026.1

1.

由于受灯光影响，网络模型会误识别强光部分为目标，只能降低曝光或者设置多次识别

2026完整形态与联盟赛

1.电脑的降压模块不稳定，无法发挥电脑的最高性能导致代码帧率较低，与电控降压有关

2.openvino可安装25版本或者24版本，但安装新版本需要修改CMakeLists，如果没修改会报找不到libopnvino的错误

3.修改了识别友军的bug，统一了io，armor，main，main_debug的装甲板颜色数据类型，误识别友军的原因是因为使用了yolov5模型，使用v8可以解决

4.修改CMakeLists的编译模式，Debug改为Realse，提高代码性能

5.联盟赛对于远距离目标弹道偏下，对于近距离目标快速小陀螺无开火建议，目前未解决

6.对于新前哨战，除了需要修改Target部分，还需要在Tracker模块中给步兵整车状态的Q矩阵的l和h维度给予参数，否则无效

7.同济代码的选板目前有跳板问题导致yaw角度突变严重，目前未解决，发现观测的整车旋转角速度不稳定，有2rad的波动，不准确，目前未解决

8.24版本的ubuntu有远程连接不上的问题，换22版本可以解决，22版本RDP连接秘密重启会改变，修改电脑对于登陆的密钥为空可以解决，记得不是RDP秘密为空

9.电脑的USB2.0口连接相机会导致读取相机帧率很低，导致给下位机发送延迟高达40ms，改用USB3.0口可以解决