![]() |
TMF8829 Universal Driver 0.1.0
|
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"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. | |
Public API for the portable TMF8829 driver.
Function names use tmf8829_snake_case, mirroring the ams-OSRAM reference (CamelCase) in a predictable way (e.g. tmf8829Enable → tmf8829_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.
| #define TMF8829_CPU_READY_TIMEOUT_MS |
Default millisecond budget for tmf8829_is_cpu_ready inside tmf8829_enable.
| #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_WAKEUP_CPU_READY_TIMEOUT_MS |
Millisecond budget passed to tmf8829_is_cpu_ready from tmf8829_wakeup (vendor ENABLE_TIME_MS).
| 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.
| [in,out] | drv | Driver instance (may be ignored). |
| [in] | offset | Byte offset into the image. |
| [out] | buf | Destination or NULL for probe only. |
| [in] | len | Max bytes to copy, or 0 for probe only. |
| [out] | image_total_size | Set on probe; may be NULL on data reads. |
| 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).
| [in] | drv | Driver instance. |
| [in] | level | Bit mask compatible with tmf8829_log_level. |
| [in] | msg | NUL-terminated message. |
| typedef void(* tmf8829_on_error_fn) (tmf8829_driver_t *drv, int err) |
Optional error reporter (driver may call when a recoverable issue occurs).
| [in] | drv | Driver instance. |
| [in] | err | Negative tmf8829_err_t or other host-defined code. |
| 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.
| [in] | drv | Driver instance. |
| [in] | data | Chunk stored in tmf8829_driver_t::buffer. |
| [in] | len | Chunk length in bytes. |
| 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.
| [in] | drv | Driver instance. |
| [in] | data | Chunk stored in tmf8829_driver_t::buffer. |
| [in] | len | Chunk length in bytes. |
| 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.
| [in] | drv | Driver instance. |
| [in] | data | Buffer of length len (typically TMF8829_PRE_HEADER_SIZE
|
| [in] | len | Number of bytes in data. |
| int tmf8829_bootloader_i2c_off | ( | tmf8829_driver_t * | drv | ) |
Bootloader: TMF8829_BL_CMD_STAT_I2C_OFF.
| int tmf8829_bootloader_spi_off | ( | tmf8829_driver_t * | drv | ) |
Bootloader: TMF8829_BL_CMD_STAT_SPI_OFF.
| uint16_t tmf8829_clk_correction_ratio_uq15 | ( | const tmf8829_driver_t * | drv | ) |
Current UQ15 ratio used by tmf8829_correct_distance; nominal unity is 32768.
drv is NULL. | 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.
| 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_cmd_load_config_page | ( | tmf8829_driver_t * | drv | ) |
| int tmf8829_cmd_write_page | ( | tmf8829_driver_t * | 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.
| [in,out] | drv | Initialised driver instance. |
| [in] | cmd | Opcode (e.g. TMF8829_CMD_MEASURE). |
| [in] | timeout_ms | Maximum time to poll for command acceptance. |
| 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.
| [in,out] | drv | Initialised driver instance. |
| [in] | size | Number of bytes in buffer to treat as pixels of size tmf8829_get_pixel_size(layout). |
| [in] | layout | Result-format byte (peak count and flags). |
| 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.
| int tmf8829_disable_interrupts | ( | tmf8829_driver_t * | drv, |
| uint8_t | mask ) |
Read-modify-write TMF8829_REG_INT_ENAB to disable mask bits.
| 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.
| [in,out] | drv | Initialised driver instance. |
| [in] | image_start_addr | Load address; use TMF8829_FW_IMAGE_LOAD_ADDR_DEFAULT for vendor image. |
| [in] | use_fifo | Non-zero for FIFO download path; 0 for direct WR_RAM. |
| 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.
| 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.
| [in,out] | drv | Initialised driver instance. |
| [in] | mask | Bits to consider (typically TMF8829_INT_ALL). |
| [out] | out_pending | Cleared interrupt bits that were set before the clear (subset of mask). |
| int tmf8829_get_configuration | ( | tmf8829_driver_t * | drv | ) |
After tmf8829_cmd_load_config_page, read the configuration page into tmf8829_driver_t::config.
| 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.
| 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.
| 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_init | ( | tmf8829_driver_t * | drv, |
| const tmf8829_ops_t * | ops ) |
Validate parameters, bind ops, and reset driver state.
| [in,out] | drv | Driver instance; tmf8829_driver_t::buffer and lengths must be valid. |
| [in] | ops | Platform operations (must remain valid for the lifetime of drv). |
| 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.
| [in,out] | drv | Initialised driver instance. |
| [in] | timeout_ms | Maximum time to poll (milliseconds). Uses timeout_ms+1 loop iterations with 1 ms delay. |
| int tmf8829_is_device_wakeup | ( | tmf8829_driver_t * | drv, |
| uint8_t * | out_awake ) |
Non-blocking wakeup check: reads enable register and CPU-ready bit.
| [in,out] | drv | Initialised driver instance. |
| [out] | out_awake | Set to 1 if CPU ready, 0 if not. |
| int tmf8829_power_up | ( | tmf8829_driver_t * | drv | ) |
Assert power-on (TMF8829_ENABLE_PON_MASK) and wait TMF8829_ENABLE_RAMP_US.
| 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.
| int tmf8829_read_histogram | ( | tmf8829_driver_t * | drv | ) |
Read a histogram frame from the FIFO (same header path as 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.
| int tmf8829_set_configuration | ( | tmf8829_driver_t * | drv | ) |
Write tmf8829_driver_t::config to the device (load page + write page sequence).
| 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.
| [in,out] | drv | Initialised driver instance. |
| [in] | new_addr | New 7-bit I2C address (0x00–0x7F). |
| 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.
| void tmf8829_set_uint16 | ( | uint16_t | value, |
| uint8_t * | data ) |
Write value to two bytes, little-endian.
| int tmf8829_soft_reset | ( | tmf8829_driver_t * | drv | ) |
Write TMF8829_RESET_SOFT_MASK to TMF8829_REG_RESET and reset clock-correction state.
| int tmf8829_standby | ( | tmf8829_driver_t * | drv | ) |
Request standby if the CPU is running (sets TMF8829_ENABLE_POFF_MASK).
| int tmf8829_start_measurement | ( | tmf8829_driver_t * | drv | ) |
| int tmf8829_stop_measurement | ( | tmf8829_driver_t * | drv | ) |
| int tmf8829_wakeup | ( | tmf8829_driver_t * | drv | ) |
Leave low-power: if CPU not ready, set RAM boot path + PON and poll readiness.