前言

在语音产品开发过程中，命令词配置是最基础也是最容易出现问题的一环。许多开发者遇到的问题并非模组硬件故障，而是配置细节处理不当。本文基于近期技术交流群中的五个真实案例，系统讲解常见命令词配置问题的排查思路与解决方案。

案例一：免唤醒命令词无响应的完整排查

问题现象

用户反馈：设置好的免唤醒命令词完全没有反应，但唤醒词可以正常响应。

根因分析

根据官方文档， 命令词不能包含标点符号（空格、逗号、句号等）。这是导致免唤醒词失效的最常见原因。

官方规范：

• 命令词中不能有空格、逗号、句号等标点符号
• CI系列多单词命令词需用中横线 -连接（如 OPEN-DOOR）
• SU系列多单词命令词用空格分隔（如 open door）

排查步骤

1. 检查命令词格式

• 确认命令词中是否包含标点符号
• 检查是否有不必要的空格

1. 验证词条有效性

• 将疑似有问题的命令词复制到回复语中
• 如果能播报说明词条本身有效，问题在配置

1. 对比测试

• 测试一个简单的命令词（如"打开"）验证功能
• 确认是词条问题还是其他配置问题

解决方案

CI系列英文命令词格式规范

正确格式：HELLO-AIR-CONDITIONING
错误格式：HELLO AIR CONDITIONING  # SU系列才用空格
错误格式：hello_air_conditioning  # 不用下划线

案例二：防误识别词对免唤醒词无效问题

问题现象

用户配置了防误识别词"please open"，但免唤醒词"please open oven"仍然能被误触发"please open"。

根本原因

防误识别词的工作原理是 降低匹配度，而非完全屏蔽。当目标命令词与防误识别词发音差异较大时，防误效果有限。

技术原理

用户说的：please open oven
目标命令：please open oven（相似度100%）
防误词条：please open（相似度约60%）

在这种情况下，"please open oven"与目标命令的相似度远高于防误词条，所以防误效果有限。

三种解决方案

方案一：添加更多防误识别词

please open | peace open | pleas open

方案二：调整特定命令词阈值

• 在平台中找到该命令词的"特定命令词阈值"设置
• 适当调低灵敏度（数值调大）

方案三：优化命令词设计

原命令：please open oven
优化后：turn on oven / activate oven

配置检查清单

• 防误识别词是否包含相似发音的多个变体
• 是否考虑了口音差异（如peace vs please）
• 命令词本身是否与日常用语过于接近
• 是否尝试过调整特定命令词阈值

案例三：舵机只往一个方向转动的360°/180°识别问题

问题现象

用户使用SG90舵机，按教程配置后，命令执行有回复但舵机只往一个方向转动然后停止，无法实现来回摇摆。

根本原因

SG90舵机有180度和360度两种版本，用户可能购买了360度版本而使用的是180度教程配置。

区分方法

解决方案

确认舵机类型后再配置：

1. 手动测试：用手转动舵机，180度版本有机械限位
2. 观察外观：部分360度版本会有标识
3. 更换配置：确认类型后使用对应的配置方法

PWM配置对比

180度舵机：
- PWM周期：20ms（50Hz）
- 控制范围：0.5ms~2.5ms高电平
- 对应角度：0°~180°
360度舵机：
- PWM周期：20ms（50Hz）
- 1.5ms高电平：停止
- <1.5ms：一个方向旋转
- >1.5ms：另一个方向旋转

案例四：UART0与UART1串口选择困惑

问题现象

用户疑问："UART0是烧录脚，UART1是发送脚，所以控制详情中应该配置为UART1吗？"

正确理解

UART0和UART1都可以配置为串口输出，烧录口配置只影响日志输出，不影响烧录功能。

引脚功能对照

配置建议

• 调试阶段：配置UART0为烧录口，方便查看日志
• 应用阶段：根据实际通信需求选择UART0或UART1
• 双串口需求：部分模组支持UART0和UART1同时使用

案例五：串口输入条件判断配置位置

问题现象

用户反馈："不知道在哪里写条件，比如当输入的16进制数为多少时触发一个动作。"

正确配置流程

串口输入触发的条件判断不在串口输入配置中，而是在 命令词的条件判断中配置。

完整配置步骤

1. 启用串口输入

``    版本配置 → 事件触发 → 添加事件触发    触发类型：串口输入    串口选择：UART1    消息号：01    ``

1. 配置参数赋给变量

``    控制详情 → 添加控制 → 参数赋给变量    输入参数：消息号01的参数值    目标变量：var1    ``

1. 添加条件判断

``    控制详情 → 添加控制 → 条件判断    条件：当变量var1等于0x01时    执行动作：GPIO输出/串口输出等    ``

数据帧格式

输入格式：AA 55 [消息号] [参数值] 55 AA
示例：AA 55 01 01 55 AA（消息号01，参数值01）

通用排查流程图

发现问题
    │
    ├─→ 命令词无响应？
    │      ├─→ 检查标点符号
    │      ├─→ 验证词条有效性
    │      └─→ 对比测试简单命令
    │
    ├─→ 误识别问题？
    │      ├─→ 检查命令词相似度
    │      ├─→ 添加防误识别词
    │      └─→ 调整特定命令词阈值
    │
    ├─→ 硬件不工作？
    │      ├─→ 确认硬件型号
    │      ├─→ 检查接线是否正确
    │      └─→ 验证配置参数匹配
    │
    └─→ 找不到配置位置？
           ├─→ 参考官方文档
           ├─→ 查看配置流程图
           └─→ 咨询技术支持

命令词配置速查表

中文命令词规范

英文命令词规范（CI系列）

英文命令词规范（SU系列）

总结

命令词配置问题的核心在于 遵循规范和 系统排查：

1. 格式第一：严格按照官方规范编写命令词，避免标点符号
2. 系统排查：遇到问题时从最简单的配置开始验证
3. 善用工具：利用平台的验证功能和日志输出定位问题
4. 参考文档：遇到不确定的配置先查阅官方FAQ
5. 寻求支持：技术交流群和官方客服都是可用的求助渠道

经验之谈：大多数配置问题都源于对规则的理解偏差。在遇到问题时，先用一个最简单的示例验证功能是否正常，再逐步恢复复杂配置，往往能快速定位问题所在。

参考资料

• SmartPi平台配置参数详解： /docs/platform-configuration/firmware-config-parameters.md
• SU-03T平台与固件FAQ： /docs/faq-platform-and-firmware/faq-platform-and-firmware-su-03t.md
• CI-03T语音调优FAQ： /docs/faq-voice-tuning/faq-voice-tuning-ci-03t.md