2、环境搭建：BM1688开发板、SDK安装、交叉编译工具链与推理运行时配置

BM1688是算能科技推出的第二代边缘计算SoC，集成8核ARM Cortex-A53 CPU、23.6 TOPS算力的TPU（支持INT8/FP16/BF16）以及独立VPU和JPEG编解码单元。在工业视觉场景中，它常被部署在产线工位旁，承担缺陷检测、OCR识别、目标定位等实时推理任务。本章围绕“从裸板到可运行推理程序”的完整链路展开，涵盖开发板硬件认知、SDK获取与安装、交叉编译工具链配置、推理运行时（BMRuntime/BMNN）初始化，以及针对工业现场的部署验证方法。环境搭建的成败直接决定后续算法移植和性能调优的效率，因此本章内容强调“可复现、可排障、可验证”。

上图展示了BM1688环境搭建的整体链路：左侧为开发板硬件资源，中间为主机开发环境与SDK组件，右侧为交叉编译和推理运行时配置，底部为部署验证闭环。在实际工业项目中，环境搭建不是一次性动作，而是随着模型迭代、SDK升级、产线需求变化而持续调整的过程。下面按操作顺序逐一展开。

2.1 开发板硬件认知与启动准备

BM1688开发板通常以核心板+底板形式提供，核心板集成SoC、DDR和eMMC，底板引出丰富接口。在工业视觉场景中，最常使用的接口包括：MIPI-CSI（接工业相机）、千兆以太网（接PLC或MES）、USB3.0（接USB相机或U盘）、GPIO（触发信号）、RS485/RS232（接传感器）。首次上电前，务必确认电源适配器规格（通常为12V/3A或24V/2A，具体以板卡丝印为准），并检查底板上的拨码开关是否处于正确的启动模式（eMMC启动、SD卡启动或烧录模式）。

开发板启动后，通过串口（默认波特率115200）或SSH登录系统。出厂系统通常预装Linux 5.10内核，用户名为root，默认密码为linaro或root（以出厂说明为准）。登录后执行cat /proc/cpuinfo确认8核A53识别正常，执行ls /dev/bm*查看TPU设备节点（/dev/bmdev和/dev/bm-soctpux）。若设备节点缺失，说明内核驱动未加载或固件异常。

对于产线部署，建议将开发板设置为静态IP，并关闭不必要的系统服务（如蓝牙、WiFi热点），以减少资源占用和潜在安全风险。同时，将系统时间同步到NTP服务器，确保日志时间戳准确。

2.2 SDK获取与安装

BM1688的SDK分为两个主要部分：libsophon（运行库，包括bmruntime、bmcv、bmvideo等）和tpu-mlir（模型转换工具链，用于将PyTorch/ONNX模型转换为.bmodel格式）。SDK版本与芯片型号严格对应，BM1688使用BMNNSDK3或BMNNSDK4系列，不同小版本之间可能存在API差异，建议固定版本并记录校验值。

安装流程如下：

1. 从算能官网或官方ftp下载对应版本的SDK压缩包（如libsophon_3.7.0_aarch64.tar.gz）。
2. 将压缩包拷贝到开发板（通过scp或U盘），解压到/opt/sophon目录。
3. 执行source /opt/sophon/libsophon-current/env.sh设置环境变量。
4. 在主机端安装tpu-mlir：解压后执行source scripts/envsetup.sh。
5. 验证安装：开发板上执行bmrt --version，主机上执行model_transform --version。

# 开发板端安装libsophon
tar -xzf libsophon_3.7.0_aarch64.tar.gz
cd libsophon_3.7.0_aarch64
sudo dpkg -i *.deb   # 或使用install.sh脚本
source /opt/sophon/libsophon-current/env.sh

# 主机端安装tpu-mlir
tar -xzf tpu-mlir_3.7.0.tar.gz
cd tpu-mlir_3.7.0
source scripts/envsetup.sh

SDK安装过程中最常见的错误是依赖库缺失（如libssl.so.1.1）或版本冲突。Ubuntu 22.04默认OpenSSL版本为3.0，而部分SDK组件依赖1.1版本，此时需要手动安装兼容库：sudo apt install libssl1.1。另外，tpu-mlir依赖Python 3.8~3.10，若主机Python版本过高，建议使用conda创建独立环境。

2.3 交叉编译工具链配置

BM1688的应用程序通常在x86主机上编写和编译，然后通过交叉编译生成aarch64架构的可执行文件，再传输到开发板运行。交叉编译工具链使用aarch64-linux-gnu-gcc/g++，版本要求为7.5或更高。在Ubuntu主机上安装：

sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
# 验证安装
aarch64-linux-gnu-gcc --version

对于CMake项目，需要编写工具链文件（toolchain.cmake），指定编译器路径和系统根目录（sysroot）。sysroot指向开发板的根文件系统，包含目标平台的库文件和头文件。获取sysroot有两种方式：一是从开发板拷贝/lib、/usr/lib等目录；二是使用SDK自带的sysroot包。

# toolchain.cmake 示例
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
set(CMAKE_SYSROOT /opt/sophon/sysroot)
set(CMAKE_FIND_ROOT_PATH /opt/sophon/sysroot)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

交叉编译时，链接器需要找到libsophon的库文件。在CMakeLists.txt中通过link_directories(/opt/sophon/libsophon-current/lib)指定库路径，并通过target_link_libraries链接bmruntime、bmcv、bmvideo等库。注意：不要将主机端的libsophon库直接拷贝到开发板，因为主机库是x86架构，必须使用开发板对应的aarch64版本。

2.4 推理运行时配置与验证

推理运行时是程序与TPU交互的桥梁。BM1688支持两种运行时模式：BMRuntime（底层C API）和BMNN（C++封装，基于BMRuntime提供更友好的接口）。对于工业视觉应用，推荐使用BMNN，因为它内置了输入输出张量管理、内存池和预处理流水线。

运行时配置的核心步骤包括：

1. 初始化上下文：bmrt_create()创建运行时句柄，指定设备ID（多卡时区分）。
2. 加载模型：bmrt_load_model()从文件系统加载.bmodel文件，模型文件包含编译后的TPU指令和权重。
3. 获取模型信息：通过bmrt_get_network_names()获取网络名称，bmrt_get_network_info()获取输入输出形状、数据类型。
4. 分配内存：使用bm_malloc_device_mem()在TPU上分配输入输出缓冲区，或使用bmrt_alloc_tensor()自动管理。
5. 执行推理：bmrt_launch_tensor()异步提交任务，bmrt_sync()等待完成。

// BMNN 初始化示例
bmcv_handle_t bmcv_handle;
bmrt_handle_t bmrt_handle;
bm_handle_t bm_handle;
bm_dev_request(&bm_handle, 0);  // 请求设备0
bmcv_create(&bmcv_handle, bm_handle);
bmrt_create(&bmrt_handle, bm_handle);
const char* model_path = "./yolov5s.bmodel";
bmrt_load_model(bmrt_handle, model_path);
// 获取网络信息
const char** net_names = NULL;
bmrt_get_network_names(bmrt_handle, &net_names);
bm_net_info_t* net_info = bmrt_get_network_info(bmrt_handle, net_names[0]);
printf("Input shape: %d x %d x %d\n", net_info->stages[0].input_shapes[0].dims[2],
       net_info->stages[0].input_shapes[0].dims[1], net_info->stages[0].input_shapes[0].dims[0]);

运行时配置完成后，必须进行端到端验证。验证内容包括：模型加载时间、单次推理延迟、吞吐量（FPS）、内存占用、CPU占用率。使用bmrt_test工具可以快速测试模型性能：

# 在开发板上执行
bmrt_test --bmodel yolov5s.bmodel --input input.bin --loop 100
# 输出示例
# [INFO] Load model time: 0.32s
# [INFO] Inference time: 12.5ms (avg)
# [INFO] FPS: 80.0

若推理结果与预期不符，首先检查输入数据预处理是否正确（归一化、通道顺序、尺寸），其次检查模型转换时是否使用了错误的量化参数。工业现场常见问题是相机采集的图像为BGR格式，而模型训练时使用RGB，导致检测精度下降。

2.5 常见误区与复盘

在环境搭建过程中，工程师常犯以下错误：

• SDK版本不匹配：将BM1684的SDK用于BM1688，导致设备节点无法识别或API调用崩溃。务必确认SDK包名包含bm1688或bm168x系列。
• 交叉编译时链接了主机库：编译通过但运行时提示cannot open shared object file。检查ldd输出，确保所有依赖库都是aarch64版本。
• 忽略环境变量：每次新开终端都需要重新source环境脚本，建议写入~/.bashrc。
• 模型文件路径错误：开发板上的工作目录与主机不同，使用路径或相对路径时需谨慎。

环境搭建的最终目标是建立一套可重复、可回滚、可监控的部署流程。建议在项目初期就编写自动化部署脚本（如Ansible或Shell脚本），将SDK安装、环境变量配置、依赖库拷贝、模型文件同步等操作固化。这样当多台设备需要部署时，可以快速复制环境，减少人为错误。

此外，工业现场的散热和供电稳定性直接影响TPU性能。BM1688在满负载运行时功耗约15W，若散热不良会导致芯片降频，推理延迟增加30%以上。建议在部署时使用主动散热风扇，并在程序中监控芯片温度（cat /sys/class/thermal/thermal_zone0/temp），当温度超过85°C时触发告警或降低推理频率。

最后，记录环境信息是良好习惯。在项目文档中记录SDK版本、内核版本、编译工具链版本、模型转换参数、依赖库列表，以及每台设备的MAC地址和IP分配。这些信息在后续故障排查和系统升级时至关重要。