基于 XiUOS 的 AI 视觉目标检测与分类系统

项目简介

本项目基于 XiUOS 实时操作系统和 Sipeed Maix-Bit (Kendryte K210) 开发板，实现了一套通用的 AI 视觉推理框架。支持 YOLOv2 目标检测和轻量级图像分类两种任务模式，通过 JSON 配置文件实现模型的零重编译切换。

核心特性

• JSON 驱动模型切换：更换检测/分类任务无需重新编译固件，只需替换 .kmodel 和 .json 文件
• KPU 硬件加速：利用 K210 内置的神经网络加速器（KPU），实现实时推理
• 智能休眠/唤醒：基于运动检测的省电机制，休眠期间自动关闭 KPU 推理和 LCD 显示
• LED 状态指示：双色 LED 实时反映系统状态（绿=目标存在/正常，红=无目标/异常）
• 多重异常处理：相机重试超时、KPU 输出有效性检测、设备死亡自动退出
• 动态帧率调节：目标数量过多时自动降帧，保证推理实时性

---

硬件需求

组件	型号	说明
主控	Sipeed Maix-Bit	K210 RISC-V 双核, 8MB SRAM
摄像头	OV5642	DVP 接口, 最高 500W 像素
显示屏	2.4” LCD	SPI 接口, 320×240
存储	MicroSD 卡	存放 kmodel 和 json 文件
LED	板载 RGB LED	绿 IO12, 红 IO13 (低电平驱动)
读卡器	可以插入microSD卡	用于向sd卡写入模型和文件

---

编译与烧录

环境准备

搭建系统：
Ubuntu 18.04

换源：
sudo nano /etc/apt/sources.list

替换如下：
deb http://mirrors.aliyun.com/ubuntu/ bionic main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ bionic-security main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ bionic-updates main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ bionic-proposed main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ bionic-backports main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ bionic main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ bionic-security main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ bionic-updates main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ bionic-proposed main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ bionic-backports main restricted universe multiverse

更新：
sudo apt-get update
sudo apt-get upgrade

依赖包安装
sudo apt install build-essential pkg-config  git
sudo apt install gcc make libncurses5-dev openssl libssl-dev bison flex libelf-dev autoconf libtool gperf libc6-dev

裁减配置工具的下载
mkdir kfrontends  && cd kfrontends
git clone https://gitlink.org.cn/xuos/kconfig-frontends.git
安装：
cd kconfig-frontends
 ./xs_build.sh

编译工具链
下载：xpack-riscv-none-embed-gcc-10.2.0-1.2-linux-x64.tar.gz
解压：tar -xjf xpack-riscv-none-embed-gcc-10.2.0-1.2-linux-x64.tar.gz -C /opt/

确保board/maix-bit/config.mk中含有：
export CROSS_COMPILE ?=/opt/xpack-riscv-none-embed-gcc-10.2.0-1.2/bin/riscv-none-embed-

使用软件：
MobaXterm：串口调试，执行命令
kflash_gui：烧录镜像

配置 (menuconfig)

make BOARD=maix-bit menuconfig

关键配置项：

• Application for XiZi board → knowing app → Using knowing apps - 必须启用
• Framework/knowing/detect → yolov2 detect procedure - 启用目标检测
• Framework/knowing/classify → classify procedure - 启用图像分类
• 各子菜单中的摄像头参数（亮度、对比度等）可按需调整

编译

cd Ubiquitous/XiZi_IIoT_Macro
make BOARD=maix-bit

编译产物为 XiZi-maix-bit.bin，通过 kflash 工具烧录到开发板。

---

JSON 配置格式

详见 **JSON_FORMAT.md**。完整文档包含：字段详解、取值范围、校验规则、示例文件、常见错误排查。

快速参考

检测 JSON (/detect.json) — 8 个字段，由 json_parser.c 解析：

字段	类型	说明
anchors	[number] ×10	锚点框宽高对 (5 对)
net_input_size	[int, int]	模型输入 [高, 宽]
net_output_shape	[int, int, int]	KPU 输出张量形状
sensor_output_size	[int, int]	DVP 采集尺寸 (宽度须匹配)(可以和net_input_size相同)
kmodel_size	int	.kmodel 字节数
labels	[string]	类别标签 (≤20 类)
obj_thresh	[number]	各类置信度阈值 (与 labels 等长)
nms_thresh	number	NMS IoU 阈值

分类 JSON (/classify.json) — 3 个字段，由 classify.c 解析：

字段	类型	说明
net_input_size	[int, int]	模型输入 [高, 宽]
kmodel_size	int	.kmodel 字节数
labels	[string]	类别标签 (≤10 类)

kmodel 路径自动推导: JSON 文件名的 .json 后缀替换为 .kmodel。

---

运行

将 .kmodel 和对应的 .json 文件放入 SD 卡根目录，通过串口终端连接开发板：

# 启动目标检测
Detect /detect.json

# 启动图像分类
Classify /classify.json

串口输出示例

# 检测模式
[0] objs:3 (120,80,200,180)helmet:0.85 (300,150,380,220)head:0.72 (50,60,100,120)
# 分类模式
[0] no_helmet: 0.95 helmet:0 no_helmet:10

---

LED 状态说明

状态	绿灯	红灯	说明
检测到目标	● 亮	○ 灭	正常检测中
无检测目标	○ 灭	● 亮	画面中无目标
休眠	○ 灭	○ 灭	画面静止且无目标，KPU 已暂停
错误	○ 灭	● 亮	LCD 底部会显示错误信息

---

模型准备指南

模型格式要求

KPU 支持加速的模型格式为kmodel

可以在maixhub中直接训练得到kmodel格式的模型

MaixHub

训练会得到kmodel模型和report.json 其中report.json中会包含需要的.json文件中的参数

---

项目结构

仅列出本应用实际使用的关键文件。

xiuos/
├── README.md / SOLUTION.md / THIRD_PARTY.md / JSON_FORMAT.md
│
├── APP_Framework/
│   ├── Applications/knowing_app/
│   │   ├── classify/classify_entry.c          # Classify 命令注册
│   │   ├── detect/detect_entry.c              # Detect 命令注册
│   │   ├── Makefile / Kconfig                 # 应用层构建
│   │
│   ├── Framework/knowing/
│   │   ├── classify/
│   │   │   ├── classify.c                     # 分类主逻辑 (JSON解析 + KPU推理 + 投票)
│   │   │   ├── classify.h
│   │   │   └── Kconfig                        # LCD尺寸 + 摄像头参数
│   │   ├── detect/
│   │   │   ├── detect.c                       # 检测主逻辑 (JSON解析 + YOLOv2 + KPU推理)
│   │   │   ├── detect.h
│   │   │   └── Kconfig                        # LCD尺寸 + 摄像头参数
│   │   ├── kpu/
│   │   │   ├── yolov2/
│   │   │   │   ├── region_layer.c             # YOLOv2 region层解码 + NMS
│   │   │   │   └── region_layer.h
│   │   │   └── yolov2_json/
│   │   │       ├── json_parser.c              # param_parse() JSON参数解析
│   │   │       └── json_parser.h
│   │   ├── Kconfig / Makefile
│   │
│   └── lib/cJSON/                             # JSON 解析库 (MIT)
│
├── Ubiquitous/XiZi_IIoT_Macro/
│   ├── board/maix-bit/
│   │   ├── board.c                            # 板级初始化 + 双核分发
│   │   ├── xsconfig.h                         # 系统配置宏 (Kconfig→代码)
│   │   ├── link.lds                           # 链接脚本 (每核独立栈)
│   │   ├── Kconfig 
│   │   │
│   │   └── third_party_driver/                # 外设驱动 (仅列出数据流涉及项)
│   │       ├── camera/
│   │       │   ├── ov5642.c                   #   OV5642 寄存器配置 (SCCB)
│   │       │   ├── dvp.c                      #   DVP 数据采集 (RGB888 三平面)
│   │       │   └── connect_dvp.c              #   DVP ioctl 适配层
│   │       ├── kpu/
│   │       │   ├── kpu.c                      #   KPU 硬件操作
│   │       │   └── connect_kpu.c              #   KPU ioctl 适配层
│   │       ├── lcd/connect_lcd.c              #   LCD SPI ioctl 适配层
│   └── kernel/thread/smp_assign.c             # SMP调度器 (每核就绪队列)

---

异常处理机制

异常类型	检测方式	处理动作
摄像头拍照失败	5次重试 + 2秒超时	累积错误计数, >30 次退出
KPU 输出为零/空	空指针 + 长度检查	跳过本帧, LCD 红字提示
推理概率异常	概率 <0 或 >1	跳过本帧, LCD 红字提示
连续无目标+静止	200帧计数 + 运动检测	进入休眠 (关KPU+LCD+LED)
故障恢复	连续3帧有目标/有动	唤醒恢复正常推理

---

许可证

本项目核心应用代码基于 Mulan PSL v2 开源协议发布。

Copyright (c) 2020-2026 AIIT XUOS Lab

使用的第三方开源组件详见 THIRD_PARTY.md。

组件	许可证	用途
cJSON	MIT	JSON 解析
YOLOv2 region_layer / json_parser	Apache 2.0	检测后处理 (NMS) + JSON参数解析
XiUOS	Mulan PSL v2	基础操作系统
Kendryte K210 SDK	Apache 2.0	芯片驱动层
MaixPy-v1	Apache 2.0	ov5642驱动

---

参考资料

• Kendryte K210 Standalone SDK
• MaixPy-v1