第 4 课 · ToF 测距

这一课学什么？

这一课只讲一个核心点：距离。

当 CoCube 能稳定读到前方距离后，程序就可以根据环境变化做判断，而不是一直按固定命令运行。

ToF 模块

学习目标

会给扩展模块上电
会检查 ToF 是否已经接好
会读取距离值并判断是否有效
会写出一个“靠近就停、远离就走”的基础逻辑

用到的硬件和功能

这一课需要接入 ToF 测距模块。

会用到的接口主要有：

cm.power_on()：给扩展模块上电。大多数外接模块在正式读取前都建议先调用一次。
cm.tof_connected()：检查 ToF 是否接入，返回 True / False。
cm.tof_distance()：读取距离，单位是毫米。正常时返回毫米值；-1 表示数据无效；-2 表示测量超时。
cocube.move(direction, speed)：持续运动。direction 取 cocube.FORWARD / cocube.BACKWARD；speed 是速度；启动后会保持当前输出。
cocube.brake()：主动刹车，让 CoCube 尽快停下。

先认识这个能力

ToF 不是“让机器人动”的模块，而是“让机器人知道前方还有多远”的模块。

这一课的程序结构会非常典型：

先读取输入
再判断输入范围
最后决定动作

开始编程

1. 先确认模块是否连接正常

import time
import cocube_module as cm

cm.power_on()
time.sleep_ms(300)

while True:
    print("connected =", cm.tof_connected(), "distance =", cm.tof_distance())
    time.sleep_ms(200)

先不要急着让 CoCube 动起来。
先确认两件事：

cm.tof_connected() 是否为真
cm.tof_distance() 是否能稳定返回合理的毫米值

2. 根据距离决定前进或停车

import time
import cocube
import cocube_module as cm

cm.power_on()
time.sleep_ms(300)

while True:
    distance = cm.tof_distance()

    if distance < 0:
        cocube.brake()
        print("ToF 还没准备好")
    elif distance < 100:
        cocube.brake()
        print("太近了，停车")
    elif distance > 180:
        cocube.move(cocube.FORWARD, 20)
        print("继续前进")
    else:
        cocube.brake()
        print("保持安全距离")

    time.sleep_ms(80)

这段程序里最重要的不是具体阈值，而是判断顺序：

先处理异常值
再处理太近
再处理太远
最后处理中间的安全区域

运行时观察什么

运行这段程序时，重点看这些现象：

初次上电后，模块可能先返回异常值
物体靠近时，CoCube 会不会及时刹住
前方空间变大时，CoCube 会不会重新前进
在两个阈值之间时，状态会不会稳定

常见问题 / 使用提醒

cm.tof_distance() 返回负值时，优先当作无效数据处理
初次上电建议等一小段时间再进入主循环
先把阈值判断跑通，再考虑叠加别的外设
距离阈值不是固定答案，要根据实际场地调

挑战一下

试着把这节课扩展成一个“简单跟随”任务：

太远就前进
太近就后退
中间区域保持等待

可以先自己决定两个阈值，例如：

小于某个距离就后退
大于某个距离就前进
中间范围就刹车等待

如果想继续升级，还可以试两件事：

把不同状态显示到屏幕上
让前进和后退使用不同速度，观察哪一种更稳定

快速参考

这一课最常用的写法是：

import cocube_module as cm

cm.power_on()
print(cm.tof_connected())
print(cm.tof_distance())

cm.power_on()：打开扩展模块电源
cm.tof_connected()：检查模块是否在线
cm.tof_distance()：读取距离
cocube.move(...)：持续前进
cocube.brake()：刹车

如果想继续查外设接口，可以查看 cocube_module 快速参考。

这一课学什么？​

学习目标​

用到的硬件和功能​

先认识这个能力​

开始编程​

1. 先确认模块是否连接正常​

2. 根据距离决定前进或停车​

运行时观察什么​

常见问题 / 使用提醒​

挑战一下​

快速参考​