杰理第三方APP通信协议设计说明文档

📎 原始文档：https://www.kdocs.cn/l/ci8tmK1MEAtZ

APP通信协议接口设计说明书

珠海市杰理科技股份有限公司

Zhuhai Jieli Technologyco.,LTD

版权所有，未经许可，禁止外传

版权所有，侵权必究
1
地址：珠海市吉大石花西路 107号9栋综合楼 邮编：519015
电话：0756-6313088 传真：0756-6313081
网站：www.zh-jieli.com

修改记录

版权所有，侵权必究
2
目录
1.文档介绍.............................................................................................................................................................................. 6

1. 1.文档目的................................................................................................................................................................... 6
   1.2.参考文献................................................................................................................................................................... 6
   1.3.术语与缩写词........................................................................................................................................................... 6
   2.功能概述和使用.................................................................................................................................................................. 6
2. 1.功能概述................................................................................................................................................................... 6
   2.2.使用说明................................................................................................................................................................. 7
   2.2. 1.板级配置................................................................................................................................................ 7
   2.2.2.开启对应协议功能................................................................................................................................ 9
   2.2.3.添加提示音资源文件............................................................................................................................ 9
   3.其他系统/模块的调用关系............................................................................................................................................... 10
   4.文件名说明与内容安排.................................................................................................................................................... 10
   5.消息模块介绍.....................................................................................................................................................................11
3. 1.公共通知消息类..................................................................................................................................................... 11
4. 1. 1.消息介绍............................................................................................................................................... 11
5. 1.2.接口介绍............................................................................................................................................... 11
6. 1.2. 1. app_pr。t。c。l_message_handler .................................................................................................. 11
   5.2. OTA通知消息类..................................................................................................................................................... 12
   5.2. 1.介绍....................................................................................................................................................... 12
   5.2.2.接口介绍.............................................................................................................................................. 13
   5.2.2. 1. app_pr。t。c。l_。ta_message_handler .......................................................................................... 13
   5.3. GMA私有消息........................................................................................................................................................ 13
   5.3. 1.消息列表.............................................................................................................................................. 13
   5.3.2.接口介绍.............................................................................................................................................. 14
   5.3.2. 1. static int gma_ special_message .................................................................................................. 14
   5.4. MMA私有消息....................................................................................................................................................... 14
   5.4.1.消息列表........................................................................................................................................... 1
   3 版权所有，侵权必究
   这部分消息是用于处理MMA一些独特的命令，或者以后需要协议扩展的命令。 ................................ 14
   5.4.2.接口介绍.............................................................................................................................................. 15
   5.4.2. 1. mma_ special_message ................................................................................................................15
   5.5. DMA私有消息........................................................................................................................................................ 15
   5.5. 1.消息列表.............................................................................................................................................. 15
   5.5.2.接口介绍.............................................................................................................................................. 16
   5.5.2. 1. duer。s_ special_message ............................................................................................................. 16
   6.与各具体协议中间层设计介绍........................................................................................................................................ 16
7. 1.概况......................................................................................................................................................................... 16
   6.2.参数配置接口......................................................................................................................................................... 17
   6.3.协议操作函数......................................................................................................................................................... 17
   6.4.协议回调接口注册函数......................................................................................................................................... 18
   7.提供给USER层使用的接口............................................................................................................................................18
8. 1.参数配置接口（在init之前）.............................................................................................................................. 18
9. 1. 1. app_pr。t。c。l_ set_pr。duct_ id ................................................................................................................ 18
10. 1.2. app_pr。t。c。l_ set_vend。r_ id ................................................................................................................. 19
11. 1.3. app_pr。t。c。l_ set_ l。cal_versi。n ............................................................................................................ 19
12. 1.4. app_pr。t。c。l_ set_ inf。_ gr。up................................................................................................................19
13. 1.5. app_pr。t。c。l_ set_tws_ sibling_mac ...................................................................................................... 20
    7.2.协议操作控制接口................................................................................................................................................. 20
    7.2. 1. app_pr。t。c。l_ ibeac。n_ switch ............................................................................................................... 20
    7.2.2. app_pr。t。c。l_ble_ adv_ switch ............................................................................................................... 20
    7.2.3. app_pr。t。c。l_ disc。nnect ....................................................................................................................... 21
    7.2.4. app_pr。t。c。l_ get_tws_ data_ f。r_ lib ...................................................................................................... 21
    7.2.5. app_pr。t。c。l_ send_v。ice_ data ............................................................................................................. 21
    7.2.6. app_pr。t。c。l_ check_ c。nnect_ success .................................................................................................. 22
    7.2.7. app_pr。t。c。l_ start_ speech_ cmd ........................................................................................................... 22
    7.2.8. app_pr。t。c。l_ st。p_ speech_ cmd ............................................................................................................23
    版权所有，侵权必究
    4
    7.3.回调函数说明......................................................................................................................................................... 23
    7.4. APP pr。t。c。l线程接口............................................................................................................................................23
    7.4. 1. app_pr。t。c。l_ inti; ..................................................................................................................................23
    7.4.2. app_pr。t。c。l_ exit .................................................................................................................................. 24
14. USER APP流程和一些接口............................................................................................................................................. 24
15. 1.公共流程................................................................................................................................................................. 24
16. 1. 1.协议栈流程.......................................................................................................................................... 24
17. 1.2.唤醒语音助手流程.............................................................................................................................. 26
18. 1.3.三元组烧写配置流程.......................................................................................................................... 27
19. 1.4.系统事件处理流程.............................................................................................................................. 27
    8.2.接口......................................................................................................................................................................... 27
    8.2. 1. app_pr。t。c。l_ set_v。lume ......................................................................................................................27
    8.2.2. app_pr。t。cal_ get_bat_by_type ..............................................................................................................28
    8.2.3. app_pr。t。cal_ get_ license_ptr ................................................................................................................28
    8.2.4. app_pr。t。c。l_ license2flash ................................................................................................................... 28
    8.2.5. app_pr。t。c。l_t。ne_register ................................................................................................................... 29
    8.2.6. mic_rec_pram_ init ................................................................................................................................. 30
    8.2.7. app_pr。t。c。l_handle_register ............................................................................................................... 30
    8.2.8. app_pr。t。c。l_tws_ sync_private_ deal ................................................................................................... 30
    8.2.9. app_pr。t。c。l_tws_rx_ data_private_ deal ...............................................................................................31
    8.2.10. app_pr。t。c。l_ sys_ event_private_ deal ................................................................................................ 31
    8.2. 11. app_pr。t。c。l_p。st_bt_ event ................................................................................................................31
    8.2. 12. app_pr。t。c。l_p。st_ app_ c。re_ callback ............................................................................................... 32
    8.2.13. app_pr。t。c。l_tws_ send_t。_ sibling.....................................................................................................32
    8.2. 14. app_pr。t。c。l_tws_ sync_ send ..............................................................................................................33
    版权所有，侵权必究
    5

1.文档介绍

介绍手机APP通信协议的API接口设计，API参数和反馈事件的意义。

1.1.文档目的

通过本文档熟悉各个手机APP通信协议API 的使用和注意事项。

1.2.参考文献

[ 1] .各家AI协议的网址和参考资料

1.3.术语与缩写词

2.功能概述和使用

2.1.功能概述

由于各个互联网公司的AI协议有较大差异，上层使用经常要用很多宏区分功能编译，这样就导致了一个代码的移植性很差。这个接口层设计是为上层应用提供相对比较统一的AI APP协议接口，屏蔽一些
版权所有，侵权必究 6
地址：珠海市吉大石花西路 107号9栋综合楼 邮编：519015
电话：0756-6313088 传真：0756-6313081
网站：www.zh-jieli.com
协议的细节,由库里面实现并抽象接口。提高上层应用代码和AI协议的可移植性。

2.2.使用说明

本说明以百度AI协议为例。

2.2.1.板级配置

相关板级配置在board_ac695x_smartbox.h 中。开启图片中所标识的宏。
版权所有，侵权必究 7

开启语音助手功能需要配置下面的宏，OPUS/SPEEX编码根据需要使能其中一个即可。

版权所有，侵权必究 8

2.2.2.开启对应协议功能

2.2.3.添加提示音资源文件

版权所有，侵权必究 9
3

4.文件名说明与内容安排

版权所有，侵权必究 l0

5.消息模块介绍

5.1.公共通知消息类

5.1.1.消息介绍

这类消息是每个APP协议都基本会有的状态通知消息。

1. //app protocol公共消息
2. enum {​
3. APP_PROTOCOL_COMMON_NOTICE = 0 ,
4. APP_PROTOCOL_CONNECTING, /保留，暂未使用/
5. APP_PROTOCOL_CONNECTED_BLE, /APP通过BLE连接成功状态更新/
6. APP_PROTOCOL_CONNECTED_SPP, /APP通过SPP连接成功状态更新/
7. APP_PROTOCOL_DISCONNECT, /APP连接断开状态更新/
8. APP_PROTOCOL_AUTH_PASS, /连接认证通过标识更新/
9. APP_PROTOCOL_SPEECH_START, /语音识别功能启动状态/
10. APP_PROTOCOL_SPEECH_STOP , /语音识别功能停止状态/
11. APP_PROTOCOL_SET_VOLUME, /app配置音量/
12. APP_PROTOCOL_GET_VOLUME, /app读取音量/
13. APP_PROTOCOL_GET_AUX_STATUS, /保留，暂未使用/
14. APP_PROTOCOL_LIB_TWS_DATA_SYNC, /需要更新给另一端tws数据/
15. APP_PROTOCOL_COMMON_NOTICE_END = 0x14F, 16. ​} ;
    这些消息主要在int app_protocol_message_handler(int opcode, const u8 *data, u32 len);函数中处理

5.1.2.接口介绍

[5.1.2.1. app_protocol_message_handler](5.1.2.1. app_protocol_message_handler)

版权所有，侵权必究 11

5.2. OTA通知消息类

5.2.1.介绍

这类消息是每个APP协议进行OTA升级时抽象出来的消息，用于通知上层状态和进度

1. enum {​
2. APP_PROTOCOL_OTA_COMMON_NOTICE = APP_PROTOCOL_COMMON_NOTICE_END + 1 , 3. APP_PROTOCOL_OTA_CHECK,
3. APP_PROTOCOL_OTA_GET_APP_VERSION ,
4. APP_PROTOCOL_OTA_CHECK_CRC,
5. APP_PROTOCOL_OTA_BEGIN,
6. APP_PROTOCOL_OTA_TRANS_DATA,
7. APP_PROTOCOL_OTA_PERCENT ,
8. APP_PROTOCOL_OTA_END,
9. APP_PROTOCOL_OTA_SUCCESS ,
10. APP_PROTOCOL_OTA_FAIL,
11. APP_PROTOCOL_OTA_CANCLE,
12. APP_PROTOCOL_OTA_REBOOT,
13. APP_PROTOCOL_OTA_COMMON_NOTICE_END = 0x1FF, 15. ​} ;
    这些消息主要在int app_ota_message_handler(int opcode, const u8 *data, u32 len)函数中处理
    版权所有，侵权必究 12

5.2.2.接口介绍

[5.2.2.1. app_protocol_ota_message_handler](5.2.2.1. app_protocol_ota_message_handler)

5.3. GMA私有消息

5.3.1.消息列表

这部分消息是用于处理GMA一些独特的命令，或者以后需要协议扩展的命令。

1. //GMA私有消息
2. enum {​
3. APP_PROTOCOL_GMA_NOTICE_BEGIN = GMA_HANDLER_ID,
4. APP_PROTOCOL_GMA_FMTX_SETFRE ,
5. APP_PROTOCOL_GMA_FMTX_GETFRE ,
6. APP_PROTOCOL_GMA_NOTICE_END = GMA_HANDLER_ID + 0xFF, 7. ​} ;
   这些消息主要在int gma_message_handler(int opcode, const u8 *data, u32 len)函数中处理
   版权所有，侵权必究 13

5.3.2.接口介绍

5.3.2.1. static int gma_special_message

5.4. MMA私有消息

5.4.1.消息列表

这部分消息是用于处理MMA一些独特的命令，或者以后需要协议扩展的命令。

1. //MMA私有消息
2. enum {​
3. APP_PROTOCOL_MMA_NOTICE = MMA_HANDLER_ID, 4. APP_PROTOCOL_MMA_SAVE_INFO,
4. APP_PROTOCOL_MMA_READ_INFO,
5. APP_PROTOCOL_MMA_SAVE_ADV_COUNTER,
6. APP_PROTOCOL_MMA_READ_ADV_COUNTER,
   
7. APP_PROTOCOL_MMA_NOTICE_END = MMA_HANDLER_ID + 0xFF, 9. ​} ;
   版权所有，侵权必究 14

5.4.2. 接口介绍

[5.4.2.1. mma_special_message](5.4.2.1. mma_special_message)

5.5. DMA私有消息

5.5.1.消息列表

这部分消息是用于处理DMA一些独特的命令，或者以后需要协议扩展的命令

1. //DMA私有消息
2. enum {​
3. APP_PROTOCOL_DMA_NOTICE = DMA_HANDLER_ID,
4. APP_PROTOCOL_DMA_SAVE_RAND,
5. APP_PROTOCOL_DMA_READ_RAND,
6. APP_PROTOCOL_DMA_TWS_SNED_RAND,
7. APP_PROTOCOL_DMA_NOTICE_END = DMA_HANDLER_ID + 0xFF, 8. ​} ;
   版权所有，侵权必究 15

5.5.2.接口介绍

5.5.2.1. dueros_special_message

6.与各具体协议中间层设计介绍

6.1.概况

每个协议的实现提供的接口需要根据app_profile_interface_t结构体来完成。为了能够支持同时支持多个协议组合，比如（DMA+JL rcsp ota），会有一个链表把这些结构体组织起来。每个协议会固定一个UUID，用于查找对应的协议接口组。但是协议只能支持一个连接。

1. #define DEMO_HANDLER_ID 0x300 /作为一个使用的例子，同时也可作为客户自己添加协议的ID/
2. #define GMA_HANDLER_ID 0x400 /阿里天猫协议接口 ID/
3. #define MMA_HANDLER_ID 0x500 /小米MMA协议接口 ID/
4. #define DMA_HANDLER_ID 0x600 /百度DMA协议接口 ID/
5. #define TME_HANDLER_ID 0x700 /腾讯酷狗TME协议接口 ID/
   
6. #define AMA_HANDLER_ID 0x800 /亚马逊的AMA协议接口 ID/

list_for_each_app_profile可以遍历所有支持的协议

版权所有，侵权必究 16

6.2.参数配置接口

1. struct app_protocol_info_t {​
   
2. /配置类接口/
3. void (*set_product_id)( u32 pid);
4. void (*set_vendor_id)(u32 vid);
5. void (*set_local_version) (u32 vid);
   
6. void (*set_special_info_group) (void *addr ) ;
7. void (*set_tws_sibling_mac) (void *mac) ; 8. ​} ;

6.3.协议操作函数

1. struct app_ctrl_operation_t {​
   [2.](2. int)[ int](2. int)(*protocol_init)();
   [3.](3. int)[ int](3. int)(*protocol_exit)();
   [4.](4. int)[ int](4. int)(*adv_enable)(int enable);
   [5.](5. int)[ int](5. int)(*ibeacon_adv)(int sw);
   [6.](6. int)[ int](6. int)(*regist_wakeup_send)(void *priv, void *cbk);
   [7.](7. int)[ int](7. int)(*regist_ recieve_cbk)(void *priv, void *cbk);
   [8.](8. int)[ int](8. int)(*latency_enable)(void *priv, u32 enable);
   [9.](9. int)[ int](9. int)(*send_data)(void *priv, void *buf, u16 len);
   [10.](10. int)[ int](10. int)(*send_voice_data)(void *buf, u16 len);
   [11.](11. int)[ int](11. int)(*disconnect)(void *addr);
   [12.](12. int)[ int](12. int)(*tws_receive_sync_data)(u8 *data, int len);
   [13.](13. int)[ int](13. int)(*get_auth_state)(void);
   [14.](14. int)[ int](14. int)(*start_voice_recognition)(int st); 15. ​} ;
   一般考虑连接的时候只有一个APP处于连接状态，所以发送的时候只有一个协议可以发送成功。
   版权所有，侵权必究 17
   

6.4.协议回调接口注册函数

1. struct callback_ register_t {​
2. void(*message_handler_regedit ) (int (*handler) (int id, int opcode, u8 *data, u32 len));
3. void(*check_tws_role_is_master_register) (bool (*handler) (void));
4. void(*tx_resume) (void (*handler) (void));
5. void(*rx_resume) (void (*handler) (void));
6. void(*get_battery) (bool (*handler) ( u8 battery_type, u8 *value)); 7. ​} ;
   蓝牙部门负责的APP协议开发要实现这三个结构体。提供对应参数的函数赋值给结构体使用。

7.提供给USER层使用的接口

7.1.参数配置接口（在init之前）

[7.1.1. app_protocol_set_product_id](7.1.1. app_protocol_set_product_id)

版权所有，侵权必究 18

[7.1.2. app_protocol_set_vendor_id](7.1.2. app_protocol_set_vendor_id)

[7.1.3. app_protocol_set_local_version](7.1.3. app_protocol_set_local_version)

[7.1.4. app_protocol_set_info_group](7.1.4. app_protocol_set_info_group)

版权所有，侵权必究 19

[7.1.5. app_protocol_set_tws_sibling_mac](7.1.5. app_protocol_set_tws_sibling_mac)

7.2.协议操作控制接口

[7.2.1. app_protocol_ibeacon_switch](7.2.1. app_protocol_ibeacon_switch)

[7.2.2. app_protocol_ble_adv_switch](7.2.2. app_protocol_ble_adv_switch)

版权所有，侵权必究 20

[7.2.3. app_protocol_disconnect](7.2.3. app_protocol_disconnect)

[7.2.4. app_protocol_get_tws_data_for_l](7.2.4. app_protocol_get_tws_data_for_l)ib

[7.2.5. app_protocol_send_voice_data](7.2.5. app_protocol_send_voice_data)

版权所有，侵权必究 21

[7.2.6. app_protocol_check_connect_success](7.2.6. app_protocol_check_connect_success)

[7.2.7. app_protocol_start_speech_cmd](7.2.7. app_protocol_start_speech_cmd)

版权所有，侵权必究 22

[7.2.8. app_protocol_stop_speech_cmd](7.2.8. app_protocol_stop_speech_cmd)

7.3.回调函数说明

7.4. APP protocol线程接口

[7.4.1. app_protocol_inti](7.4.1. app_protocol_inti);

版权所有，侵权必究 23

[7.4.2. app_protocol_exit](7.4.2. app_protocol_exit)

8. USER APP流程和一些接口

8.1.公共流程

8.1.1.协议栈流程

协议栈的流程如下图所示（以GMA为例）：
版权所有，侵权必究 24
蓝牙协议栈初始化完毕之后，调用app_protocol_init初始化第三方协议栈，在app_protocol_init里面，需要设置好参数配置的接口、协议操作函数的接口、 以及协议回调函数的接口。有三元组认证或者需要配置MAC地址的，也需要调用app->app_ctrl->protocol_init()前完成。初始化完毕后，会创建一个app_proto 的任务来运行协议栈，协议的具体命令在库里面执行。
协议栈运行过程中，可以使用app->app_ctrl类的接口来操控协议栈的状态，比如开关BLE广播、断开协议等。使用app->callback类的接口来获取协议栈的状态，或者回调协议栈所需要的信息。 比如通过 app_protocol_message_handler获取协议栈连接状态、获取或设置设备音量；通过app_protocol_get_battery 提供协议栈需要的电量信息。
调用app_protocol_exit可以退出第三方协议栈。
版权所有，侵权必究 25

8.1.2.唤醒语音助手流程

语音唤醒有两种方式：按键启动和APP启动。
按键启动时，调用app_protocol_start_speech_by_key 函数，会判断是否满足启动条件，满足条件后，会先退出sniff状态，然后播放提示音，如果TWS有连接的话，会同步播放。提示音播放完毕之后，通过 app_protocol_start_voice_recognition 函数上报启动的命令给手机，同时开启mic和opus/speex编码器，并将编码后的数据通过app_protocol_send_voice_data 函数上报手机。 收到手机停止命令或者8s超时后停止 mic和编码。
APP启动时，调用app_protocol_start_speech_by_app调用，如果有提示音，则播放提示音，无提示音或者播放完毕之后，启动mic和编码器。 收到手机停止命令或者8s超时后停止。
APP_PROTOCOL_SPEECH_EN为1时使能第三方语音助手功能，需要使能BT_MIC_EN， 以及 TCFG_ENC_OPUS_ENABLE/TCFG_ENC_SPEEX_ENABLE。 mic启动编码的超时时间由 APP_PROTOCOL_MIC_TIMEOUT决定。
版权所有，侵权必究 26

8.1.3.三元组烧写配置流程

不同协议的三元组认证格式、 内容各不相同，但是应用层的流程是一样的。使用烧写器烧写三元组时，三元组被会烧写在flash 的最后256byte 区域里面，ota升级之类的，不会擦写到该区域。
在协议初始化前，通过app_protocal_get_license_ptr 函数，获取三元组信息的指针。将三元组转化为程序里的格式后，调用app_protocol_set_info_group接口传递给协议栈。
调试时，可以直接将三元组信息转化成程序里的格式后，然后通过app_protocol_set_info_group接口传递给协议栈。
三元组烧写的具体流程，请参考《认证码烧写步骤说明.pdf》。三元组的获取方式查阅各个协议的说明文件和平台。

8.1.4.系统事件处理流程

第三方协议系统事件的统一在 app_protocol_sys_event_handler 函数里处理。 公共的处理流程在 app_protocol_common.c里面执行，非公共部分的处理流程，在各自的app_protocol_xxx.c文件里处理。
公共的系统事件主要是播放提示音、开关BLE广播、启动第三方语音助手等。具体如下：
（1）获取按键事件，启动第三方语音助手。
（2）连接/断开经典蓝牙、连接/断开手机APP、 手机APP启动助手时播放对应的提示音。
（3）通话时关闭BLE广播，通话结束时开启BLE广播。
（4）连接苹果时广播特殊内容。
（5）对耳连接、 断开或主从切换时开关广播。
（6）手机APP启动/停止第三方语音助手处理。

8.2.接口

[8.2.1. app_protocol_set_volume](8.2.1. app_protocol_set_volume)

版权所有，侵权必究 27

[8.2.2. app_protocal_get_bat_by_type](8.2.2. app_protocal_get_bat_by_type)

[8.2.3. app_protocal_get_l](8.2.3. app_protocal_get_l)icense_ptr

[8.2.4. app_protocol_l](8.2.4. app_protocol_l)icense2flash

版权所有，侵权必究 28

[8.2.5. app_protocol_tone_register](8.2.5. app_protocol_tone_register)

版权所有，侵权必究 29

8.2.6. mic_rec_pram_init

[8.2.7. app_protocol_handle_register](8.2.7. app_protocol_handle_register)

[8.2.8. app_protocol_tws_sync_private_deal](8.2.8. app_protocol_tws_sync_private_deal)

版权所有，侵权必究 30

[8.2.9. app_protocol_tws_rx_data_private_deal](8.2.9. app_protocol_tws_rx_data_private_deal)

[8.2.10. app_protocol_sys_event_private_deal](8.2.10. app_protocol_sys_event_private_deal)

[8.2.11. app_protocol_post_bt_event](8.2.11. app_protocol_post_bt_event)

版权所有，侵权必究 31

[8.2.12. app_protocol_post_app_core_callback](8.2.12. app_protocol_post_app_core_callback)

[8.2.13. app_protocol_tws_send_to_sibling](8.2.13. app_protocol_tws_send_to_sibling)

版权所有，侵权必究 32

[8.2.14. app_protocol_tws_sync_send](8.2.14. app_protocol_tws_sync_send)

版权所有，侵权必究 33