BT.656 例程(dpi-hdk-lb57e)
源码路径: example/rt_device/bt656
演示 customer/peripherals/camera/bt656 的通用 BT.656 接口(bt656.h):
单帧(snapshot)、逐帧(frame)和连续流(stream)三种用法都建立在同一条
连续采集路径上,画面显示到 1024×600 DPI 屏。
用法
下面的小节只列必要步骤;SDK 配置、构建与烧录的完整步骤见 SiFli-SDK 快速入门。
编译与运行
在已加载 SDK 环境的 shell 里执行:
cd example/rt_device/bt656/project
scons --board=dpi-hdk_lb57eybbn6_n16_qspi -j8
烧写到板子后,串口为 uart1、波特率 1000000(CONFIG_CONSOLE_UART1=y、
CONFIG_RT_SERIAL_DEFAULT_BAUDRATE=1000000)。
支持的开发板
dpi-hdk_lb57eybbn6_n16_qspi(板卡代号 dpi-hdk-lb57e,SF32LB57x HCPU)
硬件需求
ARK7128 视频解码模块,接在本板固定的 I2C1(SCL
PA23/ SDAPA22)与 DCMI PINMAP0 引脚上,引脚表见customer/peripherals/camera/bt656/README.md;模拟视频源:CVBS(NTSC/PAL)或 AHD 720P(25/30 fps),接模块 VIN2;
1024×600 DPI 屏(本板自带)。
软件需求
已加载 SDK 环境(
export.ps1/export.sh),scons与sdk.py可执行;可选:LVGL v8(
CONFIG_PKG_USING_LITTLEVGL2RTT=y)及其应用配置, 只有camera_lvgl预览需要,见“LVGL 集成示例”。
配置项目
项 |
位置 |
|---|---|
视频输入格式(NTSC / PAL / AHD 25 / AHD 30) |
|
LVGL 预览(可选) |
顶层选项 |
LCD 型号 / 背光 |
|
I2C / DCMI 引脚 |
板级 |
cd example/rt_device/bt656/project
sdk.py menuconfig --board=dpi-hdk_lb57eybbn6_n16_qspi
示例输出
main() 打印横幅和用法,采集不会自动开始(下面只摘录这两部分,前面还有
其它组件的启动日志):
===== BT.656 camera demo (dpi-hdk-lb57e) =====
usage:
camera snapshot [loops] [timeout_ms] capture & show N frames (default 1, 1000 ms)
camera frame [interval_ms] continuous frame mode (default 0 ms)
camera stream [interval_ms] continuous stream mode (default 0 ms)
camera init initialize decoder
camera stop stop continuous display
camera cpu print CPU usage (last ~2 s window)
camera info print camera status
msh >
camera init 之后确认解码器(camera info 会打印读到的芯片 ID)。下面只摘录
[camera] 开头的行。驱动自身还会打印 [I/bt656]、[I/ark7128.*] 这类
LOG_I/LOG_W 日志:默认配置 RT_DEBUG=y(rtos/rtthread/src/Kconfig)时
它们经 rtdbg 直接输出;若在 menuconfig 关闭 RT_DEBUG,这些行会被编译掉,
只剩 [camera] 的 rt_kprintf 输出。打开 CONFIG_RT_USING_ULOG=y 后改由
ulog 输出。
msh /> camera init
[camera] ready: CVBS NTSC, signal locked
命令与交互
相机功能由一条 camera 命令提供,LVGL 预览另有 camera_lvgl:
命令 |
说明 |
|---|---|
|
起流取 N 帧再停流,默认 1 帧 / 1000 ms |
|
连续预览(与 stream 同一条采集路径) |
|
连续预览(与 frame 同一条采集路径) |
|
初始化采集层,打印格式与锁定状态 |
|
停止连续显示 |
|
打印 CPU 占用率(最近约 2 s 窗口) |
|
打印格式、锁定状态、预览状态、CPU 信息 |
|
打印用法(不带子命令时同样打印) |
|
LVGL 图像控件预览(需在 menuconfig 里打开 |
interval_ms 是两帧之间的最小间隔,0(默认)表示全速。frame 与 stream
目前完全等价:都走同一条连续采集路径,只有 camera info 打印的模式名不同。
示例:
msh /> camera snapshot # 采一帧
msh /> camera snapshot 10 # 起流取 10 帧
msh /> camera frame # 连续预览,约 27~30 fps
msh /> camera stream 100 # 连续预览,每帧至少间隔 100 ms
msh /> camera info
[camera] format : CVBS NTSC (720x240, stride 1440, interlaced field)
[camera] signal : locked (chip id 0x7128)
[camera] stats : captured=120, dropped=0, errors=0
[camera] preview: running, mode=frame, captured=120, failed=0
[camera] cpu : 45.2% (last ~2 s window)
msh /> camera stop
运行中每 2 秒打印一行统计(fps 为预览启动以来的累计平均值):
[camera] 29.1 fps, 34 ms/frame, fail=0, cpu 45.2%
示例解析(可选)
上电行为
bt656_init():调用 ARK7128 芯片适配层的init()(配置 I2C1、 读 ID、下发当前格式寄存器表),再初始化 DMA、链接 DCMI 句柄并打开 DCMI 中断(HAL_DCMI_Init()在bt656_start()里执行);显示不会自动开始,需要执行
camera stream/camera frame/camera snapshot(内部调用bt656_start(),一次完成重锁相、DCMI 初始化 和开流)。
驱动在 2026-11 做了两层拆分:应用只包含
bt656.h,使用bt656_start/get/release/stop;具体解码芯片通过bt656_decoder_ops注册,换芯片不需要改应用。前后对照见customer/peripherals/camera/bt656/docs/接口改造说明.md。
三种命令的实际行为
snapshot |
frame |
stream |
|
|---|---|---|---|
触发 |
|
|
|
DCMI |
|
同左 |
同左 |
完成判据 |
CVBS: DMA 字节数;AHD: DCMI FRAME |
同左 |
同左 |
结束 |
取够帧数后 |
|
|
适用 |
抓图/调试 |
连续预览 |
连续预览 |
三种命令都走同一条采集路径:bt656_get() 借一帧 → 渲染 →
bt656_release() 归还。缓冲由驱动固定分配,显示慢时直接丢弃新帧(计入
dropped),内存不会堆积,因此预览只需要一个线程。
连续采集存在已知的固定横向偏移问题(复位后首次开流、摄像头掉电重启、 反复启停偶发),当前驱动没有做补偿。
显示链路
DCMI 采集(YUV422/UYVY)
└─ 预览线程:bt656_get() 借一帧
└─ YUV→RGB565(EPIC 硬件 / CPU 回退)
└─ show_fb(1024×600,视频 1:1 居中)
└─ 只回写图像所在行 cache
└─ 面板由 LCDC/PTC 连续自扫描 show_fb
└─ bt656_release() 归还
YUV→RGB565 默认走 EPIC 硬件(
drv_epic_blend),失败自动回退 CPU;这块屏是 RAMLESS DPI + line-buffer bypass:
draw_rect只能整屏,且 PTC 状态机会一直扫描第一次下发的缓冲。因此只在首次把扫描起点指到show_fb, 之后每帧只更新画布 + 回写 cache;必须先
RTGRAPHIC_CTRL_SET_BUF_FORMAT(RGB565),否则图层格式断言。
LVGL 集成示例(可选)
src/bt656_lvgl.c 演示把摄像头画面作为一张图片嵌入 LVGL 界面:
/* lv_timer 回调,在 LVGL 线程里执行 */
if (bt656_get(&f, 0) == RT_EOK) { /* 非阻塞 */
dsc.header.cf = LV_IMG_CF_YUV422_PACKED_UYVY;
dsc.data = f.data;
dsc.data_size = (uint32_t)f.stride * f.height;
lv_img_set_src(cam_img, &dsc);
if (prev_held_valid) { /* 归还上一帧 */
bt656_release(&prev_held);
}
prev_held = f;
prev_held_valid = RT_TRUE;
}
LVGL v8 的 YUV422 图片格式由 SDK 的 LVGL GPU 驱动交给 EPIC 合成,
不需要 CPU 转换,也不需要 show_fb。(示例依赖 LVGL v8 的
lv_img_dsc_t / lv_timer_create API,v9 不适用。)
每帧要先调用
lv_img_cache_invalidate_src(&dsc):缓冲地址不变、内容变了, 不失效会被 LVGL 的图片缓存命中,显示不更新;不能在
lv_img_set_src()之后立即bt656_release():EPIC 是异步 DMA, 要等下一帧更新时才归还上一帧。
启用步骤(LVGL 需要完整的 LVGL 应用配置,只打开包开关是不够的):
# project/proj.conf —— 以 example/lvgl_v8_ttf/project/proj.conf 为参考
CONFIG_RT_USING_MEMHEAP=y
CONFIG_PKG_USING_LITTLEVGL2RTT=y
# CONFIG_LV_USING_EXT_RESOURCE_MANAGER is not set
# SDK 的 LVSF 默认主题会引用这些字号(1024x600 时)
CONFIG_LV_FONT_MONTSERRAT_16=y
CONFIG_LV_FONT_MONTSERRAT_20=y
CONFIG_LV_FONT_MONTSERRAT_24=y
CONFIG_LV_FONT_MONTSERRAT_28=y
CONFIG_LV_FONT_MONTSERRAT_36=y
CONFIG_LV_FONT_DEFAULT_MONTSERRAT_16=y
实测:只加
CONFIG_PKG_USING_LITTLEVGL2RTT=y时 SDK 的 LVGL middleware 会先因RT_USING_MEMHEAP未开、lang_pack.h缺失而失败;补齐后再因lv_font_montserrat_*未声明失败。上面的组合覆盖了这三类问题。
然后打开例程自己的选项。它来自 project/Kconfig.proj,依赖
CONFIG_PKG_USING_LITTLEVGL2RTT=y,所以要在打开 LVGL 之后才会出现:
cd example/rt_device/bt656/project
sdk.py menuconfig --board=dpi-hdk_lb57eybbn6_n16_qspi
# 顶层选项:BT.656 + LVGL preview demo
msh /> camera_lvgl start # 全屏居中显示
msh /> camera_lvgl stop
限制:
只支持 CVBS(packed UYVY,
stride == 2*width);AHD 缓冲带定时码,lv_img_dsc_t没有 stride 字段,暂不支持;本示例自己创建 LVGL 宿主线程,工程里已有 LVGL 线程时请把 timer 那段搬过去;
不要与
camera stream同时运行(两者独占lcd设备)。
CPU 占用率测量
参照 example/system/cpu_usage_profiler 接入 SDK 自带的 CPU Usage Profiler,
project/proj.conf 已默认打开:
CONFIG_USING_CPU_USAGE_PROFILER=y
CONFIG_CPU_USAGE_METRICS_ENABLED=y
CONFIG_CPU_USAGE_METRICS_PRINT_DIRECTLY=y
CONFIG_CPU_USAGE_METRICS_PRINT_PERIOD=10
camera cpu:打印最近约 2 s 的 CPU 占用率;camera info:末尾附带 CPU 占用率;camera frame/camera stream的运行统计行会附带cpu xx.x%;启用 ULOG 后,系统每 10 s 打印一次各线程负载(
CPU Usage Metrics)。 注意:该表格和 SDK 的cpu命令通过LOG_I输出,需要CONFIG_RT_USING_ULOG=y;当前proj.conf没有启用 ULOG,因此这两项 在本工程里没有输出,而camera cpu/camera info/ 统计行使用rt_kprintf,不受影响。启用 ULOG 后的示例(数值仅示例):
============================
CPU Usage: 36.20/ 50.01 ( 72.39%)
========================================================
thread run_time(s) load(%)
--------------------------------------------------------
[ark_prev]: 24.10 48.19%
[tidle ]: 13.81 27.61%
[tshell ]: 0.05 0.10%
SDK 还提供 shell 命令:
cpu(立即打印统计)、cpu_prof_reset(清零)、cpu_prof_deinit/cpu_prof_init(关/开采集钩子);其中cpu的输出依赖 ULOG(原因同上);Metrics 依赖
thread->user_data记录线程运行时间,因此要求RT_USING_PTHREADS关闭(当前工程满足);cpu_get_usage()返回最近一个约 2 s 统计区间的占用率,不是瞬时采样;不想测量时把上面 4 行配置去掉再重编译即可,代码会自动走 “未启用 profiler” 的打印分支。
内存(PSRAM)
用途 |
CVBS NTSC |
CVBS PAL |
AHD 720P |
|---|---|---|---|
|
3 × 414,720 B |
3 × 414,720 B |
2 × 1,843,200 B |
|
1,228,800 B |
同左 |
同左 |
CVBS 的流缓冲每块按最大的 CVBS 格式(PAL 1440×288)预留:NTSC 一场只有
345,600 B 有效数据,缓冲仍是 414,720 B。CVBS 的流缓冲加画布共约 2.4 MB,
都在 PSRAM1。AHD 的流缓冲使用 frambuf 段,放到 PSRAM2(链接脚本的
l2_non_ret_bss_frambuf* 规则;本板需确认第二片 PSRAM 可用)。
异常诊断
下面两条
[W/bt656]是驱动的LOG_W:默认RT_DEBUG=y时可见,关闭RT_DEBUG后会被编译掉。不依赖日志时,用camera info的signal与stats(errors是否增长)以及预览线程的[camera] N captures failed (ret=...)判断:ret=-2(-RT_ETIMEOUT)表示一直取不到帧,ret=-8(-RT_EIO)表示采集已停止。
camera info打印format not configured:还没有成功执行bt656_init()(先执行camera init;它失败时会打印decoder init failed);chip id 0x0000表示 I2C 读不到芯片,检查模块供电与 I2C1(PA22/PA23)接线。signal为no lock:确认模拟源接在 VIN2、制式与Video input format一致。连续取帧超时时,驱动按信号状态分别处理:
有信号但收不到帧:打印
[W/bt656] no frame in N ms (remaining x/y), restart capture,复位 DCMI 重新起流;无信号:打印
[W/bt656] no frame in N ms, no signal, waiting for source(约每秒最多一次),不复位 DCMI,等信号恢复。
预览线程连续 50 次失败后打印
[camera] 50 captures failed (ret=-2), check signal(-2即-RT_ETIMEOUT),之后每 50 次再打印一次,线程不退出。
已知限制
面板自扫描与 CPU 写缓冲之间没有双缓冲翻转,快速运动画面可能撕裂;
PCLK 信号完整性不足时会出现偶发丢码(颜色错乱、漏码),属于硬件问题。