K230 Sensor API Reference#
Overview#
The Sensor API is used to complete the opening, power-on, initialization, mode switching, register reading and writing, and runtime parameter adjustment of the image sensor device. This set of interfaces mainly corresponds to the sensor driver control surface and is usually 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 relevant data type definitions are located at 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
Fast Index#
Device Life Cycle Management#
Device information and mode management#
Register access#
Exposure and gain control#
Frame rate control#
Image quality control#
OTP and focus control#
Information query interface#
Interface detailed description#
Equipment life cycle management#
kd_mpi_sensor_open#
Turn on the sensor device.
Function prototype
k_s32 kd_mpi_sensor_open(const char *sensor_name);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
Sensor name (e.g. “gc2093_csi2”) |
Input |
return value
Return Value |
illustrate |
|---|---|
|
sensor file descriptor (fd) |
|
Failure, return error code |
Notes
The returned fd is used for all subsequent sensor operations
After use, you must call
kd_mpi_sensor_close()to shut down the device.The 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#
Turn off the sensor device.
Function prototype
k_s32 kd_mpi_sensor_close(k_s32 fd);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
fd is no longer valid after closing
Must be paired with
kd_mpi_sensor_open()
kd_mpi_sensor_power_set#
Set sensor power state.
Function prototype
k_s32 kd_mpi_sensor_power_set(k_s32 fd, k_bool on);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
K_TRUE: power on, K_FALSE: power off |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
Initialization and configuration can only be performed after power-on.
Make sure data flow is stopped before powering off
kd_mpi_sensor_init#
Initialize the sensor device.
Function prototype
k_s32 kd_mpi_sensor_init(k_s32 fd, k_sensor_mode mode);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Sensor working mode configuration |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
Must be called after power-on
The mode structure needs to correctly configure parameters such as resolution, frame rate, etc.
kd_mpi_sensor_stream_enable#
Enable or disable sensor data streaming.
Function prototype
k_s32 kd_mpi_sensor_stream_enable(k_s32 fd, k_s32 enable);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
1: enabled, 0: disabled |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
After enabling, the sensor begins to output image data
Stops output when disabled but keeps configuration
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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output sensor ID |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
kd_mpi_sensor_mode_get#
Get the current sensor mode configuration.
Function prototype
k_s32 kd_mpi_sensor_mode_get(k_s32 fd, k_sensor_mode *mode);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output mode configuration |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
kd_mpi_sensor_mode_set#
Set the sensor working mode.
Function prototype
k_s32 kd_mpi_sensor_mode_set(k_s32 fd, k_sensor_mode mode);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Mode configuration |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Enumeration mode information |
Input/Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output capability information |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output connection status (1: connected, 0: not connected) |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
Probe configuration (CSI number, resolution, frame rate) |
Input |
|
|
Output sensor information |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Register access#
kd_mpi_sensor_reg_read#
Read the sensor register.
Function prototype
k_s32 kd_mpi_sensor_reg_read(k_s32 fd, k_u32 reg_addr, k_u32 *reg_val);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Register address |
Input |
|
|
Output register value |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
for debugging or special configuration
Register address and bit width vary from sensor to sensor
kd_mpi_sensor_reg_write#
Write to sensor register.
Function prototype
k_s32 kd_mpi_sensor_reg_write(k_s32 fd, k_u32 reg_addr, k_u32 reg_val);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Register address |
Input |
|
|
Register value |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
Wrong register configuration may cause the sensor to work abnormally
It is recommended to refer to the sensor data sheet
Exposure and gain control#
kd_mpi_sensor_again_set#
Set the analog gain (Again).
Function prototype
k_s32 kd_mpi_sensor_again_set(k_s32 fd, k_sensor_gain gain);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Gain value structure |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
The gain value must be within the sensor support range
It is recommended to call
kd_mpi_sensor_get_gain_range()first to get 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output gain value |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Gain value structure |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output gain value |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
kd_mpi_sensor_intg_time_set#
Set the integration time (exposure time).
Function prototype
k_s32 kd_mpi_sensor_intg_time_set(k_s32 fd, k_sensor_intg_time time);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Integration time structure (unit: seconds) |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
The integration time must be within the sensor support range
It is recommended to call
kd_mpi_sensor_get_exposure_time_range()first to get 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output integration time |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
kd_mpi_sensor_get_exposure_time_range#
Get the exposure time range. Need to be called after start
Function prototype
k_s32 kd_mpi_sensor_get_exposure_time_range(k_s32 fd, k_sensor_exposure_time_range *range);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output exposure range (unit: microseconds) |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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. Need to be called after start
Function prototype
k_s32 kd_mpi_sensor_get_gain_range(k_s32 fd, k_sensor_gain_info *range);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output gain range |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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 sensor frame rate.
Function prototype
k_s32 kd_mpi_sensor_fps_set(k_s32 fd, k_u32 fps);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Frame rate value |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output frame rate |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output ISP status |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Black level correction value (including R/Gr/Gb/B four channels) |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
White balance gain (including R/Gr/Gb/B four channels) |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
kd_mpi_sensor_tpg_set#
Set up the test pattern generator (TPG).
Function prototype
k_s32 kd_mpi_sensor_tpg_set(k_s32 fd, k_sensor_test_pattern tpg);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Test pattern configuration (enable/pattern) |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
TPG is used for debugging and does not rely 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output TPG configuration |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
kd_mpi_sensor_expand_curve_get#
Get the expansion curve configuration.
Function prototype
k_s32 kd_mpi_sensor_expand_curve_get(k_s32 fd, k_sensor_compand_curve *curve);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output expansion curve configuration |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Mirror mode configuration |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output OTP data buffer |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
OTP data buffer |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
OTP writing operations require caution as they may be irreversible
kd_mpi_sensor_set_focus_pos#
Set the focus position.
Function prototype
k_s32 kd_mpi_sensor_set_focus_pos(k_s32 fd, k_sensor_focus_pos *focus_pos);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Focus position configuration |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
Only supports sensor modules with autofocus function
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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output focus position |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
Output focus capability information |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
kd_mpi_sensor_set_focus_power#
Set the focus power status.
Function prototype
k_s32 kd_mpi_sensor_set_focus_power(k_s32 fd, k_bool power);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
sensor file descriptor |
Input |
|
|
K_TRUE: power on, K_FALSE: power off |
Input |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Information query interface#
kd_mpi_sensor_list_mode#
Get 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);
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
Sensor name |
Input |
|
|
Output mode list |
Output |
return value
Return Value |
illustrate |
|---|---|
|
Success |
Not |
Failure, return error code |
Notes
Returns up to 6 patterns
Automatically match 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);
}
}
Open the device based on the sensor name.
Function prototype
parameter
parameter |
type |
illustrate |
Input/Output |
|---|---|---|---|
|
|
Sensor name |
Input |
return value
Return Value |
illustrate |
|---|---|
|
sensor file descriptor |
|
Failure, return error code |
Notes
This function is a convenience version of
kd_mpi_sensor_open()Internally it looks for a matching sensor configuration and opens the device
Typical usage process#
// 1. Open sensor
k_s32 fd = kd_mpi_sensor_open("gc2093_csi2");
if (fd < 0) {
printf("Failed to open sensor\n");
return -1;
}
// 2. Power on
kd_mpi_sensor_power_set(fd, K_TRUE);
// 3. Initialize (configure mode)
k_sensor_mode mode;
// ... Configure mode structure ...
kd_mpi_sensor_init(fd, mode);
// 4. Adjust parameters (optional)
kd_mpi_sensor_fps_set(fd, 30);
kd_mpi_sensor_again_set(fd, gain);
// 5. Enable data stream
kd_mpi_sensor_stream_enable(fd, 1);
// ... Use sensor ...
// 6. Disable data stream
kd_mpi_sensor_stream_enable(fd, 0);
// 7. Power off
kd_mpi_sensor_power_set(fd, K_FALSE);
// 8. Close device
kd_mpi_sensor_close(fd);
Things to note#
fd management: All operations depend on the fd returned by
kd_mpi_sensor_open(). After use,kd_mpi_sensor_close()must be called to close.Calling sequence: It is recommended to call in the order of power on → initialization → configuration → enable flow.
Parameter range: Before setting parameters such as gain and exposure, it is recommended to call the corresponding
get_*_range()interface to obtain the effective range.Sensor differences: Different sensors may support different functions and parameter ranges, and the specific capabilities are determined by the driver.
Concurrent access: Avoid multiple threads operating the same sensor fd at the same time.
Error handling: All interfaces returning non-0 values indicate failure. The return value should be checked and processed accordingly.
