347 lines
12 KiB
Markdown
347 lines
12 KiB
Markdown
# Avaota F1 开发与集成
|
||
|
||
> 面向仓库根目录的总览文档，整合 Day1–Day9 日志、任务清单与完成总结。
|
||
|
||
---
|
||
|
||
## 1. 项目简介
|
||
|
||
本项目面向 **Avaota F1 AI 机器人**，基于 **全志 V821 / 32-bit RISC‑V** SoC，目标是在 Tina Linux 固件上实现一套「可量产」的机器人终端固件，集成：
|
||
|
||
- 音频采集（板载模拟麦克风）与播放（I2S + MAX98357A）
|
||
- IMU 六轴姿态传感（ICM‑42688‑P）
|
||
- GC2083 MIPI 摄像头 JPEG 图像采集
|
||
- UDP / HTTP / WebSocket 网络通讯
|
||
- 多线程主程序与静态链接交叉编译流程
|
||
|
||
文档与代码组织按「Day1–Day9 开发日志 + 任务清单 + 完成总结」推进，可作为以后移植到其他 Tina Linux / 全志平台的模板工程。
|
||
|
||
目前对话的位置是本地Windows 11系统的主机，用于开发的环境是局域网中的Ubuntu服务器。
|
||
|
||
---
|
||
|
||
## 2. 硬件与开发环境
|
||
|
||
### 2.1 目标硬件（板端）
|
||
|
||
- **SoC**：全志 V821，32‑bit RISC‑V 架构
|
||
- **板载外设**
|
||
- 模拟麦克风 → 内置 Audio Codec（audiocodec）
|
||
- I2S 数字功放：MAX98357A（BCLK/LRCK/DOUT：PD12/PD13/PD15）
|
||
- 摄像头：GC2083，MIPI‑CSI2，典型输出 1280×720 @ 20fps
|
||
- IMU：ICM‑42688‑P（GPIO 模拟 SPI）
|
||
- **操作系统**：Tina Linux（基于 OpenWrt 的 Allwinner SDK）
|
||
|
||
### 2.2 主机开发环境（PC）
|
||
|
||
- **系统**：Ubuntu 24.04 LTS（同时也有 Windows + WSL 的混合开发）
|
||
- **工具链 & SDK**
|
||
- Tina SDK：`tina-v821-release`
|
||
- `/home/rongye/ProgramFiles/AvaotaF1/avaota_sdk/tina-v821-release` 这是SDK位置
|
||
- 交叉编译工具链：
|
||
- **当前使用**：`prebuilt/rootfsbuilt/riscv/nds32le-linux-musl-v5d` ⭐ **musl 工具链（与开发板兼容）**
|
||
- 编译器前缀：`riscv32-linux-musl-`
|
||
- ~~已废弃~~：`out/toolchain/nds32le-linux-glibc-v5d` (glibc 工具链，与板端 musl libc 1.2.4 不兼容)
|
||
- `/home/rongye/ProgramFiles/AvaotaF1/avaota_app_demo` 这是交叉编译的位置
|
||
- Python：通过 `python-is-python3` 或为遗留脚本装 python2 并软链到 `python`
|
||
|
||
### 2.3 开发主机准备要点（Ubuntu 24.04）
|
||
|
||
- 开启 i386 架构以兼容旧版 32 位库
|
||
- 手动安装被移除的 `libncurses5` / `libtinfo5`
|
||
- 安装 bison / flex / 交叉编译依赖，修复 `lunch` / `make` 时报错
|
||
- 注意 `make -j` 一定要限制并行度（如 `-j8`），避免 OOM
|
||
|
||
---
|
||
|
||
## 3. 仓库结构建议
|
||
|
||
实际仓库结构可按以下思路组织（示例）：
|
||
|
||
```text
|
||
.
|
||
├── ../Docs/DevLogs/ # (位于上级目录) 每日开发日志
|
||
│ ├── Day1.md … Day18.md
|
||
├── docs/ # 本地硬件/SDK文档
|
||
│ ├── 1.png … 2.png
|
||
│ ├── AvaotaF1.md
|
||
│ ├── 引脚.md
|
||
│ ├── TinaSDK-Docs/
|
||
│ ├── tina_files_clean.csv
|
||
├── ESP32S3/ # 可参考的ESP32S3固件
|
||
├── src/
|
||
│ ├── audio/ # AudioCapture / AudioPlayer
|
||
│ ├── camera/ # Camera 类 / MPP 封装
|
||
│ ├── imu/ # ICM‑42688 SPI 驱动与测试
|
||
│ ├── network/ # UDP / HTTP / WebSocket 客户端
|
||
│ ├── utils/
|
||
│ ├── main.cpp # 主程序入口（多线程集成）
|
||
│ ├── main_test.cpp # 本地硬件自检程序
|
||
│ ├── Makefile # 交叉编译配置
|
||
│ └── build_*.sh # 构建脚本（main/test/phaseX）
|
||
├── build_main.sh
|
||
├── logs.md # 编译时的日志（实时填写）
|
||
└── README.md # 本文档
|
||
```
|
||
|
||
你可以直接把 Day1–Day7、任务清单与完成总结放到 `../docs/DevLogs/` 目录，并用当前 README 作为入口索引。
|
||
|
||
---
|
||
|
||
## 4. 功能模块概览
|
||
|
||
### 4.1 音频系统
|
||
|
||
**输入：板载模拟麦克风**
|
||
|
||
- 通过 SoC 内部 **Audio Codec (audiocodec)** 采集
|
||
- ALSA 设备：`hw:audiocodec` 或 `hw:0,0`（录音推荐 `plughw:0,0`）
|
||
- 运行时配置：
|
||
- `MIC Switch` 开启
|
||
- `MIC Gain` 建议值 25（在音量与底噪之间平衡）
|
||
- `adc-vol` 与 `lineout-gain` 使用 DTS 默认值或适度调整
|
||
- 采样参数：
|
||
- 16 kHz, S16_LE, Mono
|
||
- 典型链路：
|
||
- `setup_mic.sh` → `arecord` → `/tmp/test_mic.wav` → `aplay` / 上行网络
|
||
|
||
**输出：I2S + MAX98357A**
|
||
|
||
- I2S0 接 MAX98357A，扬声器输出
|
||
- Device Tree 为每个引脚创建独立 pinctrl 节点：
|
||
- `i2s0_bclk_pin`：PD12
|
||
- `i2s0_lrck_pin`：PD13
|
||
- `i2s0_dout0_pin`：PD15
|
||
- I2S 平台设备 `&i2s0_plat` 绑定这些引脚，`status = "okay"`
|
||
- 通过 ALSA `aplay` / 自己的 `AudioPlayer` 类进行播放
|
||
|
||
### 4.2 IMU 传感器（ICM‑42688‑P）
|
||
|
||
- 最终采用 **GPIO 模拟 SPI**：
|
||
- SCLK: PD3
|
||
- MOSI: PD2
|
||
- MISO: PD4
|
||
- CS : PD5
|
||
- SPI Mode0，软件 bit‑bang，速率约 500 kHz（可按需提升）
|
||
- 主要特性：
|
||
- WHO_AM_I = 0x47 识别验证
|
||
- 加速度计：±16g，1 kHz ODR
|
||
- 陀螺仪：±2000 °/s，1 kHz ODR
|
||
- 温度通道：用于环境监控与漂移补偿
|
||
- 静止状态验证：
|
||
- 合加速度 ≈ 9.8 m/s²
|
||
- 陀螺仪接近 0 °/s
|
||
- 上层封装：
|
||
- `ICM42688` 类提供采样与单位转换
|
||
- 独立 `test_imu` 自检程序
|
||
- 在主程序中通过 UDP 周期性上报 JSON/结构体数据
|
||
|
||
### 4.3 摄像头系统（GC2083 + MPP）
|
||
|
||
- 使用 Allwinner Eyesee‑MPP 框架：SYS → VI → ISP → VENC
|
||
- 流水线：
|
||
- VI（接 MIPI 摄像头）
|
||
- ISP（自动曝光、白平衡、降噪）
|
||
- VENC（JPEG 编码）
|
||
- 关键配置：
|
||
- 分辨率：1280×720 @ 20fps（可调）
|
||
- JPEG 质量：80（在质量与码率之间折中）
|
||
- VI Buffer：5 帧
|
||
- VBV Buffer：4 MB，避免 `VBV FULL` 错误
|
||
- `Camera` 类职责：
|
||
- 完成 MPP 初始化 / 绑定 / 销毁
|
||
- 按需抓拍单帧 JPEG（用于 WebSocket 发送或本地保存）
|
||
- 提供阻塞式 `capture_frame()` 接口与重试机制
|
||
- 测试程序：
|
||
- `test_camera` 抓拍多张 JPEG 保存到 SD 卡
|
||
- 实测成功率 100%，文件大小 20–80 KB 之间，画面曝光正常
|
||
|
||
### 4.4 网络通讯
|
||
|
||
**UDP**
|
||
|
||
- 轻量 IMU 数据上报通道
|
||
- 使用 POSIX socket，静态链接，无额外依赖
|
||
- 典型用法：
|
||
- `UDPSender` 初始化目标 IP/Port
|
||
- 周期性发送 IMU/状态数据
|
||
|
||
**HTTP（libcurl 或轻量封装）**
|
||
|
||
- 主要用途：
|
||
- 从服务器拉取 TTS 音频流（如 `stream.wav`）
|
||
- 拉取配置文件或诊断信息
|
||
- 流式下载接口已预留，可边下边写入 `AudioPlayer` 播放
|
||
|
||
**WebSocket**
|
||
|
||
- 早期方案：SDK 内置 `libuwsc`（后期为规避依赖，可用自实现轻量 WS 客户端）
|
||
- 主要用途：
|
||
- 上行：摄像头 JPEG 帧、音频 PCM 片段
|
||
- 下行：控制指令 / 状态同步
|
||
- 接口设计：
|
||
- `WSClient` 负责 TCP 连接、握手、帧收发、心跳与重连
|
||
- 主线程中，每个子模块持有各自的 WSClient 实例或共享连接
|
||
|
||
---
|
||
|
||
## 5. 编译与构建流程
|
||
|
||
### 5.1 Tina SDK 环境准备（概要）
|
||
|
||
1. 解压 SDK：
|
||
```bash
|
||
mkdir -p ~/ProgramFiles/avaota_sdk
|
||
tar -xvf tina-v821-*.tar.xz -C ~/ProgramFiles/avaota_sdk
|
||
```
|
||
2. 初始化环境：
|
||
```bash
|
||
cd ~/ProgramFiles/avaota_sdk/tina-v821-release
|
||
source build/envsetup.sh
|
||
lunch # 选择 avaota_f1 / v821 相关配置
|
||
```
|
||
3. 全量编译：
|
||
```bash
|
||
make -j8
|
||
pack # 需要时打包固件
|
||
```
|
||
|
||
### 5.2 应用程序交叉编译
|
||
|
||
在 `src/` 目录中提供一个或多个构建脚本，例如：
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
set -e
|
||
|
||
SDK_ROOT=~/ProgramFiles/AvaotaF1/avaota_sdk/tina-v821-release
|
||
# ⚠️ 使用 musl 工具链（与开发板兼容）
|
||
TOOLCHAIN=${SDK_ROOT}/prebuilt/rootfsbuilt/riscv/nds32le-linux-musl-v5d/bin
|
||
|
||
export PATH=${TOOLCHAIN}:$PATH
|
||
|
||
make clean
|
||
make all -j4 # 或按目标拆分：make main / make test_audio / make test_imu
|
||
```
|
||
|
||
Makefile 要点：
|
||
|
||
- 使用 `riscv32-linux-musl-g++` 编译器（musl 工具链）
|
||
- 动态链接器：`/lib32/ld.so.1`（板端需创建符号链接：`ln -s /lib32/ilp32d/libc.so /lib32/ld.so.1`）
|
||
- 链接静态或最小依赖的动态库
|
||
- 注意链接顺序：业务库 → MPP/ISP/cedarx → `-lpthread -lrt -lm -ldl -lstdc++`
|
||
|
||
### 5.3 部署与运行
|
||
|
||
1. 将交叉编译好的可执行文件拷贝到 SD 卡：
|
||
```bash
|
||
cp avaota_client /media/$USER/SDCARD/
|
||
```
|
||
2. 板端挂载 SD 卡并复制到 `/tmp`：
|
||
```bash
|
||
mount /dev/mmcblk0p1 /mnt/extsd
|
||
cp /mnt/extsd/avaota_client /tmp/
|
||
chmod +x /tmp/avaota_client
|
||
```
|
||
3. 运行：
|
||
```bash
|
||
/tmp/avaota_client
|
||
```
|
||
|
||
> 推荐所有测试程序（`test_audio` / `test_imu` / `test_camera` / `avaota_test`）都统一走上述流程，避免执行权限与只读分区问题。
|
||
|
||
---
|
||
|
||
## 6. 主程序（集成）架构示意
|
||
|
||
主程序建议使用多线程模型，将各个模块解耦：
|
||
|
||
```cpp
|
||
// 伪代码示例
|
||
int main() {
|
||
init_logging();
|
||
init_network_config(); // 服务器 IP / 端口 / 路径等
|
||
init_signal_handler(); // Ctrl+C 安全退出
|
||
|
||
std::thread cam_thread(run_camera_loop);
|
||
std::thread mic_thread(run_audio_capture_loop);
|
||
std::thread spk_thread(run_audio_play_loop);
|
||
std::thread imu_thread(run_imu_udp_loop);
|
||
|
||
// 可选：主线程处理下行指令 / 状态机
|
||
run_main_control_loop();
|
||
|
||
// 等待退出
|
||
cam_thread.join();
|
||
mic_thread.join();
|
||
spk_thread.join();
|
||
imu_thread.join();
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
每个线程内部：
|
||
|
||
- 初始化各自的硬件和网络客户端
|
||
- 进入循环：
|
||
- 采集 → 编码（可选） → 通过 UDP/WS 发送
|
||
- 或从 HTTP/WS 接收 → 解码（可选） → 播放/控制硬件
|
||
- 捕获异常并尝试重连 / 恢复，必要时上报主线程
|
||
|
||
---
|
||
|
||
## 7. 日志与文档索引
|
||
|
||
可以在 README 中给出所有开发日志与计划文档的入口，方便回溯：
|
||
|
||
- `../Docs/DevLogs/Day1.md`：SDK 编译与 32 位环境踩坑
|
||
- `../Docs/DevLogs/Day2.md`：UDP 通信、网络库编译、libuwsc / libcurl 准备
|
||
- `../Docs/DevLogs/Day3.md`：音频采集 & 播放模块（ALSA + I2S）
|
||
- `../Docs/DevLogs/Day4.md`：模拟麦克风配置 + IMU SPI 驱动与验证
|
||
- `../Docs/DevLogs/Day5.md`：GC2083 摄像头 MPP 集成与 JPEG 捕获
|
||
- `../Docs/DevLogs/Day6.md`：硬件全功能验证、本地测试程序、网络库诊断
|
||
- `../Docs/DevLogs/Day7.md`：交叉编译 Makefile 收敛、工具链配置
|
||
- `../Docs/DevLogs/Day8.md`：整体编译成功、Cedar 库链接完成
|
||
- `../Docs/DevLogs/Day9.md`：⭐ **musl 工具链修复 + 板上测试通过**
|
||
- `../Docs/task_complete.md`：完整任务清单与进度条（97% 完成）
|
||
- `../Docs/implementation_plan_complete.md`：实现计划 & 各阶段目标拆解
|
||
|
||
---
|
||
|
||
## 8. 任务完成度与后续工作
|
||
|
||
### 8.1 当前完成度（参考任务清单与总结）
|
||
|
||
- SDK/工具链/固件：✅
|
||
- musl 工具链修复：✅ **（Day 9 关键突破）**
|
||
- 音频采集 & 播放：✅
|
||
- IMU 采集：✅ **（板上测试通过）**
|
||
- 摄像头采集：✅ **（板上测试通过）**
|
||
- UDP / HTTP / WebSocket 基础：✅（库与客户端实现已完成）
|
||
- WiFi 网络配置：✅ **（192.168.110.132）**
|
||
- 板端硬件测试：✅ **（所有模块通过）**
|
||
- 网络服务器通信测试：⏳（服务器已部署，待测试）
|
||
- 性能评估与稳定性验证：⏳（待完成）
|
||
|
||
整体项目 **97%** 完成，核心功能全部验证通过！🎉
|
||
|
||
### 8.2 建议的后续 TODO
|
||
|
||
- 将服务器 IP / 端口、音频参数、帧率等抽象为配置文件（JSON / INI）
|
||
- 丰富错误日志并加上日志轮转
|
||
- 对 WebSocket / HTTP 加入重连与指数退避策略
|
||
- 若后续量产，考虑：
|
||
- 用硬件 SPI 替换 GPIO bit‑bang
|
||
- 对功耗与休眠策略进行优化
|
||
- 引入简单看门狗机制，防止长期运行卡死
|
||
|
||
---
|
||
|
||
## 9. 如何使用本 README
|
||
|
||
- **新成员上手**：从本 README 入手，结合 `../Docs/DevLogs/DayX.md` 逐步了解每个子系统的设计与坑点。
|
||
- **以后复用到新项目**：可以直接复制「编译流程」「外设接线 + DTS 配置」「主程序多线程架构」这几部分，稍作修改即可移植到其他全志 / RISC‑V 设备。
|
||
- **代码导航入口**：按模块查找 `src/audio`, `src/imu`, `src/camera`, `src/network` 目录，结合对应的 DayX 日志阅读。
|
||
|
||
祝使用愉快 🎉，也欢迎在后续开发阶段继续补充和更新本 README。
|