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

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_tch_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...
 

Detailed Description

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.

Note
All operation of the sensor is controlled through the set of functions, data structures, and symbolic values defined in this header file. You should not need to modify this file or the SonicLib functions, or use lower-level internal functions such as described in the ch_driver.h file. Using any of these non-public methods will reduce your ability to benefit from future enhancements and releases from Chirp.

Board Support Package

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.

Basic Operating Sequence

At a high level, an application using SonicLib will do the following:

  1. Initialize the hardware on the board, by calling the BSP's chbsp_board_init() function.
  2. Initialize the SonicLib data structures, by calling ch_init() for each sensor.
  3. Program and start the sensor(s), by calling ch_group_start().
  4. Set up a handler function to process interrupts from the sensor.
  5. Set up a triggering mechanism using a board timer, using chbsp_periodic_timer_init() etc., (unless the sensor will be used in free-running mode, in which no external trigger is needed). A timer handler routine will typically trigger the sensor(s) using ch_group_trigger().
  6. Configure the sensor's operating mode and range, using ch_set_config() (or equivalent single-setting functions).

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.

Macro Definition Documentation

◆ CH101_MAX_NUM_SAMPLES

#define CH101_MAX_NUM_SAMPLES   (150)

Max expected samples per measurement for CH101.

◆ CH101_PART_NUMBER

#define CH101_PART_NUMBER   (101)

Integer sensor identifier for CH101.

◆ CH201_MAX_NUM_SAMPLES

#define CH201_MAX_NUM_SAMPLES   (450)

Max expected samples per measurement for CH201.

◆ CH201_PART_NUMBER

#define CH201_PART_NUMBER   (201)

Integer sensor identifier for CH201.

◆ CH_I2C_ADDR_PROG

#define CH_I2C_ADDR_PROG   (0x45)

I2C address of sensor programming interface.

◆ CH_MIN_RANGE_VAL

#define CH_MIN_RANGE_VAL   (0x0001)

Minimum range value returned for very short distances

◆ CH_NO_TARGET

#define CH_NO_TARGET   (0xFFFFFFFF)

Range value returned if no target was detected.

◆ CH_NUM_THRESHOLDS

#define CH_NUM_THRESHOLDS   (6)

Number of internal detection thresholds (CH201 only).

◆ CH_SIG_BYTE_0

#define CH_SIG_BYTE_0   (0x0a)

Signature byte in sensor (1 of 2).

◆ CH_SIG_BYTE_1

#define CH_SIG_BYTE_1   (0x02)

Signature byte in sensor (2 of 2).

◆ CH_SPEEDOFSOUND_MPS

#define CH_SPEEDOFSOUND_MPS   (343)

Speed of sound, in meters per second.

◆ I2C_DRV_FLAG_RESET_AFTER_NB

#define I2C_DRV_FLAG_RESET_AFTER_NB   (0x00000001)

I2C interface needs reset after non-blocking transfer.

◆ I2C_DRV_FLAG_USE_PROG_NB

#define I2C_DRV_FLAG_USE_PROG_NB   (0x00000002)

Use programming interface for non-blocking transfer.

◆ SONICLIB_VER_MAJOR

#define SONICLIB_VER_MAJOR   (2)

SonicLib major version.

◆ SONICLIB_VER_MINOR

#define SONICLIB_VER_MINOR   (1)

SonicLib minor version.

◆ SONICLIB_VER_REV

#define SONICLIB_VER_REV   (0)

SonicLib revision.

Enumeration Type Documentation

◆ ch_io_mode_t

I/O blocking mode flags.

Enumerator
CH_IO_MODE_BLOCK 

Blocking mode.

CH_IO_MODE_NONBLOCK 

Non-blocking mode.

◆ ch_mode_t

enum ch_mode_t

Sensor operating modes.

Enumerator
CH_MODE_IDLE 

Idle mode - low-power sleep, no sensing is enabled.

CH_MODE_FREERUN 

Free-running mode - sensor uses internal clock to wake and measure.

CH_MODE_TRIGGERED_TX_RX 

Triggered transmit/receive mode - transmits and receives when INT line triggered.

CH_MODE_TRIGGERED_RX_ONLY 

Triggered receive-only mode - for pitch-catch operation with another sensor.

◆ ch_range_t

enum ch_range_t

Range data types.

Enumerator
CH_RANGE_ECHO_ONE_WAY 

One way - gets full pulse/echo distance & divides by 2.

CH_RANGE_ECHO_ROUND_TRIP 

Round trip - full pulse/echo distance.

CH_RANGE_DIRECT 

Direct - for receiving node in pitch-catch mode.

◆ ch_reset_t

enum ch_reset_t

Sensor reset types.

Enumerator
CH_RESET_HARD 

Hard reset.

CH_RESET_SOFT 

Soft reset.

Function Documentation

◆ ch_get_amplitude()

uint16_t ch_get_amplitude ( ch_dev_t dev_ptr)

Get the measured amplitude from a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
Amplitude value for most recent successful range reading

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().

◆ ch_get_amplitude_avg()

uint16_t ch_get_amplitude_avg ( ch_dev_t dev_ptr)

Get the averaged measured amplitude over the sample window.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
Average amplitude value for samples in current sample window

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.

Note
Sample window averaging is only available when using special sensor firmware packages from Chirp. It is generally not available in General Purpose Rangefinding (GPR) firmware.

◆ ch_get_amplitude_data()

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.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
buf_ptrpointer to data buffer where amplitude data will be written
start_samplestarting sample number within measurement data (0 = start of data)
num_samplesnumber of samples to read from sensor
modewhether read should block (CH_IO_MODE_BLOCK (0) = blocking, CH_IO_MODE_NONBLOCK (1) = non-blocking)
Returns
0 if successful, 1 if error

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 read all valid amplitude data, set start_sample to zero (0), and set num_samples to the value returned by 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().

Note
Non-blocking amplitude reads are only supported when using certain Chirp sensor firmware types which support direct readout of the amplitude data. Other firmware types read I/Q data and calculate the amplitudes as part of this function, and will require use of blocking mode (CH_IO_MODE_BLOCK). If non-blocking mode is specified when using sensor f/w that does not support it, this function will return an error.

Non-blocking reads are managed together for a group of sensors. To perform a non-blocking read:

  1. Register a callback function using ch_io_complete_callback_set().
  2. Define and initialize a handler for the DMA interrupts generated.
  3. Synchronize with all sensors whose amplitude data should be read by waiting for all to indicate data ready.
  4. Set up a non-blocking read on each sensor, using ch_get_amplitude_data() with mode = CH_IO_MODE_NONBLOCK (1).
  5. Start the non-blocking reads on all sensors in the group, using ch_io_start_nb().
  6. Your callback function (set in step #1 above) will be called as each individual sensor's read completes. Your callback function should initiate any further processing of the I/Q data, possibly by setting a flag that will be checked from within the application's main execution loop. The callback function will likely be called at interrupt level, so the amount of processing within it should be kept to a minimum.

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).

Note
It is important that any data I/O operations to or from the sensor, including reading the amplitude data, complete before a new measurement cycle is triggered, or the new measurement may be affected.
This function only obtains the data from the most recently completed measurement cycle. It does not actually trigger a measurement.

◆ ch_get_bandwidth()

uint16_t ch_get_bandwidth ( ch_dev_t dev_ptr)

Get the bandwidth of a sensor.

Parameters
dev_ptrpointer 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.

Returns
Sensor bandwidth, in Hz, or 0 if error or bandwidth measurement is not available
Note
The bandwidth measurement is only available when using special sensor firmware packages from Chirp. It is generally not available in General Purpose Rangefinding (GPR) firmware.

◆ ch_get_config()

uint8_t ch_get_config ( ch_dev_t dev_ptr,
ch_config_t config_ptr 
)

Get current configuration settings for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
config_ptrpointer to a ch_config_t structure to receive configuration values
Returns
0 if successful, 1 if error

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.

Note
The individual configuration values returned in the ch_config_t structure may also be obtained by using dedicated single-value functions. See ch_get_mode(), ch_get_max_range(), ch_get_sample_interval(), ch_get_static_range(), and ch_get_thresholds().

◆ ch_get_dev_num()

uint8_t ch_get_dev_num ( ch_dev_t dev_ptr)

Get device number (I/O index values) for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
Device number

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_get_dev_ptr()

ch_dev_t* ch_get_dev_ptr ( ch_group_t grp_ptr,
uint8_t  dev_num 
)

Get device descriptor pointer for a sensor.

Parameters
grp_ptrpointer to the ch_group_t descriptor for this group of sensors
dev_numdevice number within sensor group
Returns
Pointer to ch_dev_t descriptor structure

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.

◆ ch_get_frequency()

uint32_t ch_get_frequency ( ch_dev_t dev_ptr)

Get the operating frequency of a sensor.

Parameters
dev_ptrpointer 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.

Returns
Frequency, in Hz

◆ ch_get_fw_version_string()

const char* ch_get_fw_version_string ( ch_dev_t dev_ptr)

Get the firmware version description string for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
Pointer to character string describing sensor firmware version

This function returns a pointer to a string that describes the sensor firmware being used on the device.

◆ ch_get_i2c_address()

uint8_t ch_get_i2c_address ( ch_dev_t dev_ptr)

Get the active I2C address for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
I2C address, or 0 if error

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.

◆ ch_get_i2c_bus()

uint8_t ch_get_i2c_bus ( ch_dev_t dev_ptr)

Get the active I2C bus for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
I2C bus index

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.

◆ ch_get_iq_data()

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.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
buf_ptrpointer to data buffer where I/Q data will be written
start_samplestarting sample number within measurement data (0 = start of data)
num_samplesnumber of samples to read from sensor
modewhether I/Q read should block (CH_IO_MODE_BLOCK (0) = blocking, CH_IO_MODE_NONBLOCK (1) = non-blocking)
Returns
0 if successful, 1 if error

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 read all valid I/Q data, set start_sample to zero (0), and set num_samples to the value returned by 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:

  1. Register a callback function using ch_io_complete_callback_set().
  2. Define and initialize a handler for the DMA interrupts generated.
  3. Synchronize with all sensors whose I/Q data should be read by waiting for all to indicate data ready.
  4. Set up a non-blocking read on each sensor, using ch_get_iq_data() with mode = CH_IO_MODE_NONBLOCK (1).
  5. Start the non-blocking reads on all sensors in the group, using ch_io_start_nb().
  6. Your callback function (set in step #1 above) will be called as each individual sensor's read completes. Your callback function should initiate any further processing of the I/Q data, possibly by setting a flag that will be checked from within the application's main execution loop. The callback function will likely be called at interrupt level, so the amount of processing within it should be kept to a minimum.

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).

Note
It is important that any data I/O operations to or from the sensor, including reading the I/Q data, complete before a new measurement cycle is triggered, or the new measurement may be affected.
This function only obtains the data from the most recently completed measurement cycle. It does not actually trigger a measurement.

◆ ch_get_max_range()

uint16_t ch_get_max_range ( ch_dev_t dev_ptr)

Get the maximum range setting for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
Maximum range setting, in millimeters

This function returns the current maximum detection range setting for the sensor, in millimeters.

Note
The maximum range may also be obtained, along with other settings, using the ch_get_config() function.

◆ ch_get_max_samples()

uint16_t ch_get_max_samples ( ch_dev_t dev_ptr)

Get the maximum possible sample count per measurement.

Parameters
dev_ptrpointer to the ch_dev_t descriptor struct
Returns
Maximum sample count for this device and firmware

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().

◆ ch_get_mode()

ch_mode_t ch_get_mode ( ch_dev_t dev_ptr)

Get the current operating mode for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t config structure
Returns
Sensor operating mode

This function returns the current operating mode for the sensor, one of:

  • CH_MODE_IDLE - low power idle mode, no measurements take place
  • CH_MODE_FREERUN - free-running mode, sensor uses internal clock to wake and measure
  • CH_MODE_TRIGGERED_TX_RX - hardware-triggered, sensor both transmits and receives
  • CH_MODE_TRIGGERED_RX_ONLY - hardware triggered, sensor only receives

◆ ch_get_num_ports()

uint8_t ch_get_num_ports ( ch_group_t grp_ptr)

Get the total number of sensor ports (possible sensors) in a sensor group.

Parameters
grp_ptrpointer to the ch_group_t descriptor for this group of sensors
Returns
Total number of ports (possible sensors) in the sensor group

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.

◆ ch_get_num_samples()

uint16_t ch_get_num_samples ( ch_dev_t dev_ptr)

Get the number of samples per measurement cycle.

Parameters
dev_ptrpointer to the ch_dev_t descriptor struct
Returns
Number of samples per measurement cycle

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().

◆ ch_get_part_number()

uint16_t ch_get_part_number ( ch_dev_t dev_ptr)

Get part number for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
Integer part number

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.

◆ ch_get_range()

uint32_t ch_get_range ( ch_dev_t dev_ptr,
ch_range_t  range_type 
)

Get the measured range from a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
range_typethe range type to be reported (e.g. one-way vs. round-trip)
Returns
Range in millimeters times 32, or CH_NO_TARGET (0xFFFFFFFF) if no target was detected, or 0 if error

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:

  • CH_RANGE_ECHO_ONE_WAY - gets full pulse/echo round-trip distance, then divides by 2
  • CH_RANGE_ECHO_ROUND_TRIP - full pulse/echo round-trip distance
  • CH_RANGE_DIRECT - for receiving sensor in pitch-catch mode (one-way)

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.

Note
This function only reports the results from the most recently completed measurement cycle. It does not actually trigger a measurement.
The range_type parameter only controls how this function interprets the results from the measurement cycle. It does not change the sensor mode.

◆ ch_get_rtc_cal_pulselength()

uint16_t ch_get_rtc_cal_pulselength ( ch_dev_t dev_ptr)

Get the real-time clock calibration pulse length.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
RTC pulse length, in ms

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.

◆ ch_get_rtc_cal_result()

uint16_t ch_get_rtc_cal_result ( ch_dev_t dev_ptr)

Get the real-time clock calibration value.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
RTC calibration value

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.

◆ ch_get_rx_holdoff()

uint16_t ch_get_rx_holdoff ( ch_dev_t dev_ptr)

Get the receive holdoff sample count.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
the number of samples that are ignored at the beginning of each measurement

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().

◆ ch_get_rx_pulse_length()

uint8_t ch_get_rx_pulse_length ( ch_dev_t dev_ptr)

Get the detected length of the received pulse.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
pulse length

This function gets the detected length of the received pulse

Note
This config is only available in select Chirp sensor firmware versions.

◆ ch_get_sample_interval()

uint16_t ch_get_sample_interval ( ch_dev_t dev_ptr)

Get the internal sample timing interval for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
Interval between samples (in ms), or 0 if device is not in free-running mode

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.

◆ ch_get_sample_window()

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.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
start_sample_ptrpointer to variable to be updated with sample number of first sample
num_samples_ptrpointer to variable to be updated with number of samples
Returns
0 if successful, non-zero if error

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().

Note
Internal sample window averaging is available when using special sensor firmware packages from Chirp. In General Purpose Rangefinding (GPR) firmware, a software only implementation is used.

◆ ch_get_scale_factor()

uint16_t ch_get_scale_factor ( ch_dev_t dev_ptr)

Get the calibration scale factor of a sensor.

Parameters
dev_ptrpointer 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.

Returns
Scale factor value, or 0 if error or not available
Note
The scale factor value is only available when using special sensor firmware packages from Chirp. It is generally not available in General Purpose Rangefinding (GPR) firmware.

◆ ch_get_static_coeff()

uint8_t ch_get_static_coeff ( ch_dev_t dev_ptr)

Get the static coefficient for IIR filter.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
static coefficient

This function gets the static coefficient for IIR filter.

Note
This config is only available in select Chirp sensor firmware versions.

◆ ch_get_static_range()

uint16_t ch_get_static_range ( ch_dev_t dev_ptr)

Get static target rejection range setting.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
Static target rejection range setting, in samples, or 0 if not enabled

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.

◆ ch_get_target_interrupt()

uint8_t ch_get_target_interrupt ( ch_dev_t dev_ptr)

Get the target detection interrupt mode setting.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
1 if target detection interrupt mode is enabled, 0 if disabled

This function returns the value of target detection interrupt mode setting.

Note
Target detection interrupt mode is only available in select Chirp sensor firmware versions.

◆ ch_get_threshold()

uint16_t ch_get_threshold ( ch_dev_t dev_ptr,
uint8_t  threshold_index 
)

Get the detection threshold.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
threshold_indexindex to the thresholds, starts from 0
Returns
amplitude threshold value

This function obtains the detection threshold value of a given index from the sensor and returns it in amplitude .

Note
This function is supported in CH201 and CH101 GPPC firmwares

◆ ch_get_thresholds()

uint8_t ch_get_thresholds ( ch_dev_t dev_ptr,
ch_thresholds_t thresh_ptr 
)

Get detection thresholds (CH201 only).

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
thresh_ptrpointer to ch_thresholds_t structure to receive threshold data
Returns
0 if success, 1 if error

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.

Note
This function is not supported on CH101 devices.

◆ ch_get_time_plan()

ch_time_plan_t ch_get_time_plan ( ch_dev_t dev_ptr)

Read sonicsync timing plan.

Parameters
dev_ptra 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).

Returns
time plan value currently in use

◆ ch_get_tof_tick()

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.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
timer_freqthe HW frequency of the ultrasound periodic timer
Returns
Time-of-flight in tick, or 0 if error

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.

Note
This function only reports the results from the most recently completed measurement cycle. It does not actually trigger a measurement.

◆ ch_get_tx_length()

uint8_t ch_get_tx_length ( ch_dev_t dev_ptr)

Get the TX length.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
TX length

This function gets the TX length

Note
This config is only available in select Chirp sensor firmware versions.

◆ ch_group_reset()

void ch_group_reset ( ch_group_t grp_ptr,
ch_reset_t  reset_type 
)

Reset a group of sensors.

Parameters
grp_ptrpointer to the ch_group_t descriptor for this group of sensors
reset_typetype 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.

◆ ch_group_start()

uint8_t ch_group_start ( ch_group_t grp_ptr)

Program and start a group of sensors.

Parameters
grp_ptrpointer to the ch_group_t descriptor for sensor group to be started
Returns
0 if successful, 1 if error

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:

  • Probe the possible sensor ports using I2C bus and each sensor's PROG line, to discover if sensor is connected.
  • Reset sensor.
  • Program sensor with firmware (version specified during ch_init()).
  • Assign unique I2C address to sensor (specified by board support package, see chbsp_i2c_get_info()).
  • Start sensor execution.
  • Wait for sensor to lock (complete initialization, including self-test).
  • Send timed pulse on INT line to calibrate sensor Real-Time Clock (RTC).

After this routine returns successfully, the sensor configuration may be set and ultrasonic measurements may begin.

◆ ch_group_trigger()

void ch_group_trigger ( ch_group_t grp_ptr)

Trigger a measurement on a group of sensors.

Parameters
grp_ptrpointer 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().

Note
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.

◆ ch_init()

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.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
grp_ptrpointer to the ch_group_t descriptor for sensor group to join
dev_numnumber of the device within the sensor group (identifies which physical sensor)
fw_init_funcpointer to the sensor firmware initialization function (determines sensor feature set)
Returns
0 if success, 1 if error

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.

Note
This function only performs internal initialization of data structures, etc. It does not actually initialize the physical sensor device(s). See ch_group_start().

◆ ch_io_complete_callback_set()

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.

Parameters
grp_ptrpointer to the ch_group_t group descriptor structure
callback_func_ptrpointer 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().

◆ ch_io_int_callback_set()

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.

Parameters
grp_ptrpointer to the ch_group_t sensor group descriptor structure
callback_func_ptrpointer 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.

◆ ch_io_notify()

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.

Parameters
grp_ptrpointer to the ch_group_t sensor group descriptor structure
i2c_bus_indexidentifier 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().

◆ ch_io_start_nb()

uint8_t ch_io_start_nb ( ch_group_t grp_ptr)

Start non-blocking I/O operation(s) for a group of sensors.

Parameters
grp_ptrpointer to the ch_group_t descriptor for sensor group
Returns
0 if success, 1 if error

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.

◆ ch_iq_to_amplitude()

uint16_t ch_iq_to_amplitude ( ch_iq_sample_t iq_sample_ptr)

Calculate amplitude from sample I/Q values.

Parameters
iq_sample_ptrpointer to ch_iq_data_t structure containing the I/Q data
Returns
Amplitude value

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().

◆ ch_mm_to_samples()

uint16_t ch_mm_to_samples ( ch_dev_t dev_ptr,
uint16_t  num_mm 
)

Convert millimeters to sample count for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
num_mmnumber of millimeters to be converted
Returns
Number of samples

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()).

◆ ch_reset()

void ch_reset ( ch_dev_t dev_ptr,
ch_reset_t  reset_type 
)

Reset a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
reset_typetype 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.

◆ ch_samples_to_mm()

uint16_t ch_samples_to_mm ( ch_dev_t dev_ptr,
uint16_t  num_samples 
)

Convert sample count to millimeters for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
num_samplessample count to be converted
Returns
Number of millimeters

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()).

◆ ch_sensor_is_connected()

uint8_t ch_sensor_is_connected ( ch_dev_t dev_ptr)

Indicate if a sensor is connected.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
Returns
1 if the sensor is connected, 0 otherwise

◆ ch_set_config()

uint8_t ch_set_config ( ch_dev_t dev_ptr,
ch_config_t config_ptr 
)

Set multiple configuration settings for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
config_ptrpointer to a ch_config_t structure containing new configuration values
Returns
0 if successful, 1 if error

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.

Note
The individual configuration values set by this function may also be set using dedicated single-value functions. These two methods are completely equivalent and may be freely mixed.
See ch_set_mode(), ch_set_max_range(), ch_set_sample_interval(), ch_set_static_range(), and ch_set_thresholds().

◆ ch_set_frequency()

uint8_t ch_set_frequency ( ch_dev_t dev_ptr,
uint32_t  target_freq_Hz 
)

Set the operating frequency of a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
target_freq_Hzto the target frequency in Hz
Returns
0 if success, 1 if error

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.

◆ ch_set_max_range()

uint8_t ch_set_max_range ( ch_dev_t dev_ptr,
uint16_t  max_range 
)

Set the maximum range for a sensor.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
max_rangemaximum range, in millimeters
Returns
0 if successful, non-zero if error

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.)

Note
The maximum range may also be specified, along with other settings, using the ch_set_config() function. These two methods are completely equivalent and may be freely mixed.

◆ ch_set_mode()

uint8_t ch_set_mode ( ch_dev_t dev_ptr,
ch_mode_t  mode 
)

Configure a sensor for the specified operating mode.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
modethe new operating mode for the sensor
Returns
0 if successful.

This function sets the sensor to operate in the specified mode, which must be one of the following:

  • CH_MODE_IDLE - low power idle mode, no measurements take place
  • CH_MODE_FREERUN - free-running mode, sensor uses internal clock to wake and measure
  • CH_MODE_TRIGGERED_TX_RX - hardware-triggered, sensor both transmits and receives
  • CH_MODE_TRIGGERED_RX_ONLY - hardware triggered, sensor only receives

◆ ch_set_num_samples()

uint8_t ch_set_num_samples ( ch_dev_t dev_ptr,
uint16_t  num_samples 
)

Set the sensor sample count directly.

Parameters
dev_ptrpointer to the ch_dev_t descriptor struct
num_samplesnumber of samples during each measurement cycle
Returns
0 if successful

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().

Note
Normally, the sample is count is not set using this function, but is instead set indirectly using either ch_set_max_range() or ch_set_config(), both of which automatically set the sample count based on a specified range in millimeters.

◆ ch_set_rx_holdoff()

uint8_t ch_set_rx_holdoff ( ch_dev_t dev_ptr,
uint16_t  num_samples 
)

Set the receive holdoff sample count.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
num_samplesthe number of samples to be ignored at the beginning of each measurement
Returns
0 if success, 1 if error

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().

◆ ch_set_rx_pretrigger()

void ch_set_rx_pretrigger ( ch_group_t grp_ptr,
uint8_t  enable 
)

Enable/disable receive-only sensor pre-triggering.

Parameters
grp_ptrpointer to the ch_group_t group descriptor structure
enable1 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.

Note
Enabling pre-triggering will reduce the maximum range of the receive-only sensor(s), relative to the setting specified in ch_set_max_range(), by about 200mm. You may want to increase the maximum range setting accordingly.

◆ ch_set_sample_interval()

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.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
interval_msinterval between samples, in milliseconds.
Returns
0 if successful, 1 if arguments are invalid.

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.

Note
This function has no effect for a sensor operating in one of the triggered modes. The sample interval for a triggered device is determined by the external trigger timing.

◆ ch_set_sample_window()

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.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
start_samplesample number of first sample in window
num_samplesnumber of samples to include in window
Returns
0 if successful, non-zero if error

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().

Note
Internal sample window averaging is available when using special sensor firmware packages from Chirp. In General Purpose Rangefinding (GPR) firmware, a software only implementation is used.

◆ ch_set_static_coeff()

uint8_t ch_set_static_coeff ( ch_dev_t dev_ptr,
uint8_t  static_coeff 
)

Set the static coefficient for IIR filter.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
static_coeffthe static coefficient for IIR filter
Returns
0 if success, 1 if error

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.

Note
This config is only available in select Chirp sensor firmware versions.

◆ ch_set_static_range()

uint8_t ch_set_static_range ( ch_dev_t dev_ptr,
uint16_t  num_samples 
)

Configure static target rejection.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
num_samplesnumber of sensor samples (at beginning of measurement cycle) over which static targets will be rejected
Returns
0 if successful, non-zero if error

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.

◆ ch_set_target_interrupt()

uint8_t ch_set_target_interrupt ( ch_dev_t dev_ptr,
uint8_t  enable 
)

Set target detection interrupt mode.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
enableenable or disable target interrupt
Returns
0 if success, 1 if error

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.

Note
Target detection interrupt mode is only available in select Chirp sensor firmware versions.

◆ ch_set_threshold()

uint8_t ch_set_threshold ( ch_dev_t dev_ptr,
uint8_t  threshold_index,
uint16_t  amplitude 
)

Set the detection threshold.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
threshold_indexindex to the thresholds, starts from 0
amplitudeamplitude threshold value
Returns
0 if success, 1 if error

This function set the detection threshold value of a given index to the sensor.

Note
This function is supported in CH201 and CH101 GPPC firmwares.

◆ ch_set_thresholds()

uint8_t ch_set_thresholds ( ch_dev_t dev_ptr,
ch_thresholds_t thresh_ptr 
)

Set detection thresholds (CH201 only).

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
thresh_ptrpointer to ch_thresholds_t structure containing threshold data
Returns
0 if success, 1 if error

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.

Note
This function is not supported on CH101 devices.

◆ ch_set_time_plan()

uint8_t ch_set_time_plan ( ch_dev_t dev_ptr,
ch_time_plan_t  time_plan 
)

Configure sonicsync timing plan.

Parameters
dev_ptra pointer to the ch_dev_t descriptor structure
time_plantime 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.

Returns
0 if successful.

◆ ch_set_tx_length()

uint8_t ch_set_tx_length ( ch_dev_t dev_ptr,
uint8_t  tx_length 
)

Set the TX length.

Parameters
dev_ptrpointer to the ch_dev_t descriptor structure
tx_lengththe transmit length
Returns
0 if success, 1 if error

This function sets the length of the pulse to transmit with

Note
This config is only available in select Chirp sensor firmware versions.

◆ ch_trigger()

void ch_trigger ( ch_dev_t dev_ptr)

Trigger a measurement on one sensor.

Parameters
dev_ptrpointer 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().

Note
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.