# 环境搭建流程

本文说明如何从公司 GitLab 拉起当前飞控固件仓库，并达到可以一起改代码、编译、烧录的状态。

当前仓库是 **PX4 v1.17.0 的日常开发快照**，不是官方完整历史。目标飞控是 **CUAV 7-Nano**，默认固件目标是 `cuav_7-nano_minimal_vtol`。该目标已关闭以太网和飞控上的 ROS 2 / DDS。USB 和 TELEM 数传不受影响。

官方英文/中文手册仍在 `docs/en`、`docs/zh`。项目自己的说明在 `docs/project`。

## 1. 机器要求

| 项 | 要求 |
|---|---|
| 系统 | Ubuntu 22.04 或 24.04，x86_64 |
| 磁盘 | 建议预留 20 GB 以上 |
| 权限 | 能 `sudo` 装软件包 |
| 网络 | 能访问 `gitlab.jiagutech.com`（SSH 端口 **22722**） |

不要对 GitLab 走代理。公司 GitLab 在国内，走代理会连错或超时。

## 2. 配置 SSH

本机生成密钥（已有 `~/.ssh/id_ed25519` 可跳过）：

```sh
ssh-keygen -t ed25519 -C "你的名字"
cat ~/.ssh/id_ed25519.pub
```

把公钥加到 Gitea：**Settings → SSH / GPG Keys**。

写入 `~/.ssh/config`：

```text
Host gitlab.jiagutech.com
  HostName gitlab.jiagutech.com
  User git
  Port 22722
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
```

```sh
chmod 600 ~/.ssh/config
```

测试：

```sh
ssh -T git@gitlab.jiagutech.com
```

成功时会看到类似：

```text
Hi there, <用户名>! You've successfully authenticated ... but Gitea does not provide shell access.
```

`does not provide shell access` 是正常的，表示密钥已经认到。

## 3. 克隆仓库

```sh
mkdir -p ~/work
cd ~/work
git clone -b 7-nano-minimal-vtol \
  ssh://git@gitlab.jiagutech.com:22722/caixiang/PX4-Autopilot.git
cd PX4-Autopilot
git log --oneline -5
```

当前日常分支是 `7-nano-minimal-vtol`。NuttX、MAVLink 等源码已经打进这个仓库，**不需要**再执行 `git submodule update`。

不要用 `http://` 地址做第一次完整推送。HTTP 会被 Nginx 的上传大小限制拦住（413）。日常拉代码、推小改动用 SSH。

## 4. 安装编译工具链

在仓库根目录执行官方脚本，装 NuttX / ARM 交叉编译器：

```sh
cd ~/work/PX4-Autopilot
bash Tools/setup/ubuntu.sh --no-sim-tools
```

`--no-sim-tools` 表示不装 Gazebo 等仿真依赖。如果也要在本机跑 SITL，去掉这个参数。

装完重新打开终端，或：

```sh
source ~/.profile
arm-none-eabi-gcc --version
```

应能看到 `arm-none-eabi-gcc`。

## 5. 编译和烧录

USB 连接 CUAV 7-Nano 后：

```sh
cd ~/work/PX4-Autopilot
make cuav_7-nano_minimal_vtol
make cuav_7-nano_minimal_vtol upload
```

固件产物：

```text
build/cuav_7-nano_minimal_vtol/cuav_7-nano_minimal_vtol.px4
```

也可以在 QGroundControl 里选这个 `.px4` 文件刷写。

编译成功后用 QGC 连上飞控，**Analyze → MAVLink Console** 检查：

```sh
ver all
free
```

硬件架构应是 `CUAV_7_NANO`。

不要编 `cuav_7-nano_default`，除非你明确需要以太网和飞控 ROS 2。日常统一用 `minimal_vtol`。

## 6. 本仓库相对官方的差异

| 项 | 本仓库 |
|---|---|
| 基础版本 | PX4 v1.17.0 |
| 日常分支 | `7-nano-minimal-vtol` |
| 以太网 / NuttX 网络栈 | 关闭 |
| 飞控 `UXRCE_DDS_CLIENT` | 关闭 |
| `netman` | 未编入 |
| 空速计 | I2C MS4525DO，需设 `SENS_EN_MS4525DO=1` |
| 历史 | 只有日常快照和之后的提交，没有官方全部 Git 历史 |

板级改动主要在：

```text
boards/cuav/7-nano/minimal_vtol.px4board
boards/cuav/7-nano/nuttx-config/minimal_vtol/defconfig
boards/cuav/7-nano/init/rc.board_defaults
boards/cuav/7-nano/init/rc.board_sensors
```

## 7. 日常开发约定

```sh
git switch 7-nano-minimal-vtol
git pull --ff-only

# 改代码、编译确认
make cuav_7-nano_minimal_vtol

git add <具体文件>
git status
git commit -m "简要说明改了什么"
git push
```

约定：

1. 不要把 `build/`、工具链压缩包、`.vscode/` 提交上去。
2. 不要把官方 `docs/en`、`docs/zh` 的大范围格式化混进项目文档提交。
3. 提交说明写清机型或模块，例如 `7-nano: enable MS4525 airspeed`。
4. 需要官方某次提交做对照时，到 [PX4 官方仓库](https://github.com/PX4/PX4-Autopilot) 查看 `v1.17.0`，不要在本仓库里重拉全部历史。

## 8. 实机常用检查

空速计（I2C，地址 `0x28`，总线 1）：

```sh
i2cdetect -b 1
param show SENS_EN_MS4525DO
ms4525do status
listener differential_pressure
```

若驱动未启动：

```sh
param set SENS_EN_MS4525DO 1
param set SYS_HAS_NUM_ASPD 1
param set ASPD_PRIMARY 1
param set UAVCAN_ENABLE 0
param save
reboot
```

GPS 插在物理 GPS2 时，见 [CUAV 7-Nano GPS2 配置与检查](CUAV_7-Nano_GPS2配置与检查.md)。

## 9. 常见问题

**SSH 超时或一直无响应**  
确认 `~/.ssh/config` 里端口是 `22722`，不要用默认 22。不要给 `gitlab.jiagutech.com` 配 HTTP/SOCKS 代理。

**HTTPS 推送报 413**  
这是 Nginx 上传大小限制。请用 SSH 推送，不要用 `http://` 传整仓。

**`git push` 终端不弹出用户名密码**  
SSH 不需要密码。如果误用了 HTTPS，先检查是否被 VS Code 的 `GIT_ASKPASS` 或 `GIT_TERMINAL_PROMPT=0` 拦掉。日常请用 SSH。

**编译找不到 `arm-none-eabi-gcc`**  
重新执行 `bash Tools/setup/ubuntu.sh --no-sim-tools`，并新开一个终端。

**QGC 连上但没有以太网 MAVLink**  
这是预期行为。`minimal_vtol` 固件不包含网络栈，地面站走 USB 或数传。

**想重新打开以太网或飞控 ROS 2**  
需要改 `boards/cuav/7-nano/minimal_vtol.px4board`，并恢复带网络的 NuttX `defconfig`。改之前先和当前维护者确认。

## 10. 建议阅读顺序

1. 本文
2. [PX4 源码学习路线](PX4源码学习路线.md)
3. [PX4 rcS 启动流程与实机准备](PX4_rcS启动流程与实机准备.md)
4. 按任务再看 GPS、电机编号、NuttX、EKF2 或 ULog 文档