1.UART-MCP 协议配置要求

▫️串口配置

• 串口引脚：TXD/RXD
• 波特率：115200（默认，可配置）
• 数据位：8
• 停止位：1
• 校验位：无

▫️固件要求

• 固件版本 V2.8（测试版，非官方正式固件）：点击下载
• 源码地址及分支：https://gitee.com/Ai-Thinker-Open/aipi-palchatv1

▫️协议格式要求

交互的协议主要以JSON格式进行交互，协议详情见本文剩余内容。

注意：每个指令发送后都需要加回车换行符："\r\n"，否则指令无法执行。

本文所列举的所有指令示例均未包含回车换行符（方便串口调试工具测试），请自行添加。

🔹小安 AI格式

• 状态下发

{"role":"AI board","msgType":"status","status":"<消息内容>"}

指令示例：WiFi 连接成功

{"role":"AI board","msgType":"status","status":"1.WiFi connect OK"}

• MCP 控制指令

{"role":"AI board","msgType":"MCP","MCP":"<消息内容>"}

指令示例：点亮LED灯

{"role":"AI board","msgType":"MCP","MCP":{"params": {"name": "setLED","arguments":{"enable":true}}}}

🔹MCU 发送格式

<指令详情> {"role":"MCU","msgType":"status","status":"<消息内容>"}

指令示例：设置 小安 AI音量 70

volume_set {"role":"MCU","msgType":"status","status":70}

2. 小安 AI 状态回复与控制

▫️设置成功响应

适用于所有指令，当时指令执行成功后，小安 AI 会返回以下格式：

{"role":"AI board","msgType":"status","status":"OK"}

▫️设置失败响应

适用于所有指令，当时指令执行失败后，小安 AI 会返回以下格式：

{"role":"AI board","msgType":"status","status":"ERROR:<错误信息>"}

▫️AI设备状态下发

{"role":"AI board","msgType":"status","status":"<消息内容>"}

• role: 发送者角色，"AI borad" 或 "MCU"
• msgType: 消息类型，"status" 代表的是状态消息，主要告知 MCU 模组当前状态
• status：消息内容信息，固定以下内容：
  • AI Start: AI设备启动
  • WIFI_CONNECTED: WiFi 连接成功
  • WIFI_GOT_IP: WiFi 获取IP成功
  • "1.WiFi connect OK":WiFi 连接完成
  • "2.WakeUP":唤醒中
  • "3.Sleep":睡眠中
  • "4.NetCFG":配网中
  • "5.NetERR":网络错误
  • "6.OTAUPDATE":OTA升级中
  • "7.OTA OK":OTA 成功
  • "8.OTA ERR":OTA 升级失败
  • "ERROR:<错误信息>":其他错误信息

▫️波特率设置

baudrate-set 指令用于设置 小安 AI 的波特率，波特率范围：300~2000000。默认波特率为115200。

baudrate-set {"role":"MCU","msgType":"status","status":<波特率>}

指令示例：设置波特率为115200

baudrate-set {"role":"MCU","msgType":"status","status":115200}

• 设置成功响应

{"role":"AI board","msgType":"status","status":"OK"}

波特率设置成功之后，小安 AI 会先返回设置成功消息，随后把波特率设置成目标值。请注意，波特率设置后，MCU 也应当设置成目标波特率，否则 MCU 与 AI 设备之间无法通信。

▫️控制唤醒

wake-up 指令用于控制 小安 AI 的唤醒，唤醒后小安 AI 会返回 2.WakeUP 状态。指令如下：

wake-up {"role":"MCU","msgType":"wake-up","wake-up":<timers>}

timers: 唤醒时长，单位 s(秒)，超过此时长，小安AI 会自动退出唤醒状态。使用该指令不会有唤醒提示。

▫️音量控制

🔹音量设置

volume-set 指令用于设置 小安 AI 的音量，音量范围：0~100。默认音量为 70。

volume-set {"role":"MCU","msgType":"status","status":<音量值>}

指令示例：设置音量为70

volume-set {"role":"MCU","msgType":"status","status":70}

• 设置成功响应

{"role":"AI board","msgType":"status","volume":70,"status":"OK"}

🔹音量查询

vvolume_check 指令用于查询 小安 AI 的音量，音量范围：0~100。

volume-check {"role":"MCU","msgType":"status"}

• 查询成功响应

{"role":"AI board","msgType":"status","volume":<音量值>,"status":"OK"}

指令示例：

volume-check {"role":"MCU","msgType":"status"}

• 查询成功响应

{"role":"AI board","msgType":"status","volume":70,"status":"OK"}

3. MCP 交互

▫️MCP为空时的上报

本固件做了 MCP 工具保存功能，当小安 AI 每次唤醒时会读取保存的 MCP 工具，如果 MCP 工具为空时，小安 AI 会上报 MCP 工具为空的状态，MCU 可以通过该状态识别到当前设备没有 MCP 工具，从而创建 MCP 工具。上报的格式如下：

{"role":"AI board","msgType":"status","status":"ERROR:Tools NULL"}

▫️创建 MCP 工具（MCU 发送）

mcp-tool 指令用于 MCU 创建 MCP 工具，需包含所有工具，完成所有工具描述后再使用该指令：

mcp-tool {"role":"MCU","msgType":"MCP","MCP":{"tools":[<所有工具描述>]}}

json 数据当中不能空格/换行，否则会导致指令解析失败。

指令示例：创建空调开关工具

mcp-tool {"role":"MCU","msgType":"MCP","MCP":{"tools":[{"name":"ACSwitch","description":"空调开关控制工具，用于查询和设置空调的开关状态","inputSchema":{"properties":{"enabled":{"description":"用于控制空调打开和关闭","type":"boolean"}}}}]}}

• 查询成功响应

{"role":"AI board","msgType":"status","status":"OK"}

▫️MCP 指令下发（小安 AI 发送）

小安 AI 接收到指令之后，会解析出指令，并发送给 MCU，MCU 必须在5 秒内响应指令，否则 AI 设备会报告指令超时。

🔹响应指令格式

• 响应成功回复，超时时间 5s (MCU控制成功回复)

mcp-responsive {"role":"MCU","msgType":"status","status":"true"}

• 响应失败，超时时间 5s(MCU控制失败回复)

mcp-responsive {"role":"MCU","msgType":"status","status":"false"}

🔹控制指令

{"role":"AI board","msgType":"MCP","MCP":{"params":{"name":"<工具名称>","arguments":{"<指令名称>":<指令参数>}}}}

• <工具名称>: 工具名称，由 MCU 创建的工具名称，具有唯一性，且不可重复
• <指令名称>: 指令名称，由 MCU 创建的工具指令名称，具有唯一性，且不可重复
• <指令参数>: 指令参数，由小安 AI 下发的指令结果，由 MCU 解析并执行

指令示例：打开空调开关，对应工具示例：指令示例：创建空调开关工具

• 与小安 AI 说：“帮我打开空调”
• AI 发送指令

{"role":"AI board","msgType":"MCP","MCP":{"params":{"name":"ACSwitch","arguments":{"enabled":true}}}}

• MCU 响应打开成功（5s 内发送）

mcp-responsive {"role":"MCU","msgType":"status","status":"true"}

🔹查询指令

查询指令下发格式与控制指令格式相同，只是指令参数为空，如下：

{"role":"AI board","msgType":"MCP","MCP":{"params":{"name":"<工具名称>","arguments":{}}}}

• 回复状态，5s 内回复

回复开启状态

mcp-responsive {"role":"MCU","msgType":"status","status":"true"}

回复关闭状态

mcp-responsive {"role":"MCU","msgType":"status","status":"false"}

回复数字型、字符串型状态

mcp-responsive {"role":"MCU","msgType":"status","status":"<状态值>"}

关于固定status的解释说明

MCU 创建 MCP 工具时，小安 AI 不会解析工具的具体描述，因此，小安 AI 无法识别各个参数的类型，只能通过 status 字段来获取工具的返回值，并且固定为字符串类型。

指令示例：回复空调打开，对应工具示例：指令示例：创建空调开关工具

• 与小安 AI 说：“空调现在是开的还关的？”
• AI 发送指令

{"role":"AI board","msgType":"MCP","MCP":{"params":{"name":"ACSwitch","arguments":{}}}}

• MCU 响应打开成功（5s 内发送）

mcp-responsive {"role":"MCU","msgType":"status","status":"true"}

▫️字幕输出

唤醒之后与小安AI的对话过程中，小安AI会输出字幕，字幕输出格式如下：

• 开始说新的句子时输出：

{"role":"AI board","msgType":"MCP Text","MCP Text":{"state":true,"emoji":"<表情>","emotion":"<心情>","text":"<字幕内容>"}}

字幕内容说明

• <表情>: 表情，由 AI 下发的 emoji 表情，如：😊
• <心情>: 心情，由 AI 下发的 emotion 表情，如：happy
• <字幕内容>: 字幕内容，由 AI 下发的字幕内容，如：你好，我是小安

• 结束句子说话结束时输出：

{"role":"AI board","msgType":"MCP Text","MCP Text":{"state":false}}

4. ❌限制条件

▫️工具名称限制

以下工具名称或描述为小安 AI内置工具，用于调节音量和点灯测试，不可重复，以免控制混淆：

1. Speaker工具：用于控制音量
   • 扬声器: 音量工具的描述
   • volume: 音量查询功能的关键字
   • SetVolume: 音量设置功能的关键字
2. Light工具：用于控制灯
   • 控制是否打开灯光: 灯工具的描述
   • enabled: 灯查询功能的关键字
   • SetEnabled: 灯设置功能的关键字

▫️协议内容限制

1. JSON 内容中不能包含空格/换行，否则会导致指令解析失败。如果使用的时 cJSON 库，请使用 cJSON_PrintUnformatted 函数输出 json 数据。
2. MCU 发送指令时，在数据接发送时使用回车换行符 \r\n 作为结尾，否则会导致指令解析失败。

▫️字幕编码限制

字幕输出时，使用 UTF-8 编码，否则会导致字幕乱码。

5.交互流程

6.👉问题或需求反馈