# xiaozhi-protocols

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

## Basic Information

- **Project Name**: xiaozhi-protocols
- **Description**: No description available
- **Primary Language**: C
- **License**: Not specified
- **Default Branch**: c_master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-16
- **Last Updated**: 2025-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# XZ Protos - C版本协议定义

基于Python版本的协议定义，使用no-std方式编写的C协议库。支持所有协议，包括音频帧协议。
除了`audio.h`是字节帧构造, 其余的协议都采用json, 可以使用`cJSON`进行构造。

## 目录结构

```
basemodel_c/
├── basemodel.h          # 主头文件，包含所有协议定义
├── common.h             # 公共类型定义和枚举
├── audio.h              # 音频帧协议（WebSocket/UDP）
├── audio.c              # 音频帧协议实现
├── ota_info.h           # OTA更新配置信息协议
├── device/
│   ├── request.h        # 设备请求协议
│   └── response.h       # 设备响应协议
├── jsonrpc/
│   ├── notifications.h  # JSON-RPC通知协议
│   ├── requests.h       # JSON-RPC请求协议
│   └── responses.h      # JSON-RPC响应协议
├── server/
│   ├── notify.h         # 服务器通知协议
│   ├── request.h        # 服务器请求协议
│   └── response.h       # 服务器响应协议
├── example_json.c            # 主要协议使用示例
├── example_opus.c      # 音频协议使用示例
└── README.md            # 本文档
```

## 设计特性

### No-std设计
- 不依赖标准C库的动态内存分配
- 使用固定大小的数组和结构体
- 所有字符串使用固定长度的字符数组
- 音频帧使用`#pragma pack`确保字节对齐

### 类型安全
- 使用枚举类型确保消息类型、状态等的类型安全
- 使用typedef定义语义明确的类型别名
- 使用bool标志位表示可选字段的存在性

### 内存效率
- 合理的字符串长度限制
- 紧凑的结构体布局
- 避免不必要的填充
- 音频帧结构使用packed布局确保序列化一致性

## 主要协议类型

### 消息类型枚举
```c
typedef enum {
    MSG_TYPE_HELLO,     // Hello握手消息
    MSG_TYPE_LISTEN,    // 监听控制消息
    MSG_TYPE_TTS,       // 文本转语音消息
    MSG_TYPE_STT,       // 语音转文本消息
    MSG_TYPE_LLM,       // 大语言模型消息
    MSG_TYPE_MCP        // Model Context Protocol消息
} msg_type_t;
```

### 关键结构体

#### 音频帧协议
- `websocket_audio_frame_t`: WebSocket音频帧（协议版本2）
- `udp_audio_frame_header_t`: UDP音频帧头部（协议版本3）
- `udp_encryption_config_t`: UDP加密配置
- `udp_encrypted_audio_frame_t`: UDP加密音频帧

#### OTA信息协议
- `ota_info_t`: OTA更新配置信息
- `firmware_t`: 固件信息
- `mqtt_t`: MQTT连接配置
- `websocket_t`: WebSocket连接配置

#### 设备协议
- `hello_req_t` / `hello_resp_t`: 握手请求/响应
- `listen_req_t`: 监听控制请求
- `tts_resp_t` / `stt_resp_t` / `llm_resp_t`: 各种响应消息

#### JSON-RPC协议
- `jsonrpc_request_t`: 标准JSON-RPC请求
- `jsonrpc_response_t`: 标准JSON-RPC响应
- `jsonrpc_notification_t`: 标准JSON-RPC通知

#### MCP协议
- `mcp_initialize_req_t` / `mcp_initialize_resp_t`: MCP初始化
- `mcp_tools_list_req_t` / `mcp_tools_list_resp_t`: 工具列表
- `mcp_tools_call_req_t`: 工具调用

## 使用示例

```c
#include "basemodel.h"

// 创建WebSocket音频帧
websocket_audio_frame_t frame = {0};
uint8_t opus_data[] = {0x01, 0x02, 0x03, 0x04};
create_websocket_audio_frame(&frame, opus_data, sizeof(opus_data), 0);

// 序列化音频帧
uint8_t buffer[1024];
uint32_t size = serialize_websocket_audio_frame(&frame, buffer, sizeof(buffer));

// 创建Hello请求
hello_req_t hello_req = {
    .type = MSG_TYPE_HELLO,
    .version = 2,
    .features = {
        .aec = true,
        .mcp = true
    },
    .transport = "websocket",
    .audio_params = {
        .channels = 1,
        .format = "opus",
        .frame_duration = 60,
        .sample_rate = 16000
    }
};
```

## 字符串长度限制

| 类型 | 最大长度 | 用途 |
|------|----------|------|
| MAX_STRING_LEN | 256 | 通用字符串 |
| MAX_URL_LEN | 512 | URL地址 |
| MAX_TEXT_LEN | 1024 | 文本内容 |
| MAX_SESSION_ID_LEN | 64 | 会话ID |
| MAX_TOKEN_LEN | 256 | 认证令牌 |
| MAX_AUDIO_PAYLOAD_SIZE | 8192 | 音频载荷 |

## 音频协议特性

### WebSocket音频帧（协议版本2）
- 帧格式：`|version u16|type u16|reserved u32|timestamp u32|payload_size u32|payload [u8]|`
- 网络字节序（大端序）序列化
- 支持AEC时间戳
- Opus编码音频数据

### UDP加密音频帧（协议版本3）
- AES-CTR加密
- 动态nonce修改
- 序列号支持数据包排序
- 加密格式：`|modified_nonce[16]|encrypted_payload[...]|`

### 音频帧函数
- `create_websocket_audio_frame()`: 创建WebSocket音频帧
- `serialize_websocket_audio_frame()`: 序列化为字节流
- `deserialize_websocket_audio_frame()`: 从字节流反序列化
- `modify_nonce_for_encryption()`: 修改nonce用于加密
- `create_encryption_config_from_hex()`: 从十六进制字符串创建加密配置

## 与Python版本的对应关系

C版本协议与Python版本完全对应，主要差异：

1. **可选字段处理**: Python使用`Optional[T]`，C使用`bool has_xxx`标志位
2. **字符串类型**: Python使用`str`，C使用固定长度字符数组
3. **枚举类型**: Python使用`Literal`，C使用`enum`
4. **JSON数据**: Python使用`Dict[str, Any]`，C使用JSON字符串

## 编译要求

- 支持C99标准的编译器
- 包含`<stdint.h>`和`<stdbool.h>`头文件
- 不依赖动态内存分配（malloc/free）

## 注意事项

1. 所有字符串字段需要手动确保null终止
2. JSON字符串字段需要应用层进行序列化/反序列化, 推荐`cJSON`
3. 可选字段使用前需要检查对应的`has_xxx`标志位
4. 数组长度限制需要在使用时进行边界检查