超声波传感器(CHx01) 学习笔记 Ⅲ-API介绍

1.1 初始化传感器的设备描述符

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 )    

此功能用于在使用传感器之前初始化各种 Chirp SonicLib 结构。ch_dev_t设备描述符是用于管理传感器的主要数据结构，
其地址随后将用作在调用大多数 API 函数时标识传感器的句柄。

1.2 编程并启动一组传感器

uint8_t ch_group_start(ch_group_t * grp_ptr)

此函数对传感器组中的所有传感器执行实际的发现、编程和初始化序列。每个传感器必须以前通过调用ch_init（） 添加到组中。

1.3 获取传感器的设备描述符指针

ch_dev_t* ch_get_dev_ptr    (ch_group_t *  grp_ptr，uint8_t dev_num )

此函数返回传感器组中某个传感器的ch_dev_t设备描述符的地址。传感器在组中由dev_num设备编号标识。

1.4 指示传感器是否已连接

uint8_t ch_sensor_is_connected(ch_dev_t * dev_ptr)

1.5 初始化定期计时器

uint8_t chbsp_periodic_timer_init    (uint16_t interval_ms，ch_timer_callback_t callback_func_ptr)

此函数初始化电路板上的定期计时器。计时器应编程为每interval_ms毫秒后生成一个中断。
callback_func_ptr参数指定将在计时器过期（并发生中断）时调用的回调例程。板级支持包中的定时器中断处理程序函数应调用此函数。
周期定时器通常用于通过让应用程序的回调函数调用ch_trigger（）或ch_group_trigger（）来触发传感器测量周期。

1.6 为一组传感器注册传感器中断回调

ch_io_int_callback_set    (ch_group_t *     grp_ptr，ch_io_int_callback_t     callback_func_ptr)

此函数注册由 callback_func_ptr 指定的例程，以便在传感器中断时调用。通常，这种中断表示测量周期已完成，传感器已准备好读取数据。传感器组中的所有传感器都使用相同的回调函数，该函数接收中断设备的设备号（端口号）作为输入参数，以识别特定的中断设备。

1.7 为指定的操作模式配置传感器

uint8_t ch_set_mode    (ch_dev_t * dev_ptr，ch_mode_t     mode)

此函数将传感器设置为在指定模式下运行，
● CH_MODE_IDLE - 低功耗空闲模式，无需进行测量
● CH_MODE_FREERUN - 自由运行模式，传感器使用内部时钟进行唤醒和测量
● CH_MODE_TRIGGERED_TX_RX - 硬件触发，传感器既发送又接收
● CH_MODE_TRIGGERED_RX_ONLY - 硬件触发，传感器仅接收

1.8 设置传感器的最大范围

uint8_t ch_set_max_range    (ch_dev_t * dev_ptr，uint16_t max_range)

此功能设置传感器的最大检测范围，以毫米为单位。
检测范围设置控制传感器在每个测量周期内侦听的时间（即它将捕获多少个样本）

1.9 处于自由运行模式的传感器配置内部采样间隔

uint8_t ch_set_sample_interval    (ch_dev_t * dev_ptr，uint16_tinterval_ms)

此功能设置在自由运行模式下工作的传感器的采样间隔（CH_MODE_FREERUN）。
传感器将使用其内部时钟唤醒并每隔interval_ms毫秒执行一次测量
注意 此功能对在其中一种触发模式下工作的传感器没有影响。触发器件的采样间隔由外部触发时序决定。

2.0 将毫米数转换为传感器的样本计数

uint16_t ch_mm_to_samples    (ch_dev_t * dev_ptr，uint16_t num_mm)

此函数转换num_mm中指定的距离（以毫米为单位），并将其转换为相应的传感器样本数。转换使用在设备初始化和校准期间设置的值，这些值描述了传感器的内部时序，以及设备的当前最大范围设置。

2.1 设置振幅平均的采样窗口

uint8_t ch_set_sample_window    (ch_dev_t * dev_ptr，uint16_t start_sample，uint16_t end_sample )

此函数设置用于幅度平均的采样窗口的起始和结束样本。start_sample是将包含在平均窗口中的第一个样本的数量。end_sample将包括最后一次解冻样品的数量。

2.2 从传感器获取原始 I/Q 测量数据

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)

此功能从传感器读取原始 I/Q 测量数据。I/Q数据集包括构成完整测量周期的每个样本的离散值对。每个单独的样本都以正交格式报告为一对值I和Q。I/Q值可用于计算被测超声信号的相对幅度。
I/Q迹线的内容在每个测量周期都会更新，即使没有检测到目标

请注意，这与ch_get_amplitude（）返回的常规振幅值不同，除非检测到目标，否则不会更新
每个样本 I/Q 对由两个有符号 16 位整数组成，由 ch_iq_sample_t 结构描述。要将任何给定的 I/Q 值对转换为该样本的幅度值，请将 I 和 Q 相平方，并取和的平方根：
传感器中的幅度值仅以内部ADC计数（最低有效位或LSB）表示，并且不会校准为任何标准单位。

每个I/Q迹线中使用的样本数量由器件的最大范围设置决定。如果将其设置为小于最大可能范围，则并非所有样本都包含有效数据。要确定迹线内活动样本的数量，请使用 ch_get_num_samples（）。
● 要读取所有有效的 I/Q 数据，请将 start_sample 设置为零 （0），并将 num_samples 设置为 ch_get_num_samples（） 返回的值。

对于CH101传感器，在每个测量周期内最多采集150个样品;对于CH201传感器，最多可采集450个样品。因此，完整的CH101 I/Q迹线将包含多达600字节的数据（150个样本x每个样本4个字节），而CH201 I/Q迹线可能包含多达1800个字节。buf_ptr指定的缓冲区必须足够大才能容纳此数量的数据。
当从传感器读取I/Q数据时，在规划读取传感器的频率（采样间隔）时，必须考虑通过I2C总线传输I/Q数据所需的额外时间。