1. Home
  2. Docs
  3. Cameras for Raspberry Pi
  4. Arducam MIPI Camera Modules
  5. MIPI_Camera API Introduction

MIPI_Camera API Introduction

Arducam MIPI Camera SDK provides the following APIs for MIPI camera

  • arducam_init_camera:  init camera
  • arducam_init_camera2: init camera with specific interface
  • arducam_set_resolution:  Set output resolution.
  • arducam_set_mode:  brief Set sensor mode.
  • arducam_get_format:  brief Get the current format.
  • arducam_set_video_callback:  Set video data output callback.
  • arducam_set_raw_callback:  Set raw data output callback.
  • arducam_capture:  Get single frame data.
  • arducam_release_buffer:  arducam_release_buffer.
  • arducam_start_preview:  Turn on image preview.
  • arducam_stop_preview:  Turn off image preview.
  • arducam_close_camera:  Release all resources and turn off the camera.
  • arducam_reset_control:  Set camera control to default value.
  • arducam_set_control:  Set camera control.
  • arducam_get_control: Get camera control value.
  • arducam_get_support_formats: Get the resolution supported by the current camera
  • arducam_get_support_controls: Get the control parameters supported by the current camera
  • arducam_write_sensor_reg:  brief Write sensor register.
  • arducam_read_sensor_reg: brief Read sensor register.
  • arducam_software_auto_exposure:  brief Enable/Disable software auto exposure 
  • arducam_software_auto_white_balance: brief Enable/Disable software auto white balance
  • arducam_unpack_raw10_to_raw8: brief Helper function, use to unpack mipi raw10.
  • arducam_unpack_raw10_to_raw16: brief Helper function, use to unpack mipi raw10.
  • arducam_manual_set_awb_compensation: used to compensate the red channel gain and blue change gain.

/**

int arducam_init_camera(CAMERA_INSTANCE *camera_instance);

  • init camera.
  • @param: camera_instance Pointer of type CAMERA_INSTANCE, use to
    obtain CAMERA_INSTANCE.
  • @return error code , 0 success, !0 error.
    • example:
      @code
      CAMERA_INStANCE camera_instance;
      arducam_init_camera(&camera_instance);
      @endcode
  • */

/**

int arducam_init_camera2(CAMERA_INSTANCE *camera_instance, struct camera_interface cam_interface);

  • init camera.
  • @param camera_instance Pointer of type CAMERA_INSTANCE, use to obtain CAMERA_INSTANCE.
  • @param camera_num Camera interface num.
  • @return error code , 0 success, !0 error.
    • example:
      @code
      CAMERA_INStANCE camera_instance;
      arducam_init_camera(&camera_instance, 0);
      @endcode
      @note Some boards have multiple camera interfaces.
  • */

/**

int arducam_set_resolution(CAMERA_INSTANCE camera_instance, int *width, int *height);

  • Set output resolution.
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param width Pointer of type int, Used to specify the width and return to the actual width.
  • @param height Pointer of type int, Used to specify the height and return to the actual height.
  • @return error code , 0 success, !0 error.
  • example:
    @code
    Int width = 1920;
    Int height = 1080;
    Int res = arducam_set_resolution(camera_instance, &width, &height);
    @endcode
    @note Some boards have multiple camera interfaces.
  • */

/**

int arducam_set_mode(CAMERA_INSTANCEcamera_instance, int mode);

 * @brief Set sensor mode

 *

 * @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.

 * @param mode Mode index.(You can use the list_format program to view the supported modes.)

 * @return error code , 0 success, !0 error.

 @code

    Int mode = 1;

    Int res = arducam_set_mode(camera_instance, mode);

 @endcode

 @note Some boards have multiple camera interfaces.

 * */

/**

int arducam_get_format(CAMERA_INSTANCE camera_instance, struct format *fmt);

  • @brief Get the current format.
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param fmt Pointer of type struct format, used to store format information.
  • @return ierror code , 0 success, !0 error.
    */

/**

int arducam_set_video_callback(CAMERA_INSTANCE camera_instance,

VIDEO_ENCODER_STATE *encoder_state, OUTPUT_CALLBACK callback, void *userdata);

  • Set video data output callback.
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param encoder_state Used to specify encoding parameters. Use default parameters if NULL.
  • @param callback Callback method, this method will be called when there is data return.
  • @param userdata Userdata, which will be a member of the buffer parameter in the callback function.
  • @return error code , 0 success, !0 error.
    • example:
      @code
      int video_callback(BUFFER *buffer) {
      buffer->userdata;
      }
      // start callback
      if(arducam_set_video_callback(camera_instance, NULL, video_callback, NULL)){
      printf(“set video callback failed.”);
      }
      // stop callback
      arducam_set_video_callback(camera_instance, NULL, NULL, NULL)
      @endcode
      @note Calling the arducam_set_resolution function before stopping video encoding will terminate the video encoding.
      @note The buffer will be automatically released after the callback function ends.
  • */

/**

int arducam_set_raw_callback(CAMERA_INSTANCE camera_instance, OUTPUT_CALLBACK

callback, void *userdata);

  • Set raw data output callback.
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param callback Callback method, this method will be called when there is data return.
  • @param userdata Userdata, which will be a member of the buffer parameter in the callback function.
  • @return error code , 0 success, !0 error.
    • example:
      @code
      int raw_callback(BUFFER *buffer) {
      buffer->userdata;
      }
      // start callback
      if(arducam_set_raw_callback(camera_instance, raw_callback, NULL)){
      printf(“set raw data callback failed.”);
      }
      // stop callback
      arducam_set_raw_callback(camera_instance, NULL, NULL)
      @endcode
      @note If you do a time-consuming operation in the callback, it will affect other parts, such as preview, video encoding(This issue may be fixed in the future).
      @note The buffer will be automatically released after the callback function ends.
  • */

/**

BUFFER *arducam_capture(CAMERA_INSTANCEcamera_instance, IMAGE_FORMAT *format, inttimeout);

  • Get single frame data.
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param format The data format to be obtained.
  • @param timeout This method will return NULL if no data is obtained at this time.
  • @return BUFFER structure pointer containing image data.
    • example:
      @code
      IMAGE_FORMAT fmt = {IMAGE_ENCODING_JPEG, 50};
      BUFFER *buffer = arducam_capture(camera_instance, &fmt, 3000);
      if (!buffer) {
      LOG(“capture timeout.”);
      return;
      }
      @endcode
      @note Currently supported image formats are:
      IMAGE_ENCODING_JPEG, IMAGE_ENCODING_I420, IMAGE_ENCODING_RAW_BAYER
      @note When the buffer is used, you need to call the arducam_release_buffer function to release it.
      @note The actual width and height of the raw bayer format and the yuv420 format are aligned, width 32 bytes aligned, and height 16 byte aligned.
  • */

/**

void arducam_release_buffer(BUFFER *buffer);

  • Used to release the memory occupied by the buffer.
    • @param buffer The buffer to be released.
  • */

/**

int arducam_start_preview(CAMERA_INSTANCE camera_instance, PREVIEW_PARAMS 

*preview_params);

  • Turn on image preview
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param preview_params Preview parameter,Use default parameters if NULL.
  • @return error code , 0 success, !0 error.
  • */

/**

int arducam_stop_preview(CAMERA_INSTANCEcamera_instance);

  • Turn off image preview
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @return error code , 0 success, !0 error.
  • */

/**

int arducam_close_camera(CAMERA_INSTANCEcamera_instance);

  • Release all resources and turn off the camera.
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @return error code , 0 success, !0 error.
  • */

/**

int arducam_reset_control(CAMERA_INSTANCE *camera_instance, intctrl_id);

  • Set camera control to default value.
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param ctrl_id Control id.
  • @return error code , 0 success, !0 error.
    • example:
      @code
      arducam_reset_control(camera_instance, V4L2_CID_EXPOSURE);
      @endcode
  • */

/**

int arducam_set_control(CAMERA_INSTANCEcamera_instance, int ctrl_id, intvalue);

  • Set camera control.
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param ctrl_id Control id.
  • @param value Control value.
  • @return error code , 0 success, !0 error.
    • example:
      @code
      arducam_set_control(camera_instance, V4L2_CID_EXPOSURE, 3000);
      @endcode
  • */

/**

int arducam_get_control(CAMERA_INSTANCE camera_instance, intctrl_id, int *value);

  • Get camera control value.
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param ctrl_id Control id.
  • @param value Current control value.
  • @return error code , 0 success, !0 error.
    • example:
      @code
      int exposure = 0;
      arducam_get_control(camera_instance, V4L2_CID_EXPOSURE, &exposure);
      printf(“Current exposure is %d\n”, exposure);
      @endcode
  • */

/**

int arducam_get_support_formats(CAMERA_INSTANCEcamera_instance, struct format *fmt, int index);

  • Get the resolution supported by the current camera
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param fmt Used to return resolution parameters.
  • @param index Format list index.
  • @return error code , 0 success, !0 error.
    • example:
      @code
      struct format support_fmt;
      unsigned int index = 0;
      while (!arducam_get_support_formats(camera_instance, &support_fmt, index++)) {
      printf(“index: %d, width: %d, height: %d\n”, index, support_fmt.width,
      support_fmt.height);
      }
      @endcode
  • */

/**

int arducam_get_support_controls(CAMERA_INSTANCEcamera_instance, struct camera_ctrl *cam_ctrl, int index);

  • Get the control parameters supported by the current camera.
    • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param cam_ctrl Used to return control parameters.
  • @param index Control list index.
  • @return error code , 0 success, !0 error.
    • example:
      @code
      unsigned int index = 0;
      struct camera_ctrl support_cam_ctrl;
      while (!arducam_get_support_controls(camera_instance, &support_cam_ctrl, index++)) {
      int value = 0;
      if (arducam_get_control(camera_instance, support_cam_ctrl.id, &value)) {
      printf(“Get ctrl %s fail.\n”, support_cam_ctrl.desc);
      }
      printf(“index: %d, CID: 0x%08X, desc: %s, min: %d, max: %d, default: %d, current: %d\n”,
      index, support_cam_ctrl.id, support_cam_ctrl.desc, support_cam_ctrl.min_value,
      support_cam_ctrl.max_value, support_cam_ctrl.default_value, value);
      }
      @endcode
  • */

/**

int arducam_write_sensor_reg(CAMERA_INSTANCE camera_instance, uint16_t address,

uint16_t value);

  • @brief Write sensor register.
    • @param camera_instance camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param address Sensor register address.
  • @param value The value you want to write
  • @return error code , 0 success, !0 error.
    */

/**

int arducam_read_sensor_reg(CAMERA_INSTANCE camera_instance, uint16_t address,

uint16_t *value);

  • @brief Read sensor register.
    • @param camera_instance camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param address Sensor register address.
  • @param value The address of the variable that stores the result.
  • @return error code , 0 success, !0 error.
    */

/**

int arducam_software_auto_exposure(CAMERA_INSTANCE camera_instance, int enable);

  • @brief Enable/Disable software auto exposure.
    • @param camera_instance camera_instance Type CAMERA_INSTANCE, Obtained from
      arducam_init_camera function.
  • @param enable 0 disable, !0 enable.
  • @return error code , 0 success, !0 error.
    • @note Calling the arducam_set_resolution function will turn off this feature.
      */

/**

int arducam_software_auto_white_balance(CAMERA_INSTANCE camera_instance, intenable);

  • @brief Enable/Disable software auto white balance.
    • @param camera_instance camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
  • @param enable 0 disable, !0 enable.
  • @return error code , 0 success, !0 error.
    • @note Calling the arducam_set_resolution function will turn off this feature.
      */

/**

BUFFER *arducam_unpack_raw10_to_raw8(uint8_t *buff_in, int width, int height);

  • @brief Helper function, use to unpack mipi raw10.
    • @param buff_in Raw10 data buffer.
  • @param width Image width
  • @param height Image height
  • @return BUFFER structure pointer containing image data.
    • @note This function will remove the part that is filled because of the alignment,
  • @note for example, the height is 1080, because the height needs 16 is the alignment,
  • @note so the actual pixel height is 1088. After passing the height of 1080 using this
  • @note function, the actual pixel height of the output is 1080.
    • @note The performance of this function is not very good.
      */

/**

BUFFER *arducam_unpack_raw10_to_raw16(uint8_t *buff_in, intwidth, int height);

  • @brief Helper function, use to unpack mipi raw10.
    • @param buff_in Raw10 data buffer.
  • @param width Image width
  • @param height Image height
  • @return BUFFER structure pointer containing image data.
    • @note This function will remove the part that is filled because of the alignment,
  • @note for example, the height is 1080, because the height needs 16 is the alignment,
  • @note so the actual pixel height is 1088. After passing the height of 1080 using this
  • @note function, the actual pixel height of the output is 1080.
    • @note The performance of this function is not very good.
      */

/**

void arducam_manual_set_awb_compensation(uint32_t r_gain, uint32_t b_gain);

  • @brief set awb function, use to compensation the rgain and bgain
    • @param r_gain the red channel compensation
  • @param b_gain the blue channel compensation
    */

Was this article helpful to you? Yes No 1