1.UART-MCP Protocol Configuration Requirements

▫️Serial Port Configuration

• Serial pins: TXD/RXD
• Baud rate: 115200 (default, configurable)
• Data bits: 8
• Stop bits: 1
• Parity: none

▫️Firmware Requirements

• Firmware version V3.2 (beta, not an official release): Click to download
• Source code repository and branch: https://gitee.com/Ai-Thinker-Open/aipi-palchatv1

▫️Protocol Format Requirements

Interaction is carried out mainly in JSON format; the details of the protocol are covered in the rest of this document.

Note: every command must be followed by a carriage return and line feed: "\r\n", otherwise the command will not be executed.

None of the command examples listed in this document include the carriage return and line feed (to make testing with serial debugging tools easier), so please add them yourself.

🔹XiaoZhi AI Format

• Status reporting

{"role":"AI board","msgType":"status","status":"<message content>"}

Example command: Wi-Fi connected successfully

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

• MCP control command

{"role":"AI board","msgType":"MCP","MCP":"<message content>"}

Example command: turn on an LED

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

🔹MCU Sending Format

<command details> {"role":"MCU","msgType":"status","status":"<message content>"}

Example command: set the XiaoZhi AI volume to 70

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

2. XiaoZhi AI Status Replies and Control

▫️Success Response

Applies to all commands. After a command is executed successfully, XiaoZhi AI returns the following:

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

▫️Failure Response

Applies to all commands. After a command fails to execute, XiaoZhi AI returns the following:

{"role":"AI board","msgType":"status","status":"ERROR:<error message>"}

▫️AI Device Status Reporting

{"role":"AI board","msgType":"status","status":"<message content>"}

• role: the sender role, either "AI borad" or "MCU"
• msgType: the message type; "status" means a status message, mainly telling the MCU the module's current state
• status: the message content. The following values are fixed:
  • AI Start: AI device started
  • WIFI_CONNECTED: Wi-Fi connected successfully
  • WIFI_GOT_IP: Wi-Fi obtained an IP address
  • "1.WiFi connect OK":Wi-Fi connection complete
  • "2.WakeUP":waking up
  • "3.Sleep":sleeping
  • "4.NetCFG":network configuration in progress
  • "5.NetERR":network error
  • "6.OTAUPDATE":OTA update in progress
  • "7.OTA OK":OTA succeeded
  • "8.OTA ERR":OTA update failed
  • "ERROR:<error message>":other error messages

▫️Baud Rate Setting

The baudrate-set command sets the baud rate of XiaoZhi AI. Baud rate range: 300~2000000. The default baud rate is 115200.

baudrate-set {"role":"MCU","msgType":"status","status":<baud rate>}

Example command: set the baud rate to 115200

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

• Success response

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

After the baud rate is set successfully, XiaoZhi AI first returns a success message and then switches the baud rate to the target value. Note that after setting the baud rate, the MCU must also be set to the target baud rate, otherwise the MCU and the AI device cannot communicate with each other.

▫️Wake-up Control

The wake-up command controls whether XiaoZhi AI is awake. After waking up, XiaoZhi AI returns the 2.WakeUP status. The command is as follows:

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

timers: the wake-up duration, in s (seconds). Once this duration passes, XiaoZhi AI automatically exits the wake-up state. Using this command does not produce a wake-up prompt.

▫️Volume Control

🔹Volume Setting

The volume-set command sets the volume of XiaoZhi AI. Volume range: 0~100. The default volume is 70.

volume-set {"role":"MCU","msgType":"status","status":<volume value>}

Example command: set the volume to 70

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

• Success response

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

🔹Volume Query

The vvolume_check command queries the volume of XiaoZhi AI. Volume range: 0~100.

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

• Query success response

{"role":"AI board","msgType":"status","volume":<volume value>,"status":"OK"}

Example command:

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

• Query success response

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

3. MCP Interaction

▫️Reporting When MCP Is Empty

This firmware adds a MCP tools save feature. Every time XiaoZhi AI wakes up it reads the saved MCP tools; if there are no MCP tools, XiaoZhi AI reports the empty MCP tools status, and the MCU can use that status to detect that the device currently has no MCP tools and create them. The report format is as follows:

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

▫️Creating MCP Tools (sent by MCU)

The mcp-tool command is used by the MCU to create MCP tools. It must contain all tools — finish describing every tool before using this command:

mcp-tool {"role":"MCU","msgType":"MCP","MCP":{"tools":[<all tool descriptions>]}}

JSON data must not contain spaces/line breaks, otherwise command parsing will fail.

Example command: create an air-conditioner switch tool

mcp-tool {"role":"MCU","msgType":"MCP","MCP":{"tools":[{"name":"ACSwitch","description":"Tool for controlling the air conditioner switch, used to query and set the on/off state of the air conditioner","inputSchema":{"properties":{"enabled":{"description":"Used to turn the air conditioner on and off","type":"boolean"}}}}]}}

• Query success response

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

▫️Sending MCP Commands (sent by XiaoZhi AI)

After receiving a command, XiaoZhi AI parses it and sends it to the MCU. The MCU must respond within 5 seconds, otherwise the AI device reports a command timeout.

🔹Response Command Format

• Successful response, 5s timeout (MCU reports that control succeeded)

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

• Failed response, 5s timeout (MCU reports that control failed)

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

🔹Control Commands

{"role":"AI board","msgType":"MCP","MCP":{"params":{"name":"<tool name>","arguments":{"<command name>":<command argument>}}}}

• <tool name>: the tool name, created by the MCU; it is unique and must not be duplicated
• <command name>: the command name, created by the MCU as part of the tool; it is unique and must not be duplicated
• <command argument>: the command argument, produced by the command XiaoZhi AI sends, parsed and executed by the MCU

Example command: turn on the air-conditioner switch; corresponding tool example: Example command: create an air-conditioner switch tool

• Say to XiaoZhi AI: "Turn the air conditioner on for me"
• AI sends the command

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

• MCU responds that it turned on successfully (sent within 5s)

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

🔹Query Commands

Query commands are sent in the same format as control commands, except that the command argument is empty, as shown below:

{"role":"AI board","msgType":"MCP","MCP":{"params":{"name":"<tool name>","arguments":{}}}}

• Reply with the status within 5s

Reply "on" status

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

Reply "off" status

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

Reply numeric or string status

mcp-responsive {"role":"MCU","msgType":"status","status":"<status value>"}

Explanation of the fixed status

When the MCU creates an MCP tool, XiaoZhi AI does not parse the tool's detailed description. Therefore XiaoZhi AI cannot identify the type of each parameter and can only obtain the tool's return value through the status field, which is always a string.

Example command: reply that the air conditioner is on; corresponding tool example: Example command: create an air-conditioner switch tool

• Say to XiaoZhi AI: "Is the air conditioner on or off right now?"
• AI sends the command

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

• MCU responds that it turned on successfully (sent within 5s)

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

▫️Subtitle Output

During the conversation with XiaoZhi AI after wake-up, XiaoZhi AI outputs subtitles. The subtitle output format is as follows:

• Output when starting to speak a new sentence:

{"role":"AI board","msgType":"MCP Text","MCP Text":{"state":true,"emoji":"<emoji>","emotion":"<emotion>","text":"<subtitle text>"}}

Subtitle content description

• <emoji>: the emoji sent by the AI, for example: 😊
• <emotion>: the emotion sent by the AI, for example: happy
• <subtitle text>: the subtitle text sent by the AI, for example: Hello, I am XiaoZhi

• Output when the sentence ends and speaking stops:

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

4. ❌Restrictions

▫️Tool Name Restrictions

The following tool names or descriptions are built into XiaoZhi AI, used for volume adjustment and light testing. They must not be duplicated, to avoid control confusion:

1. Speaker tool: used to control volume
   • 扬声器 / speaker: description of the volume tool
   • volume: keyword of the volume query function
   • SetVolume: keyword of the volume setting function
2. Light tool: used to control the light
   • 控制是否打开灯光 / whether to turn the light on: description of the light tool
   • enabled: keyword of the light query function
   • SetEnabled: keyword of the light setting function

▫️Protocol Content Restrictions

1. JSON content must not contain spaces/line breaks, otherwise command parsing will fail. If you are using the cJSON library, use the cJSON_PrintUnformatted function to output the JSON data.
2. When the MCU sends a command, end the data with the carriage return and line feed characters \r\n, otherwise command parsing will fail.

▫️Subtitle Encoding Restrictions

Subtitles must be output in UTF-8 encoding, otherwise the subtitles will be garbled.

5. Interaction Flow

6.👉Questions or Feature Requests