Camera

[Chinese]

Overview

The Camera module provides a unified camera controller management interface, supporting the operation and control of various camera devices.

• For detailed information on using CAMERA, please refer to:

  • DVP CAMERA use guide

  • UVC CAMERA use guide

• For example projects on using CAMERA, please refer to:

  • DVP CAMERA use example project

  • UVC CAMERA use example project

Key Features:

• Device Management: Supports opening, closing, and deleting camera controllers

• Stream Control: Provides functions to pause and resume video stream output

• IO Control: Supports multiple control commands through a unified ioctl interface

• Error Handling: Comprehensive parameter validation and error code return mechanism

Core API Functions:

• bk_camera_uvc_ctlr_new() - Create a UVC camera controller

• bk_camera_dvp_ctlr_new() - Create a DVP camera controller

• bk_camera_open() - Open a camera controller

• bk_camera_close() - Close a camera controller

• bk_camera_delete() - Delete a camera controller

• bk_camera_suspend() - Suspend video stream output

• bk_camera_resume() - Resume video stream output

• bk_camera_ioctl() - Camera IO control

This module adopts a unified controller handle interface design, calling specific hardware driver implementations through function pointers, providing a concise and consistent camera operation interface for upper-layer applications. All functions include comprehensive parameter validation to ensure system stability and security.

Call Flow

1. Create a controller via bk_camera_dvp_ctlr_new or bk_camera_uvc_ctlr_new

2. Open the camera using bk_camera_open

3. Perform specific control via bk_camera_ioctl (DVP-specific)

4. Close the camera using bk_camera_close

5. Delete the controller using bk_camera_delete

Note

1.Both DVP and UVC controllers need to be operated through the common interface after creation. 2.DVP has rich IO control commands, while UVC currently has limited IO control functions. 3.UVC does not involve power control, user need control power by themselves, please refer to the example.

Camera Ctlr API Reference

Header File

• bk_camera_ctlr.h

Functions

avdk_err_t bk_camera_uvc_ctlr_new(bk_camera_ctlr_handle_t *handle, bk_uvc_ctlr_config_t *config)

Create a new UVC camera controller.

This function creates and initializes a new UVC camera controller.

Parameters

• handle – Pointer to store the created controller handle

• config – Pointer to the UVC controller configuration

Returns

AVDK error code

avdk_err_t bk_camera_dvp_ctlr_new(bk_camera_ctlr_handle_t *handle, bk_dvp_ctlr_config_t *config)

Create a new DVP camera controller.

This function creates and initializes a new DVP camera controller.

Parameters

• handle – Pointer to store the created controller handle

• config – Pointer to the DVP controller configuration

Returns

AVDK error code

avdk_err_t bk_camera_open(bk_camera_ctlr_handle_t handle)

Open a camera controller.

This function opens the camera associated with the given controller handle.

Parameters

handle – Handle to the camera controller

Returns

AVDK error code

avdk_err_t bk_camera_close(bk_camera_ctlr_handle_t handle)

Close a camera controller.

This function closes the camera associated with the given controller handle.

Parameters

handle – Handle to the camera controller

Returns

AVDK error code

avdk_err_t bk_camera_suspend(bk_camera_ctlr_handle_t handle)

Suspend a camera controller.

This function suspends the camera associated with the given controller handle.

Parameters

handle – Handle to the camera controller

Returns

AVDK error code

avdk_err_t bk_camera_resume(bk_camera_ctlr_handle_t handle)

Resume a camera controller.

This function resumes the camera associated with the given controller handle.

Parameters

handle – Handle to the camera controller

Returns

AVDK error code

avdk_err_t bk_camera_ioctl(bk_camera_ctlr_handle_t handle, uint32_t cmd, void *arg)

Perform an IOCTL operation on a camera controller.

This function performs a device-specific IOCTL operation on the camera.

Parameters

• handle – Handle to the camera controller

• cmd – Command to execute

• arg – Argument for the command

Returns

AVDK error code

avdk_err_t bk_camera_delete(bk_camera_ctlr_handle_t handle)

Delete a camera controller.

This function deletes and cleans up the given camera controller.

Parameters

handle – Handle to the camera controller

Returns

AVDK error code

Camera Ctlr API Typedefs

Header File

• bk_camera_ctlr_types.h

Structures

struct bk_dvp_ctlr_config_t

DVP camera controller configuration structure.

This structure holds the configuration for a DVP (Digital Video Port) camera controller.

Public Members

bk_dvp_config_t config

DVP configuration parameters

const bk_dvp_callback_t *cbs

DVP callback functions

struct bk_uvc_ctlr_config_t

UVC camera controller configuration structure.

This structure holds the configuration for a UVC (USB Video Class) camera controller.

Public Members

bk_cam_uvc_config_t config

UVC configuration parameters

const bk_uvc_callback_t *cbs

UVC callback functions

struct bk_camera_ctlr

Camera controller interface.

This structure contains function pointers that define the operations available on a camera controller.

Public Members

avdk_err_t (*open)(bk_camera_ctlr_t *controller)

Open the camera.

Param controller

Pointer to the camera controller

Return

AVDK error code

avdk_err_t (*close)(bk_camera_ctlr_t *controller)

Close the camera.

Param controller

Pointer to the camera controller

Return

AVDK error code

avdk_err_t (*suspend)(bk_camera_ctlr_t *controller)

Suspend the camera.

Param controller

Pointer to the camera controller

Return

AVDK error code

avdk_err_t (*resume)(bk_camera_ctlr_t *controller)

Resume the camera.

Param controller

Pointer to the camera controller

Return

AVDK error code

avdk_err_t (*del)(bk_camera_ctlr_t *controller)

Delete the camera controller.

Param controller

Pointer to the camera controller

Return

AVDK error code

avdk_err_t (*ioctlr)(bk_camera_ctlr_t *controller, uint32_t cmd, void *arg)

IOCTL operation for the camera.

Param controller

Pointer to the camera controller

Param cmd

Command to execute

Param arg

Argument for the command

Return

AVDK error code

Type Definitions

typedef struct bk_camera_ctlr *bk_camera_ctlr_handle_t

Camera controller handle type.

This is an opaque handle to a camera controller instance.

typedef struct bk_camera_ctlr bk_camera_ctlr_t

Camera controller structure.

This structure defines the interface for camera controllers, providing function pointers for various camera operations.

Header File

• uvc_camera_types.h

Structures

struct uvc_separate_info_t

UVC Data Separation Information Structure.

Used to track the valid data after separating H.264/JPEG from raw data stream. This structure holds information about the location and length of valid data within a UVC data packet.

Public Members

uint32_t data_len

Length of the valid data in bytes

uint8_t *data_off

Pointer to the start of valid data within the packet

struct bk_uvc_callback_t

UVC Callback Functions Structure.

Contains function pointers for various UVC events and operations. These callbacks allow the application to respond to UVC events and manage frame buffer allocation and processing.

Attention

In the callback functions, no blocking operations or long operations should be performed, otherwise the hardware interrupt will be delayed, leading to abnormal image data.

Public Members

frame_buffer_t *(*malloc)(image_format_t format, uint32_t size)

Frame buffer allocation callback.

This function is called to allocate memory for a frame buffer.

Param format

Image format of the frame (e.g., MJPEG, YUV)

Param size

Size of memory to allocate in bytes

Return

Pointer to allocated frame buffer, or NULL on failure

void (*complete)(uint8_t port, image_format_t format, frame_buffer_t *frame, int result)

Frame processing completion callback.

This function is called when frame processing is complete.

Param port

Camera port number

Param format

Image format of the processed frame

Param frame

Pointer to the frame buffer containing the processed data

Param result

Result of the frame processing operation

void (*uvc_event_callback)(bk_usb_hub_port_info *port_info, void *arg, uvc_error_code_t code)

UVC event callback.

This function is called when UVC state changes occur.

Param port_info

Pointer to USB hub port information

Param arg

User-defined argument passed to the callback

Param code

UVC error code indicating the type of event

struct bk_cam_uvc_config_t

UVC Camera Configuration Structure.

Contains all configuration parameters needed for UVC camera initialization and operation. This structure is used when setting up a new UVC camera.

Public Members

uvc_stream_type_t type

Stream type (single or double stream)

uint8_t port

Camera port number (1-based indexing)

uint8_t drop_num

Number of frames to drop when UVC stream starts

image_format_t img_format

Image format (e.g., MJPEG, YUV, H264)

uint16_t width

Frame width in pixels

uint16_t height

Frame height in pixels

uint32_t fps

Frames per second (frame rate)

void *user_data

User-defined argument to pass to uvc_event_callback

struct uvc_separate_config_t

UVC Packet Separation Configuration Structure.

Contains configuration for handling UVC packet separation and processing. This structure defines callbacks for packet processing operations.

Public Members

uint8_t id

Camera port ID

void (*uvc_separate_packet_cb)(uint8_t *data, uint32_t length, uvc_separate_info_t *sepatate_info)

UVC packet separation callback.

This function is called to separate UVC packets from the raw data stream.

Param data

Pointer to the raw data

Param length

Length of the raw data in bytes

Param sepatate_info

Pointer to structure that will receive separation results

bk_err_t (*uvc_init_packet_cb)(bk_cam_uvc_config_t *device, uint8_t init, const bk_uvc_callback_t *cb)

UVC packet initialization callback.

This function is called to initialize UVC packet processing.

Param device

Pointer to UVC camera configuration

Param init

Initialization flag (1 for init, 0 for deinit)

Param cb

Pointer to UVC callback functions

Return

BK_ERR_NONE on success, error code on failure

void (*uvc_eof_packet_cb)(bk_cam_uvc_config_t *device)

UVC end-of-frame packet callback.

This function is called when an end-of-frame packet is received.

Param device

Pointer to UVC camera configuration

Macros

UVC_PORT_MAX

Maximum number of UVC ports.

This macro defines the maximum number of UVC ports supported, based on the USB host hub maximum external ports configuration.

BK_UVC_864X480_30FPS_MJPEG_CONFIG()

Default UVC Configuration for 864x480 Resolution at 30 FPS with MJPEG Format.

Provides a standard configuration for UVC camera initialization with:

• Resolution: 864x480 pixels

• Frame rate: 30 FPS

• Image format: MJPEG

• Single stream mode

• Port 1

• No frame dropping

• No user argument

BK_UVC_1920X1080_30FPS_H26X_CONFIG()

Enumerations

enum uvc_error_code_t

UVC Error Codes.

Defines the different types of UVC error codes that can occur during device operation.

Values:

enumerator BK_UVC_CONNECT

UVC device connected successfully

enumerator BK_UVC_CONFIG_ERROR

UVC configuration error occurred

enumerator BK_UVC_NO_MEMORY

Insufficient memory for UVC operations

enumerator BK_UVC_NO_RESOURCE

No available resources for UVC

enumerator BK_UVC_PPI_ERROR

PPI (Parallel Peripheral Interface) error

enumerator BK_UVC_DISCONNECT

UVC device disconnected

enumerator BK_UVC_NO_RESPON

UVC device not responding

enumerator BK_UVC_DMA_ERROR

DMA (Direct Memory Access) error

enumerator BK_UVC_NOT_PERMIT

Operation not permitted

enumerator BK_UVC_POWER_ERROR

Power supply error

enum uvc_stream_state_t

UVC Stream States.

Represents the different operational states of a UVC data stream.

Values:

enumerator UVC_STREAM_STATE_RUNNING

Stream is running normally

enumerator UVC_STREAM_STATE_RESUME

Stream is resumed from a suspended state

enumerator UVC_STREAM_STATE_SUSPEND

Stream is temporarily suspended

enum uvc_stream_type_t

UVC Stream Types.

Defines the streaming modes for UVC data transmission.

Values:

enumerator UVC_SINGLE_STREAM

Single stream mode - one data stream

enumerator UVC_DOUBLE_STREAM

Double stream mode - two simultaneous data streams

Header File

• dvp_camera_types.h

Structures

struct bk_dvp_io_config_t

DVP IO configuration structure.

Configuration parameters for DVP interface IO pins

Public Members

sensor_bits_width_t data_width

Data bus width

uint8_t data_pin[16]

Data IO pins (up to 16 pins)

uint8_t vsync_pin

Vertical sync IO pin

uint8_t hsync_pin

Horizontal sync IO pin

uint8_t xclk_pin

Core input clock to sensor

uint8_t pclk_pin

Sensor output clock to core

struct bk_dvp_i2c_config_t

DVP I2C configuration structure.

Configuration parameters for I2C interface used by DVP sensor

Public Members

uint8_t id

I2C bus ID

uint8_t scl_pin

I2C clock line IO pin

uint8_t sda_pin

I2C data line IO pin

uint32_t baud_rate

I2C bus baud rate

uint32_t flags

I2C configuration flags

struct bk_dvp_config_t

DVP camera configuration structure.

Complete configuration parameters for DVP camera

Public Members

bk_dvp_i2c_config_t i2c_config

I2C configuration

uint8_t reset_pin

Reset IO pin

uint8_t pwdn_pin

Power down IO pin

bk_dvp_io_config_t io_config

IO configuration

mclk_freq_t clk_source

Core input clock to sensor

uint16_t img_format

Image format

uint16_t width

Image width

uint16_t height

Image height

uint32_t fps

Frames per second

void *user_data

User data pointer

struct bk_dvp_callback_t

DVP camera callback functions.

Callback functions for DVP camera operations

Attention

In the callback functions, no blocking operations or long operations should be performed, otherwise the hardware interrupt will be delayed, leading to abnormal image data.

Public Members

frame_buffer_t *(*malloc)(image_format_t format, uint32_t size)

Allocate frame buffer.

Param format

Image format

Param size

Buffer size

Return

Pointer to allocated frame buffer

void (*complete)(image_format_t format, frame_buffer_t *frame, int result)

Frame completion callback.

Param format

Image format

Param frame

Pointer to frame buffer

Param result

Operation result

struct dvp_sensor_reg_val_t

DVP sensor register value structure.

Structure to hold sensor register address and value pairs

Public Members

uint32_t reg

Register address

uint32_t val

Register value

struct dvp_sensor_config_t

DVP sensor configuration structure.

Configuration parameters and function pointers for DVP sensor

Public Members

char *name

Sensor name

media_ppi_t def_ppi

Sensor default resolution

frame_fps_t def_fps

Sensor default FPS

mclk_freq_t clk

Sensor working clock for configured FPS and PPI

pixel_format_t fmt

Sensor input data format

sync_level_t vsync

Sensor VSYNC active level

sync_level_t hsync

Sensor HSYNC active level

uint16_t id

Sensor type (sensor_id_t)

uint16_t address

Sensor write register address by I2C

uint16_t fps_cap

Sensor supported FPS

uint16_t ppi_cap

Sensor supported resolutions

bool (*detect)(void)

Auto-detect used DVP sensor.

Return

true if sensor detected, false otherwise

int (*init)(void)

Initialize DVP sensor.

Return

0 on success, error code on failure

int (*set_ppi)(media_ppi_t ppi)

Set resolution of sensor.

Param ppi

Resolution to set

Return

0 on success, error code on failure

int (*set_fps)(frame_fps_t fps)

Set FPS of sensor.

Param fps

FPS to set

Return

0 on success, error code on failure

int (*power_down)(void)

Power down or reset sensor.

Return

0 on success, error code on failure

int (*read_register)(uint32_t reg, uint32_t *val)

Read sensor register.

Param reg

Register address

Param val

Pointer to store register value

Return

0 on success, error code on failure

int (*write_register)(uint32_t reg, uint32_t val)

Write sensor register.

Param reg

Register address

Param val

Register value to write

Return

0 on success, error code on failure

struct dvp_sensor_detect_func_t

Camera sensor detection function structure.

Public Members

const dvp_sensor_config_t *(*detect)(void)

Detection function pointer

Macros

H264_SELF_DEFINE_SEI_SIZE

Size of H.264 self-defined SEI data.

_SECTION_ATTR_IMPL(SECTION, COUNTER)

Section attribute macro implementation.

Parameters

• SECTION – Section name

• COUNTER – Counter

_CPIMTER_STRINGIFY(COUNTER)

Stringify macro.

Parameters

• COUNTER – Counter

BK_CAMERA_SENSOR_DETECT_SECTION(f)

Camera sensor detection function section registration macro.

This macro registers a sensor detection function into a dedicated section, enabling the system to automatically discover and run detection routines.

Parameters

• f – Detection function name

GC_QVGA_USE_SUBSAMPLE

Flag for QVGA subsample usage.

BK_DVP_864X480_30FPS_MJPEG_CONFIG()

DVP camera configuration for 864x480 resolution at 30 FPS with MJPEG format.

Predefined configuration macro for common DVP camera settings

Enumerations

enum sensor_id_t

DVP sensor ID types.

Enumeration of supported DVP sensor IDs

Values:

enumerator ID_UNKNOW

Unknown sensor ID

enumerator ID_PAS6329

PAS6329 sensor

enumerator ID_OV7670

OV7670 sensor

enumerator ID_PAS6375

PAS6375 sensor

enumerator ID_GC0328C

GC0328C sensor

enumerator ID_BF2013

BF2013 sensor

enumerator ID_GC0308C

GC0308C sensor

enumerator ID_HM1055

HM1055 sensor

enumerator ID_GC2145

GC2145 sensor

enumerator ID_OV2640

OV2640 sensor

enumerator ID_GC0308

GC0308 sensor

enumerator ID_TVP5150

TVP5150 sensor

enumerator ID_SC101

SC101 sensor

enum sensor_bits_width_t

Sensor data bit width types.

Enumeration of supported data bit widths for DVP sensors

Values:

enumerator SENSOR_BITS_WIDTH_8BIT

8-bit data width

enumerator SENSOR_BITS_WIDTH_10BIT

10-bit data width

enumerator SENSOR_BITS_WIDTH_12BIT

12-bit data width

enumerator SENSOR_BITS_WIDTH_16BIT

16-bit data width

enum dvp_ioctl_cmd_t

Values:

enumerator DVP_IOCTL_CMD_H264_IDR_RESET

Regenerate idr frame

enumerator DVP_IOCTL_CMD_SENSOR_WRITE_REGISTER

enumerator DVP_IOCTL_CMD_SENSOR_READ_REGISTER

Read sensor register