# xiaozhi-protocols

**Repository Path**: livehome/xiaozhi-protocols

## Basic Information

- **Project Name**: xiaozhi-protocols
- **Description**: 该项目用于统一不同语言下一致的小智交互协议，根据 xiaozhi-esp32 的 protocols 构造客户端的交互流程测试
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: py_master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-08-26
- **Last Updated**: 2025-09-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# XiaoZhi Protols 小智协议
该项目用于统一不同语言下一致的小智交互协议，根据[xiaozhi-esp32](https://github.com/78/xiaozhi-esp32)的protocols构造客户端的交互流程测试

# 使用方法
使用`uv`安装项目`uv venv && uv sync`,
`tests/instances.py`中更改配置参数，如`MAC_ADDR`等，
通过`pytest -s -v --tb=short`对全流程进行测试，可以根据不通过的测试查询原因

已经上传的`report.html`包含了大部分正确的结果和对应日志内容, 交互返回的内容也可以通过`basemodel`查看定义。

# 测试实例说明
主要分为两个通信方式, `mqtt+udp`以及`websocket`, 需要根据`ota`信息确定可以使用哪种方式，测试相关代码和文件都位于`tests`目录下

## Instances
定义设备配置信息和通信时需要暂存的所有内容

## OTA
测试的Fixture步骤, 需要通过`OTA_URL`获取`ota_info`, 分配给后续两种通信协议测试的地址和端口。

## MQTT+ UDP / Websocket
两种通信协议有稍许差别，但是交互顺序是完全一致的，根据测试函数来看
### Connection
建立连接，参考`test_mqtt_connection_mcp`和`test_handshake`
### Hello
发起通信，参考`test_hello`
### MCP Declare
MCP主要都是使用`JSON-RPC2.0`规范进行传输，查看`basemodel/jsonrpc`或者`mcp`标准来确定范式。
此处两种通信有些不同
* `mqtt+tcp`会在建立连接后服务器会主动向设备MCP问询相关功能
* `websocket`则是`hello`信息发送后才接收MCP问询。

相同处是都是由服务器主动问询，定义好回复即可，在通信阶段如果大模型判断有必要则会通过`tools/call`来请求设备返回结果。查看`test_start_listen_mcp`和`basemodel/server/request`。
### Listen
声明收音，查看`test_start_listen`和`test_start_listen_mcp`, 该阶段向服务器发送处于正在收音的状态。
### Chat
开始对话，查看`test_talk`，每次对话来回都以`tts stop`结尾。

注意
1. 在`udp`传输下只要是`realtime`模式必须持续传入`listen`数据, `websocket`可以等待。
2. 两种通信方式对音频帧的构造是不同的，可以通过查看`basemodel/audio`确认。
3. 音频的传输格式只支持`opus`，不同技术栈下自行实现。
### Goodbye
会话结束，查看`test_goodbye`，一般由服务器主动发起，在音频中明确传达了`结束/再见/退下`等意图时触发。

注意
* `mqtt+udp`的断开只有`udp`断开, `mqtt`会保持连接
* `websocket`的断开会断开长连接
# 时序图

## MQTT+UDP 通信时序图

```mermaid
sequenceDiagram
    participant Device as 设备端
    participant MQTT as MQTT服务器
    participant UDP as UDP服务器

    Note over Device,UDP: 1. 连接阶段
    Device->>MQTT: 连接MQTT服务器
    MQTT-->>Device: 连接成功
    Device->>MQTT: 订阅设备P2P消息
    
    Note over Device,UDP: 2. MCP初始化阶段
    MQTT->>Device: MCP初始化请求 (tools/initialize)
    Device-->>MQTT: MCP初始化响应
    MQTT->>Device: MCP工具列表请求 (tools/list)
    Device-->>MQTT: MCP工具列表响应

    Note over Device,UDP: 3. Hello握手阶段
    Device->>MQTT: Hello消息 (包含设备信息)
    MQTT-->>Device: Hello响应 (UDP地址/端口/加密信息)

    Note over Device,UDP: 4. Listen声明阶段
    Device->>MQTT: Listen消息 (state: start, mode: realtime)
    Device->>UDP: 建立UDP连接
    UDP-->>Device: UDP连接确认

    Note over Device,UDP: 5. Chat对话阶段
    loop 多轮对话
        Device->>UDP: 发送音频数据 (opus编码)
        MQTT->>Device: TTS开始消息
        
        opt MCP工具调用
            MQTT->>Device: MCP工具调用请求
            Device-->>MQTT: MCP工具响应
        end
        
        UDP->>Device: 返回音频数据
        MQTT->>Device: TTS结束消息
    end
    
    Note over Device,UDP: 6. Goodbye结束阶段
    alt 设备主动结束
        Device->>MQTT: Goodbye消息
    else 服务器主动结束
        MQTT->>Device: Goodbye消息
    end
    Device->>UDP: 关闭UDP连接
```

## WebSocket 通信时序图

```mermaid
sequenceDiagram
    participant Device as 设备端
    participant Server as Websocket服务器

    Note over Device,Server: 1. 连接阶段
    Device->>Server: WebSocket握手连接
    Server-->>Device: 连接成功

    Note over Device,Server: 2. Hello握手阶段
    Device->>Server: Hello消息 (包含设备信息)
    Server-->>Device: Hello响应 (包含会话ID)

    Note over Device,Server: 3. Listen声明阶段
    Device->>Server: Listen消息 (state: start, mode: realtime)
    
    Note over Device,Server: 4. MCP初始化阶段
    Server->>Device: MCP初始化请求 (tools/initialize)
    Device-->>Server: MCP初始化响应
    Server->>Device: MCP工具列表请求 (tools/list)
    Device-->>Server: MCP工具列表响应

    Note over Device,Server: 5. Chat对话阶段
    loop 音频数据传输
        Device->>Server: 发送音频数据 (二进制帧)
        Server->>Device: TTS开始消息
        opt MCP工具调用
            Server->>Device: MCP工具调用请求
            Device-->>Server: MCP工具响应
        end
        Server->>Device: 返回音频数据 (二进制帧)
        Server->>Device: TTS结束消息
    end
    
    Note over Device,Server: 6. Goodbye结束阶段
    alt 设备主动结束
        Device->>Server: Goodbye消息
    else 服务器主动结束
        Server->>Device: Goodbye消息
    end
    Device->>Server: 关闭WebSocket连接
```