根据用户的问题分析，核心是查询 `time_pulse_us` 函数的用法、参数、返回值和示例。这个问题通常与MicroPython或嵌入式系统中用于测量脉冲宽度的函数相关。 ### **`time_pulse_us` 函数详解** `time_pulse_us` 是一个用于高精度测量引脚上脉冲宽度的函数，常见于MicroPython、ESP32/ESP8266等平台，用于读取数字传感器（如超声波模块、红外接收器等）的信号持续时间 [ref_2]。 其基本工作原理是：函数会**阻塞**程序执行，持续监测指定引脚的信号电平，直到出现指定边沿（如从低到高或从高到低）的脉冲，然后开始计时，直到脉冲结束（电平再次翻转），最后返回测量的脉冲持续时间（单位为微秒，`us`）[ref_2]。 | 功能特性 | 描述 | | :--- | :--- | | **主要用途** | 精确测量数字信号的脉冲宽度。 | | **典型应用** | 超声波测距（如HC-SR04）、红外遥控信号解码、PWM信号测量等 [ref_2]。 | | **测量单位** | 微秒（`µs` 或 `us`）。 | | **工作模式** | 通常为阻塞式，在等待脉冲期间会暂停程序执行。 | | **核心参数** | 引脚对象、电平状态、超时时间。 | ### **函数原型与参数说明** 在MicroPython中，该函数通常属于 `machine` 或 `time` 模块。其标准调用形式如下： ```python # 假设从 machine 模块导入 Pin 类，从 time 模块导入 pulse_time_us 函数 from machine import Pin import time # 函数原型示意 duration = time_pulse_us(pin_obj, pulse_level, timeout_us) ``` **参数详解：** 1. **`pin_obj` (Pin对象)**: 需要被测量的引脚对象。必须事先配置为输入模式（`Pin.IN`）。 2. **`pulse_level` (整数, 通常为 1 或 0)**: 指定要测量的脉冲的电平。 * **`pulse_level=1`**: 测量一个**高电平脉冲**的宽度。函数会等待引脚变为高电平（上升沿）后开始计时，直到引脚再次变回低电平（下降沿）停止。 * **`pulse_level=0`**: 测量一个**低电平脉冲**的宽度。函数会等待引脚变为低电平（下降沿）后开始计时，直到引脚再次变回高电平（上升沿）停止 [ref_2]。 3. **`timeout_us` (整数)**: **超时时间，单位微秒**。这是一个关键的安全参数。如果在该时间内没有等到完整的脉冲（即没有检测到预期的开始边沿或结束边沿），函数将停止等待并返回一个错误值（通常是 `-1` 或 `-2`）。这可以防止程序因传感器无响应而永久阻塞 [ref_2]。 ### **返回值** * **成功时**：返回测量到的**脉冲宽度，单位是微秒（`us`）**，为一个正整数。 * **失败/超时时**：通常返回 `-1` 或 `-2`。 * `-1` 通常表示在 `timeout_us` 时间内没有等到脉冲**开始**（即没有检测到指定的起始边沿）。 * `-2` 通常表示在 `timeout_us` 时间内开始了脉冲，但没有等到脉冲**结束**（即没有检测到预期的结束边沿）[ref_2]。 * 具体返回值需参考对应平台的文档。 ### **应用实例：超声波测距模块（HC-SR04）** HC-SR04模块是 `time_pulse_us` 最典型的应用场景。其工作时序要求MCU在Trig引脚发送一个至少10us的高电平触发信号，然后在Echo引脚等待一个高电平脉冲，该脉冲的宽度与距离成正比 [ref_2]。 ```python from machine import Pin import time import utime # 定义引脚 trig_pin = Pin(12, Pin.OUT) # 触发引脚，输出模式 echo_pin = Pin(14, Pin.IN) # 回波引脚，输入模式 def get_distance(): """使用HC-SR04超声波模块测量距离（单位：厘米）""" # 1. 发送触发信号：拉低至少2us，然后拉高10us，再拉低 trig_pin.value(0) utime.sleep_us(2) trig_pin.value(1) utime.sleep_us(10) trig_pin.value(0) # 2. 测量回波脉冲宽度（高电平持续时间） # 等待 echo 引脚变为高电平（脉冲开始），最多等待 30000us (30ms) # 如果超时未等到，返回 -1 pulse_time = time_pulse_us(echo_pin, 1, 30000) # 3. 处理测量结果 if pulse_time < 0: # 测量超时，可能是模块未连接或物体超出量程 return -1 # 或根据需求返回其他错误值 # 4. 计算距离 # 声音在空气中速度约 340m/s = 0.034cm/us # 脉冲时间是声波往返时间，所以距离 = (时间 * 声速) / 2 distance_cm = (pulse_time * 0.034) / 2 return distance_cm # 主循环中调用 while True: dist = get_distance() if dist > 0: print("Distance: {:.2f} cm".format(dist)) else: print("Measurement timeout or error") time.sleep(1) # 每秒测量一次 ``` **代码关键点解析：** 1. **引脚初始化**：`trig_pin` 必须设置为输出，用于发送控制信号；`echo_pin` 必须设置为输入，用于接收测量信号 [ref_2]。 2. **触发时序**：严格按照HC-SR04数据手册的要求生成触发脉冲 [ref_2]。 3. **`time_pulse_us` 调用**： * `echo_pin`: 要测量的引脚对象。 * `1`: 测量高电平脉冲。 * `30000`: 超时设置为30000微秒（30毫秒）。HC-SR04最大量程对应回波时间约为38ms，这里设置30ms是一个兼顾测量范围和响应速度的常用值 [ref_2]。 4. **错误处理**：检查返回值是否为负，以应对模块无响应或物体超出量程的情况 [ref_2]。 5. **距离计算**：根据声速和往返时间公式进行换算。 ### **注意事项与高级用法** 1. **阻塞特性**：`time_pulse_us` 是阻塞函数，在测量期间会独占CPU。对于需要同时处理其他任务的系统，需考虑使用中断或异步方式。 2. **精度与稳定性**：测量精度受系统时钟精度和中断响应影响。对于极短或极长的脉冲，可能需要调整超时参数或使用硬件定时器。 3. **超时值设置**：超时值必须根据具体应用场景合理设置。设置过短可能导致正常脉冲被误判为超时；设置过长则会导致在传感器故障时程序响应迟钝 [ref_2]。 4. **测量不同类型脉冲**：通过修改 `pulse_level` 参数，该函数同样适用于测量低电平脉冲，例如某些红外接收头的输出信号 [ref_2]。 ### **与其他相关概念的比较** * **与 `Pulse Generator` 的区别**：`time_pulse_us` 用于**测量**已有脉冲的宽度，而Simulink或某些硬件中的 `Pulse Generator` 是用于**生成**特定波形（如方波）的模块或功能 [ref_2][ref_3]。前者是输入/测量，后者是输出/生成。 * **与 `S_PULSE` 指令的区别**：西门子PLC中的 `S_PULSE` 指令是一个**定时器**指令，用于在逻辑触发后产生一个设定宽度的脉冲输出 [ref_1]。它属于逻辑控制中的定时器应用，与嵌入式系统中用于信号测量的 `time_pulse_us` 功能完全不同。 * **与雷达 `PRF/PRI` 的关系**：雷达中的脉冲重复频率（PRF）和脉冲间隔（PRI）描述的是周期性发射脉冲的宏观时序参数 [ref_6]。而 `time_pulse_us` 测量的是单个脉冲的微观时间宽度，两者处于不同的时间尺度与应用领域。