/*! \file soniclib.h
 *
 * \brief 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 \a 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:
 *  -# Initialize the hardware on the board, by calling the BSP's \a chbsp_board_init() function.
 *  -# Initialize the SonicLib data structures, by calling \a ch_init() for each sensor.
 *  -# Program and start the sensor(s), by calling \a ch_group_start().
 *  -# Set up a handler function to process interrupts from the sensor.
 *  -# Set up a triggering mechanism using a board timer, using \a 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 \a ch_group_trigger().
 *  -# Configure the sensor's operating mode and range, using \a 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 \a ch_get_range()
 * and optionally \a ch_get_amplitude() and/or \a 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 \a ch_get_iq_data() is used).  If any
 * I/O operations are still active, the new measurement may be corrupted.
 */

/*
 Copyright � 2019-2021, Chirp Microsystems.  All rights reserved.

 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL CHIRP MICROSYSTEMS BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 You can contact the authors of this program by email at support@chirpmicro.com
 or by mail at 2560 Ninth Street, Suite 220, Berkeley, CA 94710.
 */

#ifndef __SONICLIB_H_
#define __SONICLIB_H_

/* Preliminary structure type definitions to resolve include order */
typedef struct ch_dev_t ch_dev_t;
typedef struct ch_group_t ch_group_t;


/*==============  Chirp header files for installed sensor firmware packages ===================
 *
 *   If you are installing a new Chirp sensor firmware package, you must add
 *   the name of the firmware include file to the list below.  "GPR" refers
 *   to General Purpose Rangefinding versions.
 */

/* General Purpose Rangefinding (GPR) */
#include "ch101_gpr.h"					/* GPR - CH101 */
#include "ch101_gpr_wd.h"				/* GPR - CH101 (watchdog) */
#include "ch101_gpr_narrow.h"			/* GPR narrow FoV horn - CH101 */
#include "ch101_gpr_narrow_wd.h"		/* GPR narrow FoV horn - CH101 (watchdog) */
#include "ch101_gpr_sr.h"				/* GPR Short-range - CH101 */
#include "ch101_gpr_sr_wd.h"			/* GPR Short-range - CH101 (watchdog) */
#include "ch101_gpr_sr_narrow.h"		/* GPR Short-range, narrow FoV horn - CH101 */
#include "ch101_gpr_sr_narrow_wd.h"		/* GPR Short-range, narrow FoV horn - CH101 (watchdog) */
#include "ch101_gpr_rxopt.h"			/* GPR Receive optimized - CH101 */
#include "ch101_gpr_rxopt_wd.h"			/* GPR Receive optimized - CH101 (watchdog) */
#include "ch101_gpr_rxopt_narrow.h"		/* GPR Receive optimized, narrow FoV horn - CH101 */
#include "ch101_gpr_rxopt_narrow_wd.h"	/* GPR Rx optimized, narrow FoV horn - CH101 (watchdog) */
#include "ch201_gprmt.h"				/* GPR / Multi-Threshold - CH201 */
#include "ch201_gprmt_wd.h"				/* GPR / Multi-Threshold - CH201 (watchdog) */
#include "ch201_gprstr.h"				/* GPR / Stationary Target Rejection - CH201 */
#include "ch201_gprstr_wd.h"			/* GPR / Stationary Target Rejection - CH201 (watchdog) */

/* Special Purpose */
#include "ch101_finaltest.h"			/* Finaltest test firmware - CH101 */
#include "ch101_floor.h"				/* Floor detection - CH101 */
#include "ch101_gppc.h"					/* General Purpose Pitch Catch - CH101 */
#include "ch101_sonicsync.h"			/* SonicSync - CH101 */
#include "ch201_finaltest.h"			/* Finaltest test firmware - CH201 */
#include "ch201_presence.h"				/* Presence detection - CH201 */

#include "ch101_gpr_open.h"			/* GPR "Open" version - CH101 [deprecated] */
#include "ch101_gpr_sr_open.h"		/* GPR Short-range "Open" version - CH101 [deprecated] */

/* ADD NEW HEADER FILES HERE */

/*======================== End of sensor firmware header files ================================*/

//#define CHDRV_DEBUG				// uncomment this line to enable driver debug messages

/* Miscellaneous header files */

#include "chirp_board_config.h"		/* Header from board support package containing h/w params */
#include "ch_driver.h"				/* Internal Chirp driver defines */
#include "ch_math_utils.h"			/* math utility functions */

#include <stdint.h>
#include <stdlib.h>
#include <math.h>
#include <string.h>
#ifdef CHDRV_DEBUG
#include <stdio.h>
#endif

/* SonicLib API/Driver version */
#define	SONICLIB_VER_MAJOR		(2)		/*!< SonicLib major version. */
#define	SONICLIB_VER_MINOR		(1)		/*!< SonicLib minor version. */
#define	SONICLIB_VER_REV		(8)		/*!< SonicLib revision. */

/* Chirp sensor part numbers */
#define	CH101_PART_NUMBER			(101)	/*!< Integer sensor identifier for CH101. */
#define	CH201_PART_NUMBER			(201)	/*!< Integer sensor identifier for CH201. */

/* Max expected number of samples per measurement (actual value depends on sensor f/w used) */
#define CH101_MAX_NUM_SAMPLES		(225)	/*!< Max expected samples per measurement for CH101. */
#define CH201_MAX_NUM_SAMPLES		(450)	/*!< Max expected samples per measurement for CH201. */

/* Misc definitions */
#define CH_NO_TARGET		(0xFFFFFFFF)	/*!< Range value returned if no target was detected. */
#define	CH_MIN_RANGE_VAL	(0x0001)		/*!< Minimum range value returned for very short distances */

#define CH_I2C_ADDR_PROG	(0x45) 			/*!< I2C address of sensor programming interface. */
#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_NUM_THRESHOLDS	(6)				/*!< Number of internal detection thresholds (CH201 only). */
#define CH_SPEEDOFSOUND_MPS (343) 			/*!< Speed of sound, in meters per second. */

//! Return value codes.
typedef enum {
	RET_OK 	  = 0,
	RET_ERR   = 1
} ch_retval;

//! Range data types.
typedef enum {
	CH_RANGE_ECHO_ONE_WAY 		= 0,		/*!< One way - gets full pulse/echo distance & divides by 2. */
	CH_RANGE_ECHO_ROUND_TRIP	= 1,		/*!< Round trip - full pulse/echo distance. */
	CH_RANGE_DIRECT				= 2,		/*!< Direct - for receiving node in pitch-catch mode. */
} ch_range_t;

//! Sensor operating modes.
typedef enum {
	CH_MODE_IDLE 	  			= 0x00,		/*!< Idle mode - low-power sleep, no sensing is enabled. */
	CH_MODE_FREERUN   			= 0x02,		/*!< Free-running mode - sensor uses internal clock to wake 
											     and measure. */
	CH_MODE_TRIGGERED_TX_RX 	= 0x10,		/*!< Triggered transmit/receive mode - transmits and receives 
											     when INT line triggered.*/
	CH_MODE_TRIGGERED_RX_ONLY   = 0x20		/*!< Triggered receive-only mode - for pitch-catch operation 
											     with another sensor. */
} ch_mode_t;

//! Sensor reset types.
typedef enum {
	CH_RESET_HARD     			= 0,		/*!< Hard reset. */
	CH_RESET_SOFT 	  			= 1			/*!< Soft reset. */
} ch_reset_t;

//! I/O blocking mode flags.
typedef enum {
	CH_IO_MODE_BLOCK   			= 0,		/*!< Blocking mode. */
	CH_IO_MODE_NONBLOCK     	= 1			/*!< Non-blocking mode. */
} ch_io_mode_t;

//! Time plan.
typedef enum {
	CH_TIME_PLAN_1    = 0,
	CH_TIME_PLAN_2    = 1,
	CH_TIME_PLAN_3    = 2,
	CH_TIME_PLAN_NONE = 255
} ch_time_plan_t;

//! I2C info structure.
typedef struct {
	uint8_t		address;		/*!< I2C device address */
	uint8_t		bus_num;		/*!< I2C bus index */
	uint16_t	drv_flags;		/*!< flags for special handling by Chirp driver */
} ch_i2c_info_t;

/*!< Flags for special I2C handling by Chirp driver (drv_flags field in ch_info_t struct) */
#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. */


//! Sensor I/Q data value.
typedef struct {
	int16_t q;										/*!< Q component of sample */
	int16_t i;										/*!< I component of sample */
} ch_iq_sample_t;


//! Detection threshold value (CH201 only).
typedef struct {
	uint16_t		start_sample;
	uint16_t		level;
} ch_thresh_t;


//! Multiple detection threshold structure (CH201 only).
typedef struct {
	ch_thresh_t		threshold[CH_NUM_THRESHOLDS];
} ch_thresholds_t;

//! Calibration result structure.
typedef struct {
	uint16_t		dco_period;
	uint16_t		rev_cycles;
} ch_cal_result_t;

//! Combined configuration structure.
typedef struct {
	ch_mode_t		mode;				/*!< operating mode */
	uint16_t		max_range;			/*!< maximum range, in mm */
	uint16_t		static_range;		/*!< static target rejection range, in mm (0 if unused) */
	uint16_t 		sample_interval;	/*!< sample interval, only used if in free-running mode */
	ch_thresholds_t *thresh_ptr;		/*!< ptr to detection thresholds structure (if supported), should be NULL (0) for CH101 */
	ch_time_plan_t  time_plan;          /*!< time plan, should be 0 for CH201 */
	uint8_t         enable_target_int;  /*!< enable(1) or disable(0) target detection interrupt */
} ch_config_t;


//! ASIC firmware init function pointer typedef.
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);

//! API function pointer typedefs.
typedef uint8_t	 (*ch_fw_load_func_t)(ch_dev_t *dev_ptr);
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_us_func_t)(ch_dev_t *dev_ptr);
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_rx_low_gain_func_t)(ch_dev_t *dev_ptr, uint16_t num_samples);
typedef uint16_t (*ch_get_rx_low_gain_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_demodulated_rx_data_func_t)(ch_dev_t *dev_ptr, uint8_t rx_pulse_length, uint8_t *data_ptr);
typedef uint8_t  (*ch_set_modulated_tx_data_func_t)(ch_dev_t *dev_ptr, uint8_t ta_data);
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 uint8_t  (*ch_set_cal_result_func_t)(ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr);
typedef uint8_t  (*ch_get_cal_result_func_t)(ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr);

//! API function pointer structure (internal use).
typedef struct {
	ch_fw_load_func_t				fw_load;
	ch_set_mode_func_t				set_mode;
	ch_set_sample_interval_func_t	set_sample_interval;
	ch_set_num_samples_func_t		set_num_samples;
	ch_set_max_range_func_t			set_max_range;
	ch_set_sample_window_func_t		set_sample_window;
	ch_get_range_func_t				get_range;
	ch_get_tof_us_func_t            get_tof_us;		
	ch_get_amplitude_func_t			get_amplitude;
	ch_get_amplitude_avg_func_t		get_amplitude_avg;
	ch_set_frequency_func_t			set_frequency;
	ch_get_frequency_func_t			get_frequency;
	ch_get_iq_data_func_t			get_iq_data;
	ch_get_amplitude_data_func_t	get_amplitude_data;
	ch_samples_to_mm_func_t			samples_to_mm;
	ch_mm_to_samples_func_t			mm_to_samples;
	ch_set_threshold_func_t			set_threshold;
	ch_get_threshold_func_t			get_threshold;	
	ch_set_thresholds_func_t		set_thresholds;
	ch_get_thresholds_func_t		get_thresholds;
	ch_set_target_interrupt_func_t	set_target_interrupt;
	ch_get_target_interrupt_func_t	get_target_interrupt;
	ch_set_static_range_func_t		set_static_range;
	ch_set_static_coeff_func_t		set_static_coeff;
	ch_get_static_coeff_func_t		get_static_coeff;
	ch_set_rx_holdoff_func_t		set_rx_holdoff;
	ch_get_rx_holdoff_func_t		get_rx_holdoff;
	ch_set_rx_low_gain_func_t		set_rx_low_gain;
	ch_get_rx_low_gain_func_t		get_rx_low_gain;
	ch_get_demodulated_rx_data_func_t	get_demodulated_rx_data;	
	ch_set_tx_length_func_t			set_tx_length;
	ch_get_tx_length_func_t			get_tx_length;
	ch_set_modulated_tx_data_func_t	set_modulated_tx_data;
	ch_get_rx_pulse_length_func_t	get_rx_pulse_length;
	ch_set_time_plan_func_t			set_time_plan;
	ch_get_time_plan_func_t			get_time_plan;
	ch_set_cal_result_func_t		set_cal_result;
	ch_get_cal_result_func_t		get_cal_result;
} ch_api_funcs_t;


//! Data-ready interrupt callback routine pointer.
typedef void (*ch_io_int_callback_t)(ch_group_t *grp_ptr, uint8_t io_index); 
//
//! Non-blocking I/O complete callback routine pointer.
typedef void (*ch_io_complete_callback_t)(ch_group_t *grp_ptr);		
//
//! Periodic timer callback routine pointer.
typedef void (*ch_timer_callback_t)(void);			


//!  Chirp sensor group configuration structure.

/*! \note The \a CHIRP_MAX_NUM_SENSORS and \a CHIRP_NUM_I2C_BUSES symbols must be defined 
 * by the user.  Normally this is done in the \b chirp_board_config.h header file that is 
 * part of the board support package.
 */
struct ch_group_t {		/* [note tag name matches type to help Doxygen linkage] */
	uint8_t num_ports;						/*!< Number of ports (max possible sensor connections) */
	uint8_t num_i2c_buses;					/*!< Number of I2C buses on this board */
	uint8_t sensor_count;					/*!< Number of sensors detected */
	uint16_t i2c_drv_flags;					/*!< Flags for special I2C handling by Chirp driver, from 
											     \a chbsp_get_i2c_info()*/
	uint16_t rtc_cal_pulse_ms; 				/*!< Real-time clock calibration pulse length (in ms) */
	uint16_t pretrig_delay_us;				/*!< Pre-trigger delay for rx-only sensors (in us) */
	chdrv_discovery_hook_t disco_hook;		/*!< Addr of hook routine to call when device found on bus */
	ch_io_int_callback_t io_int_callback;			/*!< Addr of routine to call when sensor interrupts */
	ch_io_complete_callback_t io_complete_callback;	/*!< Addr of routine to call when non-blocking I/O 
													     completes */
	ch_dev_t *device[CHIRP_MAX_NUM_SENSORS];		/*!< Array of pointers to ch_dev_t structures for 
													     individual sensors */
	uint8_t num_connected[CHIRP_NUM_I2C_BUSES];		/*!< Array of counters for connected sensors per bus */
	chdrv_i2c_queue_t i2c_queue[CHIRP_NUM_I2C_BUSES];	/*!< Array of I2C non-blocking transaction 
														     queues (one per bus) */
};

//! Chirp sensor device structure.
struct ch_dev_t {		/* [note tag name matches type to help Doxygen linkage] */
	ch_group_t	*group;				/*!< Pointer to parent group structure. */
	ch_mode_t	mode;				/*!< Sensor operating mode. */
	uint8_t		freqLockValue;		/*!< Value set when sensor has locked */
	uint16_t	freqCounterCycles;	/*!< Frequency counter cycles */
	uint16_t	max_range;			/*!< Maximum range, in mm */
	uint16_t	static_range;		/*!< Static target rejection range, in samples (0 if unused) */
	uint16_t 	sample_interval;	/*!< Sample interval (in ms), only if in free-running mode */
	uint16_t 	rtc_cal_result; 	/*!< Real-time clock calibration result for the sensor. */
	uint32_t 	op_frequency; 		/*!< Operating frequency for the sensor. */
	uint16_t 	bandwidth; 			/*!< Bandwidth for the sensor. */
	uint16_t 	scale_factor; 		/*!< Scale factor for the sensor. */
	uint8_t  	i2c_address; 		/*!< Current I2C addresses. */
	uint8_t  	app_i2c_address;	/*!< Assigned application I2C address for device in normal operation*/
	uint16_t	i2c_drv_flags;		/*!< Flags for special I2C handling by Chirp driver */
	uint16_t 	part_number; 		/*!< Integer part number (e.g. 101 for a CH101 device). */
	int8_t		oversample;			/*!< Oversampling factor (power of 2) */
	uint8_t  	sensor_connected; 	/*!< Sensor connection status:
									  	 1 if discovered and successfully initialized, 0 otherwise. */
	uint8_t  	io_index; 			/*!< Index value (device number) identifying device within group */
	uint8_t  	i2c_bus_index; 		/*!< Index value identifying which I2C bus is used for this device. */
	uint16_t 	max_samples; 		/*!< Maximum number of receiver samples for this sensor firmware */
	uint16_t 	num_rx_samples; 	/*!< Number of receiver samples for the current max range setting. */
	uint16_t	win_start_sample;	/*!< Starting sample of sample window, if supported */
	uint16_t	num_win_samples;	/*!< Number of samples in sample window, if supported */

	/* Sensor Firmware-specific Linkage Definitions */
	const char	  *fw_version_string;		/*!< Pointer to string identifying sensor firmware version. */
	const uint8_t *firmware;				/*!< Pointer to start of sensor firmware image to be loaded */
	const uint8_t *ram_init;				/*!< Pointer to ram initialization data */
	void     (*prepare_pulse_timer)(ch_dev_t *dev_ptr);	/*!< Pointer to function preparing sensor pulse 
														     timer to measure real-time clock (RTC) 
															 calibration pulse sent to device. */
	void     (*store_pt_result)(ch_dev_t *dev_ptr);	/*!< Pointer to function to read RTC calibration 
													     pulse timer result from sensor and place value 
														 in the \a rtc_cal_result field. */
	void     (*store_op_freq)(ch_dev_t *dev_ptr);	/*!< Pointer to function to read operating 
													     frequency and place value in the
														 \a op_frequency field. */
	void     (*store_bandwidth)(ch_dev_t *dev_ptr);	/*!< Pointer to function to read operating bandwidth 
													     and place value in the \a bandwidth field. */
	void     (*store_scalefactor)(ch_dev_t *dev_ptr);	/*!< Pointer to function to calculate scale factor
														     and place value in \a scalefactor field. */
	uint8_t  (*get_locked_state)(ch_dev_t *dev_ptr);	/*!< Pointer to function returning locked state 
														     for sensor. */
	uint16_t (*get_fw_ram_init_size)(void);			/*!< Pointer to function returning ram init size 
													     for sensor. */
	uint16_t (*get_fw_ram_init_addr)(void);			/*!< Pointer to function returning start address of 
													     ram initialization area in the sensor. */

	/* API and callback functions */
	ch_api_funcs_t		api_funcs;						/*!< Structure containing API function pointers. */

};


/* API function prototypes and documentation */


/*!
 * \brief Initialize the device descriptor for a sensor.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param grp_ptr 		pointer to the ch_group_t descriptor for sensor group to join
 * \param dev_num		number of the device within the sensor group (identifies which physical sensor)
 * \param fw_init_func 	pointer to the sensor firmware initialization function (determines sensor 
 *                     	feature set)
 *
 * \return 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 \a 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 \a 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.
 *
 * \a 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 \a 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 \a 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 \a ch_group_start().
 */
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);

/*!
 * \brief	Program and start a group of sensors.
 *
 * \param	grp_ptr pointer to the ch_group_t descriptor for sensor group to be started
 *
 * \return 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 
 * \a 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 \a ch_init()).
 * - Assign unique I2C address to sensor (specified by board support package, see \a 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.
 *
 * \note
 * When the sensor is programmed, the entire sensor firmware image is normally written in a
 * single, large I2C transfer.  To limit the size of this transfer for a specific hardware platform,
 * define the \b MAX_PROG_XFER_SIZE symbol in the \b chirp_board_config.h header file.  For more
 * information, see chirp_bsp.h.
 */
uint8_t	ch_group_start(ch_group_t *grp_ptr);

/*!
 * \brief Get current configuration settings for a sensor.
 *
 * \param	dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \param	config_ptr pointer to a ch_config_t structure to receive configuration values
 *
 * \return 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 \a 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 \a ch_get_mode(), \a ch_get_max_range(), 
 * \a ch_get_sample_interval(), \a ch_get_static_range(), and \a ch_get_thresholds().
 */
uint8_t	ch_get_config(ch_dev_t *dev_ptr, ch_config_t *config_ptr);

/*!
 * \brief Set multiple configuration settings for a sensor.
 *
 * \param	dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \param	config_ptr	pointer to a ch_config_t structure containing new configuration values
 *
 * \return 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 \a 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 \a ch_set_mode(), \a ch_set_max_range(), \a ch_set_sample_interval(), \a ch_set_static_range(), 
 * and \a ch_set_thresholds().
 */
uint8_t	ch_set_config(ch_dev_t *dev_ptr, ch_config_t *config_ptr);

/*!
 * \brief Trigger a measurement on one sensor.
 *
 * \param	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 
 * \a CH_MODE_TRIGGERED_TX_RX or \a CH_MODE_TRIGGERED_RX_ONLY mode, this pulse will begin a measurement 
 * cycle.
 *
 * To simultaneously trigger all sensors in a group, use \a 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 \a ch_get_iq_data() is used).  If any
 * I/O operations are still active, the new measurement may be corrupted.
 */
void ch_trigger(ch_dev_t *dev_ptr);

/*!
 * \brief Trigger a measurement on a group of sensors.
 *
 * \param	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 \a CH_MODE_TRIGGERED_TX_RX or \a 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 \a 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 \a ch_get_iq_data() is used).  If any
 * I/O operations are still active, the new measurement may be corrupted.
 */
void ch_group_trigger(ch_group_t *grp_ptr);

/*!
 * \brief Reset a sensor.
 *
 * \param	dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \param	reset_type	type of reset (\a CH_RESET_HARD or \a CH_RESET_SOFT)
 * 
 * This function resets a sensor.  The \a reset_type parameter indicates if a software reset or 
 * full hardware reset is requested.
 */
void ch_reset(ch_dev_t *dev_ptr, ch_reset_t reset_type);

/*!
 * \brief Reset a group of sensors.
 *
 * \param	grp_ptr 	pointer to the ch_group_t descriptor for this group of sensors
 * \param	reset_type	type of reset (\a CH_RESET_HARD or \a CH_RESET_SOFT)
 * 
 * This function resets all sensors in a sensor group.  The \a reset_type parameter indicates if a 
 * software reset or full hardware reset is requested.
 */
void ch_group_reset(ch_group_t *grp_ptr, ch_reset_t reset_type);

/*! 
 * \brief	Indicate if a sensor is connected.
 *
 * \param 	dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \return 	1 if the sensor is connected, 0 otherwise
 */
uint8_t ch_sensor_is_connected(ch_dev_t *dev_ptr);

/*!
 * \brief	Get part number for a sensor.
 *
 * \param 	dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \return 	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.
 */
uint16_t ch_get_part_number(ch_dev_t *dev_ptr);

/*!
 * \brief	Get device number (I/O index values) for a sensor.
 *
 * \param 	dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return 	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.
 */
uint8_t ch_get_dev_num(ch_dev_t *dev_ptr);

/*!
 * \brief	Get device descriptor pointer for a sensor.
 *
 * \param	grp_ptr 	pointer to the ch_group_t descriptor for this group of sensors
 * \param	dev_num		device number within sensor group
 *
 * \return 	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 \a dev_num device number.
 */
ch_dev_t *  ch_get_dev_ptr(ch_group_t *grp_ptr, uint8_t dev_num);

/*!
 * \brief	Get the total number of sensor ports (possible sensors) in a sensor group.
 *
 * \param	grp_ptr 	pointer to the ch_group_t descriptor for this group of sensors
 *
 * \return 	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.
 */
uint8_t	ch_get_num_ports(ch_group_t *grp_ptr);

/*!
 * \brief	Get the active I2C address for a sensor.
 *
 * \param 	dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return	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.
 */
uint8_t	ch_get_i2c_address(ch_dev_t *dev_ptr);

/*!
 * \brief	Get the active I2C bus for a sensor.
 *
 * \param 	dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return	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.
 */
uint8_t	ch_get_i2c_bus(ch_dev_t *dev_ptr);

/*!
 * \brief	Get the firmware version description string for a sensor.
 *
 * \param 	dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return 	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.
 */
const char *	ch_get_fw_version_string(ch_dev_t *dev_ptr);

/*!
 * \brief	Get the current operating mode for a sensor.
 *
 * \param	dev_ptr 	pointer to the ch_dev_t config structure
 *
 * \return	Sensor operating mode
 *
 * This function returns the current operating mode for the sensor, one of:
 *	- \a CH_MODE_IDLE - low power idle mode, no measurements take place
 *	- \a CH_MODE_FREERUN - free-running mode, sensor uses internal clock to wake and measure
 *	- \a CH_MODE_TRIGGERED_TX_RX - hardware-triggered, sensor both transmits and receives
 *	- \a CH_MODE_TRIGGERED_RX_ONLY - hardware triggered, sensor only receives
 */
ch_mode_t ch_get_mode(ch_dev_t *dev_ptr);

/*!
 * \brief Configure a sensor for the specified operating mode.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \param mode 		the new operating mode for the sensor
 * \return 0 if successful.
 *
 * This function sets the sensor to operate in the specified mode, which
 * must be one of the following:
 *	- \a CH_MODE_IDLE - low power idle mode, no measurements take place
 *	- \a CH_MODE_FREERUN - free-running mode, sensor uses internal clock to wake and measure
 *	- \a CH_MODE_TRIGGERED_TX_RX - hardware-triggered, sensor both transmits and receives
 *	- \a CH_MODE_TRIGGERED_RX_ONLY - hardware triggered, sensor only receives
 */
uint8_t ch_set_mode(ch_dev_t *dev_ptr, ch_mode_t mode);

/*!
 * \brief Get the internal sample timing interval for a sensor.
 *
 *  \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \return 			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
 * a sensor operating in free-running mode.  If the sensor is in a different operating 
 * mode (e.g. a triggered mode), zero is returned.
 */
uint16_t ch_get_sample_interval(ch_dev_t *dev_ptr);

/*!
 * \brief Configure the internal sample interval for a sensor in freerunning mode.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param interval_ms 	interval between samples, in milliseconds. 
 * \return 0 if successful, 1 if arguments are invalid.
 *
 * This function sets the sample interval for a sensor operating in freerunning mode 
 * (\a CH_MODE_FREERUN).  The sensor will use its internal clock to wake and perform a 
 * measurement every \a interval_ms milliseconds.  A value of zero for \a interval_ms
 * is not valid.
 *
 * \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.
 */
uint8_t ch_set_sample_interval(ch_dev_t *dev_ptr, uint16_t interval_ms);

/*!
 * \brief Get the number of samples per measurement cycle.
 *
 * \param dev_ptr pointer to the ch_dev_t descriptor struct
 *
 * \return  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 \a ch_get_max_range().
 *
 */
uint16_t ch_get_num_samples(ch_dev_t *dev_ptr);

/*!
 * \brief Set the sensor sample count directly.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor struct
 * \param num_samples 	number of samples during each measurement cycle
 *
 * \return 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 \a ch_set_max_range().
 *
 * \note Normally, the sample is count is not set using this function, but is instead set
 * indirectly using either \a ch_set_max_range() or \a ch_set_config(), both of which 
 * automatically set the sample count based on a specified range in millimeters.
 */
uint8_t ch_set_num_samples(ch_dev_t *dev_ptr, uint16_t num_samples);

/*!
 * \brief Get the maximum possible sample count per measurement.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor struct
 *
 * \return  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 \a ch_get_num_samples().
 *
 */
uint16_t ch_get_max_samples(ch_dev_t *dev_ptr);


/*!
 * \brief Get the maximum range setting for a sensor.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return 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 
 * \a ch_get_config() function.
 */
uint16_t ch_get_max_range(ch_dev_t *dev_ptr);

/*!
 * \brief Set the maximum range for a sensor.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \param max_range maximum range, in millimeters
 *
 * \return 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 
 * \a ch_set_config() function.  These two methods are completely equivalent and may 
 * be freely mixed.
 */
uint8_t ch_set_max_range(ch_dev_t *dev_ptr, uint16_t max_range);


/*!
 * \brief Get the sample window for amplitude averaging.
 *
 * \param dev_ptr 			pointer to the ch_dev_t descriptor structure
 * \param start_sample_ptr 	pointer to variable to be updated with sample number of first sample
 * \param num_samples_ptr  	pointer to variable to be updated with number of samples
 *
 * \return 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.  \a start_sample_ptr is a pointer to a variable that will be updated with the 
 * number of the first sample in the sample window.  \a 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 \a ch_get_amplitude_avg() and \a 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.
 *
 */
uint8_t  ch_get_sample_window(ch_dev_t *dev_ptr, uint16_t *start_sample_ptr, uint16_t *num_samples_ptr);


/*!
 * \brief Set the sample window for amplitude averaging.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param start_sample 	sample number of first sample in window
 * \param num_samples  	number of samples to include in window
 *
 * \return 0 if successful, non-zero if error
 *
 * This function sets the sample range to be included in the sample window used for
 * amplitude averaging.  \a start_sample is the number of the first sample that will be
 * included in the averaging window.  \a num_samples is the total number of samples
 * that will be included.  
 *
 * Also see \a ch_get_amplitude_avg() and \a 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.
 */
uint8_t	 ch_set_sample_window(ch_dev_t *dev_ptr, uint16_t start_sample, uint16_t num_samples);


/*!
 * \brief Get static target rejection range setting.
 *
 * \param dev_ptr pointer to the ch_dev_t descriptor structure
 *
 * \return 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 \a ch_set_static_range().
 *
 * To calculate the physical distance that corresponds to the number of samples, use the 
 * \a ch_samples_to_mm() function.
 */
uint16_t ch_get_static_range(ch_dev_t *dev_ptr);

/*!
 * \brief Configure static target rejection.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param num_samples 	number of sensor samples (at beginning of measurement cycle) over 
 *                    	which static targets will be rejected
 *
 * \return 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 \a num_samples 
 * to filter over a certain physical distance, use the \a ch_mm_to_samples() function.
 */
uint8_t ch_set_static_range(ch_dev_t *dev_ptr, uint16_t num_samples);

/*!
 * \brief Get the measured range from a sensor.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param range_type 	the range type to be reported (e.g. one-way vs. round-trip)
 *
 * \return Range in millimeters times 32, or \a 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 \a 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:
 *   - \a CH_RANGE_ECHO_ONE_WAY -  gets full pulse/echo round-trip distance, then divides by 2
 *   - \a CH_RANGE_ECHO_ROUND_TRIP	- full pulse/echo round-trip distance
 *   - \a 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 \a 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.
 *
 * \note The \a range_type parameter only controls how this function interprets the results from the 
 * measurement cycle.  It does not change the sensor mode.
 *
 */
uint32_t ch_get_range(ch_dev_t *dev_ptr, ch_range_t range_type);

/*!
 * \brief Get the measured Time-of-flight from a sensor in the ultrasound periodic timer tick.
 *
 * \param dev_ptr pointer to the ch_dev_t descriptor structure
 *
 * \return Time-of-flight in microseconds, 
 *         or 0 if error
 *
 * This function reads the measurement result registers from the sensor and then computes the 
 * Time-of-flight in microseconds.
 *
 * This function returns the measured time as a 32-bit integer. 
 *
 * If the sensor did not successfully find the range of a target during the most recent measurement, 
 * the returned value will be \a 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.
 * 
 * \note This function is only available when using special sensor firmware packages
 * from Chirp.
 *
 */
uint32_t ch_get_tof_us(ch_dev_t *dev_ptr);

/*!
 * \brief Get the measured amplitude from a sensor.
 *
 * \param 	dev_ptr pointer to the ch_dev_t descriptor structure
 *
 * \return 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 \a CH_NO_TARGET, as returned 
 * by \a ch_get_range().
 */
uint16_t ch_get_amplitude(ch_dev_t *dev_ptr);

/*!
 * \brief Get the averaged measured amplitude over the sample window.
 *
 * \param 	dev_ptr pointer to the ch_dev_t descriptor structure
 *
 * \return 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 \a 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.
 *
 */
uint16_t ch_get_amplitude_avg(ch_dev_t *dev_ptr);

/*!
 * \brief Get the bandwidth of a sensor.
 *
 * \param 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.  
 *
 * \return 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.
 */
uint16_t ch_get_bandwidth(ch_dev_t *dev_ptr);  

/*!
 * \brief Set the operating frequency of a sensor.
 *
 * \param dev_ptr 			pointer to the ch_dev_t descriptor structure
 * \param target_freq_hz  	operating frequency in Hz
 *
 * \return 0 if success, 1 if error
 *
 * This function sets the target operating frequency of the sensor.  This is the primary frequency of the 
 * ultrasonic pulse that is emitted by the device when transmitting.  The resulting operating frequency
 * may be slightly different than the requested value.
 *
 * See also \a ch_get_frequency().
 *
 * \note This function is only available when using special sensor firmware packages from Chirp.
 */
uint8_t ch_set_frequency(ch_dev_t *dev_ptr, uint32_t target_freq_hz);

/*!
 * \brief Get the operating frequency of a sensor.
 *
 * \param 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.  
 *
 * \return Frequency, in Hz
 */
uint32_t ch_get_frequency(ch_dev_t *dev_ptr);  

/*!
 * \brief Get the real-time clock calibration value.
 *
 * \param dev_ptr pointer to the ch_dev_t descriptor structure
 *
 * \return 	RTC calibration value
 *
 * This function returns the real-time clock (RTC) calibration value read from the sensor during
 * \a ch_group_start().  The RTC calibration value is calculated by the sensor during the RTC 
 * calibration pulse, and it is used internally in calculations that convert between time and distance.
 */
uint16_t ch_get_rtc_cal_result(ch_dev_t *dev_ptr);

/*!
 * \brief Get the real-time clock calibration pulse length.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return 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 
 * \a ch_group_start() to calibrate the sensor's internal clock.  The pulse length is specified by 
 * the board support package during the \a 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_pulselength(ch_dev_t *dev_ptr);

/*!
 * \brief Get the calibration scale factor of a sensor.
 *
 * \param 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.
 *
 * \return 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.
 */
uint16_t ch_get_scale_factor(ch_dev_t *dev_ptr);  

/*!
 * \brief Get the raw I/Q measurement data from a sensor.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param buf_ptr		pointer to data buffer where I/Q data will be written
 * \param start_sample  starting sample number within measurement data (0 = start of data)
 * \param num_samples	number of samples to read from sensor
 * \param mode			whether I/Q read should block (\a CH_IO_MODE_BLOCK (0) = blocking, 
 * 												   	\a CH_IO_MODE_NONBLOCK (1) = non-blocking)
 *
 * \return 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 \a ch_get_range() returns \a CH_NO_TARGET).  (Note that this is different 
 * than the regular amplitude value, as returned by \a ch_get_amplitude(), which is \a not updated 
 * unless a target is detected.)
 * 
 * Each sample I/Q pair consists of two signed 16-bit integers and is described by the 
 * \a 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:  
 * 			\f[Amp_n = \sqrt{(I_n)^2 + (Q_n)^2}\f]
 * 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 \a ch_get_num_samples().  
 *
 *  - To read all valid I/Q data, set \a start_sample to zero (0), and set \a num_samples to the 
 *  value returned by \a ch_get_num_samples().
 *
 * To determine what sample number corresponds to a physical distance, use \a 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 \a mode to \a 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 \a non_block option, the board support package (BSP) you are using must provide the 
 * \a chbsp_i2c_read_nb() and \a 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 \a ch_io_complete_callback_set(). 
 *
 * Non-blocking reads are managed together for a group of sensors.  To perform a non-blocking read:
 *
 *  -# Register a callback function using \a ch_io_complete_callback_set().
 *  -# Define and initialize a handler for the DMA interrupts generated.
 *  -# Synchronize with all sensors whose I/Q data should be read by waiting for all to indicate 
 *     data ready.
 *  -# Set up a non-blocking read on each sensor, using \a ch_get_iq_data() with \a mode = 
 *     \a CH_IO_MODE_NONBLOCK (1).
 *  -# Start the non-blocking reads on all sensors in the group, using \a ch_io_start_nb().
 *  -# 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 \a 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.
 *
 * \note This function only obtains the data from the most recently completed measurement cycle. 
 * It does not actually trigger a measurement.
 */
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);

/*!
 * \brief Get the raw amplitude measurement data from a sensor.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param buf_ptr		pointer to data buffer where amplitude data will be written
 * \param start_sample  starting sample number within measurement data (0 = start of data)
 * \param num_samples	number of samples to read from sensor
 * \param mode			whether read should block (\a CH_IO_MODE_BLOCK (0) = blocking, 
 * 											   	\a CH_IO_MODE_NONBLOCK (1) = non-blocking)
 *
 * \return 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 \a ch_get_range() returns \a CH_NO_TARGET).  (Note that this is different 
 * than the regular amplitude value, as returned by \a ch_get_amplitude(), which is \a 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 \a ch_get_num_samples().  
 *
 *  - To read all valid amplitude data, set \a start_sample to zero (0), and set \a num_samples to the 
 *  value returned by \a ch_get_num_samples().
 *
 * To determine what sample number corresponds to a physical distance, use \a 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 \a mode to \a 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 \a non_block option, the board support package (BSP) you are using must provide the 
 * \a chbsp_i2c_read_nb() and \a 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 \a 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:
 *
 *  -# Register a callback function using \a ch_io_complete_callback_set().
 *  -# Define and initialize a handler for the DMA interrupts generated.
 *  -# Synchronize with all sensors whose amplitude data should be read by waiting for all to indicate 
 *     data ready.
 *  -# Set up a non-blocking read on each sensor, using \a ch_get_amplitude_data() with \a mode = 
 *     \a CH_IO_MODE_NONBLOCK (1).
 *  -# Start the non-blocking reads on all sensors in the group, using \a ch_io_start_nb().
 *  -# 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 \a 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.
 *
 * \note This function only obtains the data from the most recently completed measurement cycle. 
 * It does not actually trigger a measurement.
 */
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);

/*!
 * \brief Convert sample count to millimeters for a sensor.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param num_samples  	sample count to be converted
 *
 * \return Number of millimeters
 *
 * This function converts the sample count specified in \a 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 
 * \a ch_get_range() function) and sample-oriented values, such as data obtained from 
 * \a ch_get_iq_data() or parameters for static target rejection (see \a ch_set_static_range()).
 */
uint16_t ch_samples_to_mm(ch_dev_t *dev_ptr, uint16_t num_samples);

/*!
 * \brief Convert millimeters to sample count for a sensor.
 *
 * \param dev_ptr pointer to the ch_dev_t descriptor structure
 * \param num_mm  number of millimeters to be converted
 *
 * \return Number of samples
 *
 * This function converts the distance in millimeters specified in \a 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 
 * \a ch_get_range() function) and sample-oriented values, such as data obtained from 
 * \a ch_get_iq_data() or parameters for static target rejection (see \a ch_set_static_range()).
 */
uint16_t ch_mm_to_samples(ch_dev_t *dev_ptr, uint16_t num_mm);


/*!
 * \brief Calculate amplitude from sample I/Q values.
 *
 * \param iq_sample_ptr  pointer to ch_iq_data_t structure containing the I/Q data
 *
 * \return 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:
 * 			\f[Amp = \sqrt{(I)^2 + (Q)^2}\f]
 *
 * 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 \a ch_get_iq_data() and \a ch_get_amplitude_data().
 */
uint16_t ch_iq_to_amplitude(ch_iq_sample_t *iq_sample_ptr);

/*!
 * \brief Start non-blocking I/O operation(s) for a group of sensors.
 *
 * \param grp_ptr 	pointer to the ch_group_t descriptor for sensor group
 *
 * \return 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 \a 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 \a ch_io_callback_set() will be called.
 *
 * See \a ch_get_iq_data() for more information.
 */
uint8_t ch_io_start_nb(ch_group_t *grp_ptr);

/*!
 * \brief Register sensor interrupt callback routine for a group of sensors.
 *
 * \param grp_ptr 			pointer to the ch_group_t sensor group descriptor structure
 * \param callback_func_ptr	pointer to callback function to be called when sensor interrupts
 *
 * This function registers the routine specified by \a 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_int_callback_set(ch_group_t *grp_ptr, ch_io_int_callback_t callback_func_ptr);

/*!
 * \brief Register non-blocking I/O complete callback routine for a group of sensors.
 *
 * \param grp_ptr 			pointer to the ch_group_t group descriptor structure
 * \param callback_func_ptr	pointer to callback function to be called when non-blocking I/O operations complete
 *
 * This function registers the routine specified by \a 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 \a ch_io_start_nb().
 */
void ch_io_complete_callback_set(ch_group_t *grp_ptr, ch_io_complete_callback_t callback_func_ptr);

/*!
 * \brief Notify SonicLib that a non-blocking I/O operation has completed.
 *
 * \param grp_ptr 		pointer to the ch_group_t sensor group descriptor structure
 * \param 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 \a 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 \a ch_io_complete_callback_set().
 */
void ch_io_notify(ch_group_t *grp_ptr, uint8_t i2c_bus_index);

/*!
 * \brief Get the detection threshold.
 *
 * \param dev_ptr 			pointer to the ch_dev_t descriptor structure
 * \param threshold_index 	index to the thresholds, starting from 0
 *
 * \return amplitude threshold value
 *
 * This function obtains the detection threshold value with the specified \a threshold_index
 * from the sensor and returns the corresponding threshold amplitude.
 *
 * See also \a ch_set_threshold().
 *
 * \note This function is only available when using special sensor firmware packages from Chirp.
 *
 * \note For CH201 GPRMT firmware, which supports multiple thresholds with programmable sample ranges,
 * use \a ch_get_thresholds().
 */
uint16_t ch_get_threshold(ch_dev_t *dev_ptr, uint8_t threshold_index);

/*!
 * \brief Set the detection threshold.
 *
 * \param dev_ptr 			pointer to the ch_dev_t descriptor structure
 * \param threshold_index 	index to the thresholds, starting from 0
 * \param amplitude 		amplitude threshold value
 *
 * \return 0 if success, 1 if error
 *
 * This function sets the detection threshold value with the specified \a threshold_index value
 * for the sensor.  The detection treshold is the minimum amplitude required for a target detection
 * to be reported.  The \a amplitude value is the new required amplitude, expressed in the same
 * internal units used in \a ch_get_amplitude() and other functions.
 *
 * See also \a ch_get_threshold().
 *
 * \note This function is only available when using select sensor firmware packages from Chirp.
 *
 * \note For CH201 GPRMT firmware, which supports multiple thresholds with programmable sample ranges,
 * use \a ch_set_thresholds().
 */
uint8_t ch_set_threshold(ch_dev_t *dev_ptr, uint8_t threshold_index, uint16_t amplitude);

/*!
 * \brief Get detection thresholds (CH201 only).
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param thresh_ptr 	pointer to ch_thresholds_t structure to receive threshold data
 *
 * \return 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 \a 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.  
 *
 * See also \a ch_set_thresholds().
 *
 * \note This function supports CH201 GPRMT sensor firmware, with multiple detection thresholds
 * and programmable sample ranges.  If using other firmware with individual detection tresholds,
 * use \a ch_get_threshold().
 */
uint8_t ch_get_thresholds(ch_dev_t *dev_ptr, ch_thresholds_t *thresh_ptr);

/*!
 * \brief Set detection thresholds (CH201 only).
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param thresh_ptr 	pointer to ch_thresholds_t structure containing threshold data
 *
 * \return 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 \a 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.  The CH201 GPR firmware supports six (6) thresholds.  Each threshold has a maximum
 * sample length of 255.
 *
 * See also \a ch_get_thresholds().
 *
 * \note This function supports CH201 GPRMT sensor firmware, with multiple detection thresholds
 * and programmable sample ranges.  If using other firmware with individual detection tresholds,
 * use \a ch_set_threshold().
 */
uint8_t ch_set_thresholds(ch_dev_t *dev_ptr, ch_thresholds_t *thresh_ptr);

/*!
 * \brief Enable or disable target detection interrupt mode.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \param enable  	1 to enable target interrupt mode, 0 to disable
 *
 * \return 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 \a enable to 1 to enable target detection interrupt mode.  Set
 * \a enable to 0 to disable the target detection interrupt mode.
 *
 * \note Target detection interrupt mode is only available in select Chirp sensor firmware versions.
 */
uint8_t ch_set_target_interrupt(ch_dev_t *dev_ptr, uint8_t enable);

/*!
 * \brief Get the target detection interrupt mode setting.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return 1 if target detection interrupt mode is enabled, 0 if disabled
 *
 * This function returns the current setting for target detection interrupt mode.
 *
 * \note Target detection interrupt mode is only available in select Chirp sensor firmware versions.
 */
uint8_t ch_get_target_interrupt(ch_dev_t *dev_ptr);

/*!
 * \brief Set the static coefficient for sensor IIR filter.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param static_coeff 	static coefficient for the IIR filter
 *
 * \return 0 if success, 1 if error
 *
 * This function sets the static coefficient for the sensor's internal IIR filter.
 * 
 * If using shorter ultrasound transmit pulses, you may decrease the static coefficient.
 * If using longer ultrasound transmit pulses, you may increase the static coefficient.
 *
 * See also \a ch_get_static_coeff().
 *
 * \note This function is only available in select Chirp sensor firmware versions.
 */
uint8_t ch_set_static_coeff(ch_dev_t *dev_ptr, uint8_t static_coeff);

/*!
 * \brief Get the static coefficient for IIR filter.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return IIR static coefficient
 *
 * This function gets the static coefficient value for the sensor's internal IIR filter.
 * 
 * See also \a ch_get_static_coeff().
 *
 * \note This function is only available in select Chirp sensor firmware versions.
 */
uint8_t ch_get_static_coeff(ch_dev_t *dev_ptr);

/*!
 * \brief Set the receive holdoff sample count.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param num_samples 	number of samples to be ignored at the beginning of each measurement
 *
 * \return 0 if success, 1 if error
 *
 * This function sets the receive (rx) holdoff sample count.  \a num_samples specifies a number of
 * samples at the beginning of a measurement that will be ignored for the purpose of
 * detecting a target.  (These samples correspond to the closest distances from the sensor.)
 *
 * To convert a physical distance into a sample count value to use here, use \a ch_mm_to_samples().
 * 
 * See also \a ch_get_rx_holdoff().
 */
uint8_t ch_set_rx_holdoff(ch_dev_t *dev_ptr, uint16_t num_samples);

/*!
 * \brief Get the receive holdoff sample count.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return 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 \a ch_set_rx_holdoff().
 * 
 * To convert the returned sample count to a physical distance, use \a ch_samples_to_mm().
 *
 * See also \a ch_set_rx_holdoff().
 */
uint16_t ch_get_rx_holdoff(ch_dev_t *dev_ptr);

/*!
 * \brief Set the receive low-gain sample count.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param num_samples 	number of samples that have low gain at beginning of measurement
 *
 * \return 0 if success, 1 if error
 *
 * This function sets the receive (rx) low-gain range in the sensor.  The low-gain range consists
 * of samples at the beginning of a measurement that will have a lower gain applied during the
 * sensor receive operation.  (These samples correspond to the closest distances from the sensor.)
 *
 * The low-gain range must be less than the current maximum range setting.  If \a num_samples is
 * greater than or equal to the maximum range setting, it will automatically be reduced.
 *
 * See also \a ch_get_rx_low_gain(), \a ch_get_num_samples().
 *
 * \note This function is only available in CH201 sensor firmware.
 */
uint8_t ch_set_rx_low_gain(ch_dev_t *dev_ptr, uint16_t num_samples);

/*!
 * \brief Get the receive low-gain sample count.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return 	number of samples that have low gain at beginning of measurement
 *
 * This function gets the receive (rx) low-gain range from the sensor.  The low-gain range is
 * a count of samples at the beginning of a measurement that will have lower gain applied 
 * during the ultrasound receive operation.  
 *
 * The returned low-gain range is either the default value for the sensor firmware, or
 * a value previously set by \a ch_set_rx_low_gain().
 * 
 * To convert the returned sample count to a physical distance, use \a ch_samples_to_mm().
 *
 * See also \a ch_set_rx_low_gain().
 *
 * \note This function is only available in CH201 sensor firmware.
 */
uint16_t ch_get_rx_low_gain(ch_dev_t *dev_ptr);

/*!
 * \brief Set the ultrasound transmit pulse length.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param num_cycles 	transmit pulse length (number of cycles per transmission)
 *
 * \return 0 if success, 1 if error
 *
 * This function sets the length (duration) of the ultrasonic pulse sent by the 
 * sensor when it transmits. \a num_cycles specifies the length of the pulse.  The units
 * are the number of active PMUT cycles per transmission.
 *
 * See also \a ch_get_tx_length().
 * 
 * \note This feature is only available in select Chirp sensor firmware versions.
 */
uint8_t ch_set_tx_length(ch_dev_t *dev_ptr, uint8_t num_cycles);

/*!
 * \brief Get the ultrasound transmit pulse length.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return transmit pulse length (number of cycles per transmission)
 *
 * This function gets the length of the ultrasonic pulse sent by the sensor when
 * it transmit.  The transmit length is the number of active PMUT cycles per transmission.
 *
 * See also \a ch_set_tx_length().
 * 
 * \note This feature is only available in select Chirp sensor firmware versions.
 */
uint8_t ch_get_tx_length(ch_dev_t *dev_ptr);

/*!
 * \brief Get the detected length of the received ultrasound pulse.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * \return pulse length
 *
 * This function gets the detected length of the received ultrasonic pulse.
 * 
 * \note This function is only available in select Chirp sensor firmware versions.
 */
uint8_t ch_get_rx_pulse_length(ch_dev_t *dev_ptr);

/*!
 * \brief Configure SonicSync timing plan.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param time_plan 	time plan identifier
 *
 * This routine sets the timing plan for a SonicSync master or slave node.  The possible values are:
 *  SONICSYNC_TIME_PLAN_1		(0),
 *  SONICSYNC_TIME_PLAN_2		(1),
 *  SONICSYNC_TIME_PLAN_3		(2), and
 *  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, 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 
 * \a ch_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 
 * discovered.  This may be desirable to speed up the master discovery or to avoid pairing with nearby sensor pairs that
 * use a different time plan.
 *
 * See also \a ch_get_time_plan().
 *
 * \return 0 if successful.
 * 
 * \note This function is only available when using Chirp SonicSync sensor firmware.
 */
uint8_t ch_set_time_plan(ch_dev_t *dev_ptr, ch_time_plan_t time_plan);

/*!
 * \brief Get SonicSync timing plan.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * This routine returns the timing plan currently in use for a SonicSync master or slave node.  The possible values are:
 *  SONICSYNC_TIME_PLAN_1		(0),
 *  SONICSYNC_TIME_PLAN_2		(1),
 *  SONICSYNC_TIME_PLAN_3		(2), and
 *  SONICSYNC_TIME_PLAN_NONE	(255)
 *
 * For a master device, this value will always be the value specified in a previous call to \a ch_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 
 * \a ch_set_time_plan() routine).
 *
 * See also \a ch_set_time_plan().
 *
 * \return time plan value currently in use
 * 
 * \note This function is only available when using Chirp SonicSync sensor firmware.
 */
ch_time_plan_t ch_get_time_plan(ch_dev_t *dev_ptr);

/*!
 * \brief Enable/disable receive-only sensor pre-triggering.
 *
 * \param grp_ptr 	pointer to the ch_group_t group descriptor structure
 * \param 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 \a ch_group_trigger() is called.
 * This improves the ability of a receive-only sensor to detect the transmitted pulse at very short
 * distances.
 *
 * If enabled, pre-triggering is used for all receive-only sensors in the sensor group.
 *
 * To use this function, set \a enable to 1 to enable pre-triggering, or 0 to disable pre-triggering.
 *
 * See also \a ch_get_rx_pretrigger().
 *
 * \note  Enabling pre-triggering will reduce the maximum range of the receive-only sensor(s), relative to the
 * setting specified in \a ch_set_max_range(), by about 200mm.  You may want to increase the maximum range setting
 * accordingly.
 */
void ch_set_rx_pretrigger(ch_group_t *grp_ptr, uint8_t enable);

/*!
 * \brief Get receive-only sensor pre-triggering setting.
 *
 * \param grp_ptr 	pointer to the ch_group_t group descriptor structure
 *
 * This function returns the current state (enabled or disabled) of pre-triggering receive-only 
 * sensors.
 *
 * See also \a ch_set_rx_pretrigger().
 *
 * \return 1 if receive pre-triggering is enabled, 0 if disabled
 */
uint8_t ch_get_rx_pretrigger(ch_group_t *grp_ptr);

/*!
 * \brief Check sensor firmware program
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 *
 * This function confirms that the contents of the sensor's program memory match 
 * the firmware that was loaded into it, as specified during the \a ch_init() 
 * call.  The memory contents are read back from the sensor and are compared with
 * the original byte values used to program the device.
 *
 * \return 0 if firmware matches the original program, or 1 if mismatch (error)
 */
uint8_t ch_check_program(ch_dev_t *dev_ptr);

/*!
 * \brief Set modulated TX data.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \param tx_data 	The data to be transmitted over ultrasound
 *
 * This function sets the modulated TX data
 * The tx_data must be between 0-31 decimal
 *
 * \return 0 if successful.
 *
 * \note This function is only available when using Chirp GPPC sensor firmware.
 */
uint8_t ch_set_modulated_tx_data(ch_dev_t *dev_ptr, uint8_t tx_data);

/*!
 * \brief Get the demodulated data from the received ultrasound pulse.
 *
 * \param dev_ptr 			pointer to the ch_dev_t descriptor structure
 * \param rx_pulse_length	the detected length of the received ultrasound pulse
 * \param *data_ptr				pointer to the data
 *
 * This function gets the raw data from the received ultrasound pulse and demodulates it
 *
 * \return 0 if successful.
 *
 * \note This function is only available when using Chirp GPPC sensor firmware.
 */
uint8_t ch_get_demodulated_rx_data(ch_dev_t *dev_ptr, uint8_t rx_pulse_length, uint8_t *data_ptr);

/*!
 * \brief Set the calibration result.
 *
 * \param dev_ptr 		pointer to the ch_dev_t descriptor structure
 * \param cal_ptr 		pointer to ch_cal_result_t structure to receive calibration data
 *
 * \return 0 if success, 1 if error
 *
 * WARNING: This function should not be used to set the calibration result to a fixed value, 
 * even one individually calculated for each sensor, as this could change over the lifetime 
 * of the sensor; rather, this function could be used to update the calibration result if the 
 * calibration result calculated by CHx01 at startup (i.e. returned by ch_get_cal_result()) 
 * is sufficiently different than expected or sensor performance is not good.
 *
 * This function sets the calibration result with a ch_cal_result_t structure specified by \a cal_ptr
 * for the sensor. The ch_cal_result_t structure contains DCO period and reverse drive cycles.
 *
 * To use this function, first initialize the ch_cal_result_t DCO period/reverse drive cycles pair of values
 *
 * See also \a ch_get_cal_result().
 */
uint8_t ch_set_cal_result(ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr);

/*!
 * \brief Get the calibration result.
 *
 * \param dev_ptr 	pointer to the ch_dev_t descriptor structure
 * \param cal_ptr 		pointer to ch_cal_result_t structure to receive calibration data
 *
 * \return 0 if success, 1 if error
 *
 * This function obtains the current calibration result from the sensor and
 * returns them in a ch_cal_result_t structure specified by \a cal_ptr.  The
 * ch_cal_result_t structure contains DCO period and reverse drive cycles.
 *
 * See also \a ch_set_cal_result().
 */
uint8_t ch_get_cal_result(ch_dev_t *dev_ptr, ch_cal_result_t *cal_ptr);

#endif	/* __SONICLIB_H_ */