extern_interface/docs/extern_interface.md

# 通讯模块文档

本文档主要描述Voix中的用于与遥测机及上位机进行通讯及相关附加功能的模块。
这些模块拆分自原host_com.cpp文件。

## 模块公开接口

以下接口由通讯模块公开，可以在VOIX主程序中使用。

1. `void extern_interface_init(const char* config_path, et_callback_t cb)`：模块初始化函数
    - `config_path`：配置文件路径
    - `cb`：回调函数，用于进行指令响应和遥测数据请求
2. `void (*et_callback_t)(uint32_t type, size_t len, union PacketData data)`：回调函数类型，内部数据为指针类型的数据包仅保证在回调函数中有效。
    - `type`：数据包类型
    - `len`：数据包长度，对于指针类型数据包，len为指针指向的数据长度，对于字符串类型数据包，len为字符串包含后缀`\0`的长度。
    - `data`：数据包数据
3. `union PacketData`：数据包定义
    - `pd_integer`：int64_t类型的数据
    - `pd_float`：double类型的数据
    - `pd_text`：const char*类型的数据
    - `pd_pointer`：void*类型的数据，
4. 数据包类型（宏定义）：
    - `ET_TYPE_NONE`：无数据
    - `ET_TYPE_TEXT`：文本，对应const char*类型的数据
    - `ET_TYPE_AUDIO`：音频，对应short*类型的数据
    - `ET_TYPE_COMMAND`：指令码，对应uint8_t[6]类型的数据
    - `ET_TYPE_ALARM`：告警码，对应uint8_t[4]类型的数据
    - `ET_TYPE_TELEMETRY_REQUEST`：遥测请求，对应void*类型的数据，需要主程序在数据包内的指针中写入对应的变量数据
5. `void send_data_packet(uint32_t type, size_t len, union PacketData data)`：发送数据包
    - `type`：数据包类型
    - `len`：数据包长度，对于指针类型数据包，len为指针指向的数据长度，对于字符串类型数据包，len为字符串包含后缀`\0`的长度。
    - `data`：数据包数据

## 外部依赖

通讯模块需要一些来自主程序的全局变量，主要用于生成遥测报文。

- `g_bKeepSysRuning`：系统运行状态标志
- `g_bCloseASR`：ASR关闭状态标志
- `g_iSysState`：系统状态
- `g_bVolumeKeyPressed`：静音按键状态标志
- `g_bWakeupKeyPressed`：唤醒按键状态标志
- `g_iVolumeGrade`：音量等级
- `g_iSysVerHigh`：系统版本号高8位
- `g_iSysVerLow`：系统版本号低8位
- `g_iAppVerHigh`：应用版本号高8位
- `g_iAppVerLow`：应用版本号低8位

以上全局变量通过回调函数中的遥测请求数据包获取。

## Transport模块

用于进行底层通讯的模块，包含comframe库、通讯线程及回调定义接口的封装。

主程序需要构建回调函数定义数组，并通过线程函数的参数传入。

### 公开接口

1. `void* transport_thread(void* arg)`：线程函数
    - `arg`：需要传入以零项作为结尾的`struct ComFrameTypeDef`结构体数组
2. `struct ComFrameTypeDef`：回调函数定义
    - `tp_id`：数据类型，与数据帧中的type对应
    - `tp_callback`：回调函数指针
    - `tp_flag`：类型回调标签，如 是否进行校验
3. `void (*tp_callback_t)(struct ComFrameTypeDef*, struct Comframe*)`：回调函数
    - `struct ComFrameTypeDef*`：回调函数定义结构体指针
    - `struct Comframe*`：数据帧
4. 回调标签（宏定义）：
    - `TP_FLAG_DEFAULT`：默认回调标签
    - `TP_FLAG_NOVERIFY`：不进行数据校验
    - `TP_FLAG_THREAD`：在独立线程中执行回调函数
    - `TP_FLAG_DISABLE`：禁用回调函数

## Telemetry模块

遥测模块，用于获取并同步遥测信息，并提供遥测回调函数。

### 公开接口

1. `void telemetry_handler(struct ComFrameTypeDef*, struct Comframe*)`：遥测请求回调函数

### 内部接口

1. `struct Telemetry`：遥测数据（遥测串口）
2. `struct UpperHostTelemetry`：遥测数据（上位机串口）
3. `void flush_telemetry_data()`：更新遥测数据（遥测串口）
4. `void flush_upper_host_telemetry_data()`：更新遥测数据（上位机串口）

## Command模块

用于定义命令回调函数，在transport模块中调用。

### 公开接口

1. `void command_handler(struct ComFrameTypeDef*, struct Comframe*)`：命令回调函数

### 内部接口

1. `struct CommandDef`：命令定义
    - `cmd_id`：命令ID
    - `cmd_callback`：回调函数指针
2. `void (*cmd_callback_t)(uint8_t[])`：命令回调函数

## Alarm模块

用于定义告警回调函数，在transport模块中调用。

### 公开接口

1. `void alarm_handler(struct ComFrameTypeDef*, struct Comframe*)`：告警回调函数

### 内部接口

1. `struct AlarmDef`：告警定义
    - `alarm_id`：告警ID
    - `alarm_text`：告警文本

## TypeHandler模块

用于定义除遥测请求及告警信息外的其他回调函数，在transport模块中调用。

### 公开接口

1. `void speech_injected_handler(struct ComFrameTypeDef*, struct Comframe*)`：语音注入回调函数
2. `void audio_handler(struct ComFrameTypeDef*, struct Comframe*)`：语音数据回调函数
3. `void grant_time_handler(struct ComFrameTypeDef*, struct Comframe*)`：授时回调函数