跳到主要内容

常见问题

这页按当前 CoCube MicroPython 的使用流程整理。遇到问题时，建议先看“连接与烧录”，再看“运行与文件”，最后再看具体模块。

连接与烧录​

Thonny 看不到 CoCube，或者没有可选串口​

优先检查这几项：

  • CoCube 是否已经开机。长按底部电源键约 3 秒再连接。
  • USB 线是否支持数据传输。有些线只能充电，电脑不会识别串口。
  • 端口是否在拔插后发生变化。重新打开 Thonny 的解释器配置，手动再选一次端口。
  • 电脑是否缺少串口驱动。尤其在 Windows 或部分 macOS 环境下，可能需要安装 CH343 驱动。

如果还是不行，先换一根数据线，再换一个 USB 口，通常比反复重启更有效。

烧录完成后，Shell 里还是看不到 >>>​

先按这个顺序排查：

  1. 确认 Thonny 右下角选中的仍是正确端口和 MicroPython (ESP32) 解释器。
  2. 点击工具栏红色停止按钮，重启解释器。
  3. 重新拔插 CoCube，再在 Thonny 里重新选端口。

如果你使用的是底层 Flash 下载工具，还要额外检查：

  • 芯片型号是否选对
  • 固件文件是否对应 CoCube
  • 烧录地址是否填写正确

这三项只要有一项不匹配，就可能导致设备无法正常启动。

为什么固件烧录建议始终使用 USB 有线方式？​

固件烧录对稳定性要求最高，最稳妥的方式一直是 USB 有线连接。

对当前这套 MicroPython 文档来说，也建议把“烧录固件”和“上传 .py 文件”分开理解：

  • 固件烧录：优先用有线
  • 平时开发：再用 Thonny 连接、运行、保存脚本

运行与文件​

代码已经保存到设备了，为什么重启后不会自动运行？​

最常见的原因是文件名不对。

MicroPython 只有在设备里找到 main.py 时，才会在上电后自动运行它。
像 test.py、demo.py 这样的文件会被保存下来，但不会自动启动。

如果你希望 CoCube 脱离电脑后也能运行程序，请把脚本另存为 main.py。

main.py 明明已经有了，为什么一连上 Thonny 又像没运行一样？​

这是 Thonny 的默认行为，不一定是程序坏了。

Thonny 建立连接时，通常会先中断当前运行的程序，然后进入 REPL。
所以会出现这种现象：

  • 脱机上电时，main.py 能自动运行
  • 一连上 Thonny，程序被打断，Shell 里只剩 >>>

这种情况下可以：

  • 在 Shell 里按 Ctrl + D 软重启，重新观察 main.py 的完整启动过程
  • 或者修改 Thonny 的相关设置，避免连接时自动中断运行中的程序

上传成功了，但屏幕没反应​

先不要急着怀疑整块板子坏了，优先检查：

  • 程序里是否真的调用了 display.init()
  • 显示的文字颜色是否和背景色太接近
  • 代码是不是只 print(...) 到 Shell，没有把内容画到屏幕上

如果只是想验证屏幕是否正常，先跑一段最小示例最稳。当前固件已经准备好默认中文字库，所以直接用 display.write() 即可：

import display

tft = display.init()
tft.fill(display.BLACK)
display.write("你好，CoCube", 24, 40, display.YELLOW, display.BLACK)

程序跑进 while True 后，Thonny 里什么都做不了​

这是正常现象。死循环会一直占用解释器。

处理方式：

  • 点击 Thonny 工具栏的红色停止按钮
  • 或者在 Shell 中按 Ctrl + C

如果 Shell 里出现 KeyboardInterrupt，这通常表示程序已经成功被中断，不是新的故障。

运动与定位​

机器人为什么没有按预期运动？​

时间控制本来就会受很多现实因素影响，例如：

  • 地面太滑或太粗糙
  • 电量状态不同
  • 履带摩擦差异

所以同一段 move_ms(...) 或 rotate_ms(...) 代码，不同场地看到的轨迹可能会有偏差。

更稳妥的调参顺序是：

  1. 先把速度压在 20~30
  2. 先看方向对不对
  3. 再慢慢调整时间参数

move_to()、rotate_to() 或 cocube.pos.x 看起来不正常​

先看 cocube.pos.state。

  • cocube.pos.state 为真：位置和角度数据才可靠
  • cocube.pos.state 为假：不要继续依赖坐标类接口

常见原因包括：

  • CoCube 没有放在 CoMaps 上
  • 已经偏离有效定位区域
  • 当前位置更新不稳定

如果定位无效，优先先回到 CoMaps 的正常区域，再继续测试。

外接模块​

外接模块插上了，但程序里完全没反应​

先检查最容易漏掉的一步：有没有先执行 cm.power_on()。

对当前固件来说，很多外接模块在正式读取或控制前，都建议先这样写：

import cocube_module as cm

cm.power_on()

然后再去测试最小接口，例如：

  • ToF：cm.tof_connected()、cm.tof_distance()
  • 光照：cm.dlight_level()
  • 语音：cm.asr_get_command()
  • 夹爪：cm.gripper_open()

如果连最小接口都没有反应，再去检查磁吸连接是否牢靠。

ToF 第一次读取就是 false、-1 或 -2​

这类现象很常见，常见原因是模块刚上电，还没稳定。

可以按这个顺序处理：

  • cm.power_on() 后先等一小段时间
  • 第一次失败时，再读一次，不要立刻判定模块损坏
  • 对负值优先按“无效数据”处理

当前固件里常见返回含义是：

  • 正常毫米值：读取成功
  • -1：数据无效
  • -2：测量超时

夹爪为什么不动，或者角度表现很奇怪？​

优先检查：

  • 是否已经执行 cm.power_on()
  • 角度是否在 0~70 范围内
  • 是否先单独跑通过 gripper_open()、gripper_close()、gripper_degree(...)

当前固件里：

  • 0 更接近全开
  • 70 更接近全闭

如果一开始就把底盘移动、夹爪闭合、坐标控制全部混在一起，反而更难判断问题到底出在哪一步。

语音识别​

语音模块为什么一直没有反应？​

最常见的原因有四类：

  • 模块刚上电，还没准备好
  • 环境太吵
  • 没有先说唤醒词
  • 一开始就把动作逻辑写得太复杂，没先确认命令 ID

更稳妥的测试顺序是：

  1. 先 cm.power_on()
  2. 稍等片刻
  3. 先说唤醒词，例如 你好小智
  4. 再说命令词
  5. 程序里只打印 cm.asr_get_command() 的返回值

等命令 ID 稳定了，再把它映射成动作。

自学习后的命令词为什么用不了？​

先确认两件事：

  • 自学习命令词的 ID 是从 4 开始的
  • 你是否真的用程序打印确认过返回 ID

不要只凭“我刚才录的是第一条命令”来猜编号。
最稳妥的办法还是先打印：

import time
import cocube_module as cm

cm.power_on()
time.sleep_ms(500)

while True:
    print(cm.asr_get_command())
    time.sleep_ms(50)

另外，重新学习前，最好先删除旧的学习唤醒词或命令词，并保持环境安静、发音清晰。

AI 摄像头​

为什么一调用 read_card()、read_color()、get_line() 就报错？​

这通常不是摄像头坏了，而是顺序不对。

摄像头相关接口必须按这个顺序来：

  1. init()
  2. change_algo(...)
  3. 调用和当前算法匹配的读取函数

例如：

  • read_card() 需要先切到 Card Recog
  • read_color() 需要先切到 Color Recog
  • get_line(...) 需要先切到 Line Detect

如果当前算法不匹配，固件会直接抛错提示，不会默默返回空值。

摄像头识别效果不稳定，应该先调什么？​

先调环境和目标，再调代码。

最值得先检查的是：

  • 背景和目标是否对比明显
  • 巡线时是否是白底黑线这类高对比场景
  • 线条粗细是否适中
  • 卡片或目标是否太远，导致 w、h 太小
  • 是否一次混用了多种视觉任务

最稳妥的办法仍然是：

  • 一次只测一种算法
  • 先打印结果
  • 结果稳定后，再映射到底盘动作

摄像头一初始化，为什么其他外设行为变了？​

这是当前固件的资源占用特点，不是偶发 bug。

摄像头 init() 之后：

  • cocube_module 会进入摄像头模式
  • 夹爪控制方式会切换
  • NeoPixel 所在的相关资源会被占用

所以最开始调试时，不建议一上来就把摄像头、夹爪、NeoPixel 全部混在一起。

更稳妥的顺序是：

  1. 单独把摄像头跑通
  2. 单独把外设跑通
  3. 最后再做组合程序

还没排掉？​

可以按这个顺序回看文档：

  1. 搭建开发环境
  2. 基础知识
  3. 对应课程页里的“常见问题 / 使用提醒”
  4. cocube 核心接口速查
  5. cocube_module 快速参考
  6. 摄像头模块

如果你能先把问题缩小成“连不上”“没 >>>”“读不到数据”“有 ID 但没动作”这种更具体的现象，排查速度会快很多。