|
Chirp SonicLib
4.5.2
|
SonicLib public API and support functions for TDK/InvenSense ultrasonic sensors (originally developed by Chirp Microsystems). More...
#include "chirp_board_config.h"#include <invn/icu_interface/shasta_external_regs.h>#include <invn/soniclib/details/icu.h>#include <invn/icu_interface/icu_algo_info.h>#include <invn/soniclib/details/ch_driver.h>#include <invn/soniclib/details/ch_math_utils.h>#include <stdint.h>#include <stdlib.h>#include <math.h>#include <string.h>Go to the source code of this file.
Classes | |
| struct | ch_amp_thresh_t |
| Sensor combined amplitude + detection threshold sample value. More... | |
| struct | ch_api_funcs_t |
| API function pointer structure (internal use). More... | |
| struct | ch_cal_result_t |
| Calibration result structure. More... | |
| struct | ch_calib_funcs_t |
| struct | ch_clock_cal_t |
| Clock calibration values. More... | |
| struct | ch_config_t |
| Combined configuration structure. More... | |
| struct | ch_dev_t |
| Chirp sensor device descriptor structure. More... | |
| struct | ch_group_t |
| Chirp sensor group descriptor structure. More... | |
| struct | ch_i2c_info_t |
| I2C info structure. More... | |
| struct | ch_iq_sample_t |
| Sensor I/Q data value. More... | |
| struct | ch_log_cfg_t |
| Log configuration structure. More... | |
| struct | ch_log_data_t |
| Log data structure. More... | |
| struct | ch_meas_config_t |
| Measurement configuration - used during ch_meas_init() More... | |
| struct | ch_meas_info_t |
| Measurement info. More... | |
| struct | ch_meas_queue_info_t |
| Measurement queue info. More... | |
| struct | ch_meas_seg_info_t |
| Measurement segment info. More... | |
| struct | ch_meas_segment_t |
| Measurement segment. More... | |
| struct | ch_mfg_info_t |
| Sensor manufacturing info. More... | |
| struct | ch_output_t |
| Data output structure. More... | |
| struct | ch_thresh_t |
| Detection threshold value. More... | |
| struct | ch_version_t |
| SonicLib version structure. More... | |
| struct | fw_info_st |
Typedefs | |
| typedef struct ch_dev_t | ch_dev_t |
| typedef uint8_t(* | ch_fw_init_func_t) (ch_dev_t *dev_ptr, fw_info_t **fw_info) |
| ASIC firmware init function pointer typedef. | |
| typedef uint16_t(* | ch_get_amplitude_avg_func_t) (ch_dev_t *dev_ptr) |
| typedef uint8_t(* | ch_get_amplitude_data_func_t) (ch_dev_t *dev_ptr, uint16_t *buf_ptr, uint16_t start_sample, uint16_t num_samples, ch_io_mode_t io_mode) |
| typedef uint16_t(* | ch_get_amplitude_func_t) (ch_dev_t *dev_ptr) |
| typedef uint8_t(* | ch_get_cal_result_func_t) (ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr) |
| typedef uint8_t(* | ch_get_config_func_t) (ch_dev_t *dev_ptr, ch_config_t *config_ptr) |
| API function pointer typedefs. | |
| typedef uint8_t(* | ch_get_data_ready_delay_func_t) (ch_dev_t *dev_ptr) |
| typedef uint8_t(* | ch_get_iq_data_func_t) (ch_dev_t *dev_ptr, ch_iq_sample_t *buf_ptr, uint16_t start_sample, uint16_t num_samples, ch_io_mode_t io_mode) |
| typedef uint32_t(* | ch_get_range_func_t) (ch_dev_t *dev_ptr, ch_range_t range_type) |
| typedef uint16_t(* | ch_get_rx_low_gain_func_t) (ch_dev_t *dev_ptr) |
| typedef uint8_t(* | ch_get_target_int_counter_func_t) (ch_dev_t *dev_ptr, uint8_t *meas_hist_ptr, uint8_t *thresh_count_ptr, uint8_t *reset_ptr) |
| typedef ch_tgt_int_filter_t(* | ch_get_target_interrupt_func_t) (ch_dev_t *dev_ptr) |
| typedef uint16_t(* | ch_get_tx_length_func_t) (ch_dev_t *dev_ptr) |
| typedef enum ch_group_status | ch_group_status_t |
| Sensor group status. | |
| typedef struct ch_group_t | ch_group_t |
| typedef void(* | ch_io_complete_callback_t) (ch_group_t *grp_ptr) |
| Non-blocking I/O complete callback routine pointer. | |
| typedef void(* | ch_io_int_callback_t) (ch_group_t *grp_ptr, uint8_t io_index, ch_interrupt_type_t int_type) |
| Sensor interrupt callback routine pointer. | |
| typedef ch_output_type_t(* | ch_meas_get_iq_output_func_t) (ch_dev_t *dev_ptr, uint8_t meas_num) |
| typedef ch_meas_status_t(* | ch_meas_get_status_func_t) (ch_dev_t *dev_ptr, uint8_t meas_num) |
| typedef uint8_t(* | ch_meas_set_iq_output_func_t) (ch_dev_t *dev_ptr, uint8_t meas_num, ch_output_type_t output_format) |
| typedef uint16_t(* | ch_mm_to_samples_func_t) (ch_dev_t *dev_ptr, uint16_t num_mm) |
| typedef uint8_t(* | ch_set_cal_result_func_t) (ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr) |
| typedef uint8_t(* | ch_set_config_func_t) (ch_dev_t *dev_ptr, ch_config_t *config_ptr) |
| typedef uint8_t(* | ch_set_data_output_func_t) (ch_dev_t *dev_ptr, const ch_output_t *output) |
| typedef uint8_t(* | ch_set_data_ready_delay_func_t) (ch_dev_t *dev_ptr, uint8_t num_cycles) |
| typedef uint8_t(* | ch_set_frequency_func_t) (ch_dev_t *dev_ptr, uint32_t target_freq_Hz) |
| typedef uint8_t(* | ch_set_num_samples_func_t) (ch_dev_t *dev_ptr, uint16_t num_samples) |
| typedef uint8_t(* | ch_set_rx_low_gain_func_t) (ch_dev_t *dev_ptr, uint16_t num_samples) |
| typedef uint8_t(* | ch_set_sample_window_func_t) (ch_dev_t *dev_ptr, uint16_t start_sample, uint16_t end_sample) |
| typedef uint8_t(* | ch_set_target_int_counter_func_t) (ch_dev_t *dev_ptr, uint8_t meas_hist, uint8_t thresh_count, uint8_t reset) |
| typedef uint8_t(* | ch_set_target_interrupt_func_t) (ch_dev_t *dev_ptr, ch_tgt_int_filter_t tgt_int_filter) |
| typedef uint8_t(* | ch_set_tx_length_func_t) (ch_dev_t *dev_ptr, uint16_t tx_length) |
| typedef void(* | ch_timer_callback_t) (void) |
| Periodic timer callback routine pointer. | |
| typedef void(* | ch_trigger_soft_func_t) (ch_dev_t *dev_ptr) |
| typedef struct fw_info_st | fw_info_t |
Functions | |
| uint8_t | ch_check_program (ch_dev_t *dev_ptr) |
| Check sensor firmware program. More... | |
| uint8_t | ch_check_reset_state (ch_dev_t *dev_ptr, ch_sensor_reset_state_t *reset_state_ptr) |
| Check if sensor reset has occurred. More... | |
| uint16_t | ch_cycles_to_samples (uint32_t num_cycles, ch_odr_t odr) |
| Convert sensor cycles to samples. More... | |
| uint32_t | ch_cycles_to_usec (ch_dev_t *dev_ptr, uint32_t num_cycles) |
| Convert sensor cycles to microseconds. More... | |
| uint16_t | ch_data_validation_check (ch_dev_t *dev_ptr, ch_iq_sample_t *data, uint16_t num_samples) |
| Check data in validation mode, which should be enabled before calling this. Should be run over all IQ data received by the sensor after mode is enabled to keep the counters in sync. More... | |
| uint8_t | ch_enable_data_validation (ch_dev_t *dev_ptr, int16_t seed, uint8_t enable) |
| Enable data validation mode. In this mode, ICU-x0201 sensors will overwrite the IQ data at the end of a measurement and after running the algorithm, with a known sequence to allow validating data transfer integrity while making minimal changes to the system otherwise. Currently, this is limited to a 16-bit counter that increments for each I and Q sample and is continuous across measurements. More... | |
| uint8_t | ch_enable_double_buffer (ch_dev_t *dev_ptr, uint8_t enable) |
| Enable or disable the double buffering mode. More... | |
| uint8_t | ch_enable_metadata_in_iq0 (ch_dev_t *dev_ptr, uint8_t enable) |
| Enable or disable placing metadata in the first IQ sample. More... | |
| uint8_t | ch_freerun_time_hop_disable (ch_dev_t *dev_ptr) |
| Disable time-hopping on measure period freerunning mode. More... | |
| uint8_t | ch_freerun_time_hop_enable (ch_dev_t *dev_ptr) |
| Enable time-hopping on measure period freerunning mode. More... | |
| uint8_t | ch_get_algo_config (ch_dev_t *dev_ptr, void *algo_cfg_ptr) |
| Get the measurement algorithm configuration data from a sensor. More... | |
| uint8_t | ch_get_algo_info (ch_dev_t *dev_ptr, ICU_ALGO_SHASTA_INFO *algo_info_ptr) |
| Get the measurement algorithm information data from a sensor. More... | |
| uint8_t | ch_get_algo_output (ch_dev_t *dev_ptr, void *algo_out_ptr) |
| Get the measurement algorithm output data from a sensor. More... | |
| uint8_t | ch_get_algo_state (ch_dev_t *dev_ptr, void *algo_state_ptr) |
| Get the measurement algorithm state data from a sensor. More... | |
| uint8_t | ch_get_amp_thresh_data (ch_dev_t *dev_ptr, ch_amp_thresh_t *buf_ptr, uint16_t start_sample, uint16_t num_samples, ch_io_mode_t mode) |
| Get the amplitude measurement and threshold data from a sensor. More... | |
| uint16_t | ch_get_amplitude (ch_dev_t *dev_ptr) |
| Get the measured amplitude from a sensor. More... | |
| uint16_t | ch_get_amplitude_avg (ch_dev_t *dev_ptr) |
| Get the averaged measured amplitude over the sample window. More... | |
| uint8_t | ch_get_amplitude_data (ch_dev_t *dev_ptr, uint16_t *buf_ptr, uint16_t start_sample, uint16_t num_samples, ch_io_mode_t mode) |
| Get the raw amplitude measurement data from a sensor. More... | |
| uint16_t | ch_get_bandwidth (ch_dev_t *dev_ptr) |
| Get the bandwidth of a sensor. More... | |
| uint8_t | ch_get_bus (ch_dev_t *dev_ptr) |
| Get the active SPI/I2C bus for a sensor. More... | |
| uint8_t | ch_get_cal_result (ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr) |
| Get the calibration result. More... | |
| uint8_t | ch_get_config (ch_dev_t *dev_ptr, ch_config_t *config_ptr) |
| Get current configuration settings for a sensor. More... | |
| uint32_t | ch_get_cpu_frequency (ch_dev_t *dev_ptr) |
| Get the sensor CPU frequency, in Hz. More... | |
| uint8_t | ch_get_data_ready_delay (ch_dev_t *dev_ptr) |
| Get data ready interrupt delay interval. More... | |
| uint8_t | ch_get_dev_num (ch_dev_t *dev_ptr) |
| Get device number (I/O index values) for a sensor. More... | |
| ch_dev_t * | ch_get_dev_ptr (ch_group_t *grp_ptr, uint8_t dev_num) |
| Get device descriptor pointer for a sensor. More... | |
| uint16_t | ch_get_freerun_interval (ch_dev_t *dev_ptr) |
| Get the internal sensing timing interval for a sensor, in milliseconds. More... | |
| uint16_t | ch_get_freerun_interval_ticks (ch_dev_t *dev_ptr) |
| Get the internal sensing timing interval for a sensor, in RTC clock ticks. More... | |
| uint32_t | ch_get_freerun_interval_us (ch_dev_t *dev_ptr) |
| Get the internal sensing timing interval for a sensor, in microseconds. More... | |
| uint32_t | ch_get_frequency (ch_dev_t *dev_ptr) |
| Get the operating frequency of a sensor. More... | |
| const char * | ch_get_fw_version_string (ch_dev_t *dev_ptr) |
| Get the firmware version description string for a sensor. More... | |
| uint8_t | ch_get_i2c_address (ch_dev_t *dev_ptr) |
| Get the active I2C address for a sensor. More... | |
| ch_interrupt_drive_t | ch_get_interrupt_drive (ch_dev_t *dev_ptr) |
| Get the pulse interrupt drive setting. More... | |
| ch_interrupt_mode_t | ch_get_interrupt_mode (ch_dev_t *dev_ptr) |
| Get the pulse interrupt mode setting. More... | |
| uint8_t | ch_get_iq_data (ch_dev_t *dev_ptr, ch_iq_sample_t *buf_ptr, uint16_t start_sample, uint16_t num_samples, ch_io_mode_t mode) |
| Get the raw I/Q measurement data from a sensor. More... | |
| uint16_t | ch_get_max_range (ch_dev_t *dev_ptr) |
| Get the maximum range setting in mm for a sensor. More... | |
| uint16_t | ch_get_max_samples (ch_dev_t *dev_ptr) |
| Get the maximum possible sample count per measurement. More... | |
| uint8_t | ch_get_mfg_info (ch_dev_t *dev_ptr, ch_mfg_info_t *info_ptr) |
| Get manufacturing information for a sensor. More... | |
| ch_mode_t | ch_get_mode (ch_dev_t *dev_ptr) |
| Get the current operating mode for a sensor. More... | |
| uint16_t | ch_get_next_buf_addr (ch_dev_t *dev_ptr) |
| Get the address of the IQ buffer that will be written by the next measurement. More... | |
| uint16_t | ch_get_num_output_samples (ch_dev_t *dev_ptr) |
| Get the number of valid output samples in last measurement. More... | |
| uint8_t | ch_get_num_ports (ch_group_t *grp_ptr) |
| Get the total number of sensor ports (possible sensors) in a sensor group. More... | |
| uint16_t | ch_get_num_samples (ch_dev_t *dev_ptr) |
| Get the number of samples per measurement cycle. More... | |
| uint16_t | ch_get_part_number (ch_dev_t *dev_ptr) |
| Get part number for a sensor. More... | |
| ch_pmut_clk_cfg_t | ch_get_pmut_clock (ch_dev_t *dev_ptr) |
| Get ultrasound transducer clock configuration. More... | |
| uint32_t | ch_get_range (ch_dev_t *dev_ptr, ch_range_t range_type) |
| Get the measured range from a sensor. More... | |
| uint16_t | ch_get_rtc_cal_pulselength (ch_dev_t *dev_ptr) |
| Get the real-time clock calibration pulse length. More... | |
| uint16_t | ch_get_rtc_cal_result (ch_dev_t *dev_ptr) |
| Get the real-time clock calibration value. More... | |
| uint16_t | ch_get_rtc_frequency (ch_dev_t *dev_ptr) |
| Get the sensor real-time clock (RTC) frequency, in Hz. More... | |
| uint16_t | ch_get_rx_holdoff (ch_dev_t *dev_ptr) |
| Get the receive holdoff sample count. More... | |
| uint16_t | ch_get_rx_low_gain (ch_dev_t *dev_ptr) |
| Get the receive low-gain sample count. More... | |
| uint8_t | ch_get_rx_pretrigger (ch_group_t *grp_ptr) |
| Get receive-only sensor pre-triggering setting. More... | |
| uint16_t | ch_get_sample_interval (ch_dev_t *dev_ptr) |
| Get the internal sensing timing interval for a sensor (deprecated). More... | |
| uint8_t | ch_get_sample_window (ch_dev_t *dev_ptr, uint16_t *start_sample_ptr, uint16_t *num_samples_ptr) |
| Get the sample window for amplitude averaging. More... | |
| uint16_t | ch_get_scale_factor (ch_dev_t *dev_ptr) |
| Get the amplitude scale factor of a sensor. More... | |
| const char * | ch_get_sensor_id (ch_dev_t *dev_ptr) |
| Get the unique Sensor ID String for a sensor. More... | |
| uint8_t | ch_get_target_int_counter (ch_dev_t *dev_ptr, uint8_t *meas_hist_ptr, uint8_t *thresh_count_ptr, uint8_t *reset_ptr) |
| Get the target interrupt counter filter settings. More... | |
| ch_tgt_int_filter_t | ch_get_target_interrupt (ch_dev_t *dev_ptr) |
| Get the target interrupt filtering mode setting. More... | |
| ch_trigger_type_t | ch_get_trigger_type (ch_dev_t *dev_ptr) |
| Get the trigger type for a sensor. More... | |
| uint16_t | ch_get_tx_length (ch_dev_t *dev_ptr) |
| Get the ultrasound transmit pulse length. More... | |
| void | ch_get_version (ch_version_t *version_ptr) |
| Get the SonicLib version number. More... | |
| uint32_t | ch_group_get_frequency (ch_group_t *grp_ptr) |
| Get the operating frequency for a group of sensors. More... | |
| uint32_t | ch_group_get_pmut_clock_freq (ch_group_t *grp_ptr) |
| Get the transducer clock input frequency for a group of sensors. More... | |
| uint8_t | ch_group_init (ch_group_t *grp_ptr, uint8_t num_devices, uint8_t num_buses, uint16_t rtc_cal_pulse_ms) |
| Initialize the group descriptor for a group of sensors. More... | |
| void | ch_group_reset (ch_group_t *grp_ptr, ch_reset_t reset_type) |
| Reset a group of sensors. More... | |
| uint8_t | ch_group_restart (ch_group_t *grp_ptr) |
| Restart a group of sensors. More... | |
| uint8_t | ch_group_set_frequency (ch_group_t *grp_ptr, uint32_t request_op_freq_hz) |
| Set the operating frequency for a group of sensors. More... | |
| void | ch_group_set_pmut_clock_freq (ch_group_t *grp_ptr, uint32_t pmut_clock_freq) |
| Specify the transducer clock input frequency for a group of sensors. More... | |
| uint8_t | ch_group_start (ch_group_t *grp_ptr) |
| Program and start a group of sensors. More... | |
| void | ch_group_trigger (ch_group_t *grp_ptr) |
| Trigger a measurement on a group of sensors. More... | |
| uint8_t | ch_init (ch_dev_t *dev_ptr, ch_group_t *grp_ptr, uint8_t dev_num, ch_fw_init_func_t fw_init_func) |
| Initialize the device descriptor for a sensor. More... | |
| uint8_t | ch_init_algo (ch_dev_t *dev_ptr) |
| Initialize the measurement algorithm on a sensor. More... | |
| void | ch_interrupt (ch_group_t *grp_ptr, uint8_t dev_num) |
| Run SonicLib's full-featured interrupt handler. More... | |
| void | ch_io_complete_callback_set (ch_group_t *grp_ptr, ch_io_complete_callback_t callback_func_ptr) |
| Register non-blocking I/O complete callback routine for a group of sensors. More... | |
| void | ch_io_int_callback_set (ch_group_t *grp_ptr, ch_io_int_callback_t callback_func_ptr) |
| Register sensor interrupt callback routine for a group of sensors. More... | |
| void | ch_io_notify (ch_group_t *grp_ptr, uint8_t bus_index) |
| Notify SonicLib that a non-blocking I/O operation has completed. More... | |
| uint8_t | ch_io_start_nb (ch_group_t *grp_ptr) |
| Start non-blocking I/O operation(s) for a group of sensors. More... | |
| uint16_t | ch_iq_to_amplitude (ch_iq_sample_t *iq_sample_ptr) |
| Calculate amplitude from sample I/Q values. More... | |
| void | ch_log_append (uint8_t log_id, ch_log_fmt_t format, uint64_t timestamp, ch_log_data_t *log_data_ptr) |
| Append received sensor data to log. More... | |
| uint8_t | ch_log_init (ch_group_t *grp_ptr, ch_log_fmt_t format, ch_log_cfg_t *config_ptr) |
| Initialize a log in the specified log format. More... | |
| void | ch_meas_activate (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Activate a defined measurement. More... | |
| uint8_t | ch_meas_add_segment (ch_dev_t *dev_ptr, uint8_t meas_num, ch_meas_segment_t *seg_ptr) |
| Add a segment to a measurement. More... | |
| uint8_t | ch_meas_add_segment_count (ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_cycles, uint8_t int_enable) |
| Add a count (delay) segment to a measurement. More... | |
| uint8_t | ch_meas_add_segment_rx (ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_samples, uint8_t gain_reduce, uint8_t atten, uint8_t int_enable) |
| Add a receive segment to a measurement. More... | |
| uint8_t | ch_meas_add_segment_tx (ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_cycles, uint8_t pulse_width, uint8_t phase, uint8_t int_enable) |
| Add a transmit segment to a measurement. More... | |
| void | ch_meas_get_info (ch_dev_t *dev_ptr, uint8_t meas_num, ch_meas_info_t *info_ptr) |
| Get configuration information for a measurement. More... | |
| uint16_t | ch_meas_get_interval (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Get the repeat interval for a measurement, in milliseconds. More... | |
| uint32_t | ch_meas_get_interval_ticks (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Get the repeat interval for a measurement, in sensor RTC clock ticks. More... | |
| uint32_t | ch_meas_get_interval_us (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Get the repeat interval for a measurement, in microseconds. More... | |
| ch_output_type_t | ch_meas_get_iq_output (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Get the I/Q data output format for a measurement. More... | |
| uint8_t | ch_meas_get_last_num (ch_dev_t *dev_ptr) |
| Get number of last completed measurement. More... | |
| uint16_t | ch_meas_get_max_range (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Get the maximum range setting in mm for a specific measurement. More... | |
| uint16_t | ch_meas_get_num_samples (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Get the number of samples per measurement cycle for a specific measurement. More... | |
| ch_odr_t | ch_meas_get_odr (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Get the output data rate for a measurement. More... | |
| uint8_t | ch_meas_get_queue (ch_dev_t *dev_ptr, measurement_queue_t *meas_queue_ptr) |
| Get measurement queue values for a sensor. More... | |
| void | ch_meas_get_queue_info (ch_dev_t *dev_ptr, ch_meas_queue_info_t *info_ptr) |
| Get configuration information for the sensor measurement queue. More... | |
| void | ch_meas_get_seg_info (ch_dev_t *dev_ptr, uint8_t meas_num, uint8_t seg_num, ch_meas_seg_info_t *info_ptr) |
| Get configuration information for a measurement segment. More... | |
| ch_meas_status_t | ch_meas_get_status (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Get measurement status. More... | |
| uint8_t | ch_meas_import (ch_dev_t *dev_ptr, measurement_queue_t *meas_queue_ptr, void *algo_cfg_ptr) |
| Import an externally defined measurement configuration. More... | |
| uint8_t | ch_meas_init (ch_dev_t *dev_ptr, uint8_t meas_num, const ch_meas_config_t *meas_config_ptr, const void *thresh_ptr) |
| Initialize a measurement. More... | |
| uint8_t | ch_meas_init_queue (ch_dev_t *dev_ptr) |
| Initialize the sensor measurement queue. More... | |
| void | ch_meas_init_segment_count (ch_meas_segment_t *seg_ptr, uint16_t num_cycles, uint8_t int_enable) |
| Initialize a count (delay) measurement segment. More... | |
| void | ch_meas_init_segment_rx (ch_meas_segment_t *seg_ptr, uint16_t num_samples, ch_odr_t odr, uint8_t gain_reduce, uint8_t atten, uint8_t int_enable) |
| Initialize a receive measurement segment. More... | |
| void | ch_meas_init_segment_tx (ch_meas_segment_t *seg_ptr, uint16_t num_cycles, uint8_t pulse_width, uint8_t phase, uint8_t int_enable) |
| Initialize a transmit measurement segment. More... | |
| uint8_t | ch_meas_insert_instruction (ch_dev_t *dev_ptr, uint8_t meas_num, const ch_meas_segment_t *inst_ptr, uint8_t index_to_insert) |
| Insert an instruction(segment) to a measurement. More... | |
| uint8_t | ch_meas_insert_segment (ch_dev_t *dev_ptr, uint8_t meas_num, const ch_meas_segment_t *inst_ptr, uint8_t index_to_insert) |
| Insert an instruction(segment) to a measurement. More... | |
| uint16_t | ch_meas_mm_to_samples (ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_mm) |
| Convert millimeters to sample count for a specific measurement. More... | |
| uint8_t | ch_meas_optimize (ch_dev_t *dev_ptr, measurement_queue_t *meas_queue_ptr, void *algo_cfg_ptr) |
| Optimize ultrasound measurement sequences for a sensor. More... | |
| uint8_t | ch_meas_remove_instruction (ch_dev_t *dev_ptr, uint8_t meas_num, uint8_t index_to_remove) |
| Remove an instruction(segment) in a measurement. More... | |
| uint8_t | ch_meas_remove_segment (ch_dev_t *dev_ptr, uint8_t meas_num, uint8_t index_to_remove) |
| Remove an instruction(segment) in a measurement. More... | |
| uint8_t | ch_meas_reset (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Reset a measurement. More... | |
| uint16_t | ch_meas_samples_to_mm (ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_samples) |
| Convert sample count to millimeters for a specific measurement. More... | |
| uint8_t | ch_meas_set_interval (ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t interval_ms) |
| Set the repeat interval for a measurement, in milliseconds. More... | |
| uint8_t | ch_meas_set_interval_ticks (ch_dev_t *dev_ptr, uint8_t meas_num, uint32_t rtc_ticks) |
| Set the repeat interval for a measurement, in sensor RTC clock ticks. More... | |
| uint8_t | ch_meas_set_interval_us (ch_dev_t *dev_ptr, uint8_t meas_num, uint32_t interval_us) |
| Set the repeat interval for a measurement, in microseconds. More... | |
| uint8_t | ch_meas_set_iq_output (ch_dev_t *dev_ptr, uint8_t meas_num, ch_output_type_t output_format) |
| Set the I/Q data output format for a measurement. More... | |
| uint8_t | ch_meas_set_max_range (ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t max_range_mm) |
| Set the maximum range in mm for a specific measurement. More... | |
| uint8_t | ch_meas_set_num_samples (ch_dev_t *dev_ptr, uint8_t meas_num, uint16_t num_samples) |
| Set the sensor sample count for a specific measurement. More... | |
| uint8_t | ch_meas_set_odr (ch_dev_t *dev_ptr, uint8_t meas_num, ch_odr_t odr) |
| Set the output data rate for a measurement. More... | |
| void | ch_meas_standby (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Put a measurement in standby mode. More... | |
| uint8_t | ch_meas_switch (ch_dev_t *dev_ptr) |
| Switch active and standby measurement definitions. More... | |
| uint8_t | ch_meas_time_hop_disable (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Disable time-hopping on measure period freerunning mode. More... | |
| uint8_t | ch_meas_time_hop_enable (ch_dev_t *dev_ptr, uint8_t meas_num) |
| Enable time-hopping on measure period freerunning mode. More... | |
| uint8_t | ch_meas_write_config (ch_dev_t *dev_ptr) |
| Write measurement configuration to sensor. More... | |
| uint32_t | ch_measure_pmut_frequency (ch_dev_t *dev_ptr) |
| Measure PMUT frequency on an ICU device. More... | |
| uint8_t | ch_minimal_int_handler (ch_group_t *grp_ptr, uint8_t dev_num) |
| Notify SonicLib that a sensor interrupt was received. More... | |
| uint16_t | ch_mm_to_samples (ch_dev_t *dev_ptr, uint16_t num_mm) |
| Convert millimeters to sample count for a sensor. More... | |
| void | ch_reset (ch_dev_t *dev_ptr, ch_reset_t reset_type) |
| Reset a sensor. More... | |
| uint8_t | ch_restart (ch_dev_t *dev_ptr) |
| Restart a sensor. More... | |
| uint32_t | ch_samples_to_cycles (uint16_t num_samples, ch_odr_t odr) |
| Convert samples to sensor cycles. More... | |
| uint16_t | ch_samples_to_mm (ch_dev_t *dev_ptr, uint16_t num_samples) |
| Convert sample count to millimeters for a sensor. More... | |
| uint8_t | ch_sensor_is_connected (ch_dev_t *dev_ptr) |
| Indicate if a sensor is connected. More... | |
| uint8_t | ch_set_algo_config (ch_dev_t *dev_ptr, const void *algo_cfg_ptr) |
| Set the measurement algorithm configuration data to a sensor. More... | |
| uint8_t | ch_set_cal_result (ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr) |
| Set the calibration result. More... | |
| uint8_t | ch_set_config (ch_dev_t *dev_ptr, ch_config_t *config_ptr) |
| Set multiple configuration settings for a sensor. More... | |
| uint8_t | ch_set_data_output (ch_dev_t *dev_ptr, ch_output_t *output_ptr) |
| Set data output format and rate. More... | |
| uint8_t | ch_set_data_ready_delay (ch_dev_t *dev_ptr, uint8_t delay_ms) |
| Set data ready interrupt delay interval. More... | |
| uint8_t | ch_set_freerun_interval (ch_dev_t *dev_ptr, uint16_t interval_ms) |
| Set the internal sensing interval for freerunning mode, in milliseconds. More... | |
| uint8_t | ch_set_freerun_interval_ticks (ch_dev_t *dev_ptr, uint32_t interval_ticks) |
| Set the internal sensing interval for freerunning mode, in RTC clock ticks. More... | |
| uint8_t | ch_set_freerun_interval_us (ch_dev_t *dev_ptr, uint32_t interval_us) |
| Set the internal sensing interval for freerunning mode, in microseconds. More... | |
| uint8_t | ch_set_frequency (ch_dev_t *dev_ptr, uint32_t request_op_freq_hz) |
| Set the operating frequency of a sensor. More... | |
| uint8_t | ch_set_init_firmware (ch_dev_t *dev_ptr, ch_fw_init_func_t fw_init_func) |
| Initialize the init firmware to use for a sensor. More... | |
| uint8_t | ch_set_interrupt_drive (ch_dev_t *dev_ptr, ch_interrupt_drive_t drive) |
| Set interrupt drive (open drain or push pull) More... | |
| uint8_t | ch_set_interrupt_mode (ch_dev_t *dev_ptr, ch_interrupt_mode_t mode) |
| Set interrupt mode (pulsed or latching) More... | |
| uint8_t | ch_set_max_range (ch_dev_t *dev_ptr, uint16_t max_range) |
| Set the maximum range for a sensor. More... | |
| uint8_t | ch_set_mode (ch_dev_t *dev_ptr, ch_mode_t mode) |
| Configure a sensor for the specified operating mode. More... | |
| uint8_t | ch_set_num_samples (ch_dev_t *dev_ptr, uint16_t num_samples) |
| Set the sensor sample count directly. More... | |
| uint8_t | ch_set_pmut_clock (ch_dev_t *dev_ptr, ch_pmut_clk_cfg_t clock_cfg) |
| Configure ultrasound transducer clock. More... | |
| uint8_t | ch_set_rtc (ch_dev_t *dev_ptr, ch_rtc_src_t rtc_source, uint16_t rtc_freq) |
| Configure the sensor real-time clock (RTC). More... | |
| uint8_t | ch_set_rx_holdoff (ch_dev_t *dev_ptr, uint16_t num_samples) |
| Set the receive holdoff sample count. More... | |
| uint8_t | ch_set_rx_low_gain (ch_dev_t *dev_ptr, uint16_t num_samples) |
| Set the receive low-gain sample count. More... | |
| void | ch_set_rx_pretrigger (ch_group_t *grp_ptr, uint8_t enable) |
| Enable/disable receive-only sensor pre-triggering. More... | |
| uint8_t | ch_set_sample_interval (ch_dev_t *dev_ptr, uint16_t interval_ms) |
| Set the internal sensing interval (deprecated). More... | |
| uint8_t | ch_set_sample_window (ch_dev_t *dev_ptr, uint16_t start_sample, uint16_t num_samples) |
| Set the sample window for amplitude averaging. More... | |
| uint8_t | ch_set_target_int_counter (ch_dev_t *dev_ptr, uint8_t meas_hist, uint8_t thresh_count, uint8_t reset) |
| Configure the target interrupt counter filter. More... | |
| uint8_t | ch_set_target_interrupt (ch_dev_t *dev_ptr, ch_tgt_int_filter_t tgt_int_filter) |
| Configure target interrupt filtering mode. More... | |
| void | ch_set_trigger_type (ch_dev_t *dev_ptr, ch_trigger_type_t trig_type) |
| Set the trigger type for a sensor. More... | |
| uint8_t | ch_set_tx_length (ch_dev_t *dev_ptr, uint16_t num_cycles) |
| Set the ultrasound transmit pulse length. More... | |
| uint32_t | ch_ticks_to_usec (ch_dev_t *dev_ptr, uint16_t num_ticks) |
| Convert sensor RTC clock ticks to microseconds. More... | |
| void | ch_trigger (ch_dev_t *dev_ptr) |
| Trigger a measurement on one sensor. More... | |
| void | ch_trigger_soft (ch_dev_t *dev_ptr) |
| Trigger a measurement using software (SPI) interface. More... | |
| uint8_t | ch_update_metadata_from_iq0 (ch_dev_t *dev_ptr, ch_iq_sample_t *iq_data) |
| Extract the metadata from the first IQ sample and update the device pointer. More... | |
| uint32_t | ch_usec_to_cycles (ch_dev_t *dev_ptr, uint32_t num_usec) |
| Convert microseconds to sensor cycles. More... | |
| uint16_t | ch_usec_to_ticks (ch_dev_t *dev_ptr, uint32_t num_usec) |
| Convert microseconds to sensor RTC clock ticks. More... | |
| uint8_t | ch_watchdog_disable (ch_dev_t *dev_ptr) |
| Disable watchdog timer in sensor. More... | |
| uint8_t | ch_watchdog_enable (ch_dev_t *dev_ptr) |
| Enable watchdog timer in sensor. More... | |
SonicLib public API and support functions for TDK/InvenSense ultrasonic sensors (originally developed by Chirp Microsystems).
SonicLib is a set of API functions and sensor driver routines designed to easily control ultrasonic sensors from an embedded C application. It allows an application developer to obtain ultrasonic measurement data from one or more devices, without needing to develop special low-level code to interact with the sensors directly.
The SonicLib API functions provide a consistent interface for an application to use ultrasonic sensors in various situations. This is especially important, because all TDK/InvenSense ultrasonic sensors are completely programmable, including the memory map. The SonicLib interfaces allow an application to use different sensor firmware images, without requiring code changes. Only a single initialization parameter must be modified to use the new sensor firmware.
SonicLib is used with all TDK/InvenSense ultrasonic sensors and firmware types and contains all necessary functions to initialize and manage the devices. It includes a complete set of interfaces for typical rangefinding applications that measure distance using the sensor(s). Certain special sensor firmware may support unusual features, and additional API interfaces for those special functions may be distributed separately.
All function names in the SonicLib API begin with ch_.
details subdirectory. Using any of these internal definitions will reduce your ability to benefit from future enhancements and releases from TDK/InvenSense.SonicLib also defines a set of board support package (BSP) functions that must be provided by the developer, board vendor, or TDK/InvenSense. The BSP functions are NOT part of SonicLib - they are external interface routines that allow the SonicLib functions to access the peripherals on the target board. These functions, which all begin with a "chbsp_" prefix, are described in the chirp_bsp.h header file. See the descriptions in that file for more detailed information on the BSP interfaces.
Additionally, SonicLib requires the definition of a few static configuration symbols. These are generally board dependent and are used to set the size of static arrays, choose between hardware features that are unlikely to ever change at runtime, etc.
There are two ways to provide these symbols. The default behavior expects a header called chirp_board_config.h to be directly on the include path. A default implementation of this file is provided with the BSP, or can be copied from <invn/soniclib/details/chirp_board_config.h>. Once copied and placed in your project, you can edit it to meet your needs. Make sure that your build places the directory containing chirp_board_config.h on the include path (gcc -I option).
The second method for providing the symbols is to use the build system define flags. For example, you can use the -D option with gcc. To use this method, you must first define the symbol INVN_SONICLIB_INTERNAL_BOARD_CONFIG. This will cause soniclib to use the board config in <invn/soniclib/details>. You should not edit this file directly. Instead, to change the value of the symbols defined there, simply override them with -D flags during the build.
At a high level, an application using SonicLib will do the following:
There are dedicated ch_set_xxx() functions for all configuration values. Simple configurations may be able to use the ch_set_config() convenience function to configure the sensor and set the mode.
At this point, the sensor will begin to perform measurements. At the end of each measurement cycle, the sensor will interrupt the host controller using its INT line. The handler routine set up in step #4 above will be called, and it should cause the application to read the measurement results from the sensor(s), using ch_get_range() and optionally ch_get_amplitude() and/or ch_get_iq_data().
Do not trigger a new measurement until the previous measurement has completed and all needed data has been read from the device (including I/Q data, if ch_get_iq_data() is used). If any I/O operations are still active, the new measurement may be corrupted.
To assist with debugging, verbose debug output from various internal SonicLib functions may be enabled by defining CH_LOG_MODULE_LEVEL=X during the system build.
| #define CH101_MAX_NUM_SAMPLES (225) |
Max expected samples per measurement for CH101.
| #define CH101_PART_NUMBER (101) |
Integer sensor identifier for CH101.
| #define CH201_MAX_NUM_SAMPLES (450) |
Max expected samples per measurement for CH201.
| #define CH201_PART_NUMBER (201) |
Integer sensor identifier for CH201.
| #define CH_DEFAULT_MEAS_NUM (0) |
Measurement number to use for simple ch_mm_to_samples() etc.
| #define CH_DEFAULT_TARGET_NUM (0) |
Target number to report for simple ch_get_range() etc.
| #define CH_I2C_ADDR_PROG (0x45) |
I2C address of sensor programming interface.
| #define CH_MAX_NUM_TARGETS (1) |
Maximum number of targets supported in sensor f/w
| #define CH_MEAS_MAX_MEAS (MEAS_QUEUE_MAX_MEAS) |
max number of measurements in meas queue
| #define CH_MEAS_MAX_SEGMENTS (INST_BUF_LENGTH) |
max number of segments in a measurement
| #define CH_MIN_RANGE_VAL (0x0001) |
Minimum range value returned for very short distances
| #define CH_NO_TARGET (0xFFFFFFFF) |
Range value returned if no target was detected.
| #define CH_OP_FREQ_USE_AVG (0) |
Special freq value to use average op freq for sensor group
| #define CH_PMUT_TICKS_PER_CYCLE (16) |
Number of PMUT clock ticks per transducer cycle
| #define CH_RTC_FREQ_TYPICAL (29000) |
Typical sensor RTC frequency, in Hz, to use if none available.
| #define CH_RTC_USE_BUS_SPEED (UINT16_MAX) |
Special value for RTC freq estimate, use I/O bus
| #define CH_SENSOR_ID_LENGTH 8 |
length of sensor ID string in bytes: 3 byte lot + 4 byte serial num + null
| #define CH_SIG_BYTE_0 (0x0a) |
Signature byte in sensor (1 of 2).
| #define CH_SIG_BYTE_1 (0x02) |
Signature byte in sensor (2 of 2).
| #define CH_SPEEDOFSOUND_MPS (343) |
Speed of sound, in meters per second.
| #define CH_TARGET_INT_HIST_DEFAULT (5) |
Default number of measurements included in target history
| #define CH_TARGET_INT_HIST_MAX (15) |
Maximum number of measurements included in target history
| #define CH_TARGET_INT_THRESH_DEFAULT (3) |
Default num targets in history required to interrupt
| #define CH_WINDOW_MAX_SAMPLES (64) |
Maximum number of samples in a sample window
| #define I2C_DRV_FLAG_RESET_AFTER_NB (0x00000001) |
I2C interface needs reset after non-blocking transfer.
| #define I2C_DRV_FLAG_USE_PROG_NB (0x00000002) |
Use programming interface for non-blocking transfer.
| #define ICU10201_PART_NUMBER (10201) |
Integer sensor identifier for ICU-10201.
| #define ICU20201_PART_NUMBER (20201) |
Integer sensor identifier for ICU-20201.
| #define ICU30201_PART_NUMBER (30201) |
Integer sensor identifier for ICU-30201.
| #define ICU_MAX_NUM_SAMPLES (IQ_SAMPLES_MAX) |
Max for ICU sensors, from shasta_external_regs.h
| #define ICU_UNKNOWN_PART_NUMBER (0) |
Integer sensor identifier for unknown ICU sensors.
| #define SONICLIB_VER_MAJOR (4) |
SonicLib major version.
| #define SONICLIB_VER_MINOR (5) |
SonicLib minor version.
| #define SONICLIB_VER_REV (2) |
SonicLib revision.
| #define SONICLIB_VER_SUFFIX "" |
SonicLib version suffix (contains pre-release info)
| enum ch_asic_gen_t |
| enum ch_group_status |
| enum ch_interrupt_drive_t |
| enum ch_interrupt_mode_t |
| enum ch_interrupt_type_t |
Sensor interrupt types.
| enum ch_io_mode_t |
| enum ch_meas_mode_t |
| enum ch_meas_status_t |
Measurement status.
| enum ch_mode_t |
Sensor operating modes.
| enum ch_odr_t |
Sensor output data rate (ODR).
| enum ch_output_type_t |
| enum ch_pmut_clk_cfg_t |
PMUT clock configuration (ICU sensors)
| enum ch_prod_code_t |
| enum ch_range_t |
| enum ch_reset_t |
| enum ch_rtc_cal_t |
| enum ch_rtc_src_t |
| enum ch_rtc_status_t |
Sensor real-time clock status.
| enum ch_tgt_int_filter_t |
| enum ch_trigger_type_t |
| uint8_t ch_check_program | ( | ch_dev_t * | dev_ptr | ) |
Check sensor firmware program.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function confirms that the contents of the sensor's program memory match the firmware that was loaded into it, as specified during the ch_init() call. The memory contents are read back from the sensor and are compared with the original byte values used to program the device.
| uint8_t ch_check_reset_state | ( | ch_dev_t * | dev_ptr, |
| ch_sensor_reset_state_t * | reset_state_ptr | ||
| ) |
Check if sensor reset has occurred.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| reset_state_ptr | pointer to variable that will be updated with the ch_sensor_reset_state_t value. 0 = No Reset, 1 = Reset has occurred. |
This function calls the driver function to check if the sensor has reset.
This API can be called periodically in a measurement loop to check if the sensor was arbitrarily reset. If this reset event is detected during normal sensor operation the sensor has to be completely re-initialized similar to a power-on condition.
| uint16_t ch_cycles_to_samples | ( | uint32_t | num_cycles, |
| ch_odr_t | odr | ||
| ) |
Convert sensor cycles to samples.
| num_cycles | number of cycles |
| odr | output data rate |
This function takes a count of internal sensor cycles and converts it to the corresponding number of sample periods. The cycles are the same units used to specify measurement segment lengths.
The odr parameter is the current output data rate setting for the sensor. The ODR affects the timing between samples, and therefore the number of internal cycles per sample.
See also ch_samples_to_cycles, ch_meas_get_odr.
| uint32_t ch_cycles_to_usec | ( | ch_dev_t * | dev_ptr, |
| uint32_t | num_cycles | ||
| ) |
Convert sensor cycles to microseconds.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| num_cycles | number of cycles |
This function takes a number of internal sensor cycles and converts it to the corresponding period of time specified in microseconds.
For ICU (Shasta architecture) sensors, num_cycles are in units of PMUT State Machine Clock (SMCLK) cycles. The SMCLK rate is 16 times the ultrasonic transducer acoustic operating frequency. These are the same units used to specify measurement transmit and count segment lengths.
For CH101 and CH201 (Whitney architecture) sensors, num_cycles are ultrasonic transducer cycles, so are 1/16 the corresponding ICU sensor value.
See also ch_usec_to_cycles().
| uint16_t ch_data_validation_check | ( | ch_dev_t * | dev_ptr, |
| ch_iq_sample_t * | data, | ||
| uint16_t | num_samples | ||
| ) |
Check data in validation mode, which should be enabled before calling this. Should be run over all IQ data received by the sensor after mode is enabled to keep the counters in sync.
Note that for some values of receive length, this will be unreliable - avoid using overall RX lengths 1 to 5 cycles longer than integer multiples of the ODR ratio.
| dev_ptr | The device pointer |
| data | Pointer to IQ buffer containing data sequence read from the sensor |
| num_samples | Number of IQ samples in buffer |
| uint8_t ch_enable_data_validation | ( | ch_dev_t * | dev_ptr, |
| int16_t | seed, | ||
| uint8_t | enable | ||
| ) |
Enable data validation mode. In this mode, ICU-x0201 sensors will overwrite the IQ data at the end of a measurement and after running the algorithm, with a known sequence to allow validating data transfer integrity while making minimal changes to the system otherwise. Currently, this is limited to a 16-bit counter that increments for each I and Q sample and is continuous across measurements.
This feature is currently only supported by icu_init_fw. It is not recommended to use it if the application uses continuous receive, or has non-contiguous RX segments in its measurement queue. Enabling data validation adds approximately 0.8μs per IQ sample to the measurement time. Note that for each sample, the counter value is incremented in the order of Q then I. Data validation must be handled by the application using ch_data_validation_check().
| dev_ptr | The device pointer |
| seed | Initial value for data validation counter |
| enable | Set to 1 to enable data validation mode, set to 0 to disable |
| uint8_t ch_enable_double_buffer | ( | ch_dev_t * | dev_ptr, |
| uint8_t | enable | ||
| ) |
Enable or disable the double buffering mode.
IMPORTANT: This function is currently only supported with gpt and init firmware.
The ICU-X0201 sensors can be put into a double buffering mode which does the following:
This enables a measurement to be triggered before the readout of the previous measurement is finished (or even started). The disadvantage is that the maximum number of supported samples is reduced by a factor of 2.
You must not exceed the maximum number of supported samples, which can be found as ch_get_max_samples(...)/2. SonicLib will not check this!
| dev_ptr | The device pointer |
| enable | Set to 1 to enable the double buffer mode or 0 to disable it |
| uint8_t ch_enable_metadata_in_iq0 | ( | ch_dev_t * | dev_ptr, |
| uint8_t | enable | ||
| ) |
Enable or disable placing metadata in the first IQ sample.
IMPORTANT: This function is currently only supported with gpt and init firmware.
The ICU-X0201 can be configured to place metadata in the first IQ sample, which is otherwise always read out as 0. If enabled, this will place the IQ buffer address as well as the last measurement index in the first IQ sample.
| dev_ptr | The device pointer |
| enable | Set to 1 to enable metadata in IQ sample 0 or 0 to disable. |
| uint8_t ch_freerun_time_hop_disable | ( | ch_dev_t * | dev_ptr | ) |
Disable time-hopping on measure period freerunning mode.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function disable the time-hopping for a sensor operating in freerunning mode (CH_MODE_FREERUN).
See also ch_freerun_time_hop_enable(), ch_get_freerun_interval_ticks(), ch_set_freerun_interval(), ch_set_freerun_interval_us(), ch_set_freerun_interval_ticks().
| uint8_t ch_freerun_time_hop_enable | ( | ch_dev_t * | dev_ptr | ) |
Enable time-hopping on measure period freerunning mode.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function enables the time-hopping for a sensor operating in freerunning mode (CH_MODE_FREERUN). The sensor will use its internal real-time clock (RTC) to wake and perform a measurement every measure interval plus a random delay to avoid coexistence with other sensors. Mean measure period is however equals to measure interval.
See also ch_freerun_time_hop_disable(), ch_get_freerun_interval_ticks(), ch_set_freerun_interval(), ch_set_freerun_interval_us(), ch_set_freerun_interval_ticks().
| uint8_t ch_get_algo_config | ( | ch_dev_t * | dev_ptr, |
| void * | algo_cfg_ptr | ||
| ) |
Get the measurement algorithm configuration data from a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| algo_cfg_ptr | pointer to a buffer to receive configuration data |
This function reads the configuration data from an algorithm running on the ICU sensor. This interface is independent of the specific algorithm or configuration format.
Normally, this routine will only be used by special applications or libraries which interact with specific sensor firmware. It is not used directly in a typical application.
| uint8_t ch_get_algo_info | ( | ch_dev_t * | dev_ptr, |
| ICU_ALGO_SHASTA_INFO * | algo_info_ptr | ||
| ) |
Get the measurement algorithm information data from a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| algo_info_ptr | pointer to a ICU_ALGO_SHASTA_INFO structure to receive info |
This function reads the information data from an algorithm running on the ICU sensor. This interface is independent of the specific algorithm that is being used.
Normally, this routine will only be used by special applications or libraries which interact with specific sensor firmware. It is not used directly in a typical application.
| uint8_t ch_get_algo_output | ( | ch_dev_t * | dev_ptr, |
| void * | algo_out_ptr | ||
| ) |
Get the measurement algorithm output data from a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| algo_out_ptr | pointer to a buffer to receive output data |
This function reads the output data from an algorithm running on the ICU sensor. This interface is independent of the specific algorithm or output format.
Normally, this routine will only be used by special applications or libraries which interact with specific sensor firmware. It is not used directly in a typical application.
| uint8_t ch_get_algo_state | ( | ch_dev_t * | dev_ptr, |
| void * | algo_state_ptr | ||
| ) |
Get the measurement algorithm state data from a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| algo_state_ptr | pointer to a buffer to receive state data |
This function reads the state data from an algorithm running on the ICU sensor. This interface is independent of the specific algorithm or state format.
Normally, this routine will only be used by special applications or libraries which interact with specific sensor firmware. It is not used directly in a typical application.
| uint8_t ch_get_amp_thresh_data | ( | ch_dev_t * | dev_ptr, |
| ch_amp_thresh_t * | buf_ptr, | ||
| uint16_t | start_sample, | ||
| uint16_t | num_samples, | ||
| ch_io_mode_t | mode | ||
| ) |
Get the amplitude measurement and threshold data from a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| buf_ptr | pointer to data buffer where amplitude and threshold data will be written |
| start_sample | starting sample number within measurement data (0 = start of data) |
| num_samples | number of samples to read from sensor |
| mode | whether read should block (CH_IO_MODE_BLOCK (0) = blocking, CH_IO_MODE_NONBLOCK (1) = non-blocking) |
This function obtains specially formatted sample data from the sensor, in which both the amplitude and the detection threshold are reported for each sample in a measurement.
This function is similar to ch_get_amplitude_data(), except that the data values each contains a 16-bit unsigned threshold value in addition to the 16-bit unsigned sample amplitude. The threshold value is the required amplitude at that sample offset to detect a target object, as set by ch_set_thresholds(). This output format may be useful in tuning and debugging the detection threshold values.
Each output sample consists of a ch_amp_thresh_t structure, containing one unsigned 16-bit integer value threshold value followed by one unsigned 16-bit amplitude value.
See ch_get_amplitude_data() for more information on reading amplitude values.
| uint16_t ch_get_amplitude | ( | ch_dev_t * | dev_ptr | ) |
Get the measured amplitude from a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the amplitude value for the most recent successful range measurement by the sensor. The amplitude is representative of the incoming sound pressure. The value is expressed in internal sensor counts and is not calibrated to any standard units.
The amplitude value is not updated if a measurement cycle resulted in CH_NO_TARGET, as returned by ch_get_range().
| uint16_t ch_get_amplitude_avg | ( | ch_dev_t * | dev_ptr | ) |
Get the averaged measured amplitude over the sample window.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the average amplitude value for the most recent measurement cycle across the samples within the current sample window. The sample window is a subset of the overall sensor data, and is specified by the ch_set_sample_window() function.
The amplitude is representative of the incoming sound pressure. The value is expressed in internal sensor counts and is not calibrated to any standard units.
| uint8_t ch_get_amplitude_data | ( | ch_dev_t * | dev_ptr, |
| uint16_t * | buf_ptr, | ||
| uint16_t | start_sample, | ||
| uint16_t | num_samples, | ||
| ch_io_mode_t | mode | ||
| ) |
Get the raw amplitude measurement data from a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| buf_ptr | pointer to data buffer where amplitude data will be written |
| start_sample | starting sample number within measurement data (0 = start of data) |
| num_samples | number of samples to read from sensor |
| mode | whether read should block (CH_IO_MODE_BLOCK (0) = blocking, CH_IO_MODE_NONBLOCK (1) = non-blocking) |
The raw amplitude data are updated on every measurement cycle, even if no target was detected (i.e. even if ch_get_range() returns CH_NO_TARGET). (Note that this is different than the regular amplitude value, as returned by ch_get_amplitude(), which is not updated unless a target is detected.)
Each sample amplitude consists of one unsigned 16-bit integer value.
Amplitude values in the sensor are expressed only in internal ADC counts (least-significant bits, or LSBs) and are not calibrated to any standard units.
The number of samples available in each amplitude trace is determined by the maximum range setting for the device. If it is set to less than the maximum possible range, not all samples will contain valid data. To determine the number of active samples within the trace, use ch_get_num_samples().
To determine what sample number corresponds to a physical distance, use ch_mm_to_samples().
To allow more flexibility in your application, the amplitude data readout from the device may be done in a non-blocking mode, by setting mode to CH_IO_MODE_NONBLOCK (1). In non-blocking mode, the I/O operation takes place using DMA access in the background. This function will return immediately, and a notification will later be issued when the amplitude has been read. To use the non_block option, the board support package (BSP) you are using must provide the chbsp_i2c_read_nb() and chbsp_i2c_read_mem_nb() functions. To use non-blocking reads of the amplitude data, you must specify a callback routine that will be called when the amplitude read completes. See ch_io_complete_callback_set().
Non-blocking reads are managed together for a group of sensors. To perform a non-blocking read:
For a CH101 sensor, up to 150 samples are taken during each measurement cycle; for a CH201 sensor, up to 450 samples are taken. So, a complete CH101 amplitude trace will contain up to 300 bytes of data (150 samples x 2 bytes per sample), and a CH201 amplitude trace may contain up to 900 bytes. The buffer specified by buf_ptr must be large enough to hold this amount of data.
When the amplitude data is read from the sensor, the additional time required to transfer the amplitude data over the SPI/I2C bus must be taken into account when planning how often the sensor can be read (sample interval).
| uint16_t ch_get_bandwidth | ( | ch_dev_t * | dev_ptr | ) |
Get the bandwidth of a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the operating frequency of the sensor. This is the primary frequency of the ultrasonic pulse that is emitted by the device when transmitting.
| uint8_t ch_get_bus | ( | ch_dev_t * | dev_ptr | ) |
Get the active SPI/I2C bus for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the SPI/I2C bus index for a sensor device. This function may be used by board support package routines to determine the proper SPI/I2C bus to use for a specified sensor.
| uint8_t ch_get_cal_result | ( | ch_dev_t * | dev_ptr, |
| ch_cal_result_t * | cal_ptr | ||
| ) |
Get the calibration result.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| cal_ptr | pointer to ch_cal_result_t structure to receive calibration data |
This function obtains the current calibration result from the sensor and returns them in a ch_cal_result_t structure specified by cal_ptr. The ch_cal_result_t structure contains DCO period and reverse drive cycles.
See also ch_set_cal_result().
| uint8_t ch_get_config | ( | ch_dev_t * | dev_ptr, |
| ch_config_t * | config_ptr | ||
| ) |
Get current configuration settings for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| config_ptr | pointer to a ch_config_t structure to receive configuration values |
This function obtains the current configuration settings from the sensor and returns them in a ch_config_t structure, whose address is specified by config_ptr.
| uint32_t ch_get_cpu_frequency | ( | ch_dev_t * | dev_ptr | ) |
Get the sensor CPU frequency, in Hz.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the processor speed, in Hz, for the micro-controller in the ultrasound sensor.
| uint8_t ch_get_data_ready_delay | ( | ch_dev_t * | dev_ptr | ) |
Get data ready interrupt delay interval.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the time, in milliseconds, that the sensor will wait between the completion of a measurement cycle and generating a data ready interrupt. The delay may be slightly greater than the value specified during ch_set_data_ready_delay(), due to the granularity of the sensor's wake cycle timer.
| uint8_t ch_get_dev_num | ( | ch_dev_t * | dev_ptr | ) |
Get device number (I/O index values) for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the device number (I/O index) of the sensor within its sensor group. Normally, this also corresponds to the sensor's port number on the board, and is used for indexing arrays of pin definitions etc. within the board support package routines.
| ch_dev_t* ch_get_dev_ptr | ( | ch_group_t * | grp_ptr, |
| uint8_t | dev_num | ||
| ) |
Get device descriptor pointer for a sensor.
| grp_ptr | pointer to the ch_group_t descriptor for this group of sensors |
| dev_num | device number within sensor group |
This function returns the address of the ch_dev_t device descriptor for a certain sensor in a sensor group. The sensor is identified within the group by the dev_num device number.
| uint16_t ch_get_freerun_interval | ( | ch_dev_t * | dev_ptr | ) |
Get the internal sensing timing interval for a sensor, in milliseconds.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the interval between measurements, in milliseconds, for a sensor operating in free-running mode. If the sensor is in a different operating mode (e.g. a triggered mode), zero is returned.
See also ch_get_freerun_interval_us(), ch_get_freerun_interval_ticks().
| uint16_t ch_get_freerun_interval_ticks | ( | ch_dev_t * | dev_ptr | ) |
Get the internal sensing timing interval for a sensor, in RTC clock ticks.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the interval between measurements, in sensor RTC clock periods, for a sensor operating in free-running mode. If the sensor is in a different operating mode (e.g. a triggered mode), zero is returned.
See also ch_get_freerun_interval_us(), ch_get_freerun_interval_ticks().
| uint32_t ch_get_freerun_interval_us | ( | ch_dev_t * | dev_ptr | ) |
Get the internal sensing timing interval for a sensor, in microseconds.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the interval between measurements, in milliseconds, for a sensor operating in free-running mode. If the sensor is in a different operating mode (e.g. a triggered mode), zero is returned.
See also ch_get_freerun_interval_us(), ch_get_freerun_interval_ticks().
| uint32_t ch_get_frequency | ( | ch_dev_t * | dev_ptr | ) |
Get the operating frequency of a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the acoustic operating frequency of the sensor. This is the primary frequency of the ultrasonic pulse that is emitted by the device when transmitting.
Normally, the returned operating frequency value is the natural resonant frequency for the sensor. However, if the frequency has been changed by using ch_set_frequency() or ch_group_set_frequency(), the returned value will be the adjusted operating frequency.
| const char* ch_get_fw_version_string | ( | ch_dev_t * | dev_ptr | ) |
Get the firmware version description string for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns a pointer to a string that describes the sensor firmware being used on the device.
| uint8_t ch_get_i2c_address | ( | ch_dev_t * | dev_ptr | ) |
Get the active I2C address for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the currently active I2C address for a CHx01 sensor device. This function may be used by board support package routines to determine the proper I2C address to use for a specified sensor.
Zero is returned if this function is called for ICU sensors, which use a SPI bus interface.
| ch_interrupt_drive_t ch_get_interrupt_drive | ( | ch_dev_t * | dev_ptr | ) |
Get the pulse interrupt drive setting.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the current setting for interrupt drive (open drain or push pull).
| ch_interrupt_mode_t ch_get_interrupt_mode | ( | ch_dev_t * | dev_ptr | ) |
Get the pulse interrupt mode setting.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the current setting for interrupt mode (pulsed or latching).
| uint8_t ch_get_iq_data | ( | ch_dev_t * | dev_ptr, |
| ch_iq_sample_t * | buf_ptr, | ||
| uint16_t | start_sample, | ||
| uint16_t | num_samples, | ||
| ch_io_mode_t | mode | ||
| ) |
Get the raw I/Q measurement data from a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| buf_ptr | pointer to data buffer where I/Q data will be written |
| start_sample | starting sample number within measurement data (0 = start of data) |
| num_samples | number of samples to read from sensor |
| mode | whether I/Q read should block (CH_IO_MODE_BLOCK (0) = blocking, CH_IO_MODE_NONBLOCK (1) = non-blocking) |
This function reads the raw I/Q measurement data from the sensor. The I/Q data set includes a discrete pair of values for each of the samples that make up a full measurement cycle. Each individual sample is reported as a pair of values, I and Q, in a quadrature format. The I/Q values may be used to calculate the relative amplitude of the measured ultrasound signal.
The contents of the I/Q trace are updated on every measurement cycle, even if no target was detected (i.e. even if ch_get_range() returns CH_NO_TARGET). (Note that this is different than the regular amplitude value, as returned by ch_get_amplitude(), which is not updated unless a target is detected.)
Each sample I/Q pair consists of two signed 16-bit integers and is described by the ch_iq_sample_t structure. To convert any given pair of I/Q values to the amplitude value for that sample, square both I and Q, and take the square root of the sum:
\[Amp_n = \sqrt{(I_n)^2 + (Q_n)^2}\]
Amplitude values in the sensor are expressed only in internal ADC counts (least-significant bits, or LSBs) and are not calibrated to any standard units.
The number of samples used in each I/Q trace is determined by the maximum range setting for the device. If it is set to less than the maximum possible range, not all samples will contain valid data. To determine the number of active samples within the trace, use ch_get_num_samples().
To determine what sample number corresponds to a physical distance, use ch_mm_to_samples().
To allow more flexibility in your application, the I/Q data readout from the device may be done in a non-blocking mode, by setting mode to CH_IO_MODE_NONBLOCK (1). In non-blocking mode, the I/O operation takes place using DMA access in the background. This function will return immediately, and a notification will later be issued when the I/Q has been read. To use the non_block option, the board support package (BSP) you are using must provide the chbsp_i2c_read_nb() and chbsp_i2c_read_mem_nb() functions. To use non-blocking reads of the I/Q data, you must specify a callback routine that will be called when the I/Q read completes. See ch_io_complete_callback_set().
Non-blocking reads are managed together for a group of sensors. To perform a non-blocking read:
For a CH101 sensor, up to 150 samples are taken during each measurement cycle; for a CH201 sensor, up to 450 samples are taken. So, a complete CH101 I/Q trace will contain up to 600 bytes of data (150 samples x 4 bytes per sample), and a CH201 I/Q trace may contain up to 1800 bytes. The buffer specified by buf_ptr must be large enough to hold this amount of data.
When the I/Q data is read from the sensor, the additional time required to transfer the I/Q data over the SPI/I2C bus must be taken into account when planning how often the sensor can be read (sample interval).
| uint16_t ch_get_max_range | ( | ch_dev_t * | dev_ptr | ) |
Get the maximum range setting in mm for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the current maximum detection range setting for the sensor, in millimeters.
For ICU sensors, this function always returns the values for the default measurement definition. To specify which measurement to query, use the ch_meas_get_max_range() function.
See also ch_get_num_samples(), ch_get_config().
| uint16_t ch_get_max_samples | ( | ch_dev_t * | dev_ptr | ) |
Get the maximum possible sample count per measurement.
| dev_ptr | pointer to the ch_dev_t descriptor struct |
This function returns the maximum number of samples that can be included in a measurement. This maximum sample count will vary depending on the sensor device (CH201 devices will have higher sample counts than CH101 devices) and by the specific sensor firmware that is being used.
To get the number of these possible samples that are currently active (based on the maximum range setting), use ch_get_num_samples().
| uint8_t ch_get_mfg_info | ( | ch_dev_t * | dev_ptr, |
| ch_mfg_info_t * | info_ptr | ||
| ) |
Get manufacturing information for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| info_ptr | pointer to ch_mfg_info_t structure to be updated |
This function sets fields in a ch_mfg_info_t structure with manufacturing information for the specific sensor device. These fields include:
See also ch_get_sensor_id(), ch_get_part_number().
Get the current operating mode for a sensor.
| dev_ptr | pointer to the ch_dev_t config structure |
This function returns the current operating mode for the sensor, one of:
| uint16_t ch_get_next_buf_addr | ( | ch_dev_t * | dev_ptr | ) |
Get the address of the IQ buffer that will be written by the next measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the address of the buffer that will be written by the next measurement. This is useful in the double buffer mode.
See also ch_update_metadata_from_iq0().
| uint16_t ch_get_num_output_samples | ( | ch_dev_t * | dev_ptr | ) |
Get the number of valid output samples in last measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the number of valid samples in the most recently completed measurement, as reported by the sensor. The sensor will be queried dynamically over the I/O bus interface.
In general, this number will match the configured sample count for the last measurement, which can be obtained using ch_get_num_samples(). That function is recommended for typical use, because it requires no additional I/O to the sensor.
See also ch_get_num_samples(), ch_meas_get_num_samples().
| uint8_t ch_get_num_ports | ( | ch_group_t * | grp_ptr | ) |
Get the total number of sensor ports (possible sensors) in a sensor group.
| grp_ptr | pointer to the ch_group_t descriptor for this group of sensors |
This function returns the maximum number of possible sensors within a sensor group. Typically, the number of sensors is limited by the physical connections on the board being used, so the number of sensor ports on the board is returned by this function.
| uint16_t ch_get_num_samples | ( | ch_dev_t * | dev_ptr | ) |
Get the number of samples per measurement cycle.
| dev_ptr | pointer to the ch_dev_t descriptor struct |
This function returns the configured number of samples which the Chirp sensor will obtain during each measurement cycle. The number of samples directly corresponds to the range at which the sensor can detect, so this value is determined by the current maximum range setting for the sensor.
For ICU sensors, this function always returns the configured value for the last completed measurement. To specify which measurement to indicate, use the ch_meas_get_num_samples() function.
ICU sensors can report the number of output samples directly. To obtain the number of samples in the last measurement as reported by the sensor itself, use ch_get_num_output_samples(). Normally, this will be the same as the configured value reported by this routine.
See also ch_set_num_samples, ch_meas_get_num_samples, ch_get_max_range().
| uint16_t ch_get_part_number | ( | ch_dev_t * | dev_ptr | ) |
Get part number for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the TDK/Chirp part number for the specified device. The part number is a simple integer value, for example 101 for a CH101 sensor, or 20201 for an ICU20201 sensor.
| ch_pmut_clk_cfg_t ch_get_pmut_clock | ( | ch_dev_t * | dev_ptr | ) |
Get ultrasound transducer clock configuration.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the current configuration setting for the PMUT clock.
See also ch_set_pmut_clock().
| uint32_t ch_get_range | ( | ch_dev_t * | dev_ptr, |
| ch_range_t | range_type | ||
| ) |
Get the measured range from a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| range_type | the range type to be reported (e.g. one-way vs. round-trip) |
This function reads the measurement result registers from the sensor and then computes the actual range. It should be called after the sensor has indicated that a measurement cycle is complete by generating a signal on the INT line. (Typically, this will be set up by an interrupt handler associated with that input line.)
The range_type parameter indicates whether the measurement is based on the one-way or round-trip distance to/from a target, or the direct distance between two sensors operating in pitch-catch mode. The possible values are:
This function returns the measured range as a 32-bit integer. For maximum precision, the range value is returned in a fixed-point format with 5 fractional bits. So, the return value is the number of millimeters times 32. Divide the value by 32 (shift right 5 bits) to get whole mm, or use floating point (i.e. divide by 32.0f) to preserve the full sub-millimeter precision.
If the sensor did not successfully find the range of a target during the most recent measurement, the returned range value will be CH_NO_TARGET. If an error occurs when getting or calculating the range, zero (0) will be returned.
| uint16_t ch_get_rtc_cal_pulselength | ( | ch_dev_t * | dev_ptr | ) |
Get the real-time clock calibration pulse length.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the length (duration), in milliseconds, of the the real-time clock (RTC) calibration pulse used for the sensor. The pulse is applied to the sensor's INT line during ch_group_start() to calibrate the sensor's internal clock. The pulse length is specified by the board support package during the ch_group_init() function.
The RTC calibration pulse length is used internally in calculations that convert between time and distance.
| uint16_t ch_get_rtc_cal_result | ( | ch_dev_t * | dev_ptr | ) |
Get the real-time clock calibration value.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the real-time clock (RTC) calibration value read from the sensor during ch_group_start(). The RTC calibration value is calculated by the sensor during the RTC calibration pulse, and it is used internally in calculations that convert between time and distance.
| uint16_t ch_get_rtc_frequency | ( | ch_dev_t * | dev_ptr | ) |
Get the sensor real-time clock (RTC) frequency, in Hz.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the real-time clock (RTC) frequency, in Hz, for the micro-controller in the ultrasound sensor.
| uint16_t ch_get_rx_holdoff | ( | ch_dev_t * | dev_ptr | ) |
Get the receive holdoff sample count.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function gets the receive (rx) holdoff sample count. The rx holdoff count is the number of samples at the beginning of a measurement that will be ignored for the purpose of detecting a target, as previously set by ch_set_rx_holdoff().
To convert the returned sample count to a physical distance, use ch_samples_to_mm().
For ICU sensors, this function always returns the value for the default measurement definition. To specify which measurement to query, use the icu_gpt_get_rx_holdoff() function.
See also ch_set_rx_holdoff().
| uint16_t ch_get_rx_low_gain | ( | ch_dev_t * | dev_ptr | ) |
Get the receive low-gain sample count.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function gets the receive (rx) low-gain range from the sensor. The low-gain range is a count of samples at the beginning of a measurement that will have lower gain applied during the ultrasound receive operation.
The returned low-gain range is either the default value for the sensor firmware, or a value previously set by ch_set_rx_low_gain().
To convert the returned sample count to a physical distance, use ch_samples_to_mm().
See also ch_set_rx_low_gain().
| uint8_t ch_get_rx_pretrigger | ( | ch_group_t * | grp_ptr | ) |
Get receive-only sensor pre-triggering setting.
| grp_ptr | pointer to the ch_group_t group descriptor structure |
This function returns the current state (enabled or disabled) of pre-triggering receive-only sensors.
See also ch_set_rx_pretrigger().
| uint16_t ch_get_sample_interval | ( | ch_dev_t * | dev_ptr | ) |
Get the internal sensing timing interval for a sensor (deprecated).
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the interval between measurements, in milliseconds, for a sensor operating in free-running mode. If the sensor is in a different operating mode (e.g. a triggered mode), zero is returned.
| uint8_t ch_get_sample_window | ( | ch_dev_t * | dev_ptr, |
| uint16_t * | start_sample_ptr, | ||
| uint16_t * | num_samples_ptr | ||
| ) |
Get the sample window for amplitude averaging.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| start_sample_ptr | pointer to variable to be updated with sample number of first sample |
| num_samples_ptr | pointer to variable to be updated with number of samples |
This function obtains the current range of samples that are included in the sample window used for amplitude averaging. start_sample_ptr is a pointer to a variable that will be updated with the number of the first sample in the sample window. num_samples_ptr is a pointer to a variable that will be updated with the the total number of samples in the sample window.
See also ch_get_amplitude_avg(), ch_set_sample_window().
| uint16_t ch_get_scale_factor | ( | ch_dev_t * | dev_ptr | ) |
Get the amplitude scale factor of a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the amplitude scale factor of the sensor. The scale factor is an internal value generated during the initialization of the device.
| const char* ch_get_sensor_id | ( | ch_dev_t * | dev_ptr | ) |
Get the unique Sensor ID String for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns a pointer to a string that contains a unique identifier for the sensor device. The ID string consists of 7 ascii alpha-numeric characters, terminated by a null byte (so total size is 8 bytes). CH_SENSOR_ID_LENGTH, is defined as the length of the string, including the null terminator.
The first three bytes in the ID string specify the Production Lot. The remaining four bytes specify the alphanumeric Serial Number within that production lot.
See also ch_get_mfg_info(), ch_get_fw_version_string.
| uint8_t ch_get_target_int_counter | ( | ch_dev_t * | dev_ptr, |
| uint8_t * | meas_hist_ptr, | ||
| uint8_t * | thresh_count_ptr, | ||
| uint8_t * | reset_ptr | ||
| ) |
Get the target interrupt counter filter settings.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_hist_ptr | pointer to location to receive count of measurements in filter history |
| thresh_count_ptr | pointer to location to receive number of target detections req'd |
| reset_ptr | pointer to location to receive target counter reset setting |
This function obtains the current target counter filter settings used to control sensor interrupts. This filter is enabled by calling the ch_set_target_interrupt() (or ch_set_config()) function and specifying CH_TGT_INT_FILTER_COUNTER as the filter type.
The location specified by meas_hist_ptr will be set to the number of previous measurements that are included in the history for filtering. The current measurement is combined with these previous measurements, so a total of meas_hist + 1 measurements are used. The location specified by thresh_count_ptr will be set to the threshold number of those measurements that must positively detect a target for an interrupt to be generated. The location specified by reset_ptr will be set to 1 if the sensor resets the counter filter after an interrupt is generated, 0 otherwise (default).
The maximum value for both meas_hist and thresh_count is 15.
See also ch_set_target_int_counter(), ch_set_target_interrupt().
| ch_tgt_int_filter_t ch_get_target_interrupt | ( | ch_dev_t * | dev_ptr | ) |
Get the target interrupt filtering mode setting.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the current setting for target interrupt filtering mode. The mode is one of:
See also ch_set_target_interrupt(), ch_get_target_int_counter().
| ch_trigger_type_t ch_get_trigger_type | ( | ch_dev_t * | dev_ptr | ) |
Get the trigger type for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function gets the current trigger type to be used to initiate a measurement on a sensor when in triggered mode.
By default, sensors are triggered using a hardware signal on the INT line, and this function will return CH_TRIGGER_TYPE_HW.
Alternatively, software triggering may be used, using a special SPI command to the sensor. In this case, this function will return CH_TRIGGER_TYPE_SW.
See also ch_set_trigger_type(), ch_trigger().
| uint16_t ch_get_tx_length | ( | ch_dev_t * | dev_ptr | ) |
Get the ultrasound transmit pulse length.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function gets the length of the ultrasonic pulse sent by the sensor when it transmit. The transmit length is expressed in cycles.
For ICU (Shasta architecture) sensors, cycles are in units of Measurement State Machine Clock (SMCLK) cycles.
For CH101 and CH201 (Whitney architecture) sensors, cycles are ultrasonic transducer (PMUT) cycles.
See also ch_set_tx_length().
| void ch_get_version | ( | ch_version_t * | version_ptr | ) |
Get the SonicLib version number.
| version_ptr | pointer to a ch_version_t structure to receive version |
This function fills the fields in the ch_version_t structure identified by version_ptr with the SonicLib version number.
The version number consists of three x.y.z fields: <major>.<minor>.<rev>
| uint32_t ch_group_get_frequency | ( | ch_group_t * | grp_ptr | ) |
Get the operating frequency for a group of sensors.
| grp_ptr | pointer to the ch_group_t descriptor for sensor group |
This function returns the nominal acoustic operating frequency for a group of sensors whose frequencies have been adjusted using ch_group_set_frequency(). A return value of zero indicates that no group frequency has been set.
In general, the actual operating frequency for each device will vary slightly from the nominal group value. Use ch_get_frequency() to obtain the adjusted operating frequency for an individual sensor.
See also ch_group_set_frequency(), ch_get_frequency().
| uint32_t ch_group_get_pmut_clock_freq | ( | ch_group_t * | grp_ptr | ) |
Get the transducer clock input frequency for a group of sensors.
| grp_ptr | pointer to the ch_group_t sensor group descriptor structure |
This function is used only in designs in which the ultrasonic transducers (PMUTs) of multiple sensors in a group share a clock source. The clock source may be output from one of the sensors, or it may be from an independent signal source. (See ch_set_pmut_clock().)
This function returns the frequency of the group PMUT clock signal, in Hz, regardless of its source. The returned frequency will be zero if no sensor is outputting a clock signal and no independent clock rate has been specified using ch_set_pmut_clock_freq().
The sensors operate at an acoustic frequency of 1/16 the PMUT clock rate. For example, if the reported clock rate is 800 kHz, the sensors are operating at 50 kHz.
See also ch_group_set_pmut_clock_freq(), ch_set_pmut_clock().
| uint8_t ch_group_init | ( | ch_group_t * | grp_ptr, |
| uint8_t | num_devices, | ||
| uint8_t | num_buses, | ||
| uint16_t | rtc_cal_pulse_ms | ||
| ) |
Initialize the group descriptor for a group of sensors.
| grp_ptr | pointer to the ch_group_t descriptor for sensor group to join |
| num_devices | number of the device within the sensor group |
| num_devices | number of the buses the sensors use |
| rtc_cal_pulse_ms | Length of the pulse used to calibrate the sensors RTC |
This function is used to initialize few group structure field before initializing sensors
Generally, an application will require only one ch_group_t structure to manage all Chirp sensors.
| void ch_group_reset | ( | ch_group_t * | grp_ptr, |
| ch_reset_t | reset_type | ||
| ) |
Reset a group of sensors.
| grp_ptr | pointer to the ch_group_t descriptor for this group of sensors |
| reset_type | type of reset (CH_RESET_HARD or CH_RESET_SOFT) |
This function resets all sensors in a sensor group. The reset_type parameter indicates if a software reset or full hardware reset is requested.
| uint8_t ch_group_restart | ( | ch_group_t * | grp_ptr | ) |
Restart a group of sensors.
| grp_ptr | pointer to the ch_group_t descriptor for sensor group to be restarted |
This function performs a re-start of a group of sensors that have previously been initialized and started.
Each sensor will be reprogrammed with firmware (as specified in the most recent call to ch_init()) and then will be started and configured. The sensors will not perform the normal calibration steps (including clock calibration) - they will instead use the values saved by a previous initialization.
After this routine returns successfully, the sensors should be ready to resume measurements.
See also ch_restart(), ch_group_start().
| uint8_t ch_group_set_frequency | ( | ch_group_t * | grp_ptr, |
| uint32_t | request_op_freq_hz | ||
| ) |
Set the operating frequency for a group of sensors.
| grp_ptr | pointer to the ch_group_t descriptor for sensor group |
| request_op_freq_hz | requested operating frequency in Hz, or zero to use group avg |
This function requests a desired acoustic operating frequency for a group of sensors. This is the primary frequency of the ultrasonic pulse that is emitted by each device when transmitting.
When a group of sensors are used in paired pitch/catch operation, it is often helpful to set them to a common acoustic operating frequency. A better frequency match between the transmitting and receiving sensors improves the range and reliability.
All sensors in the group must be the same production model (part number). It is not possible to set the frequency to a value that is outside the typical operating frequency range for the sensor model.
If the request_op_freq_hz parameter is CH_OP_FREQ_USE_AVG (zero), all sensors will be set to the average of the unadjusted operating frequencies for the group, which generally gives the best performance. After this call returns, you may use ch_group_get_frequency() to determine the average frequency that was used.
If request_op_freq_hz is non-zero, the specified frequency in Hz will be applied to all sensors. Use this option to request a certain operating frequency for all sensors, regardless of their natural operating frequencies.
In general, the actual operating frequency for each device will vary slightly from the requested value or calculated average frequency. The nominal group operating frequency may be obtained by using ch_group_get_frequency(). To determine the actual operating frequency for each individual sensor, use ch_get_frequency().
See also ch_group_get_frequency(), ch_set_frequency().
| void ch_group_set_pmut_clock_freq | ( | ch_group_t * | grp_ptr, |
| uint32_t | pmut_clock_freq | ||
| ) |
Specify the transducer clock input frequency for a group of sensors.
| grp_ptr | pointer to the ch_group_t sensor group descriptor structure |
| pmut_clock_freq | frequency of input clock signal, in Hz |
This function is used only in unusual designs in which the ultrasonic transducers (PMUTs) of multiple sensors share an independent, external clock source. This function is not needed if the sensors each use their own clock (the default) or if one sensor supplies the PMUT clock signal for others. (See ch_set_pmut_clock().)
This function specifies the frequency of the external clock signal, in Hz. The sensors will operate at an acoustic frequency of 1/16 the input clock rate. For example, if the input clock rate is 800 kHz, the sensor will operate at 50 kHz.
The input clock rate must be appropriate for the specific sensor model being used. Radical shifts in operating frequency are not possible.
The input clock signal must be present, and this function must be called to specify the frequency before ch_set_pmut_clock() is used to enable the external clock input for any sensors.
Only one shared PMUT clock signal can be used within a sensor group.
See also ch_group_get_pmut_clock_freq(), ch_set_pmut_clock().
| uint8_t ch_group_start | ( | ch_group_t * | grp_ptr | ) |
Program and start a group of sensors.
| grp_ptr | pointer to the ch_group_t descriptor for sensor group to be started |
This function performs the actual discovery, programming, and initialization sequence for all sensors within a sensor group. Each sensor must have previously been added to the group by calling ch_init().
In brief, this function does the following for each sensor:
After this routine returns successfully, the sensor configuration may be set and ultrasonic measurements may begin.
See also ch_init(), ch_restart(), ch_group_restart().
| void ch_group_trigger | ( | ch_group_t * | grp_ptr | ) |
Trigger a measurement on a group of sensors.
| grp_ptr | pointer to the ch_group_t descriptor for this group of sensors |
This function generates a pulse on the INT line for each sensor in the sensor group. If a sensor is in either CH_MODE_TRIGGERED_TX_RX or CH_MODE_TRIGGERED_RX_ONLY mode, this pulse will begin a measurement cycle.
If a two or more sensors are operating in pitch-catch mode (in which one transmits and the others receive), this function must be used to start a measurement cycle, so that the devices are synchronized.
To trigger a single sensor, use ch_trigger().
| uint8_t ch_init | ( | ch_dev_t * | dev_ptr, |
| ch_group_t * | grp_ptr, | ||
| uint8_t | dev_num, | ||
| ch_fw_init_func_t | fw_init_func | ||
| ) |
Initialize the device descriptor for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| grp_ptr | pointer to the ch_group_t descriptor for sensor group to join |
| dev_num | number of the device within the sensor group (identifies which physical sensor) |
| fw_init_func | pointer to the sensor firmware initialization function (determines sensor feature set) |
This function is used to initialize various Chirp SonicLib structures before using a sensor. The ch_dev_t device descriptor is the primary data structure used to manage a sensor, and its address will subsequently be used as a handle to identify the sensor when calling most API functions.
The dev_ptr parameter is the address of the ch_dev_t descriptor structure that will be initialized and then used to identify and manage this sensor. The grp_ptr parameter is the address of a ch_group_t structure describing the sensor group that will include the new sensor. Both the ch_dev_t structure and the ch_group_t structure must have already been allocated before this function is called.
A separate ch_dev_t structure must be allocated for each sensor.
dev_num is a simple index value that uniquely identifies a sensor within a group. Each possible sensor (i.e. each physical port on the board that could have a Chirp sensor attached) has a number, starting with zero (0). The device number is constant - it remains associated with a specific port even if no sensor is actually attached. Often, the dev_num value is used by both the application and the board support package as an index into arrays containing per-sensor information (e.g. data read from the sensors, pin assignments, etc.).
The Chirp sensor is fully re-programmable, and the specific features and capabilities can be modified by using different sensor firmware images. The fw_init_func parameter is the address (name) of the sensor firmware initialization routine that should be used to program the sensor and prepare it for operation. The selection of this routine name is the only required change when switching from one sensor firmware image to another.
Initialize the device descriptor for a sensor.
| dev_ptr | a pointer to the ch_dev_t config structure for a sensor |
| uint8_t ch_init_algo | ( | ch_dev_t * | dev_ptr | ) |
Initialize the measurement algorithm on a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| algo_info_ptr | pointer to a ICU_ALGO_SHASTA_INFO structure to receive info |
This function initializes a measurement algorithm that has been loaded into a sensor and configured.
Normally, this routine will only be used by special applications or libraries which interact with specific sensor firmware. It is not used directly in a typical application.
See also ch_meas_import(), ch_get_algo_state().
| void ch_interrupt | ( | ch_group_t * | grp_ptr, |
| uint8_t | dev_num | ||
| ) |
Run SonicLib's full-featured interrupt handler.
| grp_ptr | pointer to the ch_group_t sensor group descriptor structure |
| dev_num | device number within group for interrupting sensor |
This function is used from the board support package (BSP) handler routine for the sensor interrupt to announce that the interrupt has occurred. dev_num identifies which sensor has interrupted.
The SonicLib driver layer will handle further processing of the interrupt, including disabling the interrupt processing (to allow for next trigger), reading sensor metadata, and calling the application-supplied callback function.
Only one of ch_interrupt() and ch_minimal_int_handler() should be called. The latter function is a simplified handler that gives the user more control of exactly what happens during the interrupt handling.
See also ch_io_int_callback_set() and ch_minimal_int_handler().
Run SonicLib's full-featured interrupt handler.
This function is used from the board support package (BSP) handler routine for the sensor interrupt to notify SonicLib that the interrupt has occurred. The SonicLib driver layer will handle further processing of the interrupt, including a call to the application-supplied callback function.
| void ch_io_complete_callback_set | ( | ch_group_t * | grp_ptr, |
| ch_io_complete_callback_t | callback_func_ptr | ||
| ) |
Register non-blocking I/O complete callback routine for a group of sensors.
| grp_ptr | pointer to the ch_group_t group descriptor structure |
| callback_func_ptr | pointer to callback function to be called when non-blocking I/O operations complete |
This function registers the routine specified by callback_func_ptr to be called when all outstanding non-blocking I/O operations complete for a group of sensors. The non-blocking I/O operations must have previously been initiated using ch_io_start_nb().
Register non-blocking I/O complete callback routine for a group of sensors.
| void ch_io_int_callback_set | ( | ch_group_t * | grp_ptr, |
| ch_io_int_callback_t | callback_func_ptr | ||
| ) |
Register sensor interrupt callback routine for a group of sensors.
| grp_ptr | pointer to the ch_group_t sensor group descriptor structure |
| callback_func_ptr | pointer to callback function to be called when sensor interrupts |
This function registers the routine specified by callback_func_ptr to be called whenever the sensor interrupts. Generally, such an interrupt indicates that a measurement cycle has completed and the sensor has data ready to be read. All sensors in a sensor group use the same callback function, which receives the interrupting device's device number (port number) as an input parameter to identify the specific interrupting device. The callback function also receives the ch_interrupt_type_t interrupt type parameter that identifies the type (reason) for the sensor interrupt).
Register sensor interrupt callback routine for a group of sensors.
| void ch_io_notify | ( | ch_group_t * | grp_ptr, |
| uint8_t | i2c_bus_index | ||
| ) |
Notify SonicLib that a non-blocking I/O operation has completed.
| grp_ptr | pointer to the ch_group_t sensor group descriptor structure |
| bus_index | identifier indicating on which SPI/I2C bus the I/O operation was completed |
This function should be called from your non-blocking I/O interrupt handler each time a non-blocking I/O operation completes. The bus_index parameter should indicate which SPI/I2C bus is being reported.
When all outstanding non-blocking I/O operations are complete, SonicLib will call the callback function previously registered using ch_io_complete_callback_set().
Notify SonicLib that a non-blocking I/O operation has completed.
| grp_ptr | pointer to the ch_group_t config structure for a group of sensors |
| i2c_bus_index | index value identifying I2C/SPI bus within group |
Call this function once from your I2C interrupt handler each time it completes an I/O operation. It will call the function previously specified during ch_io_complete_callback_set() when all group transactions are complete.
| uint8_t ch_io_start_nb | ( | ch_group_t * | grp_ptr | ) |
Start non-blocking I/O operation(s) for a group of sensors.
| grp_ptr | pointer to the ch_group_t descriptor for sensor group |
This function starts one or more non-blocking I/O operations on a group of sensors. Generally, the I/O operations are non-blocking I/Q data read requests individually generated using ch_get_iq_data().
This function will return immediately after the I/O operations are started. When the I/O operations complete, the callback function registered using ch_io_complete_callback_set() will be called.
See ch_get_iq_data() for more information.
Start non-blocking I/O operation(s) for a group of sensors.
| grp_ptr | pointer 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.
| uint16_t ch_iq_to_amplitude | ( | ch_iq_sample_t * | iq_sample_ptr | ) |
Calculate amplitude from sample I/Q values.
| iq_sample_ptr | pointer to ch_iq_data_t structure containing the I/Q data |
This function converts the I and Q values from a single raw sensor sample to an amplitude value according to the following formula:
\[Amp = \sqrt{(I)^2 + (Q)^2}\]
Amplitude values in the sensor are expressed only in internal ADC counts (least-significant bits, or LSBs) and are not calibrated to any standard units.
See also ch_get_iq_data(), ch_get_amplitude_data().
| void ch_log_append | ( | uint8_t | log_id, |
| ch_log_fmt_t | format, | ||
| uint64_t | timestamp, | ||
| ch_log_data_t * | log_data_ptr | ||
| ) |
Append received sensor data to log.
| log_id | log ID to specify the log to use |
| format | format of the log |
| timestamp | current time in us |
| log_data_ptr | pointer to log data structure that contains the log data |
This function appends received sensor data (including I/Q data) to the log in the specified log format. The function takes a new Log ID returns by ch_log_init() function to specify the log to use.
The function should be used when the previous measurement has completed and all needed data has been read from the device (including I/Q data)
| uint8_t ch_log_init | ( | ch_group_t * | grp_ptr, |
| ch_log_fmt_t | format, | ||
| ch_log_cfg_t * | config_ptr | ||
| ) |
Initialize a log in the specified log format.
| grp_ptr | pointer to the ch_group_t descriptor for this group of sensors |
| format | format of the log. For example, CH_LOG_FMT_REDSWALLOW |
| config_ptr | pointer to log config structure that contains the input values of the log |
This function initializes a sensor data log in the specified log format.
| void ch_meas_activate | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Activate a defined measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | number of measurement to activate |
This function sets a measurement to active mode. The specified measurement definition will be used when the sensor makes a measurement. The measurement must have previously been defined, either by using ch_meas_init() and related calls to specify the measurement segments, or by importing a complete measurement definition.
If the measurement specified by meas_num was previously in standby mode (inactive), it is made active. In all cases, this definition will be used during the the next measurement performed by the sensor, even if the other measurement is also active.
This function does not affect the active vs. standby status of the other measurement. If both measurements are active after calling this function, they will alternate each time the sensor performs a measurement.
See also ch_meas_standby(), ch_meas_switch(), ch_meas_init(), ch_meas_import().
| uint8_t ch_meas_add_segment | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| ch_meas_segment_t * | seg_ptr | ||
| ) |
Add a segment to a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| seg_ptr | pointer to measurement segment to be added |
This function adds a measurement segment to the measurement specified by meas_num. seg_ptr points to a segment descriptor, which must have already been initialized.
See also ch_meas_add_segment_tx(),ch_meas_add_segment_rx(), ch_meas_init_segment_tx(), ch_meas_init_segment_rx(),
| uint8_t ch_meas_add_segment_count | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint16_t | num_cycles, | ||
| uint8_t | int_enable | ||
| ) |
Add a count (delay) segment to a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| num_cycles | length of the segment, in cycles |
| int_enable | if non-zero, the sensor will interrupt at the completion of this segment |
This function adds a count (delay) segment to the measurement specified by meas_num. Such a segment does not transmit a signal nor does it sample received ultrasound. So, no samples are associated with this portion of the measurement time.
This function combines the operations of ch_meas_init_segment_count() and ch_meas_add_segment().
| uint8_t ch_meas_add_segment_rx | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint16_t | num_samples, | ||
| uint8_t | gain_reduce, | ||
| uint8_t | atten, | ||
| uint8_t | int_enable | ||
| ) |
Add a receive segment to a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| num_samples | length of the segment, in sample periods |
| gain_reduce | gain reduction value, 0 = max gain |
| atten | attenuation level |
| int_enable | if non-zero, the sensor will interrupt at the completion of this segment |
This function adds a receive segment to the measurement specified by meas_num. It combines the operations of ch_meas_init_segment_rx() and ch_meas_add_segment().
| uint8_t ch_meas_add_segment_tx | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint16_t | num_cycles, | ||
| uint8_t | pulse_width, | ||
| uint8_t | phase, | ||
| uint8_t | int_enable | ||
| ) |
Add a transmit segment to a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| num_cycles | length of the segment, in cycles |
| pulse_width | transmit pulse width |
| phase | transmit phase |
| int_enable | if non-zero, the sensor will interrupt at the completion of this segment |
This function adds a transmit segment to the measurement specified by meas_num. It combines the operations of ch_meas_init_segment_tx() and ch_meas_add_segment().
The cycles parameter specifies the overall length of the transmit pulse that will be generated. The units are internal sensor cycles.
See also ch_meas)add_segment_rx(), ch_meas_add_segment_count(), ch_usec_to_cycles().
| void ch_meas_get_info | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| ch_meas_info_t * | info_ptr | ||
| ) |
Get configuration information for a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| info_ptr | pointer to ch_meas_info_t structure to be updated |
This function obtains configuration information for the measurement specified by meas_num. The ch_meas_info_t structure specified by info_ptr will be completed with the settings for the measurement, including:
| uint16_t ch_meas_get_interval | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Get the repeat interval for a measurement, in milliseconds.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the internal measurement interval in the sensor, in milliseconds.
See also ch_meas_set_interval(), ch_get_freerun_interval().
| uint32_t ch_meas_get_interval_ticks | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Get the repeat interval for a measurement, in sensor RTC clock ticks.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the internal measurement interval in the sensor, in sensor RTC clock periods.
See also ch_meas_set_interval_ticks().
| uint32_t ch_meas_get_interval_us | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Get the repeat interval for a measurement, in microseconds.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the internal measurement interval in the sensor, in microseconds.
See also ch_meas_set_interval_us().
| ch_output_type_t ch_meas_get_iq_output | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Get the I/Q data output format for a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
This function returns the measurement I/Q data output format, as follows:
See also ch_meas_set_iq_output().
| uint8_t ch_meas_get_last_num | ( | ch_dev_t * | dev_ptr | ) |
Get number of last completed measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the measurement number (0 or 1) for the last measurement that completed. It is useful if both measurements are active and are being executed alternately.
| uint16_t ch_meas_get_max_range | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Get the maximum range setting in mm for a specific measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
This function returns the current maximum detection range setting for the specified measurement, in millimeters.
The ch_get_max_range() function performs the same operation for the default measurement (same as setting meas_num to CH_DEFAULT_MEAS_NUM).
See also ch_meas_set_max_range(), ch_meas_get_num_samples().
| uint16_t ch_meas_get_num_samples | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Get the number of samples per measurement cycle for a specific measurement.
| dev_ptr | pointer to the ch_dev_t descriptor struct |
| meas_num | measurement number |
This function returns the configured number of samples which the Chirp sensor will obtain during each measurement cycle for the specified measurement. The number of samples directly corresponds to the range at which the sensor can detect, so this value is determined by the current maximum range setting for the sensor.
The ch_get_num_samples() function may be used to obtain the number of samples in the most recently completed measurement.
See also ch_meas_get_max_range(), ch_get_num_output_samples().
Get the output data rate for a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
This function returns the output data rate (ODR) for the sensor. The ODR setting determines the spacing in time (and therefore in measured distance) between the individual samples within a measurement.
See also ch_meas_set_odr().
| uint8_t ch_meas_get_queue | ( | ch_dev_t * | dev_ptr, |
| measurement_queue_t * | meas_queue_ptr | ||
| ) |
Get measurement queue values for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_queue_ptr | pointer to location to receive measurement queue values |
This function copies the current measurement queue values for a sensor to the measurement_queue_t structure specified by meas_queue_ptr.
This function may be used to save the original measurement queue values before calling ch_meas_import() or ch_meas_optimize().
See also ch_meas_write_config().
| void ch_meas_get_queue_info | ( | ch_dev_t * | dev_ptr, |
| ch_meas_queue_info_t * | info_ptr | ||
| ) |
Get configuration information for the sensor measurement queue.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| info_ptr | pointer to ch_meas_queue_info_t structure to be updated |
This function obtains configuration information for the sensor's measurement queue. The measurement queue contains all defined measurements plus common configuration settings. The ch_meas_queue_info_t structure specified by info_ptr will be completed with the settings for the measurement queue, including:
| void ch_meas_get_seg_info | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint8_t | seg_num, | ||
| ch_meas_seg_info_t * | info_ptr | ||
| ) |
Get configuration information for a measurement segment.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| seg_num | segment number |
| info_ptr | pointer to ch_meas_seg_info_t structure to be updated |
This function obtains configuration information for the measurement segment specified by meas_num and seg_num.
The ch_meas_seg_info_t structure specified by info_ptr will be completed with the settings for the measurement segment, including:
| ch_meas_status_t ch_meas_get_status | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Get measurement status.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
This function returns the current measurement status in the sensor. It may be used to help determine if valid measurement I/Q data can be read from the sensor.
A status value of CH_MEAS_STATUS_DONE indicates that complete measurement data is available for reading. A value of CH_MEAS_STATUS_PENDING indicates that a measurement is in progress, and the current data values should not be used.
Note that this routine only reports the status at the time it is called.
See also ch_trigger(), ch_trigger_soft().
| uint8_t ch_meas_import | ( | ch_dev_t * | dev_ptr, |
| measurement_queue_t * | meas_queue_ptr, | ||
| void * | algo_cfg_ptr | ||
| ) |
Import an externally defined measurement configuration.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_queue_ptr | pointer to a complete measurement queue structure, or NULL |
| algo_cfg_ptr | pointer to a buffer containing algorithm configuration, or NULL |
This function allows a fully defined measurement queue structure (measurement_queue_t) and algorithm-specific configuration to be imported as a unit. Taken together, these two structures fully define the measurement to be performed.
Alternatively, it is possible to import either the measurement queue or the algorithm configuration individually, by supplying a NULL pointer for the other structure. In this case, the current settings will continue to be used for the values specified in the other structure. An error is returned if both pointers are NULL.
The format of the algorithm configuration data will vary depending on the sensor firmware and algorithm that are being used.
See also ch_meas_optimize(), which combines importing and optimizing a measurement queue.
| uint8_t ch_meas_init | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| const ch_meas_config_t * | meas_config_ptr, | ||
| const void * | thresh_ptr | ||
| ) |
Initialize a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| meas_config_ptr | pointer to measurement configuration settings |
| thresh_ptr | deprecated. Parameter not used. Shall be set to NULL |
This function initializes the measurement specified by meas_num with the specified configuration. meas_config_ptr is a pointer to a ch_meas_config_t structure which must have already been initialized. The fields in this structure specify various parameters for the measurement including
thresh_ptr was used to initialize GPT thresholds. Now use icu_gpt_algo_configure() to configure algo.
| uint8_t ch_meas_init_queue | ( | ch_dev_t * | dev_ptr | ) |
Initialize the sensor measurement queue.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function resets and re-initializes the sensor measurement queue. All configuration settings and all measurements are cleared.
| void ch_meas_init_segment_count | ( | ch_meas_segment_t * | seg_ptr, |
| uint16_t | num_cycles, | ||
| uint8_t | int_enable | ||
| ) |
Initialize a count (delay) measurement segment.
| seg_ptr | pointer to the ch_meas_segment_t descriptor structure to be initialized |
| num_cycles | length of the segment, in cycles |
| int_enable | if non-zero, the sensor will interrupt at the completion of this segment |
This function initializes the measurement segment descriptor specified by seg_ptr as a count (delay) segment. Such a segment does not transmit a signal nor does it sample received ultrasound. So, no samples are associated with this portion of the measurement time.
The cycles parameter specifies the overall length of the delay. The units are internal sensor cycles. Use the ch_usec_to_cycles() function to calculate the number of cycles for a specific delay duration.
| void ch_meas_init_segment_rx | ( | ch_meas_segment_t * | seg_ptr, |
| uint16_t | num_samples, | ||
| ch_odr_t | odr, | ||
| uint8_t | gain_reduce, | ||
| uint8_t | atten, | ||
| uint8_t | int_enable | ||
| ) |
Initialize a receive measurement segment.
| seg_ptr | pointer to the ch_meas_segment_t descriptor structure to be initialized |
| num_samples | length of the segment, in sample periods |
| odr | output data rate setting to be used (set during ch_meas_init()) |
| gain_reduce | gain reduction value, 0 = max gain |
| atten | attenuation level |
| int_enable | if non-zero, the sensor will interrupt at the completion of this segment |
This function initializes the measurement segment descriptor specified by seg_ptr as a receive segment. The number of samples of added to the segments is limited by the maximum number of rx samples that firmware can read and by the number of cycles a segment can store. The length of segment in samples is converted to a number of cycles. A segment have a maximum length of 65535 cycles. If the number of sample exceeds the limitation, define the segments manually and import them to a measure queue using ch_meas_import()
| void ch_meas_init_segment_tx | ( | ch_meas_segment_t * | seg_ptr, |
| uint16_t | num_cycles, | ||
| uint8_t | pulse_width, | ||
| uint8_t | phase, | ||
| uint8_t | int_enable | ||
| ) |
Initialize a transmit measurement segment.
| seg_ptr | pointer to the ch_meas_segment_t descriptor structure to be initialized |
| num_cycles | length of the segment, in cycles |
| pulse_width | transmit pulse width |
| phase | transmit phase |
| int_enable | if non-zero, the sensor will interrupt at the completion of this segment |
This function initializes the measurement segment descriptor specified by seg_ptr as a transmit segment.
The cycles parameter specifies the overall length of the transmit pulse that will be generated. The units are internal sensor cycles.
See also ch_meas_init_segment_rx(), ch_meas_init_segment_count(), ch_usec_to_cycles().
| uint8_t ch_meas_insert_instruction | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| const ch_meas_segment_t * | inst_ptr, | ||
| uint8_t | index_to_insert | ||
| ) |
Insert an instruction(segment) to a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| inst_ptr | pointer to measurement instruction(segment) to be inserted |
| index_to_insert | instruction(segment) number to be remove |
This function inserts a measurement instruction(segment) to the measurement specified by meas_num. inst_ptr points to an instruction(segment) descriptor, which must have already been initialized.
| uint8_t ch_meas_insert_segment | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| const ch_meas_segment_t * | inst_ptr, | ||
| uint8_t | index_to_insert | ||
| ) |
Insert an instruction(segment) to a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| inst_ptr | pointer to measurement instruction(segment) to be inserted |
| index_to_insert | instruction(segment) number to be inserted |
This function inserts a measurement instruction(segment) to the measurement specified by meas_num. inst_ptr points to an instruction(segment) descriptor, which must have already been initialized.
Will be deprecated by the new equivalent function ch_meas_insert_instruction.
| uint16_t ch_meas_mm_to_samples | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint16_t | num_mm | ||
| ) |
Convert millimeters to sample count for a specific measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| num_mm | number of millimeters to be converted |
This function converts the distance in millimeters specified by num_mm and converts it to the corresponding number of sensor samples for a specific measurement number. The conversion uses values set during device initialization and calibration that describe the internal timing of the sensor, which affects how many samples correspond to a given distance.
The ch_mm_to_samples() function performs the same operation for the default measurement (same as setting meas_num to CH_DEFAULT_MEAS_NUM).
See also ch_samples_to_mm(), ch_meas_set_odr().
| uint8_t ch_meas_optimize | ( | ch_dev_t * | dev_ptr, |
| measurement_queue_t * | meas_queue_ptr, | ||
| void * | algo_cfg_ptr | ||
| ) |
Optimize ultrasound measurement sequences for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_queue_ptr | pointer to measurement queue to optimize, or NULL |
| algo_cfg_ptr | pointer to a buffer containing algorithm configuration, or NULL |
This function optimizes the transmit sequences during measurements for a sensor. The original transmit segments are replaced by a longer sequence that is tuned to the specific sensor. In particular, the "ringdown" in the sensor following a transmission is actively reduced. The sensor is able to receive the echo signal sooner, thus permitting measurements at closer distances.
Optimization is performed on a defined measurement, such as the result of combining measurement segments using ch_meas_add_segment() etc. These segments are part of the "measurement queue" for the sensor.
To optimize the current measurement settings and make no other changes to the configuration, specify NULL for both meas_queue_ptr and algo_cfg_ptr.
Alternatively, a new measurement queue may be imported, optimized, and applied using this function, similar to the ch_meas_import() function (e.g. to use an exported measurement queue definition from the SonicLink development kit). In this case, set meas_queue_ptr to the location containing the measurement queue to be optimized. The new measurement queue will be optimized, and the resulting settings will be written to the sensor. The input measurement queue definition specified by meas_queue_ptr will not be modified.
The algo_cfg_ptr parameter specifies a new measurement algorithm configuration to be applied. If algo_cfg_ptr is NULL, the current configuration will be left unchanged.
When optimization occurs, the sensor will be briefly re-programmed with special initialization firmware that analyzes the sensor's operation and determines the appropriate optimization. The results are read from the sensor and are combined with the original settings. Finally, the measurement firmware is again programmed into the sensor, and the new settings are applied. This entire sequence will typically take about 250 ms to complete.
See also ch_meas_import(), ch_meas_get_queue().
| uint8_t ch_meas_remove_instruction | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint8_t | index_to_remove | ||
| ) |
Remove an instruction(segment) in a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| index_to_remove | instruction(segment) number to be removed |
This function removes a measurement instruction(segment) to the measurement specified by meas_num. inst_ptr points to an instruction(segment) descriptor, which must have already been initialized.
| uint8_t ch_meas_remove_segment | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint8_t | index_to_remove | ||
| ) |
Remove an instruction(segment) in a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| index_to_remove | instruction(segment) number to be removed |
This function removes a measurement instruction(segment) to the measurement specified by meas_num. inst_ptr points to an instruction(segment) descriptor, which must have already been initialized.
Will be deprecated by the new equivalent function ch_meas_remove_instruction.
| uint8_t ch_meas_reset | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Reset a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
This function resets and re-initializes the measurement specified by meas_num. All segments in the measurement are removed.
After calling this function, transmit and receive segments may be added to the measurement. See ch_meas_add_segment().
| uint16_t ch_meas_samples_to_mm | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint16_t | num_samples | ||
| ) |
Convert sample count to millimeters for a specific measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| num_samples | sample count to be converted |
This function converts the sample count specified in num_samples and converts it to the corresponding physical distance in millimeters for the specified measurement. The conversion uses values set during device initialization and calibration that describe the internal timing of the sensor.
This function may be helpful when working with both physical distances (as reported by the ch_get_range() function) and sample-oriented values, such as data obtained from ch_get_iq_data() or parameters for static target rejection (see ch_set_static_range()).
The ch_samples_to_mm() function performs the same operation for the default measurement (same as setting meas_num to CH_DEFAULT_MEAS_NUM).
See also ch_mm_to_samples(), ch_meas_set_odr().
| uint8_t ch_meas_set_interval | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint16_t | interval_ms | ||
| ) |
Set the repeat interval for a measurement, in milliseconds.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| interval_ms | measurement interval, in milliseconds |
This function sets the internal measurement interval in the sensor. The sensor will perform a measurement every interval_ms milliseconds. No external trigger is required.
To set the sensing interval with greater precision, use ch_meas_set_interval_us() or ch_meas_set_interval_ticks().
See also ch_set_freerun_interval(), ch_meas_get_interval().
| uint8_t ch_meas_set_interval_ticks | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint32_t | rtc_ticks | ||
| ) |
Set the repeat interval for a measurement, in sensor RTC clock ticks.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| rtc_ticks | measurement interval, in sensor RTC clock periods |
This function sets the internal measurement interval in the sensor. The sensor will perform a measurement every rtc_ticks sensor RTC clock periods. No external trigger is required.
See also ch_meas_set_interval(), ch_meas_get_interval_ticks().
| uint8_t ch_meas_set_interval_us | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint32_t | interval_us | ||
| ) |
Set the repeat interval for a measurement, in microseconds.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| interval_us | measurement interval, in microseconds |
This function sets the internal measurement interval in the sensor. The sensor will perform a measurement every interval_us microseconds. No external trigger is required.
See also ch_meas_set_interval(), ch_meas_get_interval_ticks().
| uint8_t ch_meas_set_iq_output | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| ch_output_type_t | output_format | ||
| ) |
Set the I/Q data output format for a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| output_format | I/Q output format 0=normal (Q,I) pairs; 1=amplitude,threshold pairs, 2=amplitude array |
This function sets the measurement I/Q data output format. The data may be output in three different formats, based on the value of output_format:
See also ch_meas_get_iq_output(), ch_set_data_output(), ch_meas_init().
| uint8_t ch_meas_set_max_range | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint16_t | max_range_mm | ||
| ) |
Set the maximum range in mm for a specific measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | measurement number |
| max_range | maximum range, in millimeters |
This function sets the maximum detection range for the specified measurement, in millimeters. The detection range setting controls how long the sensor will listen (i.e. how many samples it will capture) during each measurement cycle. (The number of samples is automatically calculated for the specified range.)
Note that this function changes the number of samples in an existing measurement. The existing measurement definition will be shortened or extended to match the new sample count. If the measurement is extended, the new samples will use the same settings as in the final receive segment.
The ch_set_max_range() function performs the same operation for the default measurement (same as setting meas_num to CH_DEFAULT_MEAS_NUM).
See also ch_meas_set_num_samples(), ch_meas_get_max_range().
| uint8_t ch_meas_set_num_samples | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num, | ||
| uint16_t | num_samples | ||
| ) |
Set the sensor sample count for a specific measurement.
| dev_ptr | pointer to the ch_dev_t descriptor struct |
| meas_num | measurement number |
| num_samples | number of samples during each measurement cycle |
This function directly sets the number of samples which the Chirp sensor will obtain during a specific measurement (0 or 1). The number of samples directly corresponds to the range at which the sensor can detect.
Note that this function changes the number of samples in an existing measurement. The existing measurement definition will be shortened or extended to match the new sample count. If the measurement is extended, the new samples will use the same settings as in the final receive segment.
The ch_set_num_samples() function performs the same operation for the default measurement (same as setting meas_num to CH_DEFAULT_MEAS_NUM).
See also ch_meas_set_max_range(), ch_set_num_samples().
Set the output data rate for a measurement.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function sets the output data rate (ODR) for the sensor. The ODR setting determines the spacing in time (and therefore in measured distance) between the individual sample points within a measurement.
The standard ODR value is CH_ODR_FREQ_DIV_8 (also known as CH_ODR_DEFAULT), or one sample per 8 transceiver cycles. The ODR may be adjusted higher or lower - each higher or value will increase or decrease the output rate (i.e. the time between samples) by a factor of 2. The maximum ODR is CH_ODR_FREQ_DIV_2 (one sample every 2 transceiver cycles); the minimum ODR is CH_ODR_FREQ_DIV_32 (one sample every 32 transceiver cycles).
See also ch_meas_init(), ch_meas_get_odr().
| void ch_meas_standby | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Put a measurement in standby mode.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | number of measurement to place in standby mode |
This function places the specified measurement in standby mode. This measurement's definition will not be used by the sensor - the other measurement definition will be used to perform all readings.
Because there must always be at least one active measurement, this function will activate the other measurement if it was not already active. It is not possible to have both measurements in standby mode simultaneously.
A measurement may be set to initially be in standby mode, see ch_meas_init().
See also ch_meas_activate(), ch_meas_switch().
| uint8_t ch_meas_switch | ( | ch_dev_t * | dev_ptr | ) |
Switch active and standby measurement definitions.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_num | number of measurement to place in standby mode |
This function switches the roles of the two measurement definitions between active and standby. The currently active measurement is put into standby mode, and the standby measurement is made active.
If this function is called when both measurements are active, the next measurement due to operate (the current measurement) will be placed into standby mode, and the other measurement will remain active.
This routine returns the number of the new active measurement. This will be the next measurement performed by the sensor.
See also ch_meas_activate(), ch_meas_standby(), ch_meas_get_info().
| uint8_t ch_meas_time_hop_disable | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Disable time-hopping on measure period freerunning mode.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function disable the time-hopping for a sensor operating in freerunning mode (CH_MODE_FREERUN).
See also ch_meas_time_hop_enable(), ch_meas_get_interval_ticks(), ch_meas_set_interval(), ch_meas_set_interval_us(), ch_meas_set_interval_ticks().
| uint8_t ch_meas_time_hop_enable | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_num | ||
| ) |
Enable time-hopping on measure period freerunning mode.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function enables the time-hopping for a sensor operating in freerunning mode (CH_MODE_FREERUN). The sensor will use its internal real-time clock (RTC) to wake and perform a measurement every measure interval plus a random delay to avoid coexistence with other sensors. Mean measure period is however equals to measure interval.
See also ch_meas_time_hop_disable(), ch_meas_get_interval_ticks(), ch_meas_set_interval(), ch_meas_set_interval_us(), ch_meas_set_interval_ticks().
| uint8_t ch_meas_write_config | ( | ch_dev_t * | dev_ptr | ) |
Write measurement configuration to sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function writes a complete measurement queue configuration to the sensor device. The measurement queue settings must have already been defined, by using the standard API functions (initializing one or more measurements and adding a sequence of measurement segments).
This function additionally sanitizes the measurement queue by performing several checks to ensure it is compatible with the selected sensor mode. This function potentially modifies the queue, so users should examine the passed queue after loading it.
| uint32_t ch_measure_pmut_frequency | ( | ch_dev_t * | dev_ptr | ) |
Measure PMUT frequency on an ICU device.
| dev_ptr | pointer to the ch_dev_t config structure for a sensor |
This function must only be called after initialization (ie after calling ch_group_start()).
| uint8_t ch_minimal_int_handler | ( | ch_group_t * | grp_ptr, |
| uint8_t | dev_num | ||
| ) |
Notify SonicLib that a sensor interrupt was received.
| grp_ptr | pointer to the ch_group_t config structure for a group of sensors |
| dev_num | interrupting sensor's device number within group |
This function should be called from the board support package when an interrupt from the sensor is received. The dev_num parameter indicates which sensor interrupted.
Unlike ch_interrupt(), this function does not call the user supplied callback. It is intended to be used when the user would like more control of exactly what happens when an interrupt is received from the sensor.
Other differences from ch_interrupt():
See also ch_interrupt().
| uint16_t ch_mm_to_samples | ( | ch_dev_t * | dev_ptr, |
| uint16_t | num_mm | ||
| ) |
Convert millimeters to sample count for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| num_mm | number of millimeters to be converted |
This function converts the distance in millimeters specified by num_mm and converts it to the corresponding number of sensor samples. The conversion uses values set during device initialization and calibration that describe the internal timing of the sensor, which affects how many samples correspond to a given distance.
This function may be helpful when working with both physical distances (as reported by the ch_get_range() function) and sample-oriented values, such as data obtained from ch_get_iq_data() or parameters for filtering such as static target rejection (see ch_set_static_range()).
See also ch_samples_to_mm(), ch_meas_set_odr().
| void ch_reset | ( | ch_dev_t * | dev_ptr, |
| ch_reset_t | reset_type | ||
| ) |
Reset a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| reset_type | type of reset (CH_RESET_HARD or CH_RESET_SOFT) |
This function resets a sensor. The reset_type parameter indicates if a software reset or full hardware reset is requested.
| uint8_t ch_restart | ( | ch_dev_t * | dev_ptr | ) |
Restart a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function performs a re-start of a sensor that has previously been initialized and started. The sensor is reset, the sensor firmware is reloaded, and the configuration settings are re-applied. The sensor will not perform the normal calibration steps (including clock calibration) - it will instead use the values saved during a previous initialization.
Normally, this function should not be needed. It may be useful for special error handling or other application-specific requirements.
Different sensor firmware can be loaded, by calling ch_init() before this function and specifying a new firmware init routine. This is normally not recommended for applications, but this mechanism is sometimes used internally by SonicLib.
After this routine returns successfully, the sensor should be ready to resume measurements.
See also ch_group_restart(), ch_group_start().
| uint32_t ch_samples_to_cycles | ( | uint16_t | num_samples, |
| ch_odr_t | odr | ||
| ) |
Convert samples to sensor cycles.
| num_samples | number of samples |
| odr | output data rate |
This function takes a count of samples and converts it to the corresponding number of internal sensor cycles. The cycles are the same units used to specify measurement segment lengths.
The odr parameter is the current output data rate setting for the sensor. The ODR affects the timing between samples, and therefore the number of internal cycles per sample.
See also ch_cycles_to_samples, ch_meas_get_odr.
| uint16_t ch_samples_to_mm | ( | ch_dev_t * | dev_ptr, |
| uint16_t | num_samples | ||
| ) |
Convert sample count to millimeters for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| num_samples | sample count to be converted |
This function converts the sample count specified in num_samples and converts it to the corresponding physical distance in millimeters. The conversion uses values set during device initialization and calibration that describe the internal timing of the sensor.
This function may be helpful when working with both physical distances (as reported by the ch_get_range() function) and sample-oriented values, such as data obtained from ch_get_iq_data() or parameters for static target rejection (see ch_set_static_range()).
See also ch_mm_to_samples(), ch_meas_set_odr().
| uint8_t ch_sensor_is_connected | ( | ch_dev_t * | dev_ptr | ) |
Indicate if a sensor is connected.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| uint8_t ch_set_algo_config | ( | ch_dev_t * | dev_ptr, |
| const void * | algo_cfg_ptr | ||
| ) |
Set the measurement algorithm configuration data to a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| algo_cfg_ptr | pointer to a buffer to send configuration data |
This function writes the configuration data to an algorithm running on the ICU sensor. This interface is independent of the specific algorithm or configuration format.
Normally, this routine will only be used by special applications or libraries which interact with specific sensor firmware.
| uint8_t ch_set_cal_result | ( | ch_dev_t * | dev_ptr, |
| ch_cal_result_t * | cal_ptr | ||
| ) |
Set the calibration result.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| cal_ptr | pointer to ch_cal_result_t structure to receive calibration data |
WARNING: This function should not be used to set the calibration result to a fixed value, even one individually calculated for each sensor, as this could change over the lifetime of the sensor; rather, this function could be used to update the calibration result if the calibration result calculated by CHx01 at startup (i.e. returned by ch_get_cal_result()) is sufficiently different than expected or sensor performance is not good.
This function sets the calibration result with a ch_cal_result_t structure specified by cal_ptr for the sensor. The ch_cal_result_t structure contains DCO period and reverse drive cycles.
To use this function, first initialize the ch_cal_result_t DCO period/reverse drive cycles pair of values
See also ch_get_cal_result().
| uint8_t ch_set_config | ( | ch_dev_t * | dev_ptr, |
| ch_config_t * | config_ptr | ||
| ) |
Set multiple configuration settings for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| config_ptr | pointer to a ch_config_t structure containing new configuration values |
This function sets multiple configuration options within the sensor. The configuration settings are passed in a ch_config_t structure, whose address is specified by config_ptr. The fields in the ch_config_t structure must have been set with your new configuration values before this function is called.
| uint8_t ch_set_data_output | ( | ch_dev_t * | dev_ptr, |
| ch_output_t * | output_ptr | ||
| ) |
Set data output format and rate.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| output_ptr | pointer to the data output type, including format and decimation factor |
This function sets both the data output format type and rate for sample data within a measurement. The values are passed in a ch_output_t structure specified by output_ptr, which contains two fields, output_type and decimation_factor. The decimation factor is equivalent to the sample output data rate (ODR) of the sensor, expressed differently.
The possible values for output_type are:
The possible values for decimation_factor and the equivalent output rate (ODR) values are as follows:
| Decimation Factor | ODR Value | Sample Rate vs. Default |
|---|---|---|
| CH_DECIMATION_NONE | CH_ODR_FREQ_DIV_8 (CH_ODR_DEFAULT) | default |
| CH_DECIMATION_0_25 | CH_ODR_FREQ_DIV_2 | 4 x default |
| CH_DECIMATION_0_50 | CH_ODR_FREQ_DIV_4 | 2 x default |
| CH_DECIMATION_2 | CH_ODR_FREQ_DIV_16 | 1/2 default |
| CH_DECIMATION_3 | no equivalent | 1/3 default - only in special CHx01 f/w |
| CH_DECIMATION_4 | CH_ODR_FREQ_DIV_32 | 1/4 default |
For ICU sensors, both measurements will be set to the specified output type. To change the output format for a single measurement, use ch_meas_set_iq_output(). To change the output data rate for a single measurement, use ch_meas_set_odr().
| uint8_t ch_set_data_ready_delay | ( | ch_dev_t * | dev_ptr, |
| uint8_t | delay_ms | ||
| ) |
Set data ready interrupt delay interval.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| delay_ms | time, in milliseconds, for sensor to delay after measurement |
This function sets a delay interval that will cause the sensor to wait slightly after a measurement completes before issuing a data ready interrupt. It is used in special circumstances to handle unusual timing constraints. Normally, this function should not be used.
delay_ms specifies the time, in milliseconds, that the sensor will delay after the measurement completes before generating the interrupt signal.
The granularity of this delay is limited by the period of the sensor's internal wake cycle timer, so in some cases the delay_ms value will be increased to match the next whole number of wake cycles. (A granularity of about 4 ms is typical.)
The ch_get_data_ready_delay() function may be used to determine the actual delay period, after any adjustment to match the sensor wake cycles.
| uint8_t ch_set_freerun_interval | ( | ch_dev_t * | dev_ptr, |
| uint16_t | interval_ms | ||
| ) |
Set the internal sensing interval for freerunning mode, in milliseconds.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| interval_ms | interval between samples, in milliseconds. |
This function sets the sample interval for a sensor operating in freerunning mode (CH_MODE_FREERUN). The sensor will use its internal clock to wake and perform a measurement every interval_ms milliseconds. A value of zero for interval_ms is not valid.
To set the sensing interval with greater precision, use ch_set_freerun_interval_us() or ch_set_freerun_interval_ticks().
See also ch_get_freerun_interval(), ch_set_freerun_interval_us(), ch_set_sense_interval_cycles().
| uint8_t ch_set_freerun_interval_ticks | ( | ch_dev_t * | dev_ptr, |
| uint32_t | interval_ticks | ||
| ) |
Set the internal sensing interval for freerunning mode, in RTC clock ticks.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| interval_ticks | interval between samples, in sensor RTC clock periods |
This function sets the sample interval for a sensor operating in freerunning mode (CH_MODE_FREERUN). The sensor will use its internal real-time clock (RTC) to wake and perform a measurement every interval_ticks clock periods. A value of zero for interval_ticks is not valid.
See also ch_get_freerun_interval_ticks(), ch_set_freerun_interval(), ch_set_freerun_interval_us().
| uint8_t ch_set_freerun_interval_us | ( | ch_dev_t * | dev_ptr, |
| uint32_t | interval_us | ||
| ) |
Set the internal sensing interval for freerunning mode, in microseconds.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| interval_us | interval between samples, in microseconds. |
This function sets the sample interval for a sensor operating in freerunning mode (CH_MODE_FREERUN). The sensor will use its internal clock to wake and perform a measurement every interval_us microseconds. A value of zero for interval_us is not valid.
See also ch_get_freerun_interval_us(), ch_set_freerun_interval(), ch_set_freerun_interval_ticks().
| uint8_t ch_set_frequency | ( | ch_dev_t * | dev_ptr, |
| uint32_t | request_op_freq_hz | ||
| ) |
Set the operating frequency of a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| request_op_freq_hz | requested operating frequency in Hz |
This function requests a desired acoustic operating frequency for a sensor. This is the primary frequency of the ultrasonic pulse that is emitted by the device when transmitting.
The request_op_freq_hz parameter specifies the frequency, in Hz, that is requested. The operating frequency for the sensor will be set as close as possible to this value. The operating frequency cannot be set to a value that is outside the typical operating frequency range for the sensor model.
In general, the actual operating frequency will be slightly different than the requested value. Use ch_get_frequency() to obtain the sensor's operating frequency after the adjustment.
Often, a group of sensors will be set to a common acoustic operating frequency to optimize the transmit/receive efficiency for sensors operating in paired pitch/catch operation. Use ch_group_set_frequency(), instead of this function, to set all sensors in a group to a common value. That function can automatically apply a calculated value based on the sensors' natural frequencies.
See also ch_get_frequency(), ch_group_set_frequency().
| uint8_t ch_set_init_firmware | ( | ch_dev_t * | dev_ptr, |
| ch_fw_init_func_t | fw_init_func | ||
| ) |
Initialize the init firmware to use for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| fw_init_func | pointer to the sensor init firmware initialization function |
This function is used to define the init firmware for a sensor if the main firwmware (determined with ch_init) doesn't have initialization features in it. It can be necessary to set a specific initialization firmware (with tx optimization) if using measure optimization API.
| uint8_t ch_set_interrupt_drive | ( | ch_dev_t * | dev_ptr, |
| ch_interrupt_drive_t | drive | ||
| ) |
Set interrupt drive (open drain or push pull)
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| drive | CH_INTERRUPT_DRIVE_OPEN_DRAIN for open drain interrupt drive, CH_INTERRUPT_DRIVE_PUSH_PULL for push pull drive |
This function sets the sensor interrupt to use an open-drain or push-pull drive. In open drain, the sensor will actively drive the line low and use a pull-up resistor for the hight level. In push-pull drive, the sensor will actively drive the line both low and high. Additionally, the pull-up resistor on the interrupt pin used for hardware trigger is disabled. By default, ICU sensors use open drain interrupt drive (CH_INTERRUPT_DRIVE_OPEN_DRAIN).
To use this function, set drive to CH_INTERRUPT_DRIVE_OPEN_DRAIN to enable open drain drive. Set drive to CH_INTERRUPT_DRIVE_PUSH_PULL to use push-pull drive.
| uint8_t ch_set_interrupt_mode | ( | ch_dev_t * | dev_ptr, |
| ch_interrupt_mode_t | mode | ||
| ) |
Set interrupt mode (pulsed or latching)
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| mode | CH_INTERRUPT_MODE_PULSE for pulse interrupt mode, CH_INTERRUPT_MODE_LATCH for latching mode |
This function sets the sensor interrupt to use a pulsed or latching level change. In pulse mode, the sensor will briefly change the INT line level and then restore it to the original state. In latching mode, the sensor will change the INT line level, and it will stay at that level until reset by the interrupt handler in the board support package. By default, ICU sensors use latching interrupt mode (CH_INTERRUPT_MODE_LATCH).
To use this function, set mode to CH_INTERRUPT_MODE_PULSE to enable pulsed interrupt mode. Set mode to CH_INTERRUPT_MODE_LATCH to disable the pulse interrupt mode and use latching behavior.
| uint8_t ch_set_max_range | ( | ch_dev_t * | dev_ptr, |
| uint16_t | max_range | ||
| ) |
Set the maximum range for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| max_range | maximum range, in millimeters |
This function sets the maximum detection range for the sensor, in millimeters. The detection range setting controls how long the sensor will listen (i.e. how many samples it will capture) during each measurement cycle. (The number of samples is automatically calculated for the specified range.)
For ICU sensors, this function always controls the default measurement definition. To specify which measurement to modify, use the ch_meas_set_max_range() function.
See also ch_set_num_samples(), ch_get_max_range(), ch_set_config().
Configure a sensor for the specified operating mode.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| mode | the new operating mode for the sensor |
This function sets the sensor to operate in the specified mode, which must be one of the following:
| uint8_t ch_set_num_samples | ( | ch_dev_t * | dev_ptr, |
| uint16_t | num_samples | ||
| ) |
Set the sensor sample count directly.
| dev_ptr | pointer to the ch_dev_t descriptor struct |
| num_samples | number of samples during each measurement cycle |
This function directly sets the number of samples which the Chirp sensor will perform during a single measurement cycle. The number of samples directly corresponds to the range at which the sensor can detect.
For ICU sensors, note that this function changes the number of samples in an existing measurement. The existing measurement definition will be shortened or extended to match the new sample count. If the measurement is extended, the new samples will use the same settings as in the final receive segment. This function always controls the default measurement definition. To specify which measurement to modify, use the ch_meas_set_num_samples() function.
See also ch_set_max_range(), ch_get_num_samples().
| uint8_t ch_set_pmut_clock | ( | ch_dev_t * | dev_ptr, |
| ch_pmut_clk_cfg_t | clock_cfg | ||
| ) |
Configure ultrasound transducer clock.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| clock_cfg | clock configuration setting |
This function configures the PMUT clock input and output settings to allow the multiple sensors to share a common clock signal. One sensor may be set to output the signal from the PMUT clock, while others may be set to use that signal as a clock input. This permits very exact frequency matching for critical applications. Alternatively, all sensors may be set to use an independent, external clock signal.
This function may only be called after ch_group_start() has initialized the sensors. The original PMUT clock settings will be modified, and the new settings will be applied immediately. The PMUT clock settings must be set separately for each sensor.
When one sensor supplies the clock for one or more other sensors, the sequence of enabling and disabling the clock settings across the sensors is important. The clock source must be present whenever a secondary sensor is configured to use an external clock source.
If an independent clock source (not from a sensor) is used, that input signal must be present and ch_group_set_pmut_clock_freq() must be called to specify the clock frequency before the sensors are set to CH_PMU_CLK_SRC_EXTERNAL.
The ch_get_frequency() function will report the current acoustic operating frequency of the PMUT, regardless of the clock source. So, if the sensor is using an external clock source, the indicated frequency will match that of the sensor supplying the clock signal, or 1/16 the input clock rate if an independent signal.
Only one shared PMUT clock signal can be used within a sensor group. Individual sensors are not required to use the shared clock.
See also ch_get_pmut_clock(), ch_group_set_pmut_clock_freq().
| uint8_t ch_set_rtc | ( | ch_dev_t * | dev_ptr, |
| ch_rtc_src_t | rtc_source, | ||
| uint16_t | rtc_freq | ||
| ) |
Configure the sensor real-time clock (RTC).
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| rtc_source | RTC source (internal or external) |
| rtc_freq | RTC frequency in Hz, or CH_RTC_USE_BUS_SPEED, or zero to use factory test result |
This function changes the default real-time clock (RTC) configuration to meet special requirements and system limitations. In most applications, this function is not needed and should not be called.
Two options may be set. For the internal RTC clock, this function can specify alternatives to the standard clock calibration. Or, this function can indicate that an external clock source be used to drive the sensor's RTC functions.
An accurate measurement of the sensor's RTC clock is an important part of the time-of-flight calculations performed by the ultrasonic sensor and SonicLib. Any inaccuracy in the RTC frequency value will directly result in inaccuracy in time-of-flight, and therefore range, measurements.
Normally, the sensor's internal RTC clock frequency is measured during sensor initialization, using an external timed pulse (typically 100 ms) on the sensor INT line. This pulse takes place during ch_group_start(). Using a timed calibration pulse is recommended, because it gives the best overall sensor accuracy. In some situations, however, it may be impossible or inconvenient to apply a sufficiently accurate timed pulse to calibrate the RTC. This function provides two alternative ways to set the frequency value, with some sacrifice in ultimate sensor accuracy.
This function can specify the frequency, in Hz, for the RTC using either the stored factory test result or a custom value. This function does not actually change the sensor's internal RTC frequency, it simply sets the numeric value that will be used in calculations where the RTC frequency is needed.
ICU sensors contain factory test data that includes a measurement of the sensor's internal RTC frequency. This value provides a reasonable substitute for performing full calibration using a calibration pulse.
To use the factory RTC calibration data, specify CH_RTC_SRC_INTERNAL for rtc_source and a value of zero for rtc_freq.
Factory RTC calibration values are not available for CH101 or CH201 sensors.
In some cases, it is possible to use the I/O bus clock as a reference for calibrating the RTC. (This feature is only available in select sensor f/w variants.)
To use the bus clock for calibration, specify CH_RTC_SRC_INTERNAL for rtc_source, and set rtc_freq to CH_RTC_USE_BUS_SPEED.
For CH101/CH201 sensor types that support this calibration mode, the I2C bus clock (SCL) speed is assumed to be 400000 Hz by default. If a different, more accurate value for the bus clock speed is available, it can be specified by defining CHIRP_I2C_BUS_SPEED_HZ in the chirp_board_config.h file in the board support package, and setting the value to the correct bus speed. Inaccuracies in the bus clock rate value will affect frequency and range measurements by the sensor.
If rtc_freq is not zero or CH_RTC_USE_BUS_SPEED, the specified value will be used in all calculations requiring the RTC frequency. Normal calibration using a pulse is not performed. The rtc_freq value should be the best available estimate of the RTC frequency for this device.
To use an estimated RTC frequency, specify CH_RTC_SRC_INTERNAL for rtc_source, and set rtc_freq to the approximate RTC frequency, in Hz.
If no other estimate is available, rtc_freq may be specified as CH_RTC_FREQ_TYPICAL (29000 Hz) for a rough approximation of a typical RTC frequency.
This option is a last choice, due to the impact on measurement accuracy, but it will allow measurements to be completed.
This function can also set the source of the sensor's real-time clock. By default, the sensor will use its internal oscillator as the RTC clock time base. To use the internal RTC, no special action is required, and this routine does not have to be called unless you are changing the calibration values described above.
For enhanced timing accuracy, an external clock source (e.g. crystal oscillator) may be connected to the ICU sensor. This may be used to maintain a more exact measurement interval for sensors operating in free-running mode (CH_MODE_FREERUN).
To enable an external clock source for the RTC, set rtc_source to CH_RTC_SRC_EXTERNAL, and set rtc_freq to the frequency of the clock signal in Hz (e.g. 32768 for a 32.768 kHz crystal).
This function should be called after ch_init() but before ch_group_start(). This function must be called before ch_group_start(), because RTC calibration is normally done then. When this function is used, the sensor will not require or perform automatic RTC calibration using a timed pulse.
All sensors in a sensor group must use the same calibration method, automatic (default) or manual (using this routine for each sensor in the group before ch_group_start()).
See also ch_get_rtc_frequency().
| uint8_t ch_set_rx_holdoff | ( | ch_dev_t * | dev_ptr, |
| uint16_t | num_samples | ||
| ) |
Set the receive holdoff sample count.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| num_samples | number of samples to be ignored at the beginning of each measurement |
This function sets the receive (rx) holdoff sample count. num_samples specifies a number of samples at the beginning of a measurement that will be ignored for the purpose of detecting a target. (These samples correspond to the closest distances from the sensor.)
To convert a physical distance into a sample count value to use here, use ch_mm_to_samples().
For ICU sensors, this function always controls the default measurement definition. To specify which measurement to modify, use the icu_gpt_set_rx_holdoff() function.
See also ch_get_rx_holdoff().
| uint8_t ch_set_rx_low_gain | ( | ch_dev_t * | dev_ptr, |
| uint16_t | num_samples | ||
| ) |
Set the receive low-gain sample count.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| num_samples | number of samples that have low gain at beginning of measurement |
This function sets the receive (rx) low-gain range in the sensor. The low-gain range consists of samples at the beginning of a measurement that will have a lower gain applied during the sensor receive operation. (These samples correspond to the closest distances from the sensor.)
The low-gain range must be less than the current maximum range setting. If num_samples is greater than or equal to the maximum range setting, it will automatically be reduced.
See also ch_get_rx_low_gain(), ch_get_num_samples().
| void ch_set_rx_pretrigger | ( | ch_group_t * | grp_ptr, |
| uint8_t | enable | ||
| ) |
Enable/disable receive-only sensor pre-triggering.
| grp_ptr | pointer to the ch_group_t group descriptor structure |
| enable | 1 to enable pre-triggering, 0 to disable |
This function enables or disables pre-triggering of the receive-only sensor during Pitch-Catch operation. When pre-triggering is enabled, sensors in CH_MODE_TRIGGERED_RX_ONLY mode will be triggered slightly before sensors in CH_MODE_TRIGGERED_TX_RX mode when ch_group_trigger() is called. This improves the ability of a receive-only sensor to detect the transmitted pulse at very short distances.
If enabled, pre-triggering is used for all receive-only sensors in the sensor group.
To use this function, set enable to 1 to enable pre-triggering, or 0 to disable pre-triggering.
See also ch_get_rx_pretrigger().
| uint8_t ch_set_sample_interval | ( | ch_dev_t * | dev_ptr, |
| uint16_t | interval_ms | ||
| ) |
Set the internal sensing interval (deprecated).
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| interval_ms | interval between samples, in milliseconds. |
This function sets the sample interval for a sensor operating in freerunning mode (CH_MODE_FREERUN). The sensor will use its internal clock to wake and perform a measurement every interval_ms milliseconds. A value of zero for interval_ms is not valid.
| uint8_t ch_set_sample_window | ( | ch_dev_t * | dev_ptr, |
| uint16_t | start_sample, | ||
| uint16_t | num_samples | ||
| ) |
Set the sample window for amplitude averaging.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| start_sample | sample number of first sample in window |
| num_samples | number of samples to include in window |
This function sets the sample range to be included in the sample window used for amplitude averaging. start_sample is the number of the first sample that will be included in the averaging window. num_samples is the total number of samples that will be included.
See also ch_get_amplitude_avg(), ch_get_sample_window().
| uint8_t ch_set_target_int_counter | ( | ch_dev_t * | dev_ptr, |
| uint8_t | meas_hist, | ||
| uint8_t | thresh_count, | ||
| uint8_t | reset | ||
| ) |
Configure the target interrupt counter filter.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| meas_hist | number of previous measurements to include in target count |
| thresh_count | number of target detections req'd to generate interrupt |
| reset | if non-zero, counter filter resets when int is generated |
This function sets the counter filter used to control target interrupts. The counter filter is by enabled using the ch_set_target_interrupt() function and specifying CH_TGT_INT_FILTER_COUNTER as the filter type.
When the counter filter is used, a certain threshold number of positive target detections must be observed within a specified number of measurements in order for an interrupt to be generated by the sensor.
meas_hist specifies the number of previous measurements that will be included in the history buffer for filtering. The current measurement is combined with these previous measurements, so a total of meas_hist + 1 measurements are used.
thresh_count is the number of those measurements that must positively detect a target for an interrupt to be generated.
At the end of each measurement, the total number of measurements with target detection within all the history and the new measurement is compared against the threshold value. If it meets the threshold, the sensor will interrupt. For example, if meas_hist is 5 and thresh_count is 3, an interrupt will be generated if 3 of the most recent 6 measurements (the 5 in the history plus the new result) detected a target.
If reset is non-zero, the counter filter counts are reset when an interrupt is generated. The sensor will not interrupt again until thresh_count new measurements detect a target, using the same threshold conditions as before. If reset is zero, the sensor will maintain its history and will continue to interrupt after each measurement if the threshold number of detections within recent results is met. Counter filter resetting is disabled by default.
The maximum value for both meas_hist and thresh_count is 15.
See also ch_get_target_int_counter(), ch_set_target_interrupt().
| uint8_t ch_set_target_interrupt | ( | ch_dev_t * | dev_ptr, |
| ch_tgt_int_filter_t | tgt_int_filter | ||
| ) |
Configure target interrupt filtering mode.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| tgt_int_filter | target interrupt filter mode |
This function configures the filtering of data ready interrupts from the sensor based on target detection.
In normal operation (if target detection interrupt filtering is not enabled), the sensor will assert the INT line at the end of each measurement even if no target is detected. This is the default behavior if this function is not used, or if tgt_int_filter is CH_TGT_INT_FILTER_OFF.
When basic target interrupt filtering is enabled, the sensor will assert the INT line at the end of each measurement only if a target object was detected. If no target is detected, the sensor will not interrupt, and there is no indication from the sensor that the measurement has completed.
To use basic target interrupt filtering, set tgt_int_filter to CH_TGT_INT_FILTER_ANY.
Target counter mode provides another level of filtering, across multiple measurements. When counter filtering is enabled, the sensor will only interrupt after multiple measurements have detected a target within a certain total number of consecutive recent measurements. A configurable history of previous measurements is recorded, and the results are compared against a threshold number of target detections. The sensor will generate an interrupt only when the count of target detections within the set of recent measurements meets the threshold value,
To use counter mode filtering, set tgt_int_filter to CH_TGT_INT_FILTER_COUNTER. The measurement history and target detection threshold count used in the filter can be set by using the ch_set_target_int_counter() function.
If not otherwise specified, the default measurement history length is 5 measurements. The current measurement is combined with the measurements from the history, so a total of 6 measurements are used. The default interrupt threshold is 3 target detections. So by default, 3 of the 6 most recent measurements must detect a target to generate an interrupt.
By default, the counter filter maintains its history and counter values after an interrupt is generated, so the next measurement may again interrupt based on the threshold comparison as usual. The counter filter may instead be configured to reset after generating an interrupt by using ch_set_target_int_counter(). In this case, the full thresh_count threshold must be met based on new detections, so that minimum number of measurements must occur before another interrupt will be generated.
See also ch_set_target_int_counter(), ch_get_target_interrupt().
| void ch_set_trigger_type | ( | ch_dev_t * | dev_ptr, |
| ch_trigger_type_t | trig_type | ||
| ) |
Set the trigger type for a sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| trig_type | trigger type to be used, CH_TRIGGER_TYPE_HW or CH_TRIGGER_TYPE_SW |
This function sets the trigger type to be used to initiate a measurement on a sensor that is in triggered mode. (Sensors in free-running mode are self-triggered based on an internal timer.)
By default (if this routine is not called), sensors are triggered using a hardware signal on the INT line. For ICU sensors, either there are two INT lines, INT1 and INT2. The line to be used for triggering is selected by the CHIRP_SENSOR_TRIG_PIN definition in the chirp_board_config.h file.
Alternatively, a measurement may be initiated via software, using a SPI command sent to the sensor. This may be used in place of a standard hardware trigger using a GPIO line, although there will be more latency and less exact timing control. To enable software triggering, set trig_type to CH_TRIGGER_TYPE_SW.
See also ch_trigger(), ch_trigger_soft(), ch_get_trigger_type().
| uint8_t ch_set_tx_length | ( | ch_dev_t * | dev_ptr, |
| uint16_t | num_cycles | ||
| ) |
Set the ultrasound transmit pulse length.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| num_cycles | transmit pulse length (number of cycles per transmission) |
This function sets the length (duration) of the ultrasonic pulse sent by the sensor when it transmits. num_cycles specifies the length of the pulse.
For ICU (Shasta architecture) sensors, num_cycles are in units of Measurement State Machine Clock (SMCLK) cycles.
For CH101 and CH201 (Whitney architecture) sensors, num_cycles are ultrasonic transducer (PMUT) cycles, so are 1/16 the corresponding ICU sensor value.
See also ch_get_tx_length().
| uint32_t ch_ticks_to_usec | ( | ch_dev_t * | dev_ptr, |
| uint16_t | num_ticks | ||
| ) |
Convert sensor RTC clock ticks to microseconds.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| rtc_ticks | number of sensor RTC clock periods |
This function takes a number of internal sensor RTC clock periods and converts it to the corresponding time in microseconds.
See also ch_usec_to_ticks(), ch_set_rtc().
| void ch_trigger | ( | ch_dev_t * | dev_ptr | ) |
Trigger a measurement on one sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function generates a pulse on the INT line for a single sensor. If the sensor is in either CH_MODE_TRIGGERED_TX_RX or CH_MODE_TRIGGERED_RX_ONLY mode, this pulse will begin a measurement cycle.
To simultaneously trigger all sensors in a group, use ch_group_trigger().
| void ch_trigger_soft | ( | ch_dev_t * | dev_ptr | ) |
Trigger a measurement using software (SPI) interface.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function sends a special command to the sensor over the SPI bus to trigger a measurement. The software interface is always used regardless of the trigger type that has been set using ch_set_trigger_type().
This may be used in place of a standard hardware trigger using a GPIO line, although there will be more latency and less exact timing control.
See also ch_trigger().
| uint8_t ch_update_metadata_from_iq0 | ( | ch_dev_t * | dev_ptr, |
| ch_iq_sample_t * | iq_data | ||
| ) |
Extract the metadata from the first IQ sample and update the device pointer.
The ICU-X0201 can be configured to place metadata in the first IQ sample, which is otherwise always read out as 0. If enabled, this will place the IQ buffer address as well as the last measurement index in the first IQ sample. See ch_enable_metadata_in_iq0().
This function is used to extract metadata from the read IQ data. The metadata will be updated into dev_ptr. That is, after calling this function, the device pointer will be updated with the correct buffer address and last measurement index.
After running this function and getting a 0 exit status, the last measurement index can be retrieved using ch_meas_get_last_num() and the next buffer address with ch_get_next_buf_addr().
| dev_ptr | The device pointer |
| iq_data | Pointer to the read IQ data. The metadata is extracted from the first sample, then the first sample is set back to 0. |
| uint32_t ch_usec_to_cycles | ( | ch_dev_t * | dev_ptr, |
| uint32_t | num_usec | ||
| ) |
Convert microseconds to sensor cycles.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| num_usec | number of microseconds |
This function takes a period of time specified in microseconds and converts it to the corresponding number of internal sensor cycles.
For ICU (Shasta architecture) sensors, cycles are in units of PMUT State Machine Clock (SMCLK) cycles. The PMUT clock rate is 16 times the ultrasonic transducer acoustic operating frequency. These are the same cycle units used to specify measurement transmit and count segment lengths.
For CH101 and CH201 (Whitney architecture) sensors, cycles are ultrasonic transducer cycles, so are 1/16 the corresponding ICU sensor value.
See also ch_cycles_to_usec().
| uint16_t ch_usec_to_ticks | ( | ch_dev_t * | dev_ptr, |
| uint32_t | num_usec | ||
| ) |
Convert microseconds to sensor RTC clock ticks.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
| num_usec | number of microseconds |
This function takes a time specified in microseconds and converts it to the corresponding number of sensor RTC clock periods.
See also ch_ticks_to_usec(), ch_set_rtc().
| uint8_t ch_watchdog_disable | ( | ch_dev_t * | dev_ptr | ) |
Disable watchdog timer in sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function disables the watchdog timer function in the sensor.
See also ch_watchdog_enable().
| uint8_t ch_watchdog_enable | ( | ch_dev_t * | dev_ptr | ) |
Enable watchdog timer in sensor.
| dev_ptr | pointer to the ch_dev_t descriptor structure |
This function enables the watchdog timer function in the sensor. When the watchdog timer is enabled, the sensor must complete a measurement within approximately one second or the timer will expire. The timer is reset every time a measurement completes.
If the watchdog timer expires, the sensor will generate an interrupt and will specify CH_INTERRUPT_TYPE_WATCHDOG as the interrupt type. This interrupt type is passed as a parameter to the application's sensor interrupt callback routine that was registered using ch_io_int_callback_set(). That callback routine should examine the interrupt type and take appropriate action if a watchdog timeout occurred.
See also ch_watchdog_disable().
1.9.1