K230 Sensor API 参考#

概述#

Sensor API 用于完成图像传感器设备的打开、上电、初始化、模式切换、寄存器读写以及运行期参数调节。这组接口主要对应传感器驱动控制面，通常与 VICAP、ISP 一起使用。

当前 API 头文件位于 src/rtsmart/mpp/userapps/api/mpi_sensor_api.h，相关数据类型定义位于 k_sensor_comm.h 和 k_vicap_comm.h。

代码位置#

头文件：src/rtsmart/mpp/userapps/api/mpi_sensor_api.h
相关类型：src/rtsmart/mpp/include/comm/k_sensor_comm.h
VICAP 相关类型：src/rtsmart/mpp/include/comm/k_vicap_comm.h

快速索引#

接口详细说明#

设备生命周期管理#

kd_mpi_sensor_open#

打开传感器设备。

函数原型

k_s32 kd_mpi_sensor_open(const char *sensor_name);

参数

参数	类型	说明	输入/输出
`sensor_name`	`const char*`	传感器名称（如 “gc2093_csi2”）	输入

返回值

返回值	说明
`>= 0`	传感器文件描述符（fd）
`< 0`	失败，返回错误码

注意事项

返回的 fd 用于后续所有 sensor 操作
使用完成后必须调用 kd_mpi_sensor_close() 关闭设备
传感器名称必须与驱动中注册的名称匹配

示例

k_s32 fd = kd_mpi_sensor_open("gc2093_csi2");
if (fd < 0) {
    printf("Failed to open sensor\n");
    return -1;
}
// 使用 fd 进行后续操作
kd_mpi_sensor_close(fd);

kd_mpi_sensor_close#

关闭传感器设备。

函数原型

k_s32 kd_mpi_sensor_close(k_s32 fd);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

关闭后 fd 不再有效
必须与 kd_mpi_sensor_open() 配对使用

kd_mpi_sensor_power_set#

设置传感器电源状态。

函数原型

k_s32 kd_mpi_sensor_power_set(k_s32 fd, k_bool on);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`on`	`k_bool`	K_TRUE: 上电，K_FALSE: 断电	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

上电后才能进行初始化和配置
断电前确保已停止数据流

kd_mpi_sensor_init#

初始化传感器设备。

函数原型

k_s32 kd_mpi_sensor_init(k_s32 fd, k_sensor_mode mode);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`mode`	`k_sensor_mode`	传感器工作模式配置	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

必须在上电后调用
mode 结构体需要正确配置分辨率、帧率等参数

kd_mpi_sensor_stream_enable#

使能或禁用传感器数据流。

函数原型

k_s32 kd_mpi_sensor_stream_enable(k_s32 fd, k_s32 enable);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`enable`	`k_s32`	1: 使能，0: 禁用	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

使能后传感器开始输出图像数据
禁用后停止输出，但保持配置

设备信息与模式管理#

kd_mpi_sensor_id_get#

获取传感器 ID。

函数原型

k_s32 kd_mpi_sensor_id_get(k_s32 fd, k_u32 *sensor_id);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`sensor_id`	`k_u32*`	输出传感器 ID	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_mode_get#

获取当前传感器模式配置。

函数原型

k_s32 kd_mpi_sensor_mode_get(k_s32 fd, k_sensor_mode *mode);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`mode`	`k_sensor_mode*`	输出模式配置	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_mode_set#

设置传感器工作模式。

函数原型

k_s32 kd_mpi_sensor_mode_set(k_s32 fd, k_sensor_mode mode);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`mode`	`k_sensor_mode`	模式配置	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

某些模式切换可能需要重启数据流

kd_mpi_sensor_mode_enum#

枚举传感器支持的模式。

函数原型

k_s32 kd_mpi_sensor_mode_enum(k_s32 fd, k_sensor_enum_mode *enum_mode);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`enum_mode`	`k_sensor_enum_mode*`	枚举模式信息	输入/输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_caps_get#

获取传感器能力信息。

函数原型

k_s32 kd_mpi_sensor_caps_get(k_s32 fd, k_sensor_caps *caps);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`caps`	`k_sensor_caps*`	输出能力信息	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_connection_check#

检查传感器连接状态。

函数原型

k_s32 kd_mpi_sensor_connection_check(k_s32 fd, k_s32 *connection);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`connection`	`k_s32*`	输出连接状态（1: 已连接，0: 未连接）	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_adapt_get#

根据配置获取传感器信息。

函数原型

k_s32 kd_mpi_sensor_adapt_get(k_vicap_probe_config *config, k_vicap_sensor_info *info);

参数

参数	类型	说明	输入/输出
`config`	`k_vicap_probe_config*`	探测配置（CSI 编号、分辨率、帧率）	输入
`info`	`k_vicap_sensor_info*`	输出传感器信息	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

寄存器访问#

kd_mpi_sensor_reg_read#

读取传感器寄存器。

函数原型

k_s32 kd_mpi_sensor_reg_read(k_s32 fd, k_u32 reg_addr, k_u32 *reg_val);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`reg_addr`	`k_u32`	寄存器地址	输入
`reg_val`	`k_u32*`	输出寄存器值	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

用于调试或特殊配置
寄存器地址和位宽因传感器而异

kd_mpi_sensor_reg_write#

写入传感器寄存器。

函数原型

k_s32 kd_mpi_sensor_reg_write(k_s32 fd, k_u32 reg_addr, k_u32 reg_val);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`reg_addr`	`k_u32`	寄存器地址	输入
`reg_val`	`k_u32`	寄存器值	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

错误的寄存器配置可能导致传感器工作异常
建议参考传感器数据手册

曝光与增益控制#

kd_mpi_sensor_again_set#

设置模拟增益（Again）。

函数原型

k_s32 kd_mpi_sensor_again_set(k_s32 fd, k_sensor_gain gain);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`gain`	`k_sensor_gain`	增益值结构体	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

增益值必须在传感器支持范围内
建议先调用 kd_mpi_sensor_get_gain_range() 获取范围

示例

k_sensor_gain gain;
gain.gain[0] = 2.0f;  // 设置增益为 2.0
k_s32 ret = kd_mpi_sensor_again_set(fd, gain);

kd_mpi_sensor_again_get#

获取当前模拟增益值。

函数原型

k_s32 kd_mpi_sensor_again_get(k_s32 fd, k_sensor_gain *gain);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`gain`	`k_sensor_gain*`	输出增益值	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_dgain_set#

设置数字增益（Dgain）。

函数原型

k_s32 kd_mpi_sensor_dgain_set(k_s32 fd, k_sensor_gain gain);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`gain`	`k_sensor_gain`	增益值结构体	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_dgain_get#

获取当前数字增益值。

函数原型

k_s32 kd_mpi_sensor_dgain_get(k_s32 fd, k_sensor_gain *gain);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`gain`	`k_sensor_gain*`	输出增益值	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_intg_time_set#

设置积分时间（曝光时间）。

函数原型

k_s32 kd_mpi_sensor_intg_time_set(k_s32 fd, k_sensor_intg_time time);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`time`	`k_sensor_intg_time`	积分时间结构体（单位：秒）	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

积分时间必须在传感器支持范围内
建议先调用 kd_mpi_sensor_get_exposure_time_range() 获取范围

示例

k_sensor_intg_time time;
time.intg_time[0] = 0.01f;  // 10ms
k_s32 ret = kd_mpi_sensor_intg_time_set(fd, time);

kd_mpi_sensor_intg_time_get#

获取当前积分时间。

函数原型

k_s32 kd_mpi_sensor_intg_time_get(k_s32 fd, k_sensor_intg_time *time);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`time`	`k_sensor_intg_time*`	输出积分时间	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_get_exposure_time_range#

获取曝光时间范围。需要在start之后调用

函数原型

k_s32 kd_mpi_sensor_get_exposure_time_range(k_s32 fd, k_sensor_exposure_time_range *range);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`range`	`k_sensor_exposure_time_range*`	输出曝光范围（单位：微秒）	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

示例

k_sensor_exposure_time_range range;
k_s32 ret = kd_mpi_sensor_get_exposure_time_range(fd, &range);
if (ret == 0) {
    printf("Exposure range: %.0f - %.0f us\n", 
           range.min_intg_time_us, range.max_intg_time_us);
}

kd_mpi_sensor_get_gain_range#

获取增益范围。需要在start之后调用

函数原型

k_s32 kd_mpi_sensor_get_gain_range(k_s32 fd, k_sensor_gain_info *range);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`range`	`k_sensor_gain_info*`	输出增益范围	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

示例

k_sensor_gain_info range;
k_s32 ret = kd_mpi_sensor_get_gain_range(fd, &range);
if (ret == 0) {
    printf("Gain range: %.2f - %.2f, step: %.6f\n", 
           range.min_gain, range.max_gain, range.step_gain);
}

帧率控制#

kd_mpi_sensor_fps_set#

设置传感器帧率。

函数原型

k_s32 kd_mpi_sensor_fps_set(k_s32 fd, k_u32 fps);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`fps`	`k_u32`	帧率值	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_fps_get#

获取当前帧率。

函数原型

k_s32 kd_mpi_sensor_fps_get(k_s32 fd, k_u32 *fps);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`fps`	`k_u32*`	输出帧率	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

图像质量控制#

kd_mpi_sensor_isp_status_get#

获取 ISP 状态信息。

函数原型

k_s32 kd_mpi_sensor_isp_status_get(k_s32 fd, k_sensor_isp_status *isp_status);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`isp_status`	`k_sensor_isp_status*`	输出 ISP 状态	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_blc_set#

设置黑电平校正（BLC）。

函数原型

k_s32 kd_mpi_sensor_blc_set(k_s32 fd, k_sensor_blc blc);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`blc`	`k_sensor_blc`	黑电平校正值（包含 R/Gr/Gb/B 四个通道）	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_wb_set#

设置白平衡（WB）。

函数原型

k_s32 kd_mpi_sensor_wb_set(k_s32 fd, k_sensor_white_balance wb);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`wb`	`k_sensor_white_balance`	白平衡增益（包含 R/Gr/Gb/B 四个通道）	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_tpg_set#

设置测试图案发生器（TPG）。

函数原型

k_s32 kd_mpi_sensor_tpg_set(k_s32 fd, k_sensor_test_pattern tpg);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`tpg`	`k_sensor_test_pattern`	测试图案配置（enable/pattern）	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

TPG 用于调试，不依赖真实图像输入

kd_mpi_sensor_tpg_get#

获取 TPG 配置。

函数原型

k_s32 kd_mpi_sensor_tpg_get(k_s32 fd, k_sensor_test_pattern *tpg);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`tpg`	`k_sensor_test_pattern*`	输出 TPG 配置	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_expand_curve_get#

获取扩展曲线配置。

函数原型

k_s32 kd_mpi_sensor_expand_curve_get(k_s32 fd, k_sensor_compand_curve *curve);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`curve`	`k_sensor_compand_curve*`	输出扩展曲线配置	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_mirror_set#

设置镜像翻转。

函数原型

k_s32 kd_mpi_sensor_mirror_set(k_s32 fd, k_vicap_mirror_mode mirror);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`mirror`	`k_vicap_mirror_mode`	镜像模式配置	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

OTP 与对焦控制#

kd_mpi_sensor_otpdata_get#

获取 OTP 数据。

函数原型

k_s32 kd_mpi_sensor_otpdata_get(k_s32 fd, void *otp_data);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`otp_data`	`void*`	输出 OTP 数据缓冲区	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_otpdata_set#

设置 OTP 数据。

函数原型

k_s32 kd_mpi_sensor_otpdata_set(k_s32 fd, void *otp_data);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`otp_data`	`void*`	OTP 数据缓冲区	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

OTP 写入操作需谨慎，可能不可逆

kd_mpi_sensor_set_focus_pos#

设置对焦位置。

函数原型

k_s32 kd_mpi_sensor_set_focus_pos(k_s32 fd, k_sensor_focus_pos *focus_pos);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`focus_pos`	`k_sensor_focus_pos*`	对焦位置配置	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

仅支持带自动对焦功能的传感器模组

kd_mpi_sensor_get_focus_pos#

获取当前对焦位置。

函数原型

k_s32 kd_mpi_sensor_get_focus_pos(k_s32 fd, k_sensor_focus_pos *focus_pos);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`focus_pos`	`k_sensor_focus_pos*`	输出对焦位置	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_get_focus_caps#

获取对焦能力信息。

函数原型

k_s32 kd_mpi_sensor_get_focus_caps(k_s32 fd, k_sensor_autofocus_caps *caps);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`caps`	`k_sensor_autofocus_caps*`	输出对焦能力信息	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

kd_mpi_sensor_set_focus_power#

设置对焦电源状态。

函数原型

k_s32 kd_mpi_sensor_set_focus_power(k_s32 fd, k_bool power);

参数

参数	类型	说明	输入/输出
`fd`	`k_s32`	传感器文件描述符	输入
`power`	`k_bool`	K_TRUE: 上电，K_FALSE: 断电	输入

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

信息查询接口#

kd_mpi_sensor_list_mode#

获取传感器支持的模式列表。

函数原型

k_s32 kd_mpi_sensor_list_mode(const char *sensor_name, k_sensor_mode_list *list);

参数

参数	类型	说明	输入/输出
`sensor_name`	`const char*`	传感器名称	输入
`list`	`k_sensor_mode_list*`	输出模式列表	输出

返回值

返回值	说明
`0`	成功
非 `0`	失败，返回错误码

注意事项

最多返回 6 个模式
根据 sensor_name 自动匹配对应的 sensor_type 和 csi_num

示例

k_sensor_mode_list list;
k_s32 ret = kd_mpi_sensor_list_mode("gc2093_csi2", &list);
if (ret == 0) {
    for (k_u32 i = 0; i < list.count; i++) {
        printf("Mode %u: %ux%u@%ufps\n", 
               i, list.modes[i].width, list.modes[i].height, list.modes[i].fps);
    }
}

根据传感器名称打开设备。

函数原型

参数

参数	类型	说明	输入/输出
`sensor_name`	`const char*`	传感器名称	输入

返回值

返回值	说明
`>= 0`	传感器文件描述符
`< 0`	失败，返回错误码

注意事项

该函数是 kd_mpi_sensor_open() 的便捷版本
内部会查找匹配的传感器配置并打开设备

典型使用流程#

// 1. 打开传感器
k_s32 fd = kd_mpi_sensor_open("gc2093_csi2");
if (fd < 0) {
    printf("Failed to open sensor\n");
    return -1;
}

// 2. 上电
kd_mpi_sensor_power_set(fd, K_TRUE);

// 3. 初始化（配置模式）
k_sensor_mode mode;
// ... 配置 mode 结构体 ...
kd_mpi_sensor_init(fd, mode);

// 4. 调整参数（可选）
kd_mpi_sensor_fps_set(fd, 30);
kd_mpi_sensor_again_set(fd, gain);

// 5. 使能数据流
kd_mpi_sensor_stream_enable(fd, 1);

// ... 使用传感器 ...

// 6. 禁用数据流
kd_mpi_sensor_stream_enable(fd, 0);

// 7. 断电
kd_mpi_sensor_power_set(fd, K_FALSE);

// 8. 关闭设备
kd_mpi_sensor_close(fd);

注意事项#

fd 管理：所有操作都依赖 kd_mpi_sensor_open() 返回的 fd，使用完成后必须调用 kd_mpi_sensor_close() 关闭。
调用顺序：建议按照上电 → 初始化 → 配置 → 使能流的顺序调用。
参数范围：设置增益、曝光等参数前，建议先调用对应的 get_*_range() 接口获取有效范围。
传感器差异：不同传感器支持的功能和参数范围可能不同，具体能力由驱动决定。
并发访问：避免多个线程同时操作同一个传感器 fd。
错误处理：所有接口返回非 0 值表示失败，应检查返回值并进行相应处理。

K230 Sensor API 参考

目录

K230 Sensor API 参考#

概述#

代码位置#

快速索引#

设备生命周期管理#

设备信息与模式管理#

寄存器访问#

曝光与增益控制#

帧率控制#

图像质量控制#

OTP 与对焦控制#

信息查询接口#

接口详细说明#

设备生命周期管理#

kd_mpi_sensor_open#

kd_mpi_sensor_close#

kd_mpi_sensor_power_set#

kd_mpi_sensor_init#

kd_mpi_sensor_stream_enable#

设备信息与模式管理#

kd_mpi_sensor_id_get#

kd_mpi_sensor_mode_get#

kd_mpi_sensor_mode_set#

kd_mpi_sensor_mode_enum#

kd_mpi_sensor_caps_get#

kd_mpi_sensor_connection_check#

kd_mpi_sensor_adapt_get#

寄存器访问#

kd_mpi_sensor_reg_read#

kd_mpi_sensor_reg_write#

曝光与增益控制#

kd_mpi_sensor_again_set#

kd_mpi_sensor_again_get#

kd_mpi_sensor_dgain_set#

kd_mpi_sensor_dgain_get#

kd_mpi_sensor_intg_time_set#

kd_mpi_sensor_intg_time_get#

kd_mpi_sensor_get_exposure_time_range#

kd_mpi_sensor_get_gain_range#

帧率控制#

kd_mpi_sensor_fps_set#

kd_mpi_sensor_fps_get#

图像质量控制#

kd_mpi_sensor_isp_status_get#

kd_mpi_sensor_blc_set#

kd_mpi_sensor_wb_set#

kd_mpi_sensor_tpg_set#

kd_mpi_sensor_tpg_get#

kd_mpi_sensor_expand_curve_get#

kd_mpi_sensor_mirror_set#

OTP 与对焦控制#

kd_mpi_sensor_otpdata_get#

kd_mpi_sensor_otpdata_set#

kd_mpi_sensor_set_focus_pos#

kd_mpi_sensor_get_focus_pos#

kd_mpi_sensor_get_focus_caps#

kd_mpi_sensor_set_focus_power#

信息查询接口#

kd_mpi_sensor_list_mode#

典型使用流程#

注意事项#