msb-public
/
IoT-For-Beginners
mirror of https://github.com/microsoft/IoT-For-Beginners.git
1
0
Code Issues Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'update-translations'
${ noResults }
IoT-For-Beginners/translations/zh-CN/TROUBLESHOOTING.md

25 KiB
Raw Permalink Blame History Escape

故障排除指南

本指南帮助您解决在使用 IoT for Beginners 课程时遇到的常见问题。问题按类别组织，便于导航。

目录

安装问题

Python 安装

问题：Python 版本过低

错误： 需要 Python 3.6 或更高版本

解决方案：

  1. 从 python.org 下载最新的 Python 3
  2. 在 Windows 安装时，勾选“将 Python 添加到 PATH”
  3. 验证安装： 
    python3 --version

问题：多个 Python 版本冲突

症状： 运行错误的 Python 版本，包安装到错误位置

解决方案：

  • Windows: 使用 py -3 代替 python 明确调用 Python 3
  • macOS/Linux: 使用 python3 代替 python
  • 始终为项目创建并使用虚拟环境

问题：找不到 pip 命令

错误： 'pip' 不是内部或外部命令，也不是可运行的程序或批处理文件

解决方案：

  1. 尝试使用 pip3 代替 pip
  2. 或使用 python -m pip 或 python3 -m pip
  3. 确保 Python 已添加到 PATH（重新安装 Python 并选中该选项）

VS Code 和扩展

问题：Pylance 扩展不起作用

症状： 无 Python IntelliSense、代码补全或类型检查

解决方案：

  1. 打开 VS Code 命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）
  2. 运行“Python: 选择解释器”
  3. 选择正确的 Python 解释器（如果使用虚拟环境，则选择虚拟环境）
  4. 重新加载 VS Code 窗口

问题：VS Code 未检测到虚拟环境

症状： 选中错误的 Python 解释器

解决方案：

  1. 确保您已在终端激活虚拟环境
  2. 打开命令面板，运行“Python: 选择解释器”
  3. 选择 .venv 文件夹中的解释器
  4. 检查状态栏（左下角）显示正确的 Python 版本

PlatformIO（Wio Terminal）

问题：PlatformIO 安装失败

错误： PlatformIO 安装过程中出现各种错误

解决方案：

  1. 确保 VS Code 是最新版本
  2. 先安装 C/C++ 扩展
  3. 安装 PlatformIO 后重启 VS Code
  4. 检查网络连接（PlatformIO 需要下载大文件）

问题：PlatformIO 无法检测到开发板

症状： 无法上传代码到 Wio Terminal

解决方案：

  1. 尝试更换 USB 线（有些线只支持充电）
  2. 检查设备管理器（Windows）或执行 ls /dev/tty*（macOS/Linux）
  3. 安装或更新 USB 驱动
  4. 尝试不同 USB 端口
  5. 快速滑动 Wio Terminal 电源开关两次进入引导加载模式

问题：PlatformIO 编译错误

错误： fatal error: Arduino.h: 没有那个文件或目录

解决方案：

  1. 删除项目中的 .pio 文件夹
  2. 从命令面板运行“PlatformIO: 重建”
  3. 确认 platformio.ini 中板子配置正确： 
    [env:seeed_wio_terminal]
platform = atmelsam
board = seeed_wio_terminal
framework = arduino

Grove 库

问题：Raspberry Pi 上 Grove 库导入失败

错误： ModuleNotFoundError: No module named 'grove'

解决方案：

  1. 重新安装 Grove 库： 
    cd ~
git clone https://github.com/Seeed-Studio/grove.py
cd grove.py
sudo pip3 install .
  2. 如果使用虚拟环境，可能需要全局安装或复制库
  3. 确认 I2C 已启用：sudo raspi-config nonint do_i2c 0

问题：Grove 传感器未检测到

错误： IOError: [Errno 121] 远程 I/O 错误

解决方案：

  1. 检查物理连接（确保 Grove 数据线完全插入）
  2. 确认传感器连接到正确的端口（模拟、数字、I2C、UART）
  3. 运行 i2cdetect -y 1 查看设备是否出现在 I2C 总线上
  4. 尝试更换 Grove 数据线
  5. 确保 Grove Base Hat 正确安装在树莓派 GPIO 针脚上

硬件问题

树莓派

问题：树莓派无法启动

症状： 无显示，无 LED 动作，或出现彩虹屏

解决方案：

  1. 检查电源： 使用官方 5V 3A USB-C 电源（针对 Pi 4）
  2. SD 卡问题：
    • 重新格式化 SD 卡并重新安装 Raspberry Pi OS
    • 尝试不同的 SD 卡（推荐品牌）
    • 确保 SD 卡正确插入
  3. 检查 HDMI 连接： 尝试 Pi 4 上两个 HDMI 端口，使用靠近电源的 HDMI 端口

问题：无法通过 SSH 连接树莓派

症状： 连接被拒绝或超时

解决方案：

  1. 启用 SSH：
    • 使用 Raspberry Pi Imager 烧录 SD 卡时，在高级选项配置 SSH
    • 或在启动分区创建一个名为 ssh（无扩展名）的空文件
  2. 查找树莓派 IP 地址：
    • 查看路由器的已连接设备列表
    • 使用 ping raspberrypi.local（如果 mDNS 有效）
    • 使用网络扫描工具如 nmap 或 Angry IP Scanner
  3. 检查网络：
    • 确保树莓派和电脑在同一网络内
    • 尝试使用有线以太网连接替代 WiFi
  4. 验证用户名/密码（默认用户名 pi，密码 raspberry）

问题：未识别 Grove Base Hat

症状： 传感器无法工作，出现 I2C 错误

解决方案：

  1. 确保 Base Hat 正确插在所有 GPIO 针脚上
  2. 检查树莓派和 Base Hat 是否有弯曲的针脚
  3. 启用 I2C 接口： 
    sudo raspi-config nonint do_i2c 0
sudo reboot
  4. 验证 I2C 工作：i2cdetect -y 1

问题：树莓派运行缓慢

症状： 用户界面卡顿，响应迟缓

解决方案：

  1. 检查 SD 卡速度（使用 10 级或更高，或通过 USB 使用 SSD）
  2. 释放磁盘空间：使用 df -h 检查，删除不必要的文件
  3. 如果不频繁使用摄像头/显示，减少 raspi-config 中 GPU 内存分配
  4. 关闭无用的应用程序
  5. 如果使用的是 Pi 3 或更早版本，考虑升级到带更多内存的 Pi 4

Wio Terminal

问题：Wio Terminal 屏幕保持空白

症状： 上传代码后无显示输出

解决方案：

  1. 检查代码是否初始化显示（如 TFT_eSPI 库）
  2. 从 Seeed Wiki 更新 Wio Terminal 固件
  3. 添加显示初始化代码： 
    #include <TFT_eSPI.h>
TFT_eSPI tft;
tft.begin();
tft.fillScreen(TFT_BLACK);
  4. 尝试用 PlatformIO 上传示例程序测试硬件

问题：Wio Terminal 无法连接 WiFi

症状： 无法连接 WiFi，网络错误

解决方案：

  1. 更新 WiFi 固件： 参考 Wio Terminal WiFi 固件升级指南
  2. 核对 WiFi 账号密码： 确保 SSID 和密码正确
  3. WiFi 频段： Wio Terminal 只支持 2.4GHz WiFi（不支持 5GHz）
  4. 信号强度： 设备靠近路由器
  5. 路由器设置： 企业/WPA-Enterprise 网络可能无法连接

问题：计算机无法识别 Wio Terminal

症状： USB 设备未被检测到

解决方案：

  1. 更换 USB 线： 使用数据线，非仅充电线
  2. 进入引导加载模式： 快速向下滑动电源开关两次
    • 蓝色 LED 会脉冲闪烁，设备在设备管理器显示为 “Arduino”
  3. 安装驱动（Windows）：
  4. 尝试不同 USB 端口： 避免使用 USB 集线器，直接连接
  5. 更新系统 USB 驱动

问题：Wio Terminal 传感器无法工作

症状： Grove 传感器无数据读取

解决方案：

  1. 检查 Grove 线连接
  2. 确认使用正确的 Grove 端口（左侧或右侧）
  3. 包含正确的传感器库
  4. 检查传感器的供电要求
  5. 使用库中的示例代码测试传感器

虚拟设备（CounterFit）

问题：CounterFit 应用无法启动

错误： 启动 CounterFit 时出现各种 Python 错误

解决方案：

  1. 确保虚拟环境已激活
  2. 安装/重新安装 CounterFit： 
    pip install CounterFit
  3. 检查端口 5000 是否被占用：
    • Windows: netstat -ano | findstr :5000
    • macOS/Linux: lsof -i :5000
  4. 结束占用端口 5000 的进程或使用其他端口： 
    counterfit --port 5001

问题：代码无法连接 CounterFit

错误： 连接被拒绝或超时

解决方案：

  1. 确认 CounterFit 正在运行：在浏览器访问 http://127.0.0.1:5000
  2. 检查代码中的连接 URL 是否与 CounterFit 地址匹配
  3. 确认防火墙未阻止连接
  4. 尝试重启 CounterFit 应用和代码

问题：CounterFit 中未显示传感器

症状： 创建的传感器不显示在 CounterFit 界面

解决方案：

  1. 在运行代码前先在 CounterFit UI 中创建传感器
  2. 刷新浏览器页面
  3. 检查传感器类型是否与代码期望匹配
  4. 清空浏览器缓存

连接问题

WiFi 连接

问题：设备无法连接 WiFi

症状： 连接超时，认证失败

解决方案：

  1. 核对 SSID 和密码： 确认凭据正确
  2. WiFi 频段： 大多数 IoT 设备仅支持 2.4GHz（不支持 5GHz）
  3. 路由器设置：
    • 关闭 AP 隔离（若启用）
    • 使用 WPA2-PSK 安全性（避免 WPA3、WEP 或开放网络）
    • 确保启用 DHCP
  4. 隐藏网络： 如果 SSID 隐藏，可能需要手动配置
  5. 信号强度： 设备靠近路由器
  6. 无线干扰： 其他设备、微波炉或墙壁可能干扰信号

问题：WiFi 连接频繁断开

症状： 连接不稳定，时断时连

解决方案：

  1. 检查路由器稳定性并考虑重启
  2. 更新设备固件
  3. 使用静态 IP 代替 DHCP
  4. 减小与路由器距离或添加 WiFi 扩展器
  5. 检查其他设备的干扰
  6. 核实电源供应是否充足（尤其是树莓派）

云服务

问题：无法连接 Azure IoT Hub

错误： 认证失败，连接被拒绝

解决方案：

  1. 核对凭据：
    • 检查连接字符串是否正确
    • 确保连接字符串中无额外空格或换行
  2. 设备注册： 设备必须在 IoT Hub 中注册
  3. 防火墙/代理： 确保允许出站 MQTT（端口 8883）或 HTTPS（端口 443）
  4. IoT Hub 区域： 确保 IoT Hub 正常运行，且不在不同区域导致延迟
  5. 配额限制： 检查是否超过免费层限制
  6. 测试连接： 
    az iot hub device-identity show-connection-string --hub-name YourIoTHub --device-id YourDevice

问题：Azure Functions 未触发

症状： 消息已发送但函数未执行

解决方案：

  1. 检查 Function App 是否正在运行（未停止）
  2. 验证 Function App 设置中的连接字符串
  3. 在 Azure 门户查看函数日志
  4. 确保已正确配置 Event Hub 兼容端点
  5. 确认消息格式符合函数预期
  6. 检查 Function App 服务计划（消费型与专用型）

MQTT

问题：MQTT 连接失败

错误： 连接被拒绝，身份验证失败

解决方案：

  1. 代理地址： 验证代理 URL/IP 是否正确
  2. 端口： 检查端口号（1883 为不加密，8883 为 TLS）
  3. 身份验证： 如需验证，核实用户名/密码
  4. TLS/SSL： 确保证书有效且受信任
  5. 防火墙： 检查端口是否被阻止
  6. 使用 MQTT 客户端测试： 使用 MQTT Explorer 或 mosquitto_pub/sub 测试

问题：未收到 MQTT 消息

症状： 发布了消息，但订阅者未收到

解决方案：

  1. 主题名称： 验证订阅者主题与发布者主题完全匹配
  2. QoS 级别： 尝试 QoS 1 或 2 替代 0
  3. 通配符： 检查主题通配符使用正确（+ 表示单层，# 表示多层）
  4. 保留消息： 发布者可设置保留标志以保留最后一条消息
  5. 连接时机： 确认订阅者在消息发布前已连接

传感器和执行器问题

Grove 传感器

问题：传感器返回错误值

症状： 读数为 0、-1 或无意义的值

解决方案：

  1. 检查连接： 确保传感器正确连接
  2. 正确端口： 验证传感器接入正确端口类型：
    • 模拟传感器 → 模拟端口（A0、A2、A4）
    • 数字传感器 → 数字端口（D5、D16、D18 等）
    • I2C 传感器 → I2C 端口
  3. 校准： 某些传感器需要校准（如土壤湿度、光照）
  4. 断电重连： 断开并重新连接传感器
  5. 传感器数据手册： 查阅传感器规格和要求

问题：电容式土壤湿度传感器总是显示潮湿

症状： 土壤干燥时传感器仍显示高湿度

解决方案：

  1. 需要校准： 土壤传感器需校准：
    • 在空气中读取值（干燥基线）
    • 在水中读取值（湿润基线）
    • 映射这两个值之间的读数
  2. 检查传感器涂层： 若涂层受损，湿度传感器可能性能下降
  3. 安装位置： 确保传感器完全插入土壤

问题：温湿度传感器读数错误

症状： DHT11/DHT22 显示错误温度或湿度

解决方案：

  1. 传感器位置： 避免阳光直射、热源或气流
  2. 预热时间： 传感器上电后等待 2 秒再读取
  3. 读取频率： DHT 传感器需要读取间隔（至少 2 秒）
  4. 检查冷凝水： 冷凝可能影响读数
  5. 传感器质量： DHT11 精度低于 DHT22

摄像头

问题：树莓派未检测到摄像头

错误： mmal: mmal_vc_component_create: failed to create component 'vc.ril.camera'

解决方案：

  1. 启用摄像头接口：

    sudo raspi-config

    进入 Interface Options → Camera → Enable

  2. 检查扁平电缆： 确保摄像头线正确插入

    • Pi Zero 上蓝色面朝向 USB 端口
    • Pi 4 上蓝色面背向 USB 端口

  3. 更新固件：

    sudo apt update
sudo apt full-upgrade
sudo reboot

  4. 测试摄像头：

    raspistill -o test.jpg

问题：摄像头图像质量差

症状： 模糊、暗淡或曝光不足的图像

解决方案：

  1. 对焦： 去除镜头保护膜，若可调节则调整对焦
  2. 光照： 确保光线充足
  3. 摄像头设置： 在代码中调整曝光、ISO、白平衡
  4. 稳定性： 固定摄像头，必要时使用三脚架
  5. 分辨率： 不要超过摄像头最大分辨率

麦克风和扬声器

问题：无音频输入/输出

症状： 麦克风无录音，扬声器无声音

解决方案：

  1. 检查连接： 确认音频设备正确连接

  2. 测试硬件：

    • 扬声器：speaker-test -t wav -c 2
    • 麦克风：arecord -l 查看设备，arecord test.wav 录音

  3. 音量设置： 检查并调整音量：

    alsamixer

  4. 选择音频设备： 在代码中指定正确的音频设备

  5. 驱动问题： 更新 ALSA 或重新安装音频驱动

问题：ReSpeaker 扩展板不起作用

症状： 音频设备未被检测到

解决方案：

  1. 安装驱动程序：

    git clone https://github.com/HinTak/seeed-voicecard
cd seeed-voicecard
sudo ./install.sh
sudo reboot

  2. 检查安装： arecord -l 应显示 ReSpeaker

  3. 更新固件： 某些 Pi OS 版本需更新驱动

  4. 检查插接： 确保扩展板正确插入 GPIO 针脚

开发环境问题

VS Code

问题：终端未自动激活虚拟环境

症状： 终端打开但虚拟环境未激活

解决方案：

  1. 设置 Python 解释器： 命令面板 → "Python: Select Interpreter" → 选择虚拟环境
  2. 选择后重启 VS Code
  3. 在 settings.json 中添加： 
    "python.terminal.activateEnvironment": true

问题：代码在设备上未运行

症状： 代码运行但设备无反应

解决方案：

  1. 确认代码已保存（查看文件标签上的点）
  2. 检查 Python 版本路径： 运行 which python 或 where python
  3. Wio Terminal： 确保代码通过 PlatformIO 上传（点击上传按钮）
  4. 树莓派： SSH 登录树莓派并在上面运行代码
  5. 检查输出窗口 是否有错误信息

问题：智能感知未显示库函数

症状： 导入模块未自动补全

解决方案：

  1. 确保库已安装于当前环境
  2. 重载 VS Code 窗口
  3. 检查 Python 解释器正确
  4. 安装类型声明（若有）：pip install types-<library-name>

Python 虚拟环境

问题：无法创建虚拟环境

错误： The virtual environment was not created successfully

解决方案：

  1. 安装 venv 模块：
    • Ubuntu/Debian: sudo apt install python3-venv
    • macOS: Python 自带，通常已包含
    • Windows: 重新安装完整的 Python
  2. 检查 Python 安装： 确保安装正确
  3. 使用完整路径： 试用 python3 -m venv .venv 明确调用 python3

问题：包安装到了错误的位置

症状： 安装包后导入失败

解决方案：

  1. 确认虚拟环境已激活： 命令提示符应显示 (.venv)
  2. 检查 pip 位置： which pip 应指向 .venv/bin/pip
  3. 激活 venv 后重新安装包： pip install <package>
  4. 虚拟环境中不要用 sudo 安装 pip 包

问题：虚拟环境不可移植

症状： 移动后或不同电脑上虚拟环境无法使用

解决方案：

  1. 不要移动虚拟环境文件夹： 删除后在新位置重新创建

  2. 使用 requirements.txt：

    pip freeze > requirements.txt
pip install -r requirements.txt

  3. 重新创建虚拟环境：

    python3 -m venv .venv
source .venv/bin/activate  # 或在 Windows 上使用 activate.bat
pip install -r requirements.txt

依赖项

问题：包安装失败

错误： 安装时出现各种 pip 错误

解决方案：

  1. 升级 pip：

    pip install --upgrade pip

  2. 安装编译工具：

    • Ubuntu/Debian: sudo apt install build-essential python3-dev
    • macOS: xcode-select --install
    • Windows: 安装 Visual Studio Build Tools

  3. 检查网络连接

  4. 尝试不同的包索引： pip install --index-url https://pypi.org/simple/ <package>

  5. 安装特定版本： pip install <package>==<version>

问题：依赖冲突

错误： ERROR: pip's dependency resolver does not currently take into account all the packages that are installed

解决方案：

  1. 为每个项目使用全新虚拟环境
  2. 更新包： pip install --upgrade <package>
  3. 检查依赖： 使用 pip check 查找冲突
  4. 安装兼容版本： 在 requirements.txt 指定版本范围

性能问题

问题：代码运行缓慢

症状： 延迟、超时、无响应

解决方案：

  1. 减少传感器读取频率： 避免过于频繁读取传感器
  2. 优化循环： 避免忙等待，使用 sleep() 或延时
  3. 内存问题：
    • 关闭不必要程序
    • 释放存储空间
    • 在树莓派上用 top 或 htop 监控
  4. SD 卡速度： 使用更快的 SD 卡或 SSD
  5. 网络延迟： 网络调用使用异步操作

问题：内存不足错误

错误： MemoryError 或系统卡死

解决方案：

  1. 树莓派：
    • 关闭不必要程序
    • 增加交换空间
    • 使用轻量版系统（Lite 版）
    • 升级内存（Pi 4 有 2/4/8GB 选项）
  2. Wio Terminal：
    • 减小缓冲区大小
    • 使用更小图片
    • 优化字符串使用
    • 检查内存泄漏（未释放内存）

问题：数据丢失或损坏

症状： 消息缺失，文件损坏

解决方案：

  1. SD 卡问题：
    • 使用质量可靠 SD 卡（避免廉价/仿冒）
    • 定期备份
    • 正确关机（避免断电）
  2. 缓冲区溢出： 增大代码中的缓冲区大小
  3. 网络可靠性： 实现重试逻辑和错误处理
  4. 服务质量： 重要消息使用 MQTT QoS 1 或 2

常见错误信息

ModuleNotFoundError: No module named 'X'

原因： 包未安装或虚拟环境未激活

解决方案：

pip install X

确保先激活虚拟环境。

Linux/macOS 上 Permission denied

原因： 需要提升权限或文件权限问题

解决方案：

  • 系统操作：使用 sudo
  • pip：虚拟环境中不要用 sudo，先激活虚拟环境
  • 串口权限：添加用户到 dialout 组：sudo usermod -a -G dialout $USER，然后注销重新登录

OSError: [Errno 98] Address already in use

原因： 端口已被其他进程占用

解决方案：

  1. 查找占用端口的进程：lsof -i :<port> 或 netstat -ano | findstr :<port>
  2. 结束进程或在代码中使用不同端口

SSL: CERTIFICATE_VERIFY_FAILED

原因： SSL 证书验证失败

解决方案：

  1. 更新证书：pip install --upgrade certifi
  2. 检查系统时间是否正确：date
  3. 仅限开发（非生产环境）：禁用代码中的验证

IndentationError: unexpected indent

原因： Python 缩进问题（混用制表符与空格）

解决方案：

  1. 使用统一缩进（Python 标准为 4 个空格）
  2. 配置编辑器使用空格替代制表符
  3. VS Code 设置 "editor.insertSpaces": true 和 "editor.tabSize": 4

UnicodeDecodeError 或 UnicodeEncodeError

原因： 字符编码问题

解决方案：

# 读取文件时
with open('file.txt', 'r', encoding='utf-8') as f:
    content = f.read()

# 写入文件时
with open('file.txt', 'w', encoding='utf-8') as f:
    f.write(content)

寻求帮助

如果尝试以上解决步骤后仍有问题：

1. 查看已有资源

2. 搜索类似问题

  • GitHub Issues： 搜索 现有问题
  • Stack Overflow： 搜索错误消息
  • 设备论坛： 查看树莓派论坛或 Arduino 论坛

3. 创建 GitHub Issue

如果找不到解决方法：

  1. 访问 GitHub Issues
  2. 点击“New Issue”
  3. 提供：
    • 清晰的问题描述
    • 重现步骤
    • 错误全日志
    • 硬件/软件版本
    • 已尝试的解决方法
    • 相关截图（如有）

4. 加入社区

5. 提供优质的错误报告

一个好的错误报告应包括：

  • 环境： 操作系统、Python 版本、使用的硬件
  • 复现步骤： 导致问题的具体步骤
  • 预期行为： 应该发生什么
  • 实际行为： 实际发生了什么
  • 错误信息： 完整的错误文本，不是截图
  • 代码： 能复现问题的最小代码示例

预防小贴士

一般最佳实践

  1. 保持备份： 定期备份正常工作的 SD 卡/代码
  2. 记录变更： 在注释中记录有效的方法
  3. 版本控制： 使用 git 跟踪代码变更
  4. 逐步测试： 在合并之前测试小的改动
  5. 阅读错误信息： 它们通常会告诉你具体问题所在
  6. 定期更新： 保持软件/固件的最新状态
  7. 使用高质量组件： 避免使用劣质数据线/电源
  8. 稳定供电： 使用适当的电源（尤其是树莓派）

开发工作流程

  1. 从简单开始： 先使用能正常运行的示例代码
  2. 一次改动一点： 更容易定位故障原因
  3. 频繁测试： 尽早发现问题
  4. 保持整洁： 逻辑性地组织文件和代码
  5. 注释代码： 未来的你会感激现在的努力

此故障排除指南由社区维护。如果您找到此处未列出的问题解决方案，请考虑贡献帮助更多人！

免责声明： 本文件使用 AI 翻译服务 Co-op Translator 进行翻译。虽然我们努力确保准确性，但请注意自动翻译可能包含错误或不准确之处。原始语言版本的文件应被视为权威来源。对于重要信息，建议使用专业人工翻译。因使用本翻译而产生的任何误解或误释，我们不承担任何责任。