Chirp SonicLib  2.1.0
Classes | Macros | Typedefs | Functions
ch_driver.h File Reference

Internal driver functions for operation with the Chirp ultrasonic sensor. More...

#include "chirp_board_config.h"
#include "soniclib.h"
#include <stdint.h>
#include <stdlib.h>
#include <math.h>
#include <string.h>

Go to the source code of this file.

Classes

struct  chdrv_i2c_transaction
 I2C transaction control structure. More...
 
struct  chdrv_i2c_queue
 I2C queue structure, for non-blocking access. More...
 

Macros

#define CHDRV_I2C_MAX_WRITE_BYTES   256
 
#define CHDRV_NB_TRANS_TYPE_STD   (0)
 
#define CHDRV_NB_TRANS_TYPE_PROG   (1)
 
#define CHDRV_NB_TRANS_TYPE_EXTERNAL   (2)
 
#define CH_PROG_REG_PING   0x00
 
#define CH_PROG_REG_CPU   0x42
 
#define CH_PROG_REG_STAT   0x43
 
#define CH_PROG_REG_CTL   0x44
 
#define CH_PROG_REG_ADDR   0x05
 
#define CH_PROG_REG_CNT   0x07
 
#define CH_PROG_REG_DATA   0x06
 
#define CH_PROG_SIZEOF(R)   ( (R) & 0x40 ? 1 : 2 )
 
#define CH_PROG_XFER_SIZE   (256)
 
#define CHDRV_DEBUG_PIN_NUM   (0)
 
#define CHDRV_MAX_I2C_QUEUE_LENGTH   CHIRP_MAX_NUM_SENSORS
 
#define CHDRV_FREQLOCK_TIMEOUT_MS   100
 
#define CHDRV_BANDWIDTH_INDEX_1   6
 
#define CHDRV_BANDWIDTH_INDEX_2   (CHDRV_BANDWIDTH_INDEX_1 + 1)
 
#define CHDRV_SCALEFACTOR_INDEX   4
 
#define CHDRV_TRIGGER_PULSE_US   5
 
#define CHDRV_DELAY_OVERHEAD_US   12
 
#define CHDRV_PRETRIGGER_DELAY_US   600
 

Typedefs

typedef uint8_t(* chdrv_discovery_hook_t) (ch_dev_t *dev_ptr)
 Hook routine pointer typedefs.
 
typedef struct chdrv_i2c_transaction chdrv_i2c_transaction_t
 I2C transaction control structure.
 
typedef struct chdrv_i2c_queue chdrv_i2c_queue_t
 I2C queue structure, for non-blocking access.
 

Functions

void chdrv_group_measure_rtc (ch_group_t *grp_ptr)
 Calibrate the sensor real-time clock against the host microcontroller clock. More...
 
uint32_t chdrv_one_way_range (ch_dev_t *dev_ptr, uint16_t tof, uint16_t tof_sf)
 Convert the sensor register values to a range using the calibration data in the ch_dev_t struct. More...
 
uint32_t chdrv_round_trip_range (ch_dev_t *dev_ptr, uint16_t tof, uint16_t tof_sf)
 Convert the sensor register values to a round-trip range using the calibration data in the ch_dev_t struct. More...
 
int chdrv_group_i2c_queue (ch_group_t *grp_ptr, ch_dev_t *instance, uint8_t rd_wrb, uint8_t type, uint16_t addr, uint16_t nbytes, uint8_t *data)
 Add an I2C transaction to the non-blocking queue. More...
 
int chdrv_external_i2c_queue (ch_group_t *grp_ptr, ch_dev_t *instance, uint8_t rd_wrb, uint16_t addr, uint16_t nbytes, uint8_t *data)
 Add an I2C transaction for an external device to the non-blocking queue. More...
 
void chdrv_group_i2c_start_nb (ch_group_t *grp_ptr)
 Start a non-blocking sensor readout. More...
 
void chdrv_group_i2c_irq_handler (ch_group_t *grp_ptr, uint8_t i2c_bus_index)
 Continue a non-blocking readout. More...
 
int chdrv_wait_for_lock (ch_dev_t *dev_ptr, uint16_t timeout_ms)
 Wait for an individual sensor to finish start-up procedure. More...
 
int chdrv_group_wait_for_lock (ch_group_t *grp_ptr)
 Wait for all sensors to finish start-up procedure. More...
 
int chdrv_group_hw_trigger (ch_group_t *grp_ptr)
 Start a measurement in hardware triggered mode. More...
 
int chdrv_hw_trigger (ch_dev_t *dev_ptr)
 Start a measurement in hardware triggered mode on one sensor. More...
 
int chdrv_prog_ping (ch_dev_t *dev_ptr)
 Detect a connected sensor. More...
 
int chdrv_detect_and_program (ch_dev_t *dev_ptr)
 Detect, program, and start a sensor. More...
 
int chdrv_group_detect_and_program (ch_group_t *grp_ptr)
 Detect, program, and start all sensors in a group. More...
 
int chdrv_init (ch_dev_t *dev_ptr, uint8_t i2c_addr, uint8_t io_index, uint8_t i2c_bus_index, uint16_t part_number)
 Initialize the sensor device configuration. More...
 
int chdrv_group_prepare (ch_group_t *grp_ptr)
 Initialize data structures and hardware for sensor interaction and reset sensors. More...
 
int chdrv_group_start (ch_group_t *grp_ptr)
 Initalize and start a group of sensors. More...
 
int chdrv_write_byte (ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t data)
 Write byte to a sensor application register. More...
 
int chdrv_write_word (ch_dev_t *dev_ptr, uint16_t mem_addr, uint16_t data)
 Write 16 bits to a sensor application register. More...
 
int chdrv_read_byte (ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t *data)
 Read byte from a sensor application register. More...
 
int chdrv_read_word (ch_dev_t *dev_ptr, uint16_t mem_addr, uint16_t *data)
 Read 16 bits from a sensor application register. More...
 
int chdrv_burst_read (ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t *data, uint16_t len)
 Read multiple bytes from a sensor application register location. More...
 
int chdrv_burst_write (ch_dev_t *dev_ptr, uint16_t mem_addr, uint8_t *data, uint8_t len)
 Write multiple bytes to a sensor application register location. More...
 
int chdrv_soft_reset (ch_dev_t *dev_ptr)
 Perform a soft reset on a sensor. More...
 
int chdrv_group_hard_reset (ch_group_t *grp_ptr)
 Perform a hard reset on a group of sensors. More...
 
int chdrv_group_soft_reset (ch_group_t *grp_ptr)
 Perform a soft reset on a group of sensors. More...
 
int chdrv_set_idle (ch_dev_t *dev_ptr)
 Put sensor(s) in idle state. More...
 
int chdrv_prog_write (ch_dev_t *dev_ptr, uint8_t reg_addr, uint16_t data)
 Write to a sensor programming register. More...
 
int chdrv_prog_i2c_write (ch_dev_t *dev_ptr, uint8_t *message, uint16_t len)
 Write bytes to a sensor device in programming mode. More...
 
int chdrv_prog_i2c_read (ch_dev_t *dev_ptr, uint8_t *message, uint16_t len)
 Read bytes from a sensor device in programming mode. More...
 
int chdrv_prog_i2c_read_nb (ch_dev_t *dev_ptr, uint8_t *message, uint16_t len)
 Read bytes from a sensor device in programming mode, non-blocking. More...
 
int chdrv_prog_mem_write (ch_dev_t *dev_ptr, uint16_t addr, uint8_t *message, uint16_t nbytes)
 Write to sensor memory. More...
 
void chdrv_discovery_hook_set (ch_group_t *grp_ptr, chdrv_discovery_hook_t hook_func_ptr)
 Register a hook routine to be called after device discovery. More...
 
void chdrv_pretrigger_delay_set (ch_group_t *grp_ptr, uint16_t delay_us)
 Set the pre-trigger delay for rx-only sensors. More...
 

Detailed Description

Internal driver functions for operation with the Chirp ultrasonic sensor.

This file contains definitions for the internal Chirp sensor driver functions and structures within SonicLib. These functions are provided in source code form to simplify integration with an embedded application and for reference only.

The Chirp driver functions provide an interface between the SonicLib public API layer and the actual sensor devices. The driver manages all software-defined aspects of the Chirp sensor, including the register set.

You should not need to edit this file or call the driver functions directly. Doing so will reduce your ability to benefit from future enhancements and releases from Chirp.

Macro Definition Documentation

◆ CH_PROG_REG_ADDR

#define CH_PROG_REG_ADDR   0x05

Data transfer starting address register address.

◆ CH_PROG_REG_CNT

#define CH_PROG_REG_CNT   0x07

Data transfer size register address.

◆ CH_PROG_REG_CPU

#define CH_PROG_REG_CPU   0x42

Processor control register address.

◆ CH_PROG_REG_CTL

#define CH_PROG_REG_CTL   0x44

Data transfer control register address.

◆ CH_PROG_REG_DATA

#define CH_PROG_REG_DATA   0x06

Data transfer value register address.

◆ CH_PROG_REG_PING

#define CH_PROG_REG_PING   0x00

Read-only register used during device discovery.

◆ CH_PROG_REG_STAT

#define CH_PROG_REG_STAT   0x43

Processor status register address.

◆ CH_PROG_SIZEOF

#define CH_PROG_SIZEOF (   R)    ( (R) & 0x40 ? 1 : 2 )

Macro to determine programming register size.

◆ CH_PROG_XFER_SIZE

#define CH_PROG_XFER_SIZE   (256)

max size of a read operation via programming interface

◆ CHDRV_BANDWIDTH_INDEX_1

#define CHDRV_BANDWIDTH_INDEX_1   6

Index of first sample to use for calculating bandwidth.

◆ CHDRV_BANDWIDTH_INDEX_2

#define CHDRV_BANDWIDTH_INDEX_2   (CHDRV_BANDWIDTH_INDEX_1 + 1)

Index of second sample to use for calculating bandwidth.

◆ CHDRV_DEBUG_PIN_NUM

#define CHDRV_DEBUG_PIN_NUM   (0)

debug pin number (index) to use for debug indication

◆ CHDRV_DELAY_OVERHEAD_US

#define CHDRV_DELAY_OVERHEAD_US   12

Tuning parameter to adjust pre-trigger timing

◆ CHDRV_FREQLOCK_TIMEOUT_MS

#define CHDRV_FREQLOCK_TIMEOUT_MS   100

Time to wait in chdrv_group_start() for sensor initialization, in milliseconds.

◆ CHDRV_I2C_MAX_WRITE_BYTES

#define CHDRV_I2C_MAX_WRITE_BYTES   256

maximum number of bytes in a single I2C write

◆ CHDRV_MAX_I2C_QUEUE_LENGTH

#define CHDRV_MAX_I2C_QUEUE_LENGTH   CHIRP_MAX_NUM_SENSORS

Max queued non-blocking I2C transactions - value from chirp_board_config.h

◆ CHDRV_NB_TRANS_TYPE_EXTERNAL

#define CHDRV_NB_TRANS_TYPE_EXTERNAL   (2)

externally requested non-blocking I/O transaction

◆ CHDRV_NB_TRANS_TYPE_PROG

#define CHDRV_NB_TRANS_TYPE_PROG   (1)

non-blocking I/O via low-level programming interface

◆ CHDRV_NB_TRANS_TYPE_STD

#define CHDRV_NB_TRANS_TYPE_STD   (0)

standard non-blocking I/O transaction

◆ CHDRV_PRETRIGGER_DELAY_US

#define CHDRV_PRETRIGGER_DELAY_US   600

Time to delay between triggering rx-only and tx/rx nodes, in us

◆ CHDRV_SCALEFACTOR_INDEX

#define CHDRV_SCALEFACTOR_INDEX   4

Index for calculating scalefactor.

◆ CHDRV_TRIGGER_PULSE_US

#define CHDRV_TRIGGER_PULSE_US   5

Length of INT pulse to trigger sensor, in microseconds - minimum 800ns.

Function Documentation

◆ chdrv_burst_read()

int chdrv_burst_read ( ch_dev_t dev_ptr,
uint16_t  mem_addr,
uint8_t *  data,
uint16_t  len 
)

Read multiple bytes from a sensor application register location.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
mem_addrsensor memory/register address
datapointer to receive buffer
lennumber of bytes to read
Returns
0 if successful, non-zero otherwise

◆ chdrv_burst_write()

int chdrv_burst_write ( ch_dev_t dev_ptr,
uint16_t  mem_addr,
uint8_t *  data,
uint8_t  len 
)

Write multiple bytes to a sensor application register location.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
mem_addrsensor memory/register address
datapointer to transmit buffer containing data to send
lennumber of bytes to write
Returns
0 if successful, non-zero otherwise

◆ chdrv_detect_and_program()

int chdrv_detect_and_program ( ch_dev_t dev_ptr)

Detect, program, and start a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
Returns
0 if write to sensor succeeded, non-zero otherwise

This function probes the I2C bus for the device. If it is found, the sensor firmware is programmed into the device, and the application I2C address is set. Then the sensor is reset and execution starts.

Once started, the sensor device will begin an internal initialization and self-test sequence. The chdrv_wait_for_lock() function may be used to wait for this sequence to complete.

Note
This routine will leave the PROG pin de-asserted when it completes.

◆ chdrv_discovery_hook_set()

void chdrv_discovery_hook_set ( ch_group_t grp_ptr,
chdrv_discovery_hook_t  hook_func_ptr 
)

Register a hook routine to be called after device discovery.

Parameters
grp_ptrpointer to the ch_group_t config structure for a group of sensors
hook_func_ptraddress of hook routine to be called

This function sets a pointer to a hook routine, which will be called from the Chirp driver when each device is discovered on the I2C bus, before the device is initialized.

This function should be called between ch_init() and ch_group_start().

◆ chdrv_external_i2c_queue()

int chdrv_external_i2c_queue ( ch_group_t grp_ptr,
ch_dev_t instance,
uint8_t  rd_wrb,
uint16_t  addr,
uint16_t  nbytes,
uint8_t *  data 
)

Add an I2C transaction for an external device to the non-blocking queue.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors
instancepointer to the ch_dev_t descriptor structure for a sensor
rd_wrbread/write indicator: 0 if write operation, 1 if read operation
addrI2C address for transfer
nbytesnumber of bytes to read/write
datapointer to buffer to receive data or containing data to send
Returns
0 if successful, non-zero otherwise

This function queues an I2C transaction for an "external" device (i.e. not a Chirp sensor). It is used when the I2C bus is shared between the Chirp sensor(s) and other devices.
The transaction is flagged for special handling when the I/O operation completes. Specifically, the chbsp_external_i2c_irq_handler() will be called by the driver to allow the board support packate (BSP) to perform any necessary operations.

◆ chdrv_group_detect_and_program()

int chdrv_group_detect_and_program ( ch_group_t grp_ptr)

Detect, program, and start all sensors in a group.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors
Returns
0 for success, non-zero if write(s) failed to any sensor initially detected as present

This function probes the I2C bus for each device in the group. For each detected sensor, the firmware is programmed into the device, and the application I2C address is set. Then the sensor is reset and execution starts.

Once started, each device will begin an internal initialization and self-test sequence. The chdrv_group_wait_for_lock() function may be used to wait for this sequence to complete on all devices in the group.

Note
This routine will leave the PROG pin de-asserted for all devices in the group when it completes.

◆ chdrv_group_hard_reset()

int chdrv_group_hard_reset ( ch_group_t grp_ptr)

Perform a hard reset on a group of sensors.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors
Returns
0 if successful, non-zero otherwise

This function performs a hardware reset on each device in a group of sensors by asserting each device's RESET_N pin.

◆ chdrv_group_hw_trigger()

int chdrv_group_hw_trigger ( ch_group_t grp_ptr)

Start a measurement in hardware triggered mode.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors
Returns
0 if success, non-zero if grp_ptr pointer is invalid

This function starts a triggered measurement on each sensor in a group, by briefly asserting the INT line to each device. Each sensor must have already been placed in hardware triggered mode before this function is called.

◆ chdrv_group_i2c_irq_handler()

void chdrv_group_i2c_irq_handler ( ch_group_t grp_ptr,
uint8_t  i2c_bus_index 
)

Continue a non-blocking readout.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors
i2c_bus_indexindex value identifying I2C bus within group

Call this function once from your I2C interrupt handler each time it executes. It will call chdrv_group_i2c_complete_callback() when all transactions are complete.

◆ chdrv_group_i2c_queue()

int chdrv_group_i2c_queue ( ch_group_t grp_ptr,
ch_dev_t instance,
uint8_t  rd_wrb,
uint8_t  type,
uint16_t  addr,
uint16_t  nbytes,
uint8_t *  data 
)

Add an I2C transaction to the non-blocking queue.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors
instancepointer to an individual descriptor structure for a sensor
rd_wrbread/write indicator: 0 if write operation, 1 if read operation
typeI2C transaction type: 0 = std, 1 = prog interface, 2 = external
addrI2C address for transfer
nbytesnumber of bytes to read/write
datapointer to buffer to receive data or containing data to send
Returns
0 if successful, non-zero otherwise

◆ chdrv_group_i2c_start_nb()

void chdrv_group_i2c_start_nb ( ch_group_t grp_ptr)

Start a non-blocking sensor readout.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors

This function starts a non-blocking I/O operation on the specified group of sensors.

◆ chdrv_group_measure_rtc()

void chdrv_group_measure_rtc ( ch_group_t grp_ptr)

Calibrate the sensor real-time clock against the host microcontroller clock.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors

This function sends a pulse (timed by the host MCU) on the INT line to each device in the group, then reads back the count of sensor RTC cycles that elapsed during that pulse on each individual device. The result is stored in the ch_dev_t descriptor structure for each device and is subsequently used during range calculations.

The length of the pulse is grp_ptr->rtc_cal_pulse_ms milliseconds (typically 100ms).

Note
The calibration pulse is sent to all devices in the group at the same time. Therefore all connected devices will see the same reference pulse length.

◆ chdrv_group_prepare()

int chdrv_group_prepare ( ch_group_t grp_ptr)

Initialize data structures and hardware for sensor interaction and reset sensors.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors
Returns
0 if hardware initialization is successful, non-zero otherwise

This function is called internally by chdrv_group_start().

◆ chdrv_group_soft_reset()

int chdrv_group_soft_reset ( ch_group_t grp_ptr)

Perform a soft reset on a group of sensors.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors
Returns
0 if successful, non-zero otherwise

This function performs a soft reset on each device in a group of sensors by writing to a special control register.

◆ chdrv_group_start()

int chdrv_group_start ( ch_group_t grp_ptr)

Initalize and start a group of sensors.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors
Returns
0 if successful, 1 if device doesn't respond

This function resets each sensor in programming mode, transfers the firmware image to the sensor's on-chip memory, changes the sensor's application I2C address from the default, then starts the sensor and sends a timed pulse on the INT line for real-time clock calibration.

This function assumes firmware-specific initialization has already been performed for each ch_dev_t descriptor in the sensor group. (See ch_init()).

◆ chdrv_group_wait_for_lock()

int chdrv_group_wait_for_lock ( ch_group_t grp_ptr)

Wait for all sensors to finish start-up procedure.

Parameters
grp_ptrpointer to the ch_group_t descriptor structure for a group of sensors
Returns
0 if startup sequence finished on all detected sensors, non-zero if startup sequence timed out on any sensor(s).

After each sensor is programmed, it executes an internal start-up and self-test sequence. This function waits for all sensor devices to finish this sequence. For each device, the maximum time to wait is CHDRV_FREQLOCK_TIMEOUT_MS milliseconds.

◆ chdrv_hw_trigger()

int chdrv_hw_trigger ( ch_dev_t dev_ptr)

Start a measurement in hardware triggered mode on one sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
Returns
0 if success, non-zero if dev_ptr pointer is invalid

This function starts a triggered measurement on a single sensor, by briefly asserting the INT line to the device. The sensor must have already been placed in hardware triggered mode before this function is called.

Note
This function requires implementing the optional chirp_bsp.h functions to control the INT pin direction and level for individual sensors (chbsp_set_io_dir_in(), chbsp_set_io_dir_out(), chbsp_io_set(), and chbsp_io_clear()).

◆ chdrv_init()

int chdrv_init ( ch_dev_t dev_ptr,
uint8_t  i2c_addr,
uint8_t  io_index,
uint8_t  i2c_bus_index,
uint16_t  part_number 
)

Initialize the sensor device configuration.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure to be initialized
i2c_addrI2C address to assign to this device. This will be the "application I2C address" used to access the device after it is initialized. Each sensor on an I2C interface must use a unique application I2C address.
io_indexindex identifying this device. Each sensor in a group must have a unique io_index value.
i2c_bus_indexindex identifying the I2C interface (bus) to use with this device
part_numberinteger part number for sensor (e.g. 101 for CH101 device, or 201 for CH201))
Returns
0 (always)

This function initializes the ch_dev_t descriptor structure for the device with the specified values.

◆ chdrv_one_way_range()

uint32_t chdrv_one_way_range ( ch_dev_t dev_ptr,
uint16_t  tof,
uint16_t  tof_sf 
)

Convert the sensor register values to a range using the calibration data in the ch_dev_t struct.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
tofvalue of TOF register
tof_sfvalue of TOF_SF register
Returns
range in millimeters, or CH_NO_TARGET (0xFFFFFFFF) if no object is detected.
The range result format is fixed point with 5 binary fractional digits (divide by 32 to convert to mm).

This function takes the time-of-flight and scale factor values from the sensor, and computes the actual one-way range based on the formulas given in the sensor datasheet.

◆ chdrv_pretrigger_delay_set()

void chdrv_pretrigger_delay_set ( ch_group_t grp_ptr,
uint16_t  delay_us 
)

Set the pre-trigger delay for rx-only sensors.

Parameters
grp_ptrpointer to the ch_group_t config structure for a group of sensors
delay_ustime to delay between triggering rx-only and tx/rx nodes, in microseconds

This function sets a delay interval that will be inserted between triggering rx-only sensors and tx/rx sensors. This delay allows the rx-only sensor(s) to settle from any startup disruption (e.g. PMUT "ringdown") before the ultrasound pulse is generated by the tx node.

◆ chdrv_prog_i2c_read()

int chdrv_prog_i2c_read ( ch_dev_t dev_ptr,
uint8_t *  message,
uint16_t  len 
)

Read bytes from a sensor device in programming mode.

Parameters
dev_ptrpointer to the ch_dev_t config structure for a sensor
messagepointer to a buffer where read bytes will be placed
lennumber of bytes to read
Returns
0 if successful, non-zero otherwise

This function reads bytes from the device using the programming I2C address. The PROG line for the device must have been asserted before this function is called.

◆ chdrv_prog_i2c_read_nb()

int chdrv_prog_i2c_read_nb ( ch_dev_t dev_ptr,
uint8_t *  message,
uint16_t  len 
)

Read bytes from a sensor device in programming mode, non-blocking.

Parameters
dev_ptrpointer to the ch_dev_t config structure for a sensor
messagepointer to a buffer where read bytes will be placed
lennumber of bytes to read
Returns
0 if successful, non-zero otherwise

This function temporarily changes the device I2C address to the low-level programming interface, and issues a non-blocking read request. The PROG line for the device must have been asserted before this function is called.

◆ chdrv_prog_i2c_write()

int chdrv_prog_i2c_write ( ch_dev_t dev_ptr,
uint8_t *  message,
uint16_t  len 
)

Write bytes to a sensor device in programming mode.

Parameters
dev_ptrpointer to the ch_dev_t config structure for a sensor
messagepointer to a buffer containing the bytes to write
lennumber of bytes to write
Returns
0 if successful, non-zero otherwise

This function writes bytes to the device using the programming I2C address. The PROG line for the device must have been asserted before this function is called.

◆ chdrv_prog_mem_write()

int chdrv_prog_mem_write ( ch_dev_t dev_ptr,
uint16_t  addr,
uint8_t *  message,
uint16_t  nbytes 
)

Write to sensor memory.

Parameters
dev_ptrpointer to the ch_dev_t config structure for a sensor
addrsensor programming register start address
messagepointer to data to transmit
nbytesnumber of bytes to write
Returns
0 if write to sensor succeeded, non-zero otherwise

This function writes to sensor memory using the low-level programming interface. The type of write is automatically determined based on data length and target address alignment.

◆ chdrv_prog_ping()

int chdrv_prog_ping ( ch_dev_t dev_ptr)

Detect a connected sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
Returns
1 if sensor is found, 0 if no sensor is found

This function checks for a sensor on the I2C bus by attempting to reset, halt, and read from the device using the programming interface I2C address (0x45).

In order for the device to respond, the PROG pin for the device must be asserted before this function is called. If there are multiple sensors in an application, only one device's PROG pin should be active at any time.

◆ chdrv_prog_write()

int chdrv_prog_write ( ch_dev_t dev_ptr,
uint8_t  reg_addr,
uint16_t  data 
)

Write to a sensor programming register.

Parameters
dev_ptrpointer to the ch_dev_t config structure for a sensor
reg_addrsensor programming register address.
data8-bit or 16-bit data to transmit.
Returns
0 if write to sensor succeeded, non-zero otherwise

This function writes a value to a sensor programming register.

◆ chdrv_read_byte()

int chdrv_read_byte ( ch_dev_t dev_ptr,
uint16_t  mem_addr,
uint8_t *  data 
)

Read byte from a sensor application register.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
mem_addrsensor memory/register address
datapointer to receive buffer
Returns
0 if successful, non-zero otherwise

◆ chdrv_read_word()

int chdrv_read_word ( ch_dev_t dev_ptr,
uint16_t  mem_addr,
uint16_t *  data 
)

Read 16 bits from a sensor application register.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
mem_addrsensor memory/register address
datapointer to receive buffer
Returns
0 if successful, non-zero otherwise

◆ chdrv_round_trip_range()

uint32_t chdrv_round_trip_range ( ch_dev_t dev_ptr,
uint16_t  tof,
uint16_t  tof_sf 
)

Convert the sensor register values to a round-trip range using the calibration data in the ch_dev_t struct.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
tofvalue of TOF register
tof_sfvalue of TOF_SF register
Returns
range in millimeters, or CH_NO_TARGET (0xFFFFFFFF) if no object is detected.
The range result format is fixed point with 5 binary fractional digits (divide by 32 to convert to mm).

This function takes the time-of-flight and scale factor values from the sensor, and computes the actual round-trip range based on the formulas given in the sensor datasheet.

◆ chdrv_set_idle()

int chdrv_set_idle ( ch_dev_t dev_ptr)

Put sensor(s) in idle state.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
Returns
0 if successful, non-zero otherwise

This function places the sensor in an idle state by loading an idle loop instruction sequence. This is used only during early initialization of the device. This is NOT the same as putting a running device into "idle mode" by using the ch_set_mode() function.

◆ chdrv_soft_reset()

int chdrv_soft_reset ( ch_dev_t dev_ptr)

Perform a soft reset on a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
mem_addrsensor memory/register address
Returns
0 if successful, non-zero otherwise

This function performs a soft reset on an individual sensor by writing to a special control register.

◆ chdrv_wait_for_lock()

int chdrv_wait_for_lock ( ch_dev_t dev_ptr,
uint16_t  timeout_ms 
)

Wait for an individual sensor to finish start-up procedure.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
timeout_msnumber of milliseconds to wait for sensor to finish start-up before returning failure
Returns
0 if startup sequence finished, non-zero if startup sequence timed out or sensor is not connected

After the sensor is programmed, it executes an internal start-up and self-test sequence. This function waits the specified time in milliseconds for the sensor to finish this sequence.

◆ chdrv_write_byte()

int chdrv_write_byte ( ch_dev_t dev_ptr,
uint16_t  mem_addr,
uint8_t  data 
)

Write byte to a sensor application register.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
reg_addrregister address
datadata value to transmit
Returns
0 if successful, non-zero otherwise

◆ chdrv_write_word()

int chdrv_write_word ( ch_dev_t dev_ptr,
uint16_t  mem_addr,
uint16_t  data 
)

Write 16 bits to a sensor application register.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure for a sensor
mem_addrsensor memory/register address
datadata value to transmit
Returns
0 if successful, non-zero otherwise