Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for the documentation for a specific release, use the drop-down menu on the left and select the desired version.

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.h

  • Related types: src/rtsmart/mpp/include/comm/k_sensor_comm.h

  • VICAP 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

const char*

Sensor name (e.g. “gc2093_csi2”)

Input

return value

Return Value

illustrate

>= 0

sensor file descriptor (fd)

< 0

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

fd

k_s32

sensor file descriptor

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

on

k_bool

K_TRUE: power on, K_FALSE: power off

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

mode

k_sensor_mode

Sensor working mode configuration

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

enable

k_s32

1: enabled, 0: disabled

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

sensor_id

k_u32*

Output sensor ID

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

mode

k_sensor_mode*

Output mode configuration

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

mode

k_sensor_mode

Mode configuration

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

enum_mode

k_sensor_enum_mode*

Enumeration mode information

Input/Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

caps

k_sensor_caps*

Output capability information

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

connection

k_s32*

Output connection status (1: connected, 0: not connected)

Output

return value

Return Value

illustrate

0

Success

Not 0

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

config

k_vicap_probe_config*

Probe configuration (CSI number, resolution, frame rate)

Input

info

k_vicap_sensor_info*

Output sensor information

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

reg_addr

k_u32

Register address

Input

reg_val

k_u32*

Output register value

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

reg_addr

k_u32

Register address

Input

reg_val

k_u32

Register value

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

gain

k_sensor_gain

Gain value structure

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

gain

k_sensor_gain*

Output gain value

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

gain

k_sensor_gain

Gain value structure

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

gain

k_sensor_gain*

Output gain value

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

time

k_sensor_intg_time

Integration time structure (unit: seconds)

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

time

k_sensor_intg_time*

Output integration time

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

range

k_sensor_exposure_time_range*

Output exposure range (unit: microseconds)

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

range

k_sensor_gain_info*

Output gain range

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

fps

k_u32

Frame rate value

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

fps

k_u32*

Output frame rate

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

isp_status

k_sensor_isp_status*

Output ISP status

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

blc

k_sensor_blc

Black level correction value (including R/Gr/Gb/B four channels)

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

wb

k_sensor_white_balance

White balance gain (including R/Gr/Gb/B four channels)

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

tpg

k_sensor_test_pattern

Test pattern configuration (enable/pattern)

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

tpg

k_sensor_test_pattern*

Output TPG configuration

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

curve

k_sensor_compand_curve*

Output expansion curve configuration

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

mirror

k_vicap_mirror_mode

Mirror mode configuration

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

otp_data

void*

Output OTP data buffer

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

otp_data

void*

OTP data buffer

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

focus_pos

k_sensor_focus_pos*

Focus position configuration

Input

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

focus_pos

k_sensor_focus_pos*

Output focus position

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

caps

k_sensor_autofocus_caps*

Output focus capability information

Output

return value

Return Value

illustrate

0

Success

Not 0

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

fd

k_s32

sensor file descriptor

Input

power

k_bool

K_TRUE: power on, K_FALSE: power off

Input

return value

Return Value

illustrate

0

Success

Not 0

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

const char*

Sensor name

Input

list

k_sensor_mode_list*

Output mode list

Output

return value

Return Value

illustrate

0

Success

Not 0

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

const char*

Sensor name

Input

return value

Return Value

illustrate

>= 0

sensor file descriptor

< 0

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.

Comments list
Comments
Log in