TMF8829 Universal Driver 0.1.0
Loading...
Searching...
No Matches
tmf8829.h File Reference

Public API for the portable TMF8829 driver. More...

#include "tmf8829/tmf8829_version.h"
#include "tmf8829_ops.h"
#include "tmf8829_regs.h"
#include "tmf8829_types.h"
Include dependency graph for tmf8829.h:

Go to the source code of this file.

Data Structures

struct  tmf8829_driver
 One driver instance per physical TMF8829. More...

Macros

#define TMF8829_ENABLE_CAP_DISCHARGE_US
 Microseconds to hold the enable pin low before power-on (cap discharge).
#define TMF8829_ENABLE_RAMP_US
 Microseconds to wait after driving enable high before polling CPU ready.
#define TMF8829_CPU_READY_TIMEOUT_MS
 Default millisecond budget for tmf8829_is_cpu_ready inside tmf8829_enable.
#define TMF8829_WAKEUP_CPU_READY_TIMEOUT_MS
 Millisecond budget passed to tmf8829_is_cpu_ready from tmf8829_wakeup (vendor ENABLE_TIME_MS).

Typedefs

typedef void(* tmf8829_log_fn) (tmf8829_driver_t *drv, int level, const char *msg)
 Optional host logging callback (not invoked unless the driver calls it).
typedef void(* tmf8829_on_stream_header_fn) (tmf8829_driver_t *drv, const uint8_t *data, uint16_t len)
 Invoked once per FIFO read with the fused pre-header and frame header.
typedef void(* tmf8829_on_result_fn) (tmf8829_driver_t *drv, const uint8_t *data, uint16_t len)
 Invoked for each result payload chunk read from the FIFO.
typedef void(* tmf8829_on_histogram_fn) (tmf8829_driver_t *drv, const uint8_t *data, uint16_t len)
 Invoked for each histogram payload chunk read from the FIFO.
typedef void(* tmf8829_on_error_fn) (tmf8829_driver_t *drv, int err)
 Optional error reporter (driver may call when a recoverable issue occurs).
typedef int(* tmf8829_fw_image_read_fn) (tmf8829_driver_t *drv, uint32_t offset, uint8_t *buf, uint32_t len, uint32_t *image_total_size)
 Read-only access to a firmware image for tmf8829_download_firmware.

Functions

int tmf8829_init (tmf8829_driver_t *drv, const tmf8829_ops_t *ops)
 Validate parameters, bind ops, and reset driver state.
int tmf8829_set_log_level (tmf8829_driver_t *drv, uint8_t level)
 Update tmf8829_driver_t::log_level for optional tmf8829_driver_t::log use.
int tmf8829_enable (tmf8829_driver_t *drv)
 Drive the enable pin high and wait for CPU ready.
int tmf8829_disable (tmf8829_driver_t *drv)
 Drive the enable pin low (sensor off).
int tmf8829_is_cpu_ready (tmf8829_driver_t *drv, uint8_t timeout_ms)
 Poll TMF8829_REG_ENABLE until TMF8829_ENABLE_CPU_READY_MASK is set or time elapses.
int tmf8829_get_and_clr_interrupts (tmf8829_driver_t *drv, uint8_t mask, uint8_t *out_pending)
 Read TMF8829_REG_INT_STATUS and write-1-to-clear bits in mask.
int tmf8829_clr_and_enable_interrupts (tmf8829_driver_t *drv, uint8_t mask)
 Read-modify-write TMF8829_REG_INT_ENAB to enable mask bits.
int tmf8829_disable_interrupts (tmf8829_driver_t *drv, uint8_t mask)
 Read-modify-write TMF8829_REG_INT_ENAB to disable mask bits.
int tmf8829_soft_reset (tmf8829_driver_t *drv)
 Write TMF8829_RESET_SOFT_MASK to TMF8829_REG_RESET and reset clock-correction state.
int tmf8829_hard_reset (tmf8829_driver_t *drv)
 Write TMF8829_RESET_HARD_MASK to TMF8829_REG_RESET and wait until CPU is ready.
int tmf8829_standby (tmf8829_driver_t *drv)
 Request standby if the CPU is running (sets TMF8829_ENABLE_POFF_MASK).
int tmf8829_power_up (tmf8829_driver_t *drv)
 Assert power-on (TMF8829_ENABLE_PON_MASK) and wait TMF8829_ENABLE_RAMP_US.
int tmf8829_wakeup (tmf8829_driver_t *drv)
 Leave low-power: if CPU not ready, set RAM boot path + PON and poll readiness.
int tmf8829_is_device_wakeup (tmf8829_driver_t *drv, uint8_t *out_awake)
 Non-blocking wakeup check: reads enable register and CPU-ready bit.
int tmf8829_read_device_info (tmf8829_driver_t *drv)
 Read serial number, app version, and chip id registers into drv.
int tmf8829_command (tmf8829_driver_t *drv, uint8_t cmd, uint16_t timeout_ms)
 Issue a raw application command byte and poll TMF8829_REG_CMD_STAT for acceptance.
int tmf8829_cmd_load_config_page (tmf8829_driver_t *drv)
 TMF8829_CMD_LOAD_CONFIG_PAGE
int tmf8829_cmd_write_page (tmf8829_driver_t *drv)
 TMF8829_CMD_WRITE_PAGE using tmf8829_driver_t::config
int tmf8829_get_configuration (tmf8829_driver_t *drv)
 After tmf8829_cmd_load_config_page, read the configuration page into tmf8829_driver_t::config.
int tmf8829_set_configuration (tmf8829_driver_t *drv)
 Write tmf8829_driver_t::config to the device (load page + write page sequence).
int tmf8829_start_measurement (tmf8829_driver_t *drv)
 TMF8829_CMD_MEASURE
int tmf8829_stop_measurement (tmf8829_driver_t *drv)
 TMF8829_CMD_STOP
int tmf8829_bootloader_spi_off (tmf8829_driver_t *drv)
 Bootloader: TMF8829_BL_CMD_STAT_SPI_OFF.
int tmf8829_bootloader_i2c_off (tmf8829_driver_t *drv)
 Bootloader: TMF8829_BL_CMD_STAT_I2C_OFF.
int tmf8829_download_firmware (tmf8829_driver_t *drv, uint32_t image_start_addr, int use_fifo)
 Stream firmware through tmf8829_driver_t::fw_image_read and start the RAM application.
int tmf8829_read_results (tmf8829_driver_t *drv)
 Read a result frame from the FIFO (header via TMF8829_REG_FIFO_STATUS, payload via TMF8829_REG_FIFO).
int tmf8829_read_histogram (tmf8829_driver_t *drv)
 Read a histogram frame from the FIFO (same header path as results).
uint16_t tmf8829_get_uint16 (const uint8_t *data)
 Little-endian uint16 from two bytes.
uint32_t tmf8829_get_uint32 (const uint8_t *data)
 Little-endian uint32 from four bytes.
void tmf8829_set_uint16 (uint16_t value, uint8_t *data)
 Write value to two bytes, little-endian.
uint8_t tmf8829_get_pixel_size (uint8_t layout)
 Bytes per result pixel for a given TMF8829_REG_CFG_RESULT_FORMAT layout byte.
uint16_t tmf8829_correct_distance (const tmf8829_driver_t *drv, uint16_t distance)
 Scale a raw distance using tmf8829_driver_t::_clk_corr_ratio_uq (UQ15).
void tmf8829_correct_distance_data_segment (tmf8829_driver_t *drv, uint16_t size, uint8_t layout)
 Apply tmf8829_correct_distance to each distance field in tmf8829_driver_t::buffer.
int tmf8829_clk_correction_set (tmf8829_driver_t *drv, uint8_t enable)
 Enable or disable collection of clock-correction samples in result reads.
uint16_t tmf8829_clk_correction_ratio_uq15 (const tmf8829_driver_t *drv)
 Current UQ15 ratio used by tmf8829_correct_distance; nominal unity is 32768.
int tmf8829_set_i2c_address (tmf8829_driver_t *drv, uint8_t new_addr)
 Change the device's I2C slave address and update the driver instance.

Detailed Description

Public API for the portable TMF8829 driver.

Version
0.1.0

Function names use tmf8829_snake_case, mirroring the ams-OSRAM reference (CamelCase) in a predictable way (e.g. tmf8829Enabletmf8829_enable).

All host I/O goes through tmf8829_ops_t. Measurement data uses a pull model: acknowledge interrupts with tmf8829_get_and_clr_interrupts, then tmf8829_read_results or tmf8829_read_histogram.

Macro Definition Documentation

◆ TMF8829_CPU_READY_TIMEOUT_MS

#define TMF8829_CPU_READY_TIMEOUT_MS

Default millisecond budget for tmf8829_is_cpu_ready inside tmf8829_enable.

◆ TMF8829_ENABLE_CAP_DISCHARGE_US

#define TMF8829_ENABLE_CAP_DISCHARGE_US

Microseconds to hold the enable pin low before power-on (cap discharge).

◆ TMF8829_ENABLE_RAMP_US

#define TMF8829_ENABLE_RAMP_US

Microseconds to wait after driving enable high before polling CPU ready.

◆ TMF8829_WAKEUP_CPU_READY_TIMEOUT_MS

#define TMF8829_WAKEUP_CPU_READY_TIMEOUT_MS

Millisecond budget passed to tmf8829_is_cpu_ready from tmf8829_wakeup (vendor ENABLE_TIME_MS).

Typedef Documentation

◆ tmf8829_fw_image_read_fn

typedef int(* tmf8829_fw_image_read_fn) (tmf8829_driver_t *drv, uint32_t offset, uint8_t *buf, uint32_t len, uint32_t *image_total_size)

Read-only access to a firmware image for tmf8829_download_firmware.

Size probe: if buf is NULL and len is 0, write the total image size in bytes into *image_total_size (if non-NULL) and return 0. Negative return indicates failure.

Data read: copy up to len bytes from offset into buf. Return the number of bytes copied on success, or negative on failure. Short reads (return value less than len before end of image) are treated as errors by the downloader.

Parameters
[in,out]drvDriver instance (may be ignored).
[in]offsetByte offset into the image.
[out]bufDestination or NULL for probe only.
[in]lenMax bytes to copy, or 0 for probe only.
[out]image_total_sizeSet on probe; may be NULL on data reads.
Returns
Non-negative byte count on success, negative on error.

◆ tmf8829_log_fn

typedef void(* tmf8829_log_fn) (tmf8829_driver_t *drv, int level, const char *msg)

Optional host logging callback (not invoked unless the driver calls it).

Parameters
[in]drvDriver instance.
[in]levelBit mask compatible with tmf8829_log_level.
[in]msgNUL-terminated message.

◆ tmf8829_on_error_fn

typedef void(* tmf8829_on_error_fn) (tmf8829_driver_t *drv, int err)

Optional error reporter (driver may call when a recoverable issue occurs).

Parameters
[in]drvDriver instance.
[in]errNegative tmf8829_err_t or other host-defined code.

◆ tmf8829_on_histogram_fn

typedef void(* tmf8829_on_histogram_fn) (tmf8829_driver_t *drv, const uint8_t *data, uint16_t len)

Invoked for each histogram payload chunk read from the FIFO.

Parameters
[in]drvDriver instance.
[in]dataChunk stored in tmf8829_driver_t::buffer.
[in]lenChunk length in bytes.

◆ tmf8829_on_result_fn

typedef void(* tmf8829_on_result_fn) (tmf8829_driver_t *drv, const uint8_t *data, uint16_t len)

Invoked for each result payload chunk read from the FIFO.

Parameters
[in]drvDriver instance.
[in]dataChunk stored in tmf8829_driver_t::buffer.
[in]lenChunk length in bytes.

◆ tmf8829_on_stream_header_fn

typedef void(* tmf8829_on_stream_header_fn) (tmf8829_driver_t *drv, const uint8_t *data, uint16_t len)

Invoked once per FIFO read with the fused pre-header and frame header.

Parameters
[in]drvDriver instance.
[in]dataBuffer of length len (typically TMF8829_PRE_HEADER_SIZE
  • TMF8829_FRAME_HEADER_SIZE bytes).
[in]lenNumber of bytes in data.

Function Documentation

◆ tmf8829_bootloader_i2c_off()

int tmf8829_bootloader_i2c_off ( tmf8829_driver_t * drv)

◆ tmf8829_bootloader_spi_off()

int tmf8829_bootloader_spi_off ( tmf8829_driver_t * drv)

◆ tmf8829_clk_correction_ratio_uq15()

uint16_t tmf8829_clk_correction_ratio_uq15 ( const tmf8829_driver_t * drv)

Current UQ15 ratio used by tmf8829_correct_distance; nominal unity is 32768.

Returns
Unity ratio if drv is NULL.

◆ tmf8829_clk_correction_set()

int tmf8829_clk_correction_set ( tmf8829_driver_t * drv,
uint8_t enable )

Enable or disable collection of clock-correction samples in result reads.

When enabling, internal ratio state is reset.

◆ tmf8829_clr_and_enable_interrupts()

int tmf8829_clr_and_enable_interrupts ( tmf8829_driver_t * drv,
uint8_t mask )

Read-modify-write TMF8829_REG_INT_ENAB to enable mask bits.

◆ tmf8829_cmd_load_config_page()

int tmf8829_cmd_load_config_page ( tmf8829_driver_t * drv)

◆ tmf8829_cmd_write_page()

int tmf8829_cmd_write_page ( tmf8829_driver_t * drv)

◆ tmf8829_command()

int tmf8829_command ( tmf8829_driver_t * drv,
uint8_t cmd,
uint16_t timeout_ms )

Issue a raw application command byte and poll TMF8829_REG_CMD_STAT for acceptance.

Parameters
[in,out]drvInitialised driver instance.
[in]cmdOpcode (e.g. TMF8829_CMD_MEASURE).
[in]timeout_msMaximum time to poll for command acceptance.
Precondition
Driver initialised and device in application mode.

◆ tmf8829_correct_distance()

uint16_t tmf8829_correct_distance ( const tmf8829_driver_t * drv,
uint16_t distance )

Scale a raw distance using tmf8829_driver_t::_clk_corr_ratio_uq (UQ15).

Returns
Saturated 16-bit corrected distance.

◆ tmf8829_correct_distance_data_segment()

void tmf8829_correct_distance_data_segment ( tmf8829_driver_t * drv,
uint16_t size,
uint8_t layout )

Apply tmf8829_correct_distance to each distance field in tmf8829_driver_t::buffer.

Parameters
[in,out]drvInitialised driver instance.
[in]sizeNumber of bytes in buffer to treat as pixels of size tmf8829_get_pixel_size(layout).
[in]layoutResult-format byte (peak count and flags).

◆ tmf8829_disable()

int tmf8829_disable ( tmf8829_driver_t * drv)

Drive the enable pin low (sensor off).

If tmf8829_ops_t::write_pin_enable is NULL (enable pin permanently tied high), returns TMF8829_E_NOT_IMPLEMENTED since the sensor cannot be powered down via software.

◆ tmf8829_disable_interrupts()

int tmf8829_disable_interrupts ( tmf8829_driver_t * drv,
uint8_t mask )

Read-modify-write TMF8829_REG_INT_ENAB to disable mask bits.

◆ tmf8829_download_firmware()

int tmf8829_download_firmware ( tmf8829_driver_t * drv,
uint32_t image_start_addr,
int use_fifo )

Stream firmware through tmf8829_driver_t::fw_image_read and start the RAM application.

Precondition
Bootloader running, tmf8829_driver_t::fw_image_read set, buffer large enough (non-FIFO: TMF8829_BL_WR_HEADER + TMF8829_BL_MAX_PAYLOAD; FIFO: full image chunks).
Parameters
[in,out]drvInitialised driver instance.
[in]image_start_addrLoad address; use TMF8829_FW_IMAGE_LOAD_ADDR_DEFAULT for vendor image.
[in]use_fifoNon-zero for FIFO download path; 0 for direct WR_RAM.
Returns
TMF8829_OK on success, negative tmf8829_err_t or callback error code.

◆ tmf8829_enable()

int tmf8829_enable ( tmf8829_driver_t * drv)

Drive the enable pin high and wait for CPU ready.

If tmf8829_ops_t::write_pin_enable is NULL (enable pin permanently tied high), the pin toggle and discharge delays are skipped and the function only polls for CPU readiness.

To do a power cycle, call tmf8829_disable followed by tmf8829_enable followed by choosing a communication interface.

Returns
TMF8829_OK, TMF8829_E_TIMEOUT, TMF8829_E_BUS, or TMF8829_E_PARAM.

◆ tmf8829_get_and_clr_interrupts()

int tmf8829_get_and_clr_interrupts ( tmf8829_driver_t * drv,
uint8_t mask,
uint8_t * out_pending )

Read TMF8829_REG_INT_STATUS and write-1-to-clear bits in mask.

Parameters
[in,out]drvInitialised driver instance.
[in]maskBits to consider (typically TMF8829_INT_ALL).
[out]out_pendingCleared interrupt bits that were set before the clear (subset of mask).
Returns
TMF8829_OK, TMF8829_E_BUS, or TMF8829_E_PARAM.

◆ tmf8829_get_configuration()

int tmf8829_get_configuration ( tmf8829_driver_t * drv)

After tmf8829_cmd_load_config_page, read the configuration page into tmf8829_driver_t::config.

◆ tmf8829_get_pixel_size()

uint8_t tmf8829_get_pixel_size ( uint8_t layout)

Bytes per result pixel for a given TMF8829_REG_CFG_RESULT_FORMAT layout byte.

Uses TMF8829_RESULT_FORMAT_* masks in layout.

◆ tmf8829_get_uint16()

uint16_t tmf8829_get_uint16 ( const uint8_t * data)

Little-endian uint16 from two bytes.

◆ tmf8829_get_uint32()

uint32_t tmf8829_get_uint32 ( const uint8_t * data)

Little-endian uint32 from four bytes.

◆ tmf8829_hard_reset()

int tmf8829_hard_reset ( tmf8829_driver_t * drv)

Write TMF8829_RESET_HARD_MASK to TMF8829_REG_RESET and wait until CPU is ready.

◆ tmf8829_init()

int tmf8829_init ( tmf8829_driver_t * drv,
const tmf8829_ops_t * ops )

Validate parameters, bind ops, and reset driver state.

Parameters
[in,out]drvDriver instance; tmf8829_driver_t::buffer and lengths must be valid.
[in]opsPlatform operations (must remain valid for the lifetime of drv).
Returns
TMF8829_OK on success, or negative tmf8829_err_t.

◆ tmf8829_is_cpu_ready()

int tmf8829_is_cpu_ready ( tmf8829_driver_t * drv,
uint8_t timeout_ms )

Poll TMF8829_REG_ENABLE until TMF8829_ENABLE_CPU_READY_MASK is set or time elapses.

Parameters
[in,out]drvInitialised driver instance.
[in]timeout_msMaximum time to poll (milliseconds). Uses timeout_ms+1 loop iterations with 1 ms delay.
Returns
TMF8829_OK when ready, TMF8829_E_TIMEOUT, TMF8829_E_BUS, or TMF8829_E_PARAM.

◆ tmf8829_is_device_wakeup()

int tmf8829_is_device_wakeup ( tmf8829_driver_t * drv,
uint8_t * out_awake )

Non-blocking wakeup check: reads enable register and CPU-ready bit.

Parameters
[in,out]drvInitialised driver instance.
[out]out_awakeSet to 1 if CPU ready, 0 if not.
Returns
TMF8829_OK, TMF8829_E_BUS, or TMF8829_E_PARAM.

◆ tmf8829_power_up()

int tmf8829_power_up ( tmf8829_driver_t * drv)

Assert power-on (TMF8829_ENABLE_PON_MASK) and wait TMF8829_ENABLE_RAMP_US.

◆ tmf8829_read_device_info()

int tmf8829_read_device_info ( tmf8829_driver_t * drv)

Read serial number, app version, and chip id registers into drv.

Returns TMF8829_E_STATE if TMF8829_REG_APP_ID reports bootloader mode (TMF8829_APP_ID__BOOTLOADER, 0x80) instead of application mode (TMF8829_APP_ID__APPLICATION, 0x01). It only succeeds if the device is in application mode (i.e. has the firmware loaded).

This behavior is kept for parity with the original ams-OSRAM reference drivers (Linux and Arduino), which also treat bootloader state as an error in the corresponding device-info routine.

Returns
TMF8829_OK or a negative error code.

◆ tmf8829_read_histogram()

int tmf8829_read_histogram ( tmf8829_driver_t * drv)

Read a histogram frame from the FIFO (same header path as results).

Returns
TMF8829_OK on valid histogram EOF; TMF8829_E_NO_RESULT if not a histogram frame.

◆ tmf8829_read_results()

int tmf8829_read_results ( tmf8829_driver_t * drv)

Read a result frame from the FIFO (header via TMF8829_REG_FIFO_STATUS, payload via TMF8829_REG_FIFO).

Optionally applies clock distance correction to payload segments when enabled. Invokes tmf8829_driver_t::on_stream_header / tmf8829_driver_t::on_result if set.

Returns
TMF8829_OK if EOF marker matches TMF8829_FRAME_EOF; TMF8829_E_NO_RESULT if wrong frame type or bad footer; TMF8829_E_PARAM / TMF8829_E_BUS as appropriate.

◆ tmf8829_set_configuration()

int tmf8829_set_configuration ( tmf8829_driver_t * drv)

Write tmf8829_driver_t::config to the device (load page + write page sequence).

Precondition
The config page must have been loaded first via tmf8829_get_configuration or manually populated from a known-good state. The device must be in application mode with no measurement active.

◆ tmf8829_set_i2c_address()

int tmf8829_set_i2c_address ( tmf8829_driver_t * drv,
uint8_t new_addr )

Change the device's I2C slave address and update the driver instance.

Writes new_addr to TMF8829_REG_I2C_DEVADDR, then updates tmf8829_driver_t::i2c_addr so subsequent transfers use the new address.

Precondition
Device in application mode; bus type must be TMF8829_BUS_I2C.
Parameters
[in,out]drvInitialised driver instance.
[in]new_addrNew 7-bit I2C address (0x00–0x7F).
Returns
TMF8829_OK, TMF8829_E_PARAM, or TMF8829_E_BUS.

◆ tmf8829_set_log_level()

int tmf8829_set_log_level ( tmf8829_driver_t * drv,
uint8_t level )

Update tmf8829_driver_t::log_level for optional tmf8829_driver_t::log use.

Returns
TMF8829_OK, or TMF8829_E_PARAM if uninitialised.

◆ tmf8829_set_uint16()

void tmf8829_set_uint16 ( uint16_t value,
uint8_t * data )

Write value to two bytes, little-endian.

◆ tmf8829_soft_reset()

int tmf8829_soft_reset ( tmf8829_driver_t * drv)

Write TMF8829_RESET_SOFT_MASK to TMF8829_REG_RESET and reset clock-correction state.

◆ tmf8829_standby()

int tmf8829_standby ( tmf8829_driver_t * drv)

Request standby if the CPU is running (sets TMF8829_ENABLE_POFF_MASK).

◆ tmf8829_start_measurement()

int tmf8829_start_measurement ( tmf8829_driver_t * drv)

TMF8829_CMD_MEASURE

Precondition
Configuration written, device in application mode, no measurement active.

◆ tmf8829_stop_measurement()

int tmf8829_stop_measurement ( tmf8829_driver_t * drv)

TMF8829_CMD_STOP

Precondition
Measurement active; wakes device if in standby.

◆ tmf8829_wakeup()

int tmf8829_wakeup ( tmf8829_driver_t * drv)

Leave low-power: if CPU not ready, set RAM boot path + PON and poll readiness.