K230 Sensor API Reference#
Overview#
The Sensor API is used to complete image sensor device operations including opening, powering on, initializing, mode switching, register read/write, and runtime parameter adjustment. This set of interfaces primarily corresponds to the sensor driver control surface and is typically used together with VICAP and ISP.
The current API header file is located at src/rtsmart/mpp/userapps/api/mpi_sensor_api.h, and the related data type definitions are located in k_sensor_comm.h and k_vicap_comm.h.
Code Location#
Header file:
src/rtsmart/mpp/userapps/api/mpi_sensor_api.hRelated types:
src/rtsmart/mpp/include/comm/k_sensor_comm.hVICAP-related types:
src/rtsmart/mpp/include/comm/k_vicap_comm.h
Quick Index#
Device Lifecycle Management#
Device Information and Mode Management#
Register Access#
Exposure and Gain Control#
Frame Rate Control#
Image Quality Control#
OTP and Focus Control#
Information Query Interfaces#
Interface Detailed Description#
Device Lifecycle Management#
kd_mpi_sensor_open#
Open the sensor device.
Function Prototype
k_s32 kd_mpi_sensor_open(const char *sensor_name);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor name (e.g., “gc2093_csi2”) |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Sensor file descriptor (fd) |
|
Failure, returns error code |
Notes
The returned fd is used for all subsequent sensor operations
kd_mpi_sensor_close()must be called after use to close the deviceThe sensor name must match the name registered in the driver
Example
k_s32 fd = kd_mpi_sensor_open("gc2093_csi2");
if (fd < 0) {
printf("Failed to open sensor\n");
return -1;
}
// Use fd for subsequent operations
kd_mpi_sensor_close(fd);
kd_mpi_sensor_close#
Close the sensor device.
Function Prototype
k_s32 kd_mpi_sensor_close(k_s32 fd);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non |
Failure, returns error code |
Notes
The fd is no longer valid after closing
Must be used in pair with
kd_mpi_sensor_open()
kd_mpi_sensor_power_set#
Set the sensor power state.
Function Prototype
k_s32 kd_mpi_sensor_power_set(k_s32 fd, k_bool on);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
K_TRUE: power on, K_FALSE: power off |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non |
Failure, returns error code |
Notes
Initialization and configuration can only be performed after power on
Ensure the data stream has been stopped before power off
kd_mpi_sensor_init#
Initialize the sensor device.
Function Prototype
k_s32 kd_mpi_sensor_init(k_s32 fd, k_sensor_mode mode);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Sensor working mode configuration |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non |
Failure, returns error code |
Notes
Must be called after power on
The mode structure needs to be correctly configured with parameters such as resolution and frame rate
kd_mpi_sensor_stream_enable#
Enable or disable the sensor data stream.
Function Prototype
k_s32 kd_mpi_sensor_stream_enable(k_s32 fd, k_s32 enable);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
1: enable, 0: disable |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non |
Failure, returns error code |
Notes
The sensor starts outputting image data after being enabled
Output stops after being disabled, but the configuration is retained
Device Information and Mode Management#
kd_mpi_sensor_id_get#
Get sensor ID.
Function Prototype
k_s32 kd_mpi_sensor_id_get(k_s32 fd, k_u32 *sensor_id);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output sensor ID |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_mode_get#
Get current sensor mode configuration.
Function Prototype
k_s32 kd_mpi_sensor_mode_get(k_s32 fd, k_sensor_mode *mode);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output mode configuration |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_mode_set#
Set sensor working mode.
Function Prototype
k_s32 kd_mpi_sensor_mode_set(k_s32 fd, k_sensor_mode mode);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Mode configuration |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Notes
Some mode switches may require restarting the data stream
kd_mpi_sensor_mode_enum#
Enumerate the modes supported by the sensor.
Function Prototype
k_s32 kd_mpi_sensor_mode_enum(k_s32 fd, k_sensor_enum_mode *enum_mode);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Enum mode information |
Input/Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_caps_get#
Get sensor capability information.
Function Prototype
k_s32 kd_mpi_sensor_caps_get(k_s32 fd, k_sensor_caps *caps);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output capability information |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_connection_check#
Check sensor connection status.
Function Prototype
k_s32 kd_mpi_sensor_connection_check(k_s32 fd, k_s32 *connection);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output connection status (1: connected, 0: disconnected) |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_adapt_get#
Get sensor information based on configuration.
Function Prototype
k_s32 kd_mpi_sensor_adapt_get(k_vicap_probe_config *config, k_vicap_sensor_info *info);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Probe configuration (CSI number, resolution, frame rate) |
Input |
|
|
Output sensor information |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Register Access#
kd_mpi_sensor_reg_read#
Reads a sensor register.
Function Prototype
k_s32 kd_mpi_sensor_reg_read(k_s32 fd, k_u32 reg_addr, k_u32 *reg_val);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Register address |
Input |
|
|
Output register value |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Notes
Used for debugging or special configuration
Register addresses and bit widths vary by sensor
kd_mpi_sensor_reg_write#
Writes to a sensor register.
Function Prototype
k_s32 kd_mpi_sensor_reg_write(k_s32 fd, k_u32 reg_addr, k_u32 reg_val);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Register address |
Input |
|
|
Register value |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Notes
Incorrect register configuration may cause sensor malfunction
Refer to the sensor datasheet for details
Exposure and Gain Control#
kd_mpi_sensor_again_set#
Set analog gain (Again).
Function Prototype
k_s32 kd_mpi_sensor_again_set(k_s32 fd, k_sensor_gain gain);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Gain value structure |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Notes
The gain value must be within the supported range of the sensor
It is recommended to call
kd_mpi_sensor_get_gain_range()first to obtain the range
Example
k_sensor_gain gain;
gain.gain[0] = 2.0f; // Set gain to 2.0
k_s32 ret = kd_mpi_sensor_again_set(fd, gain);
kd_mpi_sensor_again_get#
Get the current analog gain value.
Function Prototype
k_s32 kd_mpi_sensor_again_get(k_s32 fd, k_sensor_gain *gain);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output gain value |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_dgain_set#
Set digital gain (Dgain).
Function Prototype
k_s32 kd_mpi_sensor_dgain_set(k_s32 fd, k_sensor_gain gain);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Gain value structure |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_dgain_get#
Get the current digital gain value.
Function Prototype
k_s32 kd_mpi_sensor_dgain_get(k_s32 fd, k_sensor_gain *gain);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output gain value |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_intg_time_set#
Set integration time (exposure time).
Function Prototype
k_s32 kd_mpi_sensor_intg_time_set(k_s32 fd, k_sensor_intg_time time);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Integration time structure (unit: seconds) |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Notes
The integration time must be within the supported range of the sensor
It is recommended to call
kd_mpi_sensor_get_exposure_time_range()first to obtain the range
Example
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#
Get the current integration time.
Function Prototype
k_s32 kd_mpi_sensor_intg_time_get(k_s32 fd, k_sensor_intg_time *time);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output integration time |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_get_exposure_time_range#
Get the exposure time range. Must be called after start.
Function Prototype
k_s32 kd_mpi_sensor_get_exposure_time_range(k_s32 fd, k_sensor_exposure_time_range *range);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output exposure range (unit: microseconds) |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Example
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#
Get the gain range. Must be called after start.
Function Prototype
k_s32 kd_mpi_sensor_get_gain_range(k_s32 fd, k_sensor_gain_info *range);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output gain range |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Example
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);
}
Frame Rate Control#
kd_mpi_sensor_fps_set#
Set the sensor frame rate.
Function Prototype
k_s32 kd_mpi_sensor_fps_set(k_s32 fd, k_u32 fps);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Frame rate value |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_fps_get#
Get the current frame rate.
Function Prototype
k_s32 kd_mpi_sensor_fps_get(k_s32 fd, k_u32 *fps);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output frame rate |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Image Quality Control#
kd_mpi_sensor_isp_status_get#
Get ISP status information.
Function Prototype
k_s32 kd_mpi_sensor_isp_status_get(k_s32 fd, k_sensor_isp_status *isp_status);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output ISP status |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_blc_set#
Set Black Level Correction (BLC).
Function Prototype
k_s32 kd_mpi_sensor_blc_set(k_s32 fd, k_sensor_blc blc);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Black level correction value (includes R/Gr/Gb/B four channels) |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_wb_set#
Set White Balance (WB).
Function Prototype
k_s32 kd_mpi_sensor_wb_set(k_s32 fd, k_sensor_white_balance wb);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
White balance gain (includes R/Gr/Gb/B four channels) |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_tpg_set#
Set Test Pattern Generator (TPG).
Function Prototype
k_s32 kd_mpi_sensor_tpg_set(k_s32 fd, k_sensor_test_pattern tpg);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Test pattern configuration (enable/pattern) |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Notes
TPG is used for debugging and does not depend on real image input
kd_mpi_sensor_tpg_get#
Get TPG configuration.
Function Prototype
k_s32 kd_mpi_sensor_tpg_get(k_s32 fd, k_sensor_test_pattern *tpg);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output TPG configuration |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_expand_curve_get#
Get expand curve configuration.
Function Prototype
k_s32 kd_mpi_sensor_expand_curve_get(k_s32 fd, k_sensor_compand_curve *curve);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output expand curve configuration |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_mirror_set#
Set mirror flip.
Function Prototype
k_s32 kd_mpi_sensor_mirror_set(k_s32 fd, k_vicap_mirror_mode mirror);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Mirror mode configuration |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
OTP and Focus Control#
kd_mpi_sensor_otpdata_get#
Get OTP data.
Function Prototype
k_s32 kd_mpi_sensor_otpdata_get(k_s32 fd, void *otp_data);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output OTP data buffer |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_otpdata_set#
Set OTP data.
Function Prototype
k_s32 kd_mpi_sensor_otpdata_set(k_s32 fd, void *otp_data);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
OTP data buffer |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Notes
OTP write operations should be performed with caution, as they may be irreversible
kd_mpi_sensor_set_focus_pos#
Set focus position.
Function Prototype
k_s32 kd_mpi_sensor_set_focus_pos(k_s32 fd, k_sensor_focus_pos *focus_pos);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Focus position configuration |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Notes
Only sensor modules with autofocus capability are supported
kd_mpi_sensor_get_focus_pos#
Get the current focus position.
Function Prototype
k_s32 kd_mpi_sensor_get_focus_pos(k_s32 fd, k_sensor_focus_pos *focus_pos);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output focus position |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_get_focus_caps#
Get focus capability information.
Function Prototype
k_s32 kd_mpi_sensor_get_focus_caps(k_s32 fd, k_sensor_autofocus_caps *caps);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
Output focus capability information |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
kd_mpi_sensor_set_focus_power#
Set the focus power state.
Function Prototype
k_s32 kd_mpi_sensor_set_focus_power(k_s32 fd, k_bool power);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor file descriptor |
Input |
|
|
K_TRUE: power on, K_FALSE: power off |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Information Query Interface#
kd_mpi_sensor_list_mode#
Gets the list of modes supported by the sensor.
Function Prototype
k_s32 kd_mpi_sensor_list_mode(const char *sensor_name, k_sensor_mode_list *list);
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor name |
Input |
|
|
Output mode list |
Output |
Return Value
Return Value |
Description |
|---|---|
|
Success |
Non- |
Failure, returns error code |
Notes
Returns up to 6 modes
Automatically matches the corresponding sensor_type and csi_num based on sensor_name
Example
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);
}
}
Opens the device based on the sensor name.
Function Prototype
Parameters
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
|
Sensor name |
Input |
Return Value
Return Value |
Description |
|---|---|
|
Sensor file descriptor |
|
Failure, returns error code |
Notes
This function is a convenience version of
kd_mpi_sensor_open()Internally, it finds the matching sensor configuration and opens the device
Typical Usage Flow#
// 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);
Notes#
fd Management: All operations depend on the fd returned by
kd_mpi_sensor_open(). You must callkd_mpi_sensor_close()to close it after use.Call Sequence: It is recommended to follow the order: Power on → Initialize → Configure → Enable stream.
Parameter Range: Before setting parameters such as gain and exposure, it is recommended to call the corresponding
get_*_range()interface to obtain the valid range.Sensor Differences: Different sensors may support different functions and parameter ranges, with specific capabilities determined by the driver.
Concurrent Access: Avoid multiple threads operating on the same sensor fd simultaneously.
Error Handling: All interfaces returning a non-zero value indicates failure. You should check the return value and handle it accordingly.
