Chirp SonicLib
2.1.0
|
Chirp SonicLib public API and support functions for Chirp ultrasonic sensors. More...
#include "ch101_gpr_open.h"
#include "ch101_gpr_sr_open.h"
#include "ch101_gppc.h"
#include "ch101_sonicsync.h"
#include "ch201_gprmt.h"
#include "ch201_gpr_str.h"
#include "ch101_floor.h"
#include "ch201_presence.h"
#include "chirp_board_config.h"
#include "ch_driver.h"
#include "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_i2c_info_t |
I2C info structure. More... | |
struct | ch_iq_sample_t |
Sensor I/Q data value. More... | |
struct | ch_thresh_t |
Detection threshold value (CH201 only). More... | |
struct | ch_thresholds_t |
Multiple detection threshold structure (CH201 only). More... | |
struct | ch_config_t |
Combined configuration structure. More... | |
struct | ch_api_funcs_t |
API function pointer structure (internal use). More... | |
struct | ch_group_t |
Chirp sensor group configuration structure. More... | |
struct | ch_dev_t |
Chirp sensor device structure. More... | |
Macros | |
#define | SONICLIB_VER_MAJOR (2) |
#define | SONICLIB_VER_MINOR (1) |
#define | SONICLIB_VER_REV (0) |
#define | CH101_PART_NUMBER (101) |
#define | CH201_PART_NUMBER (201) |
#define | CH101_MAX_NUM_SAMPLES (150) |
#define | CH201_MAX_NUM_SAMPLES (450) |
#define | CH_NO_TARGET (0xFFFFFFFF) |
#define | CH_MIN_RANGE_VAL (0x0001) |
#define | CH_I2C_ADDR_PROG (0x45) |
#define | CH_SIG_BYTE_0 (0x0a) |
#define | CH_SIG_BYTE_1 (0x02) |
#define | CH_NUM_THRESHOLDS (6) |
#define | CH_SPEEDOFSOUND_MPS (343) |
#define | I2C_DRV_FLAG_RESET_AFTER_NB (0x00000001) |
#define | I2C_DRV_FLAG_USE_PROG_NB (0x00000002) |
Typedefs | |
typedef struct ch_dev_t | ch_dev_t |
typedef struct ch_group_t | ch_group_t |
typedef uint8_t(* | ch_fw_init_func_t) (ch_dev_t *dev_ptr, ch_group_t *grp_ptr, uint8_t i2c_addr, uint8_t dev_num, uint8_t i2c_bus_index) |
ASIC firmware init function pointer typedef. | |
typedef uint8_t(* | ch_fw_load_func_t) (ch_dev_t *dev_ptr) |
API function pointer typedefs. | |
typedef uint8_t(* | ch_get_config_func_t) (ch_dev_t *dev_ptr, ch_config_t *config_ptr) |
typedef uint8_t(* | ch_set_config_func_t) (ch_dev_t *dev_ptr, ch_config_t *config_ptr) |
typedef uint8_t(* | ch_set_mode_func_t) (ch_dev_t *dev_ptr, ch_mode_t mode) |
typedef uint8_t(* | ch_set_sample_interval_func_t) (ch_dev_t *dev_ptr, uint16_t sample_interval) |
typedef uint8_t(* | ch_set_num_samples_func_t) (ch_dev_t *dev_ptr, uint16_t num_samples) |
typedef uint8_t(* | ch_set_max_range_func_t) (ch_dev_t *dev_ptr, uint16_t max_range) |
typedef uint8_t(* | ch_set_sample_window_func_t) (ch_dev_t *dev_ptr, uint16_t start_sample, uint16_t end_sample) |
typedef uint32_t(* | ch_get_range_func_t) (ch_dev_t *dev_ptr, ch_range_t range_type) |
typedef uint32_t(* | ch_get_tof_tick_func_t) (ch_dev_t *dev_ptr, uint32_t timer_freq) |
typedef uint16_t(* | ch_get_amplitude_func_t) (ch_dev_t *dev_ptr) |
typedef uint16_t(* | ch_get_amplitude_avg_func_t) (ch_dev_t *dev_ptr) |
typedef uint8_t(* | ch_set_frequency_func_t) (ch_dev_t *dev_ptr, uint32_t target_freq_Hz) |
typedef uint32_t(* | ch_get_frequency_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 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_samples_to_mm_func_t) (ch_dev_t *dev_ptr, uint16_t num_samples) |
typedef uint16_t(* | ch_mm_to_samples_func_t) (ch_dev_t *dev_ptr, uint16_t num_mm) |
typedef uint8_t(* | ch_set_threshold_func_t) (ch_dev_t *dev_ptr, uint8_t threshold_index, uint16_t amplitude) |
typedef uint16_t(* | ch_get_threshold_func_t) (ch_dev_t *dev_ptr, uint8_t threshold_index) |
typedef uint8_t(* | ch_set_thresholds_func_t) (ch_dev_t *dev_ptr, ch_thresholds_t *thresh_ptr) |
typedef uint8_t(* | ch_get_thresholds_func_t) (ch_dev_t *dev_ptr, ch_thresholds_t *thresh_ptr) |
typedef uint8_t(* | ch_set_target_interrupt_func_t) (ch_dev_t *dev_ptr, uint8_t enable) |
typedef uint8_t(* | ch_get_target_interrupt_func_t) (ch_dev_t *dev_ptr) |
typedef uint8_t(* | ch_set_static_range_func_t) (ch_dev_t *dev_ptr, uint16_t static_range) |
typedef uint8_t(* | ch_set_static_coeff_func_t) (ch_dev_t *dev_ptr, uint8_t static_coeff) |
typedef uint8_t(* | ch_get_static_coeff_func_t) (ch_dev_t *dev_ptr) |
typedef uint8_t(* | ch_set_rx_holdoff_func_t) (ch_dev_t *dev_ptr, uint16_t rx_holdoff) |
typedef uint16_t(* | ch_get_rx_holdoff_func_t) (ch_dev_t *dev_ptr) |
typedef uint8_t(* | ch_set_tx_length_func_t) (ch_dev_t *dev_ptr, uint8_t tx_length) |
typedef uint8_t(* | ch_get_tx_length_func_t) (ch_dev_t *dev_ptr) |
typedef uint8_t(* | ch_get_rx_pulse_length_func_t) (ch_dev_t *dev_ptr) |
typedef uint8_t(* | ch_set_time_plan_func_t) (ch_dev_t *dev_ptr, ch_time_plan_t time_plan) |
typedef ch_time_plan_t(* | ch_get_time_plan_func_t) (ch_dev_t *dev_ptr) |
typedef void(* | ch_io_int_callback_t) (ch_group_t *grp_ptr, uint8_t io_index) |
Data-ready interrupt callback routine pointer. | |
typedef void(* | ch_io_complete_callback_t) (ch_group_t *grp_ptr) |
Non-blocking I/O complete callback routine pointer. | |
typedef void(* | ch_timer_callback_t) (void) |
Periodic timer callback routine pointer. | |
Enumerations | |
enum | ch_retval { RET_OK = 0, RET_ERR = 1 } |
Return value codes. | |
enum | ch_range_t { CH_RANGE_ECHO_ONE_WAY = 0, CH_RANGE_ECHO_ROUND_TRIP = 1, CH_RANGE_DIRECT = 2 } |
Range data types. More... | |
enum | ch_mode_t { CH_MODE_IDLE = 0x00, CH_MODE_FREERUN = 0x02, CH_MODE_TRIGGERED_TX_RX = 0x10, CH_MODE_TRIGGERED_RX_ONLY = 0x20 } |
Sensor operating modes. More... | |
enum | ch_reset_t { CH_RESET_HARD = 0, CH_RESET_SOFT = 1 } |
Sensor reset types. More... | |
enum | ch_io_mode_t { CH_IO_MODE_BLOCK = 0, CH_IO_MODE_NONBLOCK = 1 } |
I/O blocking mode flags. More... | |
enum | ch_time_plan_t { CH_TIME_PLAN_1 = 0, CH_TIME_PLAN_2 = 1, CH_TIME_PLAN_3 = 2, CH_TIME_PLAN_NONE = 255 } |
Time plan. | |
Functions | |
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_group_start (ch_group_t *grp_ptr) |
Program and start a group of sensors. More... | |
uint8_t | ch_get_config (ch_dev_t *dev_ptr, ch_config_t *config_ptr) |
Get current configuration settings for a sensor. More... | |
uint8_t | ch_set_config (ch_dev_t *dev_ptr, ch_config_t *config_ptr) |
Set multiple configuration settings for a sensor. More... | |
void | ch_trigger (ch_dev_t *dev_ptr) |
Trigger a measurement on one sensor. More... | |
void | ch_group_trigger (ch_group_t *grp_ptr) |
Trigger a measurement on a group of sensors. More... | |
void | ch_reset (ch_dev_t *dev_ptr, ch_reset_t reset_type) |
Reset a sensor. More... | |
void | ch_group_reset (ch_group_t *grp_ptr, ch_reset_t reset_type) |
Reset a group of sensors. More... | |
uint8_t | ch_sensor_is_connected (ch_dev_t *dev_ptr) |
Indicate if a sensor is connected. More... | |
uint16_t | ch_get_part_number (ch_dev_t *dev_ptr) |
Get part number for a sensor. 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... | |
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... | |
uint8_t | ch_get_i2c_address (ch_dev_t *dev_ptr) |
Get the active I2C address for a sensor. More... | |
uint8_t | ch_get_i2c_bus (ch_dev_t *dev_ptr) |
Get the active I2C bus for 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... | |
ch_mode_t | ch_get_mode (ch_dev_t *dev_ptr) |
Get the current operating mode 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... | |
uint16_t | ch_get_sample_interval (ch_dev_t *dev_ptr) |
Get the internal sample timing interval for a sensor. More... | |
uint8_t | ch_set_sample_interval (ch_dev_t *dev_ptr, uint16_t interval_ms) |
Configure the internal sample interval for a sensor in freerunning mode. More... | |
uint16_t | ch_get_num_samples (ch_dev_t *dev_ptr) |
Get the number of samples per measurement cycle. More... | |
uint8_t | ch_set_num_samples (ch_dev_t *dev_ptr, uint16_t num_samples) |
Set the sensor sample count directly. More... | |
uint16_t | ch_get_max_samples (ch_dev_t *dev_ptr) |
Get the maximum possible sample count per measurement. More... | |
uint16_t | ch_get_max_range (ch_dev_t *dev_ptr) |
Get the maximum range setting for a sensor. 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_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... | |
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... | |
uint16_t | ch_get_static_range (ch_dev_t *dev_ptr) |
Get static target rejection range setting. More... | |
uint8_t | ch_set_static_range (ch_dev_t *dev_ptr, uint16_t num_samples) |
Configure static target rejection. More... | |
uint32_t | ch_get_range (ch_dev_t *dev_ptr, ch_range_t range_type) |
Get the measured range from a sensor. More... | |
uint32_t | ch_get_tof_tick (ch_dev_t *dev_ptr, uint32_t timer_freq) |
Get the measured Time-of-flight from a sensor in the ultrasound periodic timer tick. 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... | |
uint16_t | ch_get_bandwidth (ch_dev_t *dev_ptr) |
Get the bandwidth of a sensor. More... | |
uint8_t | ch_set_frequency (ch_dev_t *dev_ptr, uint32_t target_freq_Hz) |
Set the operating frequency of a sensor. More... | |
uint32_t | ch_get_frequency (ch_dev_t *dev_ptr) |
Get the operating frequency of a sensor. 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_cal_pulselength (ch_dev_t *dev_ptr) |
Get the real-time clock calibration pulse length. More... | |
uint16_t | ch_get_scale_factor (ch_dev_t *dev_ptr) |
Get the calibration scale factor of a sensor. 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... | |
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_samples_to_mm (ch_dev_t *dev_ptr, uint16_t num_samples) |
Convert sample count to millimeters for a sensor. 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... | |
uint16_t | ch_iq_to_amplitude (ch_iq_sample_t *iq_sample_ptr) |
Calculate amplitude from sample I/Q values. 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... | |
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_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_notify (ch_group_t *grp_ptr, uint8_t i2c_bus_index) |
Notify SonicLib that a non-blocking I/O operation has completed. More... | |
uint16_t | ch_get_threshold (ch_dev_t *dev_ptr, uint8_t threshold_index) |
Get the detection threshold. More... | |
uint8_t | ch_set_threshold (ch_dev_t *dev_ptr, uint8_t threshold_index, uint16_t amplitude) |
Set the detection threshold. More... | |
uint8_t | ch_get_thresholds (ch_dev_t *dev_ptr, ch_thresholds_t *thresh_ptr) |
Get detection thresholds (CH201 only). More... | |
uint8_t | ch_set_thresholds (ch_dev_t *dev_ptr, ch_thresholds_t *thresh_ptr) |
Set detection thresholds (CH201 only). More... | |
uint8_t | ch_set_target_interrupt (ch_dev_t *dev_ptr, uint8_t enable) |
Set target detection interrupt mode. More... | |
uint8_t | ch_get_target_interrupt (ch_dev_t *dev_ptr) |
Get the target detection interrupt mode setting. More... | |
uint8_t | ch_set_static_coeff (ch_dev_t *dev_ptr, uint8_t static_coeff) |
Set the static coefficient for IIR filter. More... | |
uint8_t | ch_get_static_coeff (ch_dev_t *dev_ptr) |
Get the static coefficient for IIR filter. More... | |
uint8_t | ch_set_rx_holdoff (ch_dev_t *dev_ptr, uint16_t num_samples) |
Set the receive holdoff sample count. More... | |
uint16_t | ch_get_rx_holdoff (ch_dev_t *dev_ptr) |
Get the receive holdoff sample count. More... | |
uint8_t | ch_set_tx_length (ch_dev_t *dev_ptr, uint8_t tx_length) |
Set the TX length. More... | |
uint8_t | ch_get_tx_length (ch_dev_t *dev_ptr) |
Get the TX length. More... | |
uint8_t | ch_get_rx_pulse_length (ch_dev_t *dev_ptr) |
Get the detected length of the received pulse. More... | |
uint8_t | ch_set_time_plan (ch_dev_t *dev_ptr, ch_time_plan_t time_plan) |
Configure sonicsync timing plan. More... | |
ch_time_plan_t | ch_get_time_plan (ch_dev_t *dev_ptr) |
Read sonicsync timing plan. More... | |
void | ch_set_rx_pretrigger (ch_group_t *grp_ptr, uint8_t enable) |
Enable/disable receive-only sensor pre-triggering. More... | |
Chirp SonicLib public API and support functions for Chirp ultrasonic sensors.
Chirp SonicLib is a set of API functions and sensor driver routines designed to easily control Chirp ultrasonic sensors from an embedded C application. It allows an application developer to obtain ultrasonic range 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 Chirp sensors in various situations. This is especially important, because all Chirp sensors are completely programmable, including the register map. The SonicLib interfaces allow an application to use new Chirp sensor firmware images, without requiring code changes. Only a single initialization parameter must be modified to use the new sensor firmware.
SonicLib also defines a set of board support package (BSP) functions that must be provided by the developer, board vendor, or Chirp. 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.
The BSP also provides the required chirp_board_config.h header file, which contains definitions of how many (possible) sensors and I2C buses are present on the board. These values are used for static array allocations in SonicLib.
At a high level, an application using SonicLib will do the following:
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.
#define CH101_MAX_NUM_SAMPLES (150) |
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_I2C_ADDR_PROG (0x45) |
I2C address of sensor programming interface.
#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_NUM_THRESHOLDS (6) |
Number of internal detection thresholds (CH201 only).
#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 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 SONICLIB_VER_MAJOR (2) |
SonicLib major version.
#define SONICLIB_VER_MINOR (1) |
SonicLib minor version.
#define SONICLIB_VER_REV (0) |
SonicLib revision.
enum ch_io_mode_t |
enum ch_mode_t |
Sensor operating modes.
enum ch_range_t |
enum ch_reset_t |
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 flexibilty 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 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_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.
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.
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 operating frequency of the sensor. This is the primary frequency of the ultrasonic pulse that is emitted by the device when transmitting.
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 sensor device. This function may be used by board support package routines to determine the proper I2C address to use for a specified sensor.
uint8_t ch_get_i2c_bus | ( | ch_dev_t * | dev_ptr | ) |
Get the active I2C bus for a sensor.
dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the I2C bus index for a sensor device. This function may be used by board support package routines to determine the proper I2C bus to use for a specified sensor.
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 flexibilty 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 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 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.
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().
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:
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 current number of samples which the Chirp sensor will perform 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. Also see 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 Chirp part number for the specified device. The part number is a simple integer value, for example 101 for a CH101 device.
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 chbsp_board_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_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().
uint8_t ch_get_rx_pulse_length | ( | ch_dev_t * | dev_ptr | ) |
Get the detected length of the received pulse.
dev_ptr | pointer to the ch_dev_t descriptor structure |
This function gets the detected length of the received pulse
uint16_t ch_get_sample_interval | ( | ch_dev_t * | dev_ptr | ) |
Get the internal sample timing interval for a sensor.
dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the interval between measurements, in milliseconds, for 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.
Also see ch_get_amplitude_avg() and ch_set_sample_window().
uint16_t ch_get_scale_factor | ( | ch_dev_t * | dev_ptr | ) |
Get the calibration scale factor of a sensor.
dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the calibration scale factor of the sensor. The scale factor is an internal value generated during the initialization of the device.
uint8_t ch_get_static_coeff | ( | ch_dev_t * | dev_ptr | ) |
Get the static coefficient for IIR filter.
dev_ptr | pointer to the ch_dev_t descriptor structure |
This function gets the static coefficient for IIR filter.
uint16_t ch_get_static_range | ( | ch_dev_t * | dev_ptr | ) |
Get static target rejection range setting.
dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the number of samples at the beginning of a measurement cycle over which static target rejection filtering will be applied. Also see ch_set_static_range().
To calculate the physical distance that corresponds to the number of samples, use the ch_samples_to_mm() function.
uint8_t ch_get_target_interrupt | ( | ch_dev_t * | dev_ptr | ) |
Get the target detection interrupt mode setting.
dev_ptr | pointer to the ch_dev_t descriptor structure |
This function returns the value of target detection interrupt mode setting.
uint16_t ch_get_threshold | ( | ch_dev_t * | dev_ptr, |
uint8_t | threshold_index | ||
) |
Get the detection threshold.
dev_ptr | pointer to the ch_dev_t descriptor structure |
threshold_index | index to the thresholds, starts from 0 |
This function obtains the detection threshold value of a given index from the sensor and returns it in amplitude .
uint8_t ch_get_thresholds | ( | ch_dev_t * | dev_ptr, |
ch_thresholds_t * | thresh_ptr | ||
) |
Get detection thresholds (CH201 only).
dev_ptr | pointer to the ch_dev_t descriptor structure |
thresh_ptr | pointer to ch_thresholds_t structure to receive threshold data |
This function obtains the current detection threshold values from the sensor and returns them in a ch_thresholds_t structure specified by thresh_ptr. The ch_thresholds_t structure holds an array of ch_thresh_t structures, each of which contains a starting sample number and amplitude threshold value.
ch_time_plan_t ch_get_time_plan | ( | ch_dev_t * | dev_ptr | ) |
Read sonicsync timing plan.
dev_ptr | a pointer to the ch_dev_t descriptor structure |
This routine returns the timing plan currently in use for an sonicsync master or slave node. The possible values are: SONICSYNC_TIME_PLAN_1 (0) SONICSYNC_TIME_PLAN_2 (1) SONICSYNC_TIME_PLAN_3 (2) SONICSYNC_TIME_PLAN_NONE (255)
For a master device, this value will always be the value specified in a previous call to ch101_sonicsync_set_time_plan(). If no such call was made, the master device will use the default time plan SONICSYNC_TIME_PLAN_1, and that value will be returned by this routine.
By default, a slave device initially uses SONICSYNC_TIME_PLAN_NONE, which causes the slave to cycle through the various time plans attempting to pair with the master. Until the slave has successfully paired with a master node, this routine will return SONICSYNC_TIME_PLAN_NONE.
Once the slave has successfully discovered and paired with a master, this routine will return the value indicating the time plan. Therefore, this routine may be used a polling mechanism to determine when a slave has successfully paired. Once paired, the time plan value for the slave will not change (unless explicitly set using the ch101_sonicsync_set_time_plan() routine).
uint32_t ch_get_tof_tick | ( | ch_dev_t * | dev_ptr, |
uint32_t | timer_freq | ||
) |
Get the measured Time-of-flight from a sensor in the ultrasound periodic timer tick.
dev_ptr | pointer to the ch_dev_t descriptor structure |
timer_freq | the HW frequency of the ultrasound periodic timer |
This function reads the measurement result registers from the sensor and then computes the timer tick by the given HW frequency of the ultrasound periodic timer.
This function returns the measured timer tick as a 32-bit integer.
If the sensor did not successfully find the range of a target during the most recent measurement, the returned timer tick value will be zero (0). If an error occurs when getting or calculating the range, zero (0) will be returned.
uint8_t ch_get_tx_length | ( | ch_dev_t * | dev_ptr | ) |
Get the TX length.
dev_ptr | pointer to the ch_dev_t descriptor structure |
This function gets the TX length
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_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.
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.
Generally, an application will require only one ch_group_t structure to manage all Chirp sensors. However, 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.
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().
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.
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 |
i2c_bus_index | identifier indicating on which 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 i2c_bus_index parameter should indicate which 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().
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_callback_set() will be called.
See ch_get_iq_data() for more information.
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.
Also see ch_get_iq_data() and ch_get_amplitude_data().
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 in 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, along with the current maximum range setting for the device.
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()).
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.
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()).
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_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_frequency | ( | ch_dev_t * | dev_ptr, |
uint32_t | target_freq_Hz | ||
) |
Set the operating frequency of a sensor.
dev_ptr | pointer to the ch_dev_t descriptor structure |
target_freq_Hz | to the target frequency in Hz |
This function set the target 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_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.)
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.
Also see ch_set_max_range().
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 | the 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. To convert a physical distance into a sample count value to use here, use ch_mm_to_samples().
See also ch_get_rx_holdoff().
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 the 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.
uint8_t ch_set_sample_interval | ( | ch_dev_t * | dev_ptr, |
uint16_t | interval_ms | ||
) |
Configure the internal sample interval for a sensor in freerunning mode.
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.
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.
Also see ch_get_amplitude_avg() and ch_get_sample_window().
uint8_t ch_set_static_coeff | ( | ch_dev_t * | dev_ptr, |
uint8_t | static_coeff | ||
) |
Set the static coefficient for IIR filter.
dev_ptr | pointer to the ch_dev_t descriptor structure |
static_coeff | the static coefficient for IIR filter |
This function sets the static coefficient for IIR filter
If TX length are set lower, you may decrease the static coefficient.
If TX length are set higher, you may increase the static coefficient.
uint8_t ch_set_static_range | ( | ch_dev_t * | dev_ptr, |
uint16_t | num_samples | ||
) |
Configure static target rejection.
dev_ptr | pointer to the ch_dev_t descriptor structure |
num_samples | number of sensor samples (at beginning of measurement cycle) over which static targets will be rejected |
Static target rejection is a special processing mode in which the sensor will actively filter out signals from close, non-moving objects, so that they do not continue to generate range readings. This allows detection and reporting of target objects that are farther away than the static objects. (Normally, the sensor reports the range value for the closest detected object.)
Static target rejection is applied for a specified number of samples, starting at the beginning of a measurement cycle* (i.e. for the closest objects). The num_samples parameter specifies the number of samples that will be filtered. To calculate the appropriate value for num_samples to filter over a certain physical distance, use the ch_mm_to_samples() function.
uint8_t ch_set_target_interrupt | ( | ch_dev_t * | dev_ptr, |
uint8_t | enable | ||
) |
Set target detection interrupt mode.
dev_ptr | pointer to the ch_dev_t descriptor structure |
enable | enable or disable target interrupt |
This function enables or disables the target detection interrupt mode.
In normal operation (if target detection interrupt mode is not enabled), the sensor will assert the INT line at the end of a measurement whether or not a target was detected.
When target detection interrupt mode is enabled, the sensor will only assert the INT line at the end of a measurement if a target object was detected. If no target is detected, the sensor will not assert the INT line. There is no indication from the sensor that the measurement has completed.
To use this function, set enable to 1 to enable target detection interrupt mode. Set enable to 0 to disable the target detection interrupt mode.
uint8_t ch_set_threshold | ( | ch_dev_t * | dev_ptr, |
uint8_t | threshold_index, | ||
uint16_t | amplitude | ||
) |
Set the detection threshold.
dev_ptr | pointer to the ch_dev_t descriptor structure |
threshold_index | index to the thresholds, starts from 0 |
amplitude | amplitude threshold value |
This function set the detection threshold value of a given index to the sensor.
uint8_t ch_set_thresholds | ( | ch_dev_t * | dev_ptr, |
ch_thresholds_t * | thresh_ptr | ||
) |
Set detection thresholds (CH201 only).
dev_ptr | pointer to the ch_dev_t descriptor structure |
thresh_ptr | pointer to ch_thresholds_t structure containing threshold data |
This function obtains the current detection threshold values from the sensor and returns them in a ch_thresholds_t structure specified by thresh_ptr. The ch_thresholds_t structure holds an array of ch_thresh_t structures, each of which contains a starting sample number and amplitude threshold value.
To use this function, first initialize the ch_thresh_t sample/level pair of values for each threshold. A CH201 device supports six (6) thresholds. Each threshold has a maximum sample length of 255.
uint8_t ch_set_time_plan | ( | ch_dev_t * | dev_ptr, |
ch_time_plan_t | time_plan | ||
) |
Configure sonicsync timing plan.
dev_ptr | a pointer to the ch_dev_t descriptor structure |
time_plan | time plan identifier |
This routine sets the timing plan for an sonicsync master or slave node. The possible values are: SONICSYNC_TIME_PLAN_1 (0) SONICSYNC_TIME_PLAN_2 (1) SONICSYNC_TIME_PLAN_3 (2) SONICSYNC_TIME_PLAN_NONE (255)
For a master device, this value specifies the timing plan that will be used for the master and slave pair. (The default value of SONICSYNC_TIME_PLAN_1 is used if this routine is not called.) SONICSYNC_TIME_PLAN_NONE should not be specified as the master node time plan.
By default, a slave device initially uses SONICSYNC_TIME_PLAN_NONE, which causes the slave to cycle through the various time plans attempting to pair with the master. (This is the behavior if this routine is not called.) When the slave successfully discovers and pairs with the master, the successful time plan is recorded and then used for all subsequent exchanges, unless it is reset to SONICSYNC_TIME_PLAN_NONE by a call to this routine. Once the slave has successfully paired with a master device, the time plan value may be determined by calling the ch101_sonicsync_get_time_plan() routine.
However, a slave device may be forced to only use a single time plan by calling this routine before the master is discoverd. This may be desirable to speed up the master discovery or to avoid pairing with nearby sensor pairs that use a different time plan.
uint8_t ch_set_tx_length | ( | ch_dev_t * | dev_ptr, |
uint8_t | tx_length | ||
) |
Set the TX length.
dev_ptr | pointer to the ch_dev_t descriptor structure |
tx_length | the transmit length |
This function sets the length of the pulse to transmit with
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().