ch_rangefinder.c File Reference

Chirp SonicLib API range finding function implementations. More...

#include <invn/soniclib/ch_log.h>
#include <invn/soniclib/details/ch_common.h>
#include <invn/soniclib/sensor_fw/icu_gpt/icu_gpt.h>
#include <invn/soniclib/ch_rangefinder_types.h>
#include <invn/soniclib/ch_rangefinder.h>

Macros
#define	CH_LOG_MODULE_NAME   "CH_RANGEFINDER"

Functions
uint8_t	ch_get_num_targets (ch_dev_t *dev_ptr)
	Get the number of targets detected in last measurement. More...
uint8_t	ch_get_num_thresholds (const ch_dev_t *dev_ptr)
	Get number of detection thresholds. More...
uint16_t	ch_get_rx_holdoff (ch_dev_t *dev_ptr)
	Get the receive holdoff sample count. More...
uint16_t	ch_get_static_range (const ch_dev_t *dev_ptr)
	Get static target rejection range setting. More...
uint16_t	ch_get_target_amplitude (ch_dev_t *dev_ptr, uint8_t target_num)
	Get the amplitude for a specific target detected in last measurement. More...
uint32_t	ch_get_target_range (ch_dev_t *dev_ptr, uint8_t target_num, ch_range_t range_type)
	Get the range to a specific target detected in last measurement. More...
uint32_t	ch_get_target_tof_us (ch_dev_t *dev_ptr, uint8_t target_num)
	Get the measured time-of-flight for a specific target in microseconds. More...
uint16_t	ch_get_threshold (ch_dev_t *dev_ptr, uint8_t threshold_index)
	Get the detection threshold. More...
uint8_t	ch_get_thresholds (ch_dev_t *dev_ptr, ch_thresholds_t *thresh_ptr)
	Get detection thresholds. More...
uint32_t	ch_get_tof_us (ch_dev_t *dev_ptr)
	Get the measured time-of-flight from a sensor in microseconds. More...
uint8_t	ch_is_target_in_ringdown (ch_dev_t *dev_ptr)
	Return if a target is detected near sensor (in the ringdown) More...
uint8_t	ch_rangefinder_display_config_info (ch_dev_t *dev_ptr)
uint8_t	ch_rangefinder_get_algo_config (const ch_dev_t *dev_ptr, ch_rangefinder_algo_config_t *config_ptr)
uint16_t	ch_rangefinder_get_amplitude (ch_dev_t *dev_ptr)
uint32_t	ch_rangefinder_get_range (ch_dev_t *dev_ptr, ch_range_t range_type)
uint16_t	ch_rangefinder_get_rx_holdoff (ch_dev_t *dev_ptr)
uint32_t	ch_rangefinder_get_target_range (ch_dev_t *dev_ptr, uint8_t target_num, ch_range_t range_type)
uint8_t	ch_rangefinder_get_thresholds (ch_dev_t *dev_ptr, ch_thresholds_t *lib_thresh_buf_ptr)
uint8_t	ch_rangefinder_set_algo_config (ch_dev_t *dev_ptr, const ch_rangefinder_algo_config_t *config_ptr)
uint8_t	ch_rangefinder_set_rx_holdoff (ch_dev_t *dev_ptr, uint16_t num_samples)
uint8_t	ch_rangefinder_set_static_range (ch_dev_t *dev_ptr, uint16_t num_samples)
uint8_t	ch_rangefinder_set_thresholds (ch_dev_t *dev_ptr, ch_thresholds_t *lib_thresh_buf_ptr)
uint8_t	ch_set_rx_holdoff (ch_dev_t *dev_ptr, uint16_t num_samples)
	Set the receive holdoff sample count. More...
uint8_t	ch_set_static_range (ch_dev_t *dev_ptr, uint16_t num_samples)
	Configure static target rejection. 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_set_thresholds (ch_dev_t *dev_ptr, ch_thresholds_t *thresh_ptr)
	Set detection thresholds. More...

Variables
const uint8_t	THRESH_LEN_REGS [CHX01_COMMON_NUM_THRESHOLDS]

Detailed Description

Chirp SonicLib API range finding function implementations.

Function Documentation

ch_get_num_targets()

uint8_t ch_get_num_targets

(

ch_dev_t *

dev_ptr

)

Get the number of targets detected in last measurement.

Parameters

dev_ptr

pointer to the ch_dev_t descriptor structure

Returns

number of targets detected in last measurement

This function returns the number of valid targets that were detected in the last measurement completed by the sensor. Data for each of these targets may then be read using ch_get_target_range() and ch_get_target_amplitude().

See also ch_get_target_range(), ch_set_num_ranges().

ch_get_num_thresholds()

uint8_t ch_get_num_thresholds

(

const ch_dev_t *

dev_ptr

)

Get number of detection thresholds.

Parameters

dev_ptr

pointer to the ch_dev_t descriptor structure

Returns

number of detection thresholds, or 0 if thresholds are not supported

This function returns the number of independent detection threshold values that are supported by the current sensor and sensor firmware. For firmware supporting multiple thresholds, the number of thresholds is the same as the number of threshold fields in the ch_thresholds_t structure.

See also ch_set_thresholds().

ch_get_rx_holdoff()

uint16_t ch_get_rx_holdoff

(

ch_dev_t *

dev_ptr

)

Get the receive holdoff sample count.

Parameters

dev_ptr

pointer to the ch_dev_t descriptor structure

Returns

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

For ICU sensors, this function always returns the value for the default measurement definition. To specify which measurement to query, use the icu_gpt_get_rx_holdoff() function.

See also ch_set_rx_holdoff().

ch_get_static_range()

uint16_t ch_get_static_range

(

const ch_dev_t *

dev_ptr

)

Get static target rejection range setting.

Parameters

dev_ptr

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

To calculate the physical distance that corresponds to the number of samples, use the ch_samples_to_mm() function.

For ICU sensors, this function always returns the value for the default measurement definition. To specify which measurement to query, use the icu_gpt_get_static_filter() function.

See also ch_set_static_range().

ch_get_target_amplitude()

uint16_t ch_get_target_amplitude	(	ch_dev_t *	dev_ptr,
		uint8_t	target_num
	)

Get the amplitude for a specific target detected in last measurement.

Parameters

dev_ptr	pointer to the ch_dev_t descriptor structure
target_num	number of target to report

Returns

amplitude value (LSBs)

This function reads the measurement data for a specific target and returns the measured amplitude value. The amplitude is representative of the incoming sound pressure. The value is expressed in internal sensor counts (LSBs) 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_target_range().

See also ch_get_target_range(), ch_get_amplitude().

ch_get_target_range()

uint32_t ch_get_target_range	(	ch_dev_t *	dev_ptr,
		uint8_t	target_num,
		ch_range_t	range_type
	)

Get the range to a specific target detected in last measurement.

Parameters

dev_ptr	pointer to the ch_dev_t descriptor structure
target_num	number of target to report
range_type	the 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 data for a specific target 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.)

target_num specifies the target whose range is to be calculated. The ch_get_num_targets() function may be used to determine the total number of valid targets detected by the measurement.

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)

See also ch_get_target_amplitude(), ch_get_range(), ch_get_num_targets().

ch_get_target_tof_us()

uint32_t ch_get_target_tof_us	(	ch_dev_t *	dev_ptr,
		uint8_t	target_num
	)

Get the measured time-of-flight for a specific target in microseconds.

Parameters

dev_ptr	pointer to the ch_dev_t descriptor structure
target_num	number of the detected target to be reported

Returns

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. The time-of-flight is returned 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 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. The time-of-flight that is reported is the total time measured by the sensor between transmission and reception. The value is always the full round-trip time-of-flight.

ch_get_threshold()

uint16_t ch_get_threshold	(	ch_dev_t *	dev_ptr,
		uint8_t	threshold_index
	)

Get the detection threshold.

Parameters

dev_ptr	pointer to the ch_dev_t descriptor structure
threshold_index	index to the thresholds, starting from 0

Returns

amplitude threshold value

This function obtains the detection threshold value with the specified threshold_index from the sensor and returns the corresponding threshold amplitude.

See also ch_set_threshold().

Note

This function is only available when using special sensor firmware packages from Chirp.

For ICU sensors and CH201 sensors with GPRMT firmware, multiple thresholds with programmable sample ranges are supported - use ch_get_thresholds().

ch_get_thresholds()

uint8_t ch_get_thresholds	(	ch_dev_t *	dev_ptr,
		ch_thresholds_t *	thresh_ptr
	)

Get detection thresholds.

Parameters

dev_ptr	pointer to the ch_dev_t descriptor structure
thresh_ptr	pointer 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.

For ICU sensors, this function only reports the thresholds for the default measurement (CH_DEFAULT_MEAS_NUM). If both measurements are being used, the thresholds for each may be obtained individually by using the icu_gpt_get_thresholds() function.

See also ch_set_thresholds().

Note

This function is available for ICU sensors and when using most sensor firmware for CH201 sensors. If using other CH101/CH201 firmware with only a single detection treshold, use ch_get_threshold().

ch_get_tof_us()

uint32_t ch_get_tof_us

(

ch_dev_t *

dev_ptr

)

Get the measured time-of-flight from a sensor in microseconds.

Parameters

dev_ptr

pointer to the ch_dev_t descriptor structure

Returns

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. The time-of-flight is returned 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 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. The time-of-flight that is reported is the total time measured by the sensor between transmission and reception. The value is always the full round-trip time-of-flight.

ch_is_target_in_ringdown()

uint8_t ch_is_target_in_ringdown

(

ch_dev_t *

dev_ptr

)

Return if a target is detected near sensor (in the ringdown)

Parameters

dev_ptr

pointer to the ch_dev_t descriptor structure

Returns

1 if a target is detected, else 0

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_ptr	pointer to the ch_dev_t descriptor structure
num_samples	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. (These samples correspond to the closest distances from the sensor.)

To convert a physical distance into a sample count value to use here, use ch_mm_to_samples().

For ICU sensors, this function always controls the default measurement definition. To specify which measurement to modify, use the icu_gpt_set_rx_holdoff() function.

See also ch_get_rx_holdoff().

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_ptr	pointer to the ch_dev_t descriptor structure
num_samples	number of sensor samples (at beginning of measurement cycle) over which static targets will be rejected

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.

For ICU sensors, this function always controls the default measurement definition. To specify which measurement to modify, use the icu_gpt_set_static_filter() function.

See also ch_get_static_range().

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_ptr	pointer to the ch_dev_t descriptor structure
threshold_index	index to the thresholds, starting from 0
amplitude	amplitude threshold value

Returns

0 if success, 1 if error

This function sets the detection threshold value with the specified threshold_index value for the sensor. The detection threshold is the minimum amplitude required for a target detection to be reported. The amplitude value is the new required amplitude, expressed in the same internal units used in ch_get_amplitude() and other functions.

See also ch_get_threshold().

Note

This function is only available when using select sensor firmware packages from Chirp.

For ICU sensors and CH201 sensors with GPRMT firmware, multiple thresholds with programmable sample ranges are supported - use ch_set_thresholds().

ch_set_thresholds()

uint8_t ch_set_thresholds	(	ch_dev_t *	dev_ptr,
		ch_thresholds_t *	thresh_ptr
	)

Set detection thresholds.

Parameters

dev_ptr	pointer to the ch_dev_t descriptor structure
thresh_ptr	pointer to ch_thresholds_t structure containing threshold data

Returns

0 if success, 1 if error

This function sets the detection threshold values for the sensor based on the values in the 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. The ICU sensor supports eight (8) separate thresholds, while the CH201 sensor with GPRMT firmware supports six (6) thresholds. Each threshold has a maximum sample length of 255.

It is not necessary to use the full set of thresholds, if the application and sensing environment do not require that many different levels. Unused thresholds should occupy the last elements in the ch_thresholds_t structure and should have zero (0) for their starting sample number. These entries will be ignored, and the threshold specified in the final valid entry will apply to the rest of the measurement.

For ICU sensors, this function only sets the thresholds for the default measurement (CH_DEFAULT_MEAS_NUM). If both measurements are being used, the thresholds for each may be set individually by using the icu_gpt_set_thresholds() function.

See also ch_get_thresholds().

Note

This function supports ICU sensors and CH201 sensors with GPRMT firmware, with multiple detection thresholds and programmable sample ranges. If using other firmware with a single detection treshold, use ch_set_threshold().

Variable Documentation

THRESH_LEN_REGS

const uint8_t THRESH_LEN_REGS[CHX01_COMMON_NUM_THRESHOLDS]

Initial value:

= {
        CHX01_GPRMT_REG_THRESH_LEN_0,
        CHX01_GPRMT_REG_THRESH_LEN_1,
        CHX01_GPRMT_REG_THRESH_LEN_2,
        CHX01_GPRMT_REG_THRESH_LEN_3,
        CHX01_GPRMT_REG_THRESH_LEN_4,
        0  
}