ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
ra8_ov5640.h File Reference
Camera services

Transport-independent OmniVision OV5640 sensor driver. More...

#include <stdint.h>
#include "ra8_err.h"
Include dependency graph for ra8_ov5640.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ra8_ov5640_bus_t
 Injected SCCB and time services. More...
struct  ra8_ov5640_t
 Caller-owned sensor instance; supports multiple independent parts. More...
struct  ra8_ov5640_jpeg_status_t
 Snapshot of the OV5640 JPEG pipeline and its most recent frame. More...

Typedefs

typedef ra8_err_t(* ra8_ov5640_read_fn_t) (void *ctx, uint8_t address, uint16_t reg, uint8_t *out_value)
typedef ra8_err_t(* ra8_ov5640_write_fn_t) (void *ctx, uint8_t address, uint16_t reg, uint8_t value)
typedef void(* ra8_ov5640_delay_fn_t) (void *ctx, uint32_t milliseconds)

Enumerations

enum  ra8_ov5640_id_t : uint16_t { k_ra8_ov5640_chip_id = 0x5640U }
 OV5640 identity and SCCB address constants. More...
enum  ra8_ov5640_addr_t : uint8_t {
  k_ra8_ov5640_addr_primary = 0x3CU ,
  k_ra8_ov5640_addr_secondary = 0x3DU
}
enum  ra8_ov5640_mode_t : uint8_t {
  k_ra8_ov5640_mode_vga_uyvy = 0U ,
  k_ra8_ov5640_mode_vga_jpeg = 1U
}
 Sensor output modes with validated register tables. More...
enum  ra8_ov5640_jpeg_quant_scale_t : uint8_t {
  k_ra8_ov5640_jpeg_quant_scale_min = 0x00U ,
  k_ra8_ov5640_jpeg_quant_scale_default = 0x0CU ,
  k_ra8_ov5640_jpeg_quant_scale_max = 0x3FU
}
 Raw OV5640 JPEG quantization-scale bounds and documented presets. More...

Functions

ra8_err_t ra8_ov5640_init (ra8_ov5640_t *dev, const ra8_ov5640_bus_t *bus)
 Bind a caller-supplied SCCB transport without touching the sensor.
ra8_err_t ra8_ov5640_probe (ra8_ov5640_t *dev, uint16_t *out_id)
 Probe both legal SCCB addresses and verify chip ID 0x5640.
ra8_err_t ra8_ov5640_configure (ra8_ov5640_t *dev, ra8_ov5640_mode_t mode)
 Software-reset and program one validated output mode.
ra8_err_t ra8_ov5640_set_jpeg_quantization_scale (ra8_ov5640_t *dev, uint8_t quant_scale)
 Set the sensor JPEG encoder's raw quantization scale.
ra8_err_t ra8_ov5640_jpeg_status_get (ra8_ov5640_t *dev, ra8_ov5640_jpeg_status_t *out_status)
 Snapshot sensor JPEG length, overflow, and routing controls.
ra8_err_t ra8_ov5640_stream_set (ra8_ov5640_t *dev, bool enabled)
 Enter software standby or resume sensor streaming.
ra8_err_t ra8_ov5640_read_reg (ra8_ov5640_t *dev, uint16_t reg, uint8_t *out_value)
 Read one sensor register through the bound transport.
ra8_err_t ra8_ov5640_write_reg (ra8_ov5640_t *dev, uint16_t reg, uint8_t value)
 Write one sensor register through the bound transport.

Detailed Description

Transport-independent OmniVision OV5640 sensor driver.

Tag
[Ring 4 / Service] {World: NS}

The driver owns the OV5640 register protocol and validated mode tables, but owns no RA8 peripheral or board pin. Callers inject single- register SCCB operations and a millisecond delay callback, following the same dependency-inversion pattern as ra8_lsm6dso.

Copyright
Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT
Since
0.1.0

Definition in file ra8_ov5640.h.

Typedef Documentation

◆ ra8_ov5640_delay_fn_t

typedef void(* ra8_ov5640_delay_fn_t) (void *ctx, uint32_t milliseconds)

Definition at line 57 of file ra8_ov5640.h.

◆ ra8_ov5640_read_fn_t

typedef ra8_err_t(* ra8_ov5640_read_fn_t) (void *ctx, uint8_t address, uint16_t reg, uint8_t *out_value)

Definition at line 52 of file ra8_ov5640.h.

◆ ra8_ov5640_write_fn_t

typedef ra8_err_t(* ra8_ov5640_write_fn_t) (void *ctx, uint8_t address, uint16_t reg, uint8_t value)

Definition at line 56 of file ra8_ov5640.h.

Enumeration Type Documentation

◆ ra8_ov5640_addr_t

enum ra8_ov5640_addr_t : uint8_t
Enumerator
k_ra8_ov5640_addr_primary 

Default seven-bit SCCB address.

k_ra8_ov5640_addr_secondary 

Alternate seven-bit SCCB address.

Definition at line 34 of file ra8_ov5640.h.

◆ ra8_ov5640_id_t

enum ra8_ov5640_id_t : uint16_t

OV5640 identity and SCCB address constants.

Enumerator
k_ra8_ov5640_chip_id 

Expected combined chip identifier.

Definition at line 30 of file ra8_ov5640.h.

◆ ra8_ov5640_jpeg_quant_scale_t

enum ra8_ov5640_jpeg_quant_scale_t : uint8_t

Raw OV5640 JPEG quantization-scale bounds and documented presets.

Enumerator
k_ra8_ov5640_jpeg_quant_scale_min 

Highest-quality raw scale.

k_ra8_ov5640_jpeg_quant_scale_default 

Vendor reset-scale value.

k_ra8_ov5640_jpeg_quant_scale_max 

Lowest-quality raw scale.

Definition at line 46 of file ra8_ov5640.h.

◆ ra8_ov5640_mode_t

enum ra8_ov5640_mode_t : uint8_t

Sensor output modes with validated register tables.

Enumerator
k_ra8_ov5640_mode_vga_uyvy 

Packed VGA UYVY DVP stream.

k_ra8_ov5640_mode_vga_jpeg 

Sensor-encoded VGA JPEG stream.

Definition at line 40 of file ra8_ov5640.h.

Function Documentation

◆ ra8_ov5640_configure()

ra8_err_t ra8_ov5640_configure ( ra8_ov5640_t * dev,
ra8_ov5640_mode_t mode )
nodiscard

Software-reset and program one validated output mode.

Applies the proven VGA UYVY base table, optionally switches the sensor JPEG engine, then verifies critical register readbacks.

Parameters
[in,out]devProbed sensor instance.
[in]modeValidated output mode to program.
Returns
Error code.
Return values
k_ra8_okThe selected mode was programmed and verified.
k_ra8_err_not_supportedmode has no validated table.
k_ra8_err_not_initializeddev was not initialized.
otherPropagated SCCB transaction or readback error.
Precondition
ra8_ov5640_probe selected a responding sensor address.
Sensor XCLK remains running throughout configuration.
Postcondition
On success the sensor is awake and streaming the selected mode.
On success critical output registers match their expected masks.
Note
Not thread-safe with respect to the same instance or transport.
Since
0.1.0

Definition at line 801 of file ra8_ov5640.c.

References ra8_ov5640_t::bus, ra8_ov5640_bus_t::ctx, ra8_ov5640_bus_t::delay_ms, ra8_ov5640_t::initialized, internal_ov5640_configure_jpeg(), internal_ov5640_verify_jpeg(), internal_ov5640_verify_uyvy(), internal_ov5640_write_vga_base(), k_ov5640_cfg_settle_ms, k_ov5640_reg_sw_reset, k_ov5640_reset_guard_ms, k_ov5640_sw_reset_hold, k_ra8_err_not_initialized, k_ra8_err_not_supported, k_ra8_ok, k_ra8_ov5640_mode_vga_jpeg, k_ra8_ov5640_mode_vga_uyvy, RA8_CHECK_NULL_PTR, and ra8_ov5640_write_reg().

Referenced by c6_cam_camera_init(), cam_prepare_capture(), and internal_bring_up_sensor().

◆ ra8_ov5640_init()

ra8_err_t ra8_ov5640_init ( ra8_ov5640_t * dev,
const ra8_ov5640_bus_t * bus )
nodiscard

Bind a caller-supplied SCCB transport without touching the sensor.

Copies the transport callbacks and selects the primary address.

Parameters
[out]devCaller-owned sensor instance to initialize.
[in]busRead, write, delay, and opaque-context callbacks.
Returns
Error code.
Return values
k_ra8_okThe instance was initialized.
k_ra8_err_null_ptrAn argument or mandatory callback was nullptr.
Precondition
dev points to writable storage.
bus and its callbacks remain valid for the instance lifetime.
Postcondition
On success dev is ready for probe and register access.
No SCCB transaction or delay callback has occurred.
Note
Independent instances are thread-safe when their transports are.
Since
0.1.0

Definition at line 484 of file ra8_ov5640.c.

References ra8_ov5640_bus_t::delay_ms, k_ra8_ok, k_ra8_ov5640_addr_primary, RA8_CHECK_NULL_PTR, ra8_ov5640_bus_t::read_reg, and ra8_ov5640_bus_t::write_reg.

Referenced by cam_sensor_bind(), internal_c6_cam_sensor_bind(), and sensor_bind().

◆ ra8_ov5640_jpeg_status_get()

ra8_err_t ra8_ov5640_jpeg_status_get ( ra8_ov5640_t * dev,
ra8_ov5640_jpeg_status_t * out_status )
nodiscard

Snapshot sensor JPEG length, overflow, and routing controls.

Reads the documented JPEG length and status registers plus the input-format, header-output, and compression-enable controls.

Parameters
[in,out]devSensor instance initialized by ra8_ov5640_init.
[out]out_statusCaller-owned destination for the decoded snapshot.
Returns
Error code.
Return values
k_ra8_okEvery status register was read and decoded.
k_ra8_err_null_ptrdev or out_status was nullptr.
k_ra8_err_not_initializeddev has not been initialized.
otherPropagated SCCB read error.
Precondition
Sensor XCLK is running and the bound SCCB transport is idle.
out_status points to writable storage.
Postcondition
On success out_status describes the sampled sensor state.
Sensor configuration and streaming state remain unchanged.
Note
Stop streaming before this call when a frame-coherent length is needed.
Not thread-safe with respect to the same instance or transport.
Since
0.1.0

Definition at line 936 of file ra8_ov5640.c.

References ra8_ov5640_jpeg_status_raw_t::height_hi, ra8_ov5640_jpeg_status_raw_t::height_lo, ra8_ov5640_jpeg_status_raw_t::href_minimum, ra8_ov5640_t::initialized, internal_ov5640_read_jpeg_status(), ra8_ov5640_jpeg_status_raw_t::jpeg_ctrl01, ra8_ov5640_jpeg_status_raw_t::jpeg_header, ra8_ov5640_jpeg_status_raw_t::jpeg_input, k_ov5640_dimension_hi_shift, k_ov5640_jfifo_overflow_mask, k_ov5640_jpeg_enable_mask, k_ov5640_jpeg_header_mask, k_ov5640_jpeg_input_yuv422_mask, k_ov5640_jpeg_length_hi_shift, k_ov5640_jpeg_length_mid_shift, k_ra8_err_not_initialized, k_ra8_ok, ra8_ov5640_jpeg_status_raw_t::length_hi, ra8_ov5640_jpeg_status_raw_t::length_lo, ra8_ov5640_jpeg_status_raw_t::length_mid, ra8_ov5640_jpeg_status_raw_t::overflow, RA8_CHECK_NULL_PTR, ra8_ov5640_jpeg_status_raw_t::timing_ctrl21, ra8_ov5640_jpeg_status_raw_t::vfifo_ctrl00, ra8_ov5640_jpeg_status_raw_t::width_hi, and ra8_ov5640_jpeg_status_raw_t::width_lo.

Referenced by c6_cam_camera_capture_jpeg().

◆ ra8_ov5640_probe()

ra8_err_t ra8_ov5640_probe ( ra8_ov5640_t * dev,
uint16_t * out_id )
nodiscard

Probe both legal SCCB addresses and verify chip ID 0x5640.

Reads the two identification registers at 0x3C, then 0x3D.

Parameters
[in,out]devInitialized caller-owned sensor instance.
[out]out_idLast chip ID read, or the verified OV5640 ID.
Returns
Error code.
Return values
k_ra8_okAn OV5640 was found and selected.
k_ra8_err_not_foundNeither legal address returned the expected ID.
k_ra8_err_null_ptrAn argument was nullptr.
k_ra8_err_not_initializeddev was not initialized.
Precondition
ra8_ov5640_init completed successfully.
Sensor XCLK is running and hardware reset is released.
Postcondition
On success dev retains the responding SCCB address.
On failure dev returns to the primary SCCB address.
Note
Not thread-safe with respect to the same instance or transport.
Since
0.1.0

Definition at line 612 of file ra8_ov5640.c.

References ra8_ov5640_t::address, ra8_ov5640_t::initialized, internal_ov5640_read_chip_id(), k_ra8_err_not_found, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_ov5640_addr_primary, k_ra8_ov5640_addr_secondary, k_ra8_ov5640_chip_id, and RA8_CHECK_NULL_PTR.

Referenced by c6_cam_camera_init(), cam_run(), and internal_bring_up_sensor().

◆ ra8_ov5640_read_reg()

ra8_err_t ra8_ov5640_read_reg ( ra8_ov5640_t * dev,
uint16_t reg,
uint8_t * out_value )
nodiscard

Read one sensor register through the bound transport.

Dispatches one 16-bit-register SCCB read at the selected address.

Parameters
[in,out]devInitialized sensor instance.
[in]regSensor register address.
[out]out_valueRegister byte on success.
Returns
Error code.
Return values
k_ra8_okThe byte was read.
k_ra8_err_null_ptrdev or out_value was nullptr.
k_ra8_err_not_initializeddev was not initialized.
otherPropagated transport error.
Precondition
ra8_ov5640_init completed successfully.
The bound transport is idle and the sensor is clocked.
Postcondition
On success out_value contains the register byte.
The selected device address is unchanged.
Note
Not thread-safe with respect to the same instance or transport.
Since
0.1.0

Definition at line 500 of file ra8_ov5640.c.

References ra8_ov5640_t::address, ra8_ov5640_t::bus, ra8_ov5640_bus_t::ctx, ra8_ov5640_t::initialized, k_ra8_err_not_initialized, RA8_CHECK_NULL_PTR, and ra8_ov5640_bus_t::read_reg.

Referenced by internal_ov5640_read_chip_id(), internal_ov5640_read_jpeg_status(), internal_ov5640_read_jpeg_status_format(), internal_ov5640_update_bits(), internal_ov5640_verify(), and sensor_report_register().

◆ ra8_ov5640_set_jpeg_quantization_scale()

ra8_err_t ra8_ov5640_set_jpeg_quantization_scale ( ra8_ov5640_t * dev,
uint8_t quant_scale )
nodiscard

Set the sensor JPEG encoder's raw quantization scale.

Programs JPEG CTRL07 bits [5:0]. The legal range is 0..63 and a smaller value produces higher quality. This is the sensor's raw scale, not a synthetic 1..100 quality percentage.

Parameters
[in,out]devSensor instance initialized by ra8_ov5640_init.
[in]quant_scaleRaw OV5640 quantization scale in the inclusive range [k_ra8_ov5640_jpeg_quant_scale_min, k_ra8_ov5640_jpeg_quant_scale_max].
Returns
k_ra8_ok on success, or the transport/validation error.
Return values
k_ra8_err_invalid_argquant_scale exceeds 63.
k_ra8_err_not_initializeddev has not been initialized.
otherPropagated SCCB read or write error.
Precondition
ra8_ov5640_init completed successfully.
JPEG mode was selected before changing its encoder scale.
Postcondition
On success JPEG CTRL07 bits [5:0] equal quant_scale.
Unrelated JPEG CTRL07 bits retain their prior values.
Note
Not thread-safe with respect to the same instance or transport.
Since
0.1.0

Definition at line 833 of file ra8_ov5640.c.

References ra8_ov5640_t::initialized, internal_ov5640_update_bits(), k_ov5640_jpeg_quant_scale_mask, k_ov5640_reg_jpeg_quality, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ov5640_jpeg_quant_scale_max, and RA8_CHECK_NULL_PTR.

◆ ra8_ov5640_stream_set()

ra8_err_t ra8_ov5640_stream_set ( ra8_ov5640_t * dev,
bool enabled )
nodiscard

Enter software standby or resume sensor streaming.

Writes the OV5640 system-control streaming state and waits for the transition to settle through the injected delay callback.

Parameters
[in,out]devInitialized sensor instance.
[in]enabledtrue to stream, false for software standby.
Returns
Error code.
Return values
k_ra8_okThe requested state was written.
k_ra8_err_not_initializeddev was not initialized.
otherPropagated SCCB write error.
Precondition
ra8_ov5640_init completed successfully.
Sensor XCLK remains running.
Postcondition
On success the sensor is in the requested streaming state.
Note
Not thread-safe with respect to the same instance or transport.
Since
0.1.0

Definition at line 971 of file ra8_ov5640.c.

References ra8_ov5640_t::bus, ra8_ov5640_bus_t::ctx, ra8_ov5640_bus_t::delay_ms, ra8_ov5640_t::initialized, k_ov5640_reg_sw_reset, k_ov5640_stream_settle_ms, k_ov5640_sw_reset_wake, k_ov5640_sw_standby, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and ra8_ov5640_write_reg().

Referenced by c6_cam_camera_capture_jpeg().

◆ ra8_ov5640_write_reg()

ra8_err_t ra8_ov5640_write_reg ( ra8_ov5640_t * dev,
uint16_t reg,
uint8_t value )
nodiscard

Write one sensor register through the bound transport.

Dispatches one 16-bit-register SCCB write at the selected address.

Parameters
[in,out]devInitialized sensor instance.
[in]regSensor register address.
[in]valueRegister byte to write.
Returns
Error code.
Return values
k_ra8_okThe byte was written.
k_ra8_err_null_ptrdev was nullptr.
k_ra8_err_not_initializeddev was not initialized.
otherPropagated transport error.
Precondition
ra8_ov5640_init completed successfully.
The bound transport is idle and the sensor is clocked.
Postcondition
On success the transport accepted the complete register write.
The selected device address is unchanged.
Note
Not thread-safe with respect to the same instance or transport.
Since
0.1.0

Definition at line 511 of file ra8_ov5640.c.

References ra8_ov5640_t::address, ra8_ov5640_t::bus, ra8_ov5640_bus_t::ctx, ra8_ov5640_t::initialized, k_ra8_err_not_initialized, RA8_CHECK_NULL_PTR, and ra8_ov5640_bus_t::write_reg.

Referenced by internal_ov5640_configure_jpeg(), internal_ov5640_update_bits(), internal_ov5640_write_vga_base(), ra8_ov5640_configure(), and ra8_ov5640_stream_set().