1. 概述
- 1.1 集成说明
- 1.2 错误码说明
2. 音频播控
3. 文本交互
4. 事件触发
5. 事件监听
6. 系统信息
7. 经典蓝牙
8. IoT控制
9. 闹钟倒计时
10. 命令行操作

1. 概述

面向天猫精灵语音芯片生态提供AliGenie SDK，其中的开放API 是天猫精灵对外提供AIoT能力的接口，生态产品可以在二次开发中调用相关接口实现自己的业务能力，例如播放 TTS，例如设置音量，例如触发唤醒事件。

AliGenie SDK中开放 API 主要分为以下几类：

音频播控
文本交互
触发事件
监听事件
系统信息
经典蓝牙
IoT控制
闹钟倒计时

本文对上述几类开放 API 的功能、参数、返回值进行说明。同时，AliGenie SDK提供了一套CLI命令，用于业务应用和系统调试。

Aligenie SDK的更新日志请参见《AliGenie SDK版本更新记录》。

1.1 集成说明

生态产品集成AliGenie SDK时，需要引用头文件：ag_open_api.h，链接库：libagopenapi.so或者libagopenapi.a。除此之外，Linux平台还需要链接一些标准库：dl、pthread、stdc++、m，否则链接时有可能出现动态库找不到的警告以及找不到标准库符号的错误。RTOS平台使用生态开放接口之前，需要先调用int ag_open_api_init(void);接口来进行初始化，以拉起AliGenie SDK核心模块。

1.2 错误码说明

大多数接口都支持异常错误码，以下是错误码的定义。

enum RES_CODE {
    /*
     * It means function is called finished but not sure
     * success or not, because these APIs are asynchronous.
     * All you can do is to read detail notes of API that you called.
     */
    RES_CODE_DONE = 1,
    /* Called successfully. Always comes from synchronous API */
    RES_CODE_SUCCESS = 0,
    /* do function failed */
    RES_CODE_FAIL = -1,
    /* function or feature is unsupported */
    RES_CODE_UNSUPPORTED_FEATURES = -2,
    /* Genie is not ready to be called */
    RES_CODE_UNINITIALIZED = -3,
    /* invalid parameter */
    RES_CODE_INVALID_PARAMETER = -4,
    /* softbus timeout (RTOS has no softbus) */
    RES_CODE_SOFTBUS_TIMEOUT = -5,
    /* network is disconected */
    RES_CODE_NET_DISCONNNECTED = -6,
    /* network request timeout */
    RES_CODE_NET_TIMEOUT = -7,
};

有些接口是异步的，因此返回 RES_CODE_DONE 只表示调用完成，但并不保证是否能正常执行。

2. 音频播控

2.1 播放

函数原型：
int ag_audio_play(const char *url, const AG_AUDIO_TYPE type);
功能描述：
播放音乐（URL）、提示音（Prompt）。支持离线播放本地音乐。异步播放，即提交播放请求后直接返回，不等待播放结束。播放音乐、提示音的控制逻辑会有些不同。
- URL：音乐播放，被打断后可自动恢复。
- Prompt：提示音播放，只播放一次，被打断不可恢复，例如暂停、停止等播控。

函数参数：

url：需要播放的音频的绝对路径，可以是本地文件，也可以是云端链接

type：播放类型

typedef enum {
AG_AUDIO_TYPE_URL = 0,
AG_AUDIO_TYPE_PROMPT,
AG_AUDIO_TYPE_TTS, /* 本地流式播放，暂不支持 */
} AG_AUDIO_TYPE;

返回值：
- 成功返回当次播放的ID (>0)，失败返回负数，请参考错误码 enum RES_CODE。
- 此为异步接口，获取到播放ID不表示播放成功。可通过 事件监听 章节获取播放器状态进而判定结果。

2.2 停止播放

函数原型：
int ag_audio_stop();
功能描述：停止所有音频播放。
返回值：
- 成功返回 RES_CODE_DONE，失败返回负数，请参考错误码 enum RES_CODE。
- 此为异步接口。可通过 事件监听 章节获取播放器状态进而判定结果。

2.3 暂停播放

函数原型：
int ag_audio_pause();
功能描述：暂停所有音频播放，URL、本地音乐暂停后可以续播。
返回值：
- 成功返回 RES_CODE_DONE，失败返回负数，请参考错误码 enum RES_CODE。
- 此为异步接口。可通过 事件监听 章节获取播放器状态进而判定结果。

2.4 恢复播放

函数原型：
int ag_audio_resume();
功能描述：恢复URL、本地音乐播放，是ag_audio_pause()的逆过程，不适用于ag_audio_suspend()。
返回值：
- 成功返回 RES_CODE_DONE，失败返回负数，请参考错误码 enum RES_CODE。
- 此为异步接口。可通过 事件监听 章节获取播放器状态进而判定结果。

2.5 自动恢复播放

函数原型：
int ag_audio_suspend();
功能描述：
播放URL、本地音乐时，挂起当前播放音频。期间可播放一个提示音。在播放完提示音后自动恢复音乐播放。目前SDK会自动调用此函数，不需要外部再次调用。
返回值：
- 成功返回 RES_CODE_DONE，失败返回负数，请参考错误码 enum RES_CODE。
- 此为异步接口。可通过 事件监听 章节获取播放器状态进而判定结果。

2.6 获取播放进度

函数原型：
int ag_audio_get_play_progress();
功能描述：获取URL、本地音乐播放进度。
返回值：
- 成功返回当前播放进度（ms），失败返回负数，请参考错误码 enum RES_CODE。
- 当没有播放时，返回 0 。

2.7 获取播放总时长

函数原型：
int ag_audio_get_play_duration();
功能描述：获取URL、本地音乐时长。
返回值：
- 成功返回当前播放的总长度（ms），失败返回负数，请参考错误码 enum RES_CODE。
- 当没有播放时，返回 0 。

2.8 跳转播放进度

函数原型：
int ag_audio_set_seek_progress(const int ms);
功能描述：跳转到指定毫秒处。
函数参数：
- ms：指定秒数。
返回值：
- 成功返回 RES_CODE_DONE，失败返回负数，请参考错误码 enum RES_CODE。
- 此为异步接口，可通过 ag_audio_get_play_progress 确认是否生效。

2.9 获取播放状态

函数原型：
AG_AUDIO_STATUS_T ag_audio_get_player_status(void);
功能描述：获取播放器当前播放的状态。

返回值：

成功返回以下状态码，失败返回负数，请参考错误码 enum RES_CODE。

typedef enum {
AG_AUDIO_PLAYER_START = 0,
AG_AUDIO_PLAYER_PAUSE,
AG_AUDIO_PLAYER_RESUME,
AG_AUDIO_PLAYER_SUSPEND,
AG_AUDIO_PLAYER_COMPLETE,
AG_AUDIO_PLAYER_STOP,
AG_AUDIO_PLAYER_ERROR,
} AG_AUDIO_STATUS_T;

2.10 设置音量

函数原型：
int ag_audio_set_volume(const int volume, const bool needstore)
功能描述：设置音量。
函数参数：
- volume : 要设置的音量值，值在0~100。
- needstore : 是否需要存储音量， true: 需要存储，false：不要存储。
返回值：成功返回 RES_CODE_SUCCESS，失败返回负数，请参考错误码 enum RES_CODE。

2.11 获取音量

函数原型：
int ag_audio_get_volume(void);
功能描述：获取当前设备音量。
返回值：成功返回当前系统音量 **[0-100]**，失败返回负数，请参考错误码 enum RES_CODE。

2.12 获取存储音量

函数原型：
int ag_audio_get_stored_volume(void);
功能描述：获取当前存储的音量，设置音量时设置needstore才会保存下来的音量值。
返回值：成功返回当前存储的音量 **[0-100]**，失败返回负数，请参考错误码 enum RES_CODE。

3. 文本交互

3.1 文本交互

函数原型：
int ag_text_recognize(const char *request_text);
功能描述：将文字传递给服务端，服务端会当成语音识别后结果，然后作出响应。
函数参数：
- request_text : UTF-8格式汉字。
返回值：
- 成功返回ID（>0），失败返回负数，请参考错误码 enum RES_CODE。
- 此为异步接口，获取到播放ID不表示播放成功。可通过 监听会话状态 章节获取会话状态进而判定结果。

3.2 文字转TTS播报

函数原型：
int ag_text_to_speech(const char *request_text);
功能描述：在线 TTS 播报。将文字传递给服务端，播放服务端推送下来的TTS。
函数参数：
- request_text : UTF-8格式汉字。
返回值：
- 成功返回ID（>0），失败返回负数，请参考错误码 enum RES_CODE。
- 此为异步接口，获取到ID不表示播放成功。可通过 事件监听 章节获取播放器状态进而判定结果。

3.3 取消tts合成

函数原型：
int ag_stop_text_to_speech(int id);
功能描述：终止tts合成
函数参数：
- id : 调用在线TTS时获取的ID。
返回值：
- 成功返回 RES_CODE_DONE，失败返回负数，请参考错误码 enum RES_CODE。

4. 事件触发

4.1 触发输入事件

函数原型：
int ag_input_event(const AG_INPUT_EVENT_TYPE input_event);
功能描述：异步触发输入事件，SDK会进行响应。

函数参数：

typedef enum {
 AG_INPUT_EVENT_INVALID = -1,
 AG_INPUT_EVENT_VOL_UP = 0,    // 增大音量
 AG_INPUT_EVENT_VOL_DOWN = 1,    // 减小音量
 AG_INPUT_EVENT_MIC_MUTE_SWITCH = 2,    // 静音/取消静音切换
 AG_INPUT_EVENT_MIC_MUTE = 3,     // 静音
 AG_INPUT_EVENT_MIC_UNMUTE = 4,    // 取消静音
 AG_INPUT_EVENT_BUTTON_WAKEUP = 5,    // 按键唤醒
 AG_INPUT_EVENT_FACTORY_RESET = 6,    // 恢复出厂设置（播放提示音、删除临时文件、重启）
 AG_INPUT_EVENT_FACTORY_RESET_SOFT = 7, // 恢复出厂设置（只删除临时文件）
 AG_INPUT_EVENT_BT_PAIR = 8,    // 蓝牙配对
 AG_INPUT_EVENT_WIFI_SETUP = 9,    // Wi-Fi配网
 AG_INPUT_EVENT_RESUME = 10,    // 恢复播放
 AG_INPUT_EVENT_PAUSE = 11,    // 暂停播放
 AG_INPUT_EVENT_STOP_PLAY = 12,    // 停止播放
 AG_INPUT_EVENT_PREVIOUS = 13,    // 上一首
 AG_INPUT_EVENT_NEXT = 14,    // 下一首
 AG_INPUT_EVENT_MAX
} AG_INPUT_EVENT_TYPE;

返回值：成功返回 RES_CODE_DONE，失败返回负数，请参考错误码 enum RES_CODE。

4.2 触发开始对话

函数原型：
int ag_input_start_talk(void);
功能描述：唤醒精灵，开始对话。等效于ag_input_event(AG_INPUT_EVENT_BUTTON_WAKEUP)。
函数参数：无
返回值：成功返回 RES_CODE_DONE，失败返回负数，请参考错误码 enum RES_CODE。

4.3 触发停止录音

函数原型：
void ag_input_stop_talk(void);
功能描述：主动触发vad end，停止收音，然后做语音识别。正常情况应该是vad算法自动判断结束对话。停止收音后精灵对已录到的音频做交互。
函数参数：无
返回值：无

4.4 触发结束对话

函数原型：

void ag_input_exit_talk(int id);

功能描述：终止本次对话，终止后精灵取消此次唤醒。
函数参数：
- id：希望终止的对话ID。一次只会有一次对话，此参数可避免终止错对话。如果 id <= 0，则会关闭当前对话。
返回值：无

5. 事件监听

5.1 监听会话状态

函数原型：
void *ag_event_listen_session_state(session_stat_listener_t listener);
功能描述：监听会话状态的变化。状态包括：唤醒、VAD结束、收到ASR文本、NLP结束、会话结束。 :::warning
不允许在监听回调中调用对应的取消监听函数，否则会造成死锁。
注册的监听处理函数不能执行长耗时操作，不能阻塞，否则会影响其他接口响应时间。
长耗时操作可通过消息形式通知其他线程执行。 :::

ag_event_listen_session_state() 只监听会话状态的变化
ag_event_listen_conversation() 除了可以监听会话状态之外，也可获取会话信息
- 函数参数： ```c typedef enum { / wakeup / AG_SESSION_STAT_WAKEUP = 0, / stop recording / AG_SESSION_STAT_VAD_END, / ASR text from server end / AG_SESSION_STAT_TEXT_END, / server done end / AG_SESSION_STAT_NLP, / session end / AG_SESSION_STAT_TERMINATION, } AG_SESSION_STAT_T;

typedef void (session_stat_listener_t)(int session_id, AG_SESSION_STAT_T status, void extra);



-  返回值：成功返回非空句柄，失败返回空 

<a name="TZvK4"></a>
## 5.2 取消会话状态监听

-  函数原型：<br />`void ag_event_unlisten_session_state(void *handler);` 
-  功能描述：取消会话状态监听，是 ag_event_listen_session_state() 的逆过程。 
:::warning
**不允许在监听回调中调用对应的取消监听函数，否则会造成死锁**
:::


-  函数参数：注册时返回的非空句柄。 
-  返回值：空 

<a name="HD1rk"></a>
## 5.3 监听会话内容

-  函数原型：

void ag_event_listen_conversation(ag_ev_conversation_listener listener);



-  功能描述：注册监听函数，监听会话的信息。 
:::warning

- **不允许在监听回调中调用对应的取消监听函数，否则会造成死锁。**
- **注册的监听处理函数不能执行长耗时操作，不能阻塞，否则会影响其他接口响应时间。**
- **长耗时操作可通过消息形式通知其他线程执行。**
:::


   - ag_event_listen_session_state() 只监听会话状态的变化
   - ag_event_listen_conversation() 除了可以监听会话状态之外，也可获取会话信息
-  函数参数：

typedef struct { / 唤醒 / void (start_talk)(int session_id); / ASR文本 / void (ask_text)(int session_id, const char text, bool is_finish); / VAD 结束 / void (stop_listen)(int session_id); / NLP结果 / void (nlp_result)(int session_id, int code, const char domain, const char command, const char param); / 回复文本 / void (resp_text)(int session_id, const char text); / 回复TTS播放状态 / void (resp_playing_status)(AG_AUDIO_STATUS_T status); / 结束会话 / void (end_talk)(int session_id); } ag_ev_conversation_listener;



-  返回值：成功返回非空句柄，失败返回空 

<a name="Sqind"></a>
## 5.5 事件监听

-  函数原型：<br />`void *ag_event_listen_event(struct ex_event_listener *listener);` 
-  功能描述：增强型事件监听接口，监听上报的大多数事件。不感兴趣的事件，务必设置为 NULL。 
:::warning

- **不允许在监听回调中调用对应的取消监听函数，否则会造成死锁。**
- **注册的监听处理函数不能执行长耗时操作，不能阻塞，否则会影响其他接口响应时间。**
- **长耗时操作可通过消息形式通知其他线程执行。**
:::


-  函数参数：注册的事件监听函数集合的结构体 
```c
struct events_listener {
    /* 上线状态(连接服务器)变化事件 */
    void (*online_status)(bool is_online);
    /* 用户绑定事件 */
    void (*login_status)(bool is_binding);
    /* uri播放器的状态变化事件 */
    void (*uri_player_status)(int id, AG_AUDIO_STATUS_T status);
    /* prompt播放器的状态变化事件 */
    void (*prompt_player_status)(int id, AG_AUDIO_STATUS_T status);
    /* tts播放器状态变化事件 */
    void (*tts_player_status)(int id, AG_AUDIO_STATUS_T status);
    /* 音量变化事件 */
    void (*volume)(int vol);
    /* 静音设置事件 */
    void (*mute)(bool is_mute)
    /* tts播放异常事件 */
    void (*tts_exception)(int );
    /* 系统状态变换事件 */
    void (*system_status)(char *status);
}

返回值：成功返回非空句柄，失败返回空

5.6 取消事件监听

函数原型：
void ag_event_unlisten_event(void *handler);
功能描述：取消会话监听，是 ag_event_listen_event() 的逆过程。 :::warning 不允许在监听回调中调用对应的取消监听函数，否则会造成死锁 :::

函数参数：注册时返回的非空句柄。
返回值：无

5.7 nlp监听

函数原型：
void *ag_event_listen_nlp(nlp_listener_t listener);
功能描述：监听nlp事件。 :::warning
不允许在监听回调中调用对应的取消监听函数，否则会造成死锁。
注册的监听处理函数不能执行长耗时操作，不能阻塞，否则会影响其他接口响应时间。
长耗时操作可通过消息形式通知其他线程执行。 :::

函数参数：监听回调函数句柄。

typedef void (*nlp_listener_t)(int id, const char *domain,
             const char *command, const char *param);

返回值：成功返回非空句柄，失败返回空

5.8 取消nlp监听

函数原型：
void ag_event_unlisten_nlp(void *handler);
功能描述：取消nlp监听，是 ag_event_listen_nlp() 的逆过程。 :::warning 不允许在监听回调中调用对应的取消监听函数，否则会造成死锁 :::

函数参数：注册时返回的非空句柄。
返回值：无

5.9 本地nlu监听

函数原型：
void *ag_event_listen_local_nlu(local_nlu_listener_t listener, bool isOnOfflineSep);
功能描述：监听本地nlu事件，只有在设备支持离线ASR时有效。 :::warning
不允许在监听回调中调用对应的取消监听函数，否则会造成死锁。
注册的监听处理函数不能执行长耗时操作，不能阻塞，否则会影响其他接口响应时间。
长耗时操作可通过消息形式通知其他线程执行。 :::

函数参数：
- listener：监听回调函数句柄
- isOnOfflineSep：是否离在线分离，true表示在线时不再触发离线词，false表示离在线并行 :::tips
listener回调返回 ‘true’ 表示由本地处理，会同时取消云端请求。’false’ 表示本地不处理。
请求会同时发给云端与本地，响应最先返回的应答。
如果希望本地处理请求，请尽快返回 ‘true’，并让其他线程异步处理，否则可能会被云端抢占，产生不符合预期的结果。 :::
```
typedef bool (*local_nlu_listener_t)(int id, const char *nlu_json,
              const char *extra_json, int score);
```
返回值：成功返回非空句柄，失败返回空

5.10 取消本地nlu监听

函数原型：
void ag_event_unlisten_local_nlu(void *handler);
功能描述：取消本地nlu监听，是 ag_event_listen_local_nlu() 的逆过程。 :::warning 不允许在监听回调中调用对应的取消监听函数，否则会造成死锁 :::

函数参数：注册时返回的非空句柄。
返回值：无

6. 系统信息

6.1 获取精灵版本号

函数原型：
int ag_os_get_genie_version(char * const version)
功能描述：获取天猫精灵SDK版本号。
函数参数：
- verson : 天猫精灵SDK的版本号，外部需要把对应的数组初始化为0，并且长度大于 AG_VERSION_LEN。
返回值：成功返回版本字串长度，失败返回负数，请参考错误码 enum RES_CODE。

6.2 获取固件版本号

函数原型：
int ag_os_get_firmware_version(char * const version)
功能描述：获取固件版本号。
函数参数：
- verson : 固件版本号，等同于OTA固件版本号，外部需要把对应的数组初始化为0，并且长度大于AG_VERSION_LEN。
返回值：成功返回版本字串长度，失败返回负数，请参考错误码 enum RES_CODE。

6.3 获取Mac地址

函数原型：
int ag_os_get_mac_address(char * const mac)
功能描述：获取MAC地址。
函数参数：
- mac : 存储系统的mac地址，外部需要把对应的数组初始化为0，并且长度大于等于AG_MAC_LEN。
返回值：成功返回 RES_CODE_SUCCESS，失败返回负数，请参考错误码 enum RES_CODE。

6.4 获取UUID

函数原型：
int ag_os_get_uuid(char * const uuid)
功能描述：获取设备UUID。
函数参数：
- uuid : 存储sdk的uuid，外部需要把对应的数组初始化为0，并且长度大于等于AG_UUID_LEN。
返回值：成功返回 RES_CODE_SUCCESS，失败返回负数，请参考错误码 enum RES_CODE。

6.5 重启系统

函数原型：
int ag_os_reboot(void);
功能描述：重启系统。
返回值：成功会直接重启，失败返回负数，请参考错误码 enum RES_CODE。

6.6 获取服务器连接状态

函数原型：
AG_SERVER_CONNECT_STATUS ag_os_get_server_connection_status();
功能描述：获取服务器连接状态。

返回值：

typedef enum{
AG_SERVER_CONNECT_DISCONNECTED,    // 已断开
AG_SERVER_CONNECT_CONNECTING,      // 连接中
AG_SERVER_CONNECT_CONNECTED,       // 已连接
} AG_SERVER_CONNECT_STATUS;

7. 经典蓝牙

7.1 设置精灵蓝牙可见性

函数原型：
int ag_bt_set_scan_mode(bool conn_flag, bool disc_flag);
功能描述：用于设置精灵蓝牙可见性 :::warning 在设置可见性时，需注意对蓝牙音频播放的影响，若在蓝牙音频播放时将可见性打开，可能会导致蓝牙播放卡顿。 :::

函数参数：
- conn_flag：设置可连接性（page scan），若设置为true，则精灵蓝牙可接受已配对设备的链接；
- disc_flag：设置可发现性（inquiry scan），若设置为true，则精灵蓝牙可被手机、电脑等设备搜索发现。
返回值：0 表示成功，其他表示失败

7.2 设置本机蓝牙名称

函数原型：
int ag_bt_set_name(const char *name);
功能描述：用于设置本机蓝牙名称，蓝牙名称长度限制为96个字符(包括\0)。默认蓝牙名称为ALI-AM710。
函数参数：
- name：蓝牙名称
返回值：0 表示成功，其他表示失败

7.3 获取本机蓝牙名称

函数原型：
int ag_bt_get_name(char *name);
功能描述：用于获取本机蓝牙名称
函数参数：
- name：蓝牙名称，长度限制为96字符，使用前请先申请一个size为96个字符的char数组
返回值：0 表示成功，其他表示失败

8. IoT控制

8.1 功能应用

在GATT Server领域，目前天猫精灵开放接口应用场景如下：

添加ble服务，并启动ble广播
接受ble连接、断开请求，上报连接事件
收发ble数据

8.2 调用流程

下图描述了天猫精灵Gatt Server典型的调用流程
AliGenie SDK集成和接口说明-rev.5 - 图1

8.3 接口描述

8.3.1 初始化Gatt server

函数原型：
int ag_gatts_init(ag_gatts_callback *callback);
功能描述：通知底层对Gatt server进行初始化，上层需要等待初始化完成后的on_gatts_init_callback异步回调。考虑到多端调用的需求，底层会将callback与回调中的server_if关联起来，用于区分不同的callback路径。
函数参数：

typedef enum {
    API_GATTS_REGISTER_SERVER = 0,
    API_GATTS_CONNECT,
    API_GATTS_DISCONNECT,
    API_GATTS_GET_RSSI_DONE,
    API_GATTS_EVENT_MAX
} API_GATTS_EVENT_T;

/** GATT ID adding instance id tracking to the UUID */
typedef struct {
    char  uuid[API_GATT_MAX_UUID_LEN];
    uint8_t inst_id;
} API_GATT_ID_T;

/** GATT Service ID also identifies the service type (primary/secondary) */
typedef struct {
    API_GATT_ID_T    id;
    uint8_t is_primary;
} API_GATTS_SRVC_ID_T;
typedef struct {
    int server_if;
    API_GATTS_SRVC_ID_T srvc_id;
    int srvc_handle;
} API_GATTS_ADD_SRVC_RST_T;

typedef struct {
    int server_if;
    char uuid[API_GATT_MAX_UUID_LEN];
    int srvc_handle;
    int char_handle;
} API_GATTS_ADD_CHAR_RST_T ;

typedef struct {
    int server_if;
    char uuid[API_GATT_MAX_UUID_LEN];
    int srvc_handle;
    int descr_handle;
} API_GATTS_ADD_DESCR_RST_T;

typedef struct {
    int conn_id;
    int trans_id;
    char btaddr[API_MAX_BDADDR_LEN];
    int attr_handle;
    int offset;
    int length;
    uint8_t need_rsp;
    uint8_t is_prep;
    uint8_t value[API_GATT_MAX_ATTR_LEN];
} API_GATTS_REQ_WRITE_RST_T;

typedef struct {
    int conn_id;
    int trans_id;
    char btaddr[API_MAX_BDADDR_LEN];
    int attr_handle;
    int offset;
    uint8_t is_long;
} API_GATTS_REQ_READ_RST_T;

typedef struct {
    /**
     * @brief Inform the gatt server init result
     * @param[in] serverIf Indicates id of server interface
     * @return void
     */
    void (*on_gatts_init_callback)(int serverIf);
    /**
     * @brief Callback invoked in response to create_service
     * @param[in] bt_gatts_add_srvc Service parameter(uuid and primary flag)
     * @return void
     */
    void (*on_gatts_add_service_callback)(API_GATTS_ADD_SRVC_RST_T *bt_gatts_add_srvc);
    /**
     * @brief Callback invoked when a characteristic has been added to a service
     * @param[in] bt_gatts_add_char Characteristic parameter(server if, uuid ,
     *                                      service handle and characteristic handle)
     * @return void
     */
    void (*on_gatts_add_char_callback)(API_GATTS_ADD_CHAR_RST_T *bt_gatts_add_char);
    /**
     * @brief Callback invoked when a characteristic has been added to a service
     * @param[in] bt_gatts_add_char Characteristic parameter(server if, uuid ,
     *                                      service handle and characteristic handle)
     * @return void
     */
    void (*on_gatts_add_desc_callback)(API_GATTS_ADD_DESCR_RST_T *bt_gatts_add_desc);
    /**
     * @brief Callback invoked when a remote device has requested to write to a characteristic or descriptor
     * @param[in] bt_gatts_req_write (connection id,
     *                              transaction id,
     *                              remote device address,
     *                              attribute handle,
     *                              offset,
     *                              length,
     *                              need response flag,
     *                              data of value)
     * @return void
     */
    void (*on_gatts_req_write)(API_GATTS_REQ_WRITE_RST_T *bt_gatts_req_write);
    /**
     * @brief Callback invoked when a remote device has requested to read a characteristic or descriptor
     * @param[in] bt_gatts_req_read (connection id,
     *                              transaction id,
     *                              remote device address,
     *                              attribute handle,
     *                              offset,
     *                              is long or not)
     * @return void
     */
    void (*on_gatts_req_read)(API_GATTS_REQ_READ_RST_T *bt_gatts_req_read);
    /**
     * @brief Callback when gatt connection event comes
     * @param[in] bt_gatts_connection_evt connection event
     * @return void
     */
    void (*on_gatts_connection_event_callback)(API_GATTS_EVENT_T bt_gatts_connection_evt);
    /**
     * @brief Callback invoked when GATT Service is started
     * @return void
     */
    void (*on_gatts_start_server_callback)();
        /**
     * @brief Callback invoked when GATT Service is stop
     * @return void
     */
    void (*on_gatts_stop_server_callback)();
    /**
     * @brief Callback invoked when GATT Service is delete
     * @return void
     */
    void (*on_gatts_delete_server_callback)();
    /**
     * @brief Enable advertisement callback
     * @param[in] enable Characteristic notify callbac
     * @return void
     */
    void (*on_adv_enable)(int status);
} ag_gatts_callback;

返回值：on_gatts_init_callback中会携带一个参数serverIf，是当前Gatt server的一个id，如果协议栈支持同时存在多个Gatt server，那可以在每次调用ag_gatts_init返回不同的id。

8.3.2 注销Gatt server

函数原型：
int ag_gatts_deinit(int serverIf);
功能描述：此接口用于通知底层进行Gatts的清理工作，与ag_gatts_init进行对应。
函数参数：
- serverIf：调用ag_gatts_init返回的id。
返回值：0 表示成功，其他表示失败

8.3.3 添加Gatt Service

函数原型：
int ag_gatts_add_service(int server_if, char *service_uuid, uint8_t is_primary, int number);
功能描述：在收到on_gatts_init_callback后，可以添加Gatt Service。在该函数调用完成后，底层会异步回调on_gatts_add_service_callback。
函数参数：
- server_if：通过on_gatts_init_callback回调参数获取，等同于ag_gatts_init返回的id
- service_uuid：Added service start handle
- is_primary：Is primary service or not
- number：Handle number
返回值：0 表示成功，其他表示失败

8.3.4 添加Characteristic

函数原型：
int ag_gatts_add_char(int server_if, int service_handle, char *uuid, int properties, int permissions);
功能描述：在收到on_gatts_add_service_callback后，可以开始添加Characteristic。在该函数调用完成后，底层会异步回调on_gatts_add_char_callback。
函数参数：
- server_if：通过on_gatts_add_service_callback回调参数获取
- service_handle：通过on_gatts_add_service_callback回调参数获取
- uuid：Characteristic uuid
- properties：Characteristic properties(input), e.g
  - read(0x02)
  - write without response(0x04)
  - write(0x08)
  - notify(0x10)
  - indicate(0x20)
- permissions：permissions Access characteristic permissions(input), e.g.
  - perm_read(0x01)
  - perm_read_encrypted(0x02)
  - perm_read_enc_mitm(0x04)
  - perm_write(0x10)
  - perm_write_encrypted(0x20)
  - perm_write_enc_mitm(0x40)
返回值：0 表示成功，其他表示失败

8.3.5 添加Descriptor

函数原型：
int ag_gatts_add_desc(int server_if, int service_handle, char *uuid, int permissions);
功能描述：在Char添加完成后，可以继续添加Descriptor，在该函数调用完成后，底层会异步回调on_gatts_add_desc_callback。
函数参数：
- server_if：通过on_gatts_add_service_callback回调参数获取
- service_handle：通过on_gatts_add_service_callback回调参数获取
- uuid：Characteristic uuid
- permissions：permissions Access characteristic permissions(input), e.g.
  - perm_read(0x01)
  - perm_read_encrypted(0x02)
  - perm_read_enc_mitm(0x04)
  - perm_write(0x10)
  - perm_write_encrypted(0x20)
  - perm_write_enc_mitm(0x40)
返回值：0 表示成功，其他表示失败

8.3.6 启动Gatt Service

函数原型：
int ag_gatts_start_service(int server_if, int service_handle, int transport);
功能描述：启动service，在该函数调用完成后，底层会异步回调on_gatts_start_server_callback
函数参数：
- server_if：通过on_gatts_add_service_callback回调参数获取
- service_handle：通过on_gatts_add_service_callback回调参数获取
- transport：0 : auto, 1 : BREDR, 2 : LE
返回值：0 表示成功，其他表示失败

8.3.7 设置广播数据

函数原型：
int ag_gatts_serverIfset_adv_data(char *data);
功能描述：设置广播数据
函数参数：
- data：广播数据
返回值：0 表示成功，其他表示失败

8.3.8 启动广播数据

函数原型：
int ag_gatts_enable_adv(bool enable);
功能描述：启动广播
函数参数：
- enable：为true表示启动，为flase表示停止广播
返回值：0 表示成功，其他表示失败

8.3.9 数据应答

函数原型：
int ag_gatts_send_response(int conn_id, int trans_id, int status, int handle, char *p_value, int value_len, int auth_req);
功能描述：通过on_gatts_req_write回调接收到数据或者通过on_gatts_req_read回调收到对方发过来的数据读取请求
，可以通过该函数来应答数据。
函数参数：
- conn_id：Connection id
- trans_id：Transaction id
- status：Send response satus
- handle：Send response handle
- p_value：Send response value
- value_len：Send response value length
- auth_req：Authentication request
返回值：0 表示成功，其他表示失败

8.3.10 主动发送数据

函数原型：
int ag_gatts_send_indication(int server_if, int handle, int conn_id, int fg_confirm, char *p_value, int value_len);
功能描述：主动发送数据。发送数据前要确认设备已经连接。连接状态可以通过on_gatts_connection_event_callback回调获取。
函数参数：
- server_if：Registered service identifier
- handle：Send indication attribute handle
- conn_id：Connection id
- fg_confirm：Is need confirmation or not
- p_value：Send indication value
- value_len：Send indication value length
返回值：0 表示成功，其他表示失败

8.3.11 停止Gatt Service

函数原型：
int ag_gatts_stop_service(int server_if, int service_handle);
功能描述：在销毁Gatts的时候，应先停止service。在该函数调用完成后，需要等待on_gatts_stop_server_callback回调
函数参数：
- server_if：通过on_gatts_add_service_callback回调参数获取
- service_handle：通过on_gatts_add_service_callback回调参数获取
返回值：0 表示成功，其他表示失败

8.3.12 删除Gatt Service

函数原型：
int ag_gatts_delete_service(int server_if, int service_handle);
功能描述：在停止service，收到on_gatts_stop_server_callback回调后，可以删除service。在该函数调用完成后，需要等待on_gatts_delete_server_callback回调
函数参数：
- server_if：通过on_gatts_add_service_callback回调参数获取
- service_handle：通过on_gatts_add_service_callback回调参数获取
返回值：0 表示成功，其他表示失败

8.3.13 销毁Gatt Service

函数原型：
int ag_gatts_unregister_service(int server_if);
功能描述：删除service，收到on_gatts_delete_server_callback后，可以彻底销毁该Gatt Service，该函数调用之后，无需再等待回调。
函数参数：
- server_if：通过on_gatts_init_callback回调参数获取
返回值：0 表示成功，其他表示失败

9. 闹钟倒计时

闹钟倒计时模块向开发者提供对接语音交互、天猫精灵APP闹钟应用设置的相关接口。

用户通过语音对话，如“帮我设定明天早上七点的闹钟”进行触发；
通过天猫经手机APP上“精灵闹钟”功能进行处理；

闹钟的时间获取、本地计时、日历计算、时间显示等均依赖BSP进行处理。请参考BSP RTC相关文档进行开发。

9.1 事件监听

函数原型：
int ag_clock_listen(ag_cl_listener *listener);
功能描述：监听闹钟倒计时事件 :::warning
不允许在监听回调中调用对应的取消监听函数，否则会造成死锁。
注册的监听处理函数不能执行长耗时操作，不能阻塞，否则会影响其他接口响应时间。
长耗时操作可通过消息形式通知其他线程执行。 :::

函数参数：监听回调函数句柄。

typedef struct {
 /* 闹钟更新 */
 void (*alarm_update)(time_t next_trigger_time);
 /* 闹钟触发 */
 void (*alarm_trigger)();
 /* 倒计时触发（开始计时） */
 void (*countdown_trigger)(int countdown_time);
} ag_cl_listener;

返回值：成功返回0，否则返回-1

9.2 取消事件监听

函数原型：
void ag_clock_unlisten();
功能描述：取消闹钟倒计时事件监听，是 ag_clock_listen() 的逆过程。 :::warning 不允许在监听回调中调用对应的取消监听函数，否则会造成死锁 :::

函数参数：无
返回值：无

9.3 获取下个闹钟的触发时间

函数原型：
time_t ag_clock_get_alarm_trigger_time(void);
功能描述：获取下个闹钟的触发时间。
函数参数：无
返回值：返回下个闹钟的触发时间，为0表示当前没有设置闹钟。

10. 命令行操作

10.1 音频播控

ag_play命令主要调用了一系列多媒体相关的接口 ag_audio_xxx，实现了音频播放控制。

使用方法如下：

AliGenie Audio Player
Usage:
    ag_play help|-h: show this message
    ag_play tts|t <path/for/tts/file>: play local tts stream
    ag_play url|u <path/for/tts/file>: play url or local music [default]
    ag_play url_ex|ue <path/for/music> [exJson]: play url or local music with expand function.
        exJson: path of json-file or json-text
    ag_play prompt|p <path/for/music>: play prompt
    ag_play text|tx <text>: read text
    ag_play stream_end|se [type [id]]: stream audio end (type: "tts" [default])
    ag_play stop|sp: stop player
    ag_play seek|sk <ms>: seek to the time in ms to play
    ag_play pause|ps: pause player
    ag_play resume|rs: resume player
    ag_play suspend|ss: suspend player
    ag_play progress|pg: get playback progress
    ag_play duration|dr: get playback duration
    ag_play status|st: get player status
    ag_play volume|vl [value, [save]]: get volume or set volume.
        save: string "save", to save volume.

使用示例：

  $ ag_play /data/smartbox/prompt/xiaokubao/40.mp3
  $ ag_play text 天猫精灵真棒
  $ ag_play stop

:::tips Window系统终端输入中文可能会导致无法正常识别，例如 “ag_play tts 你好” 可能会无效。 :::

10.2 文本交互

ag_talk命令用于实现用文字模拟语音交互，主要调用了 ag_text_recognize。

使用方法如下：

Talk to Tmall Genie by text
Usage: text_talk <text ...>

使用示例：

$ ag_talk 现在几点

:::tips Window系统终端输入中文可能会导致无法正常识别，例如 “ag_talk 你好” 可能会无效。 :::

10.3 触发事件

ag_input命令用于实现用触发事件`。

使用方法如下：

AliGenie Trigger Event
Usage:
    ag_input help|-h : show this message
    ag_input volume_up|vp : turn up volume
    ag_input volume_down|vd : turn down volume
    ag_input mic_mute_switch|mms : switch to mute or not
    ag_input mic_mute|mm : turn to mute
    ag_input mic_unmute|mu : turn to unmute
    ag_input wakeup|wu : wakeup device
    ag_input reset|rst : reset to factory setting
    ag_input soft_reset|srst : soft reset to factory setting
    ag_input bt_pair|bp : turn to bluetooth pairing mode
    ag_input wifi_setup|ws : wifi re-connect
    ag_input resume|rs : resume player
    ag_input pause|ps : pause player
    ag_input stop|ss : stop player
    ag_input previous|pv : play previous song
    ag_input next|nx : play next song
    ag_input hotplug|hp <dev_type> <ev_type> [json_payload]: device hotplug event
             dev_type under bt_headset/wired_headset/sdcard/udisk
             ev_type under plugin/plugout
             payload should be json-file path or json-text
    ag_input start_talk|st : start a talk (same as wakeup)
    ag_input stop_talk|sot : vad end manually
    ag_input exit_talk|et [id]: drop a talk session with id
    ag_input genie_on|go : listen genie on/off state

使用示例：

$ ag_input wu # 唤醒天猫精灵

10.4 监听事件

ag_event命令用于监听事件。

使用方法如下：

AliGenie Listen Event
Usage:
    ag_event help|-h : show this message
    ag_event listen_conversation|lc : listen conversation
    ag_event listen_session_state|lss : listen session state
    ag_event listen_event|le : listen event
    ag_event listen_nlp|lp : listen nlp
    ag_event listen_local_nlu|llu <isOnOfflineSep>: listen local nlu
         isOnOfflineSep under true/false
    ag_event genie_on|go : listen genie on/off state
    ag_event unlisten|ul [conversation|session|event|nlp|local_nlu|on]: unlisten listener if listened before

使用示例：

$ ag_event lss #监听会话状态

10.5 系统信息

ag_os命令主要用于获取系统信息以及系统控制。

使用方法如下：

Get AliGenie SDK information.
Usage:
    ag_os help: show this message
    ag_os all: show uuid\mac\version\connect (default)
    ag_os uuid: get uuid
    ag_os mac: get mac address
    ag_os version|ver: get SDK version
    ag_os connect|con: whether connected server
    ag_os reboot: reboot device
    ag_os wait [ms]: wait for genie ready for ms.
    ag_os on: check whether genie is on.
    ag_os crash_report|cr: create crash_report to /data/crash_reports

使用示例：

$ ag_os uuid
uuid: 83E68F050D3A710A57909B08905E30F2

10.6 闹钟倒计时

ag_clock命令主要用于监听闹钟倒计时时间，并支持主动获取下个闹钟的触发时间。

使用方法如下：

AliGenie Bluetooth Function.
Usage:
    ag_clock help|-h : help: show this message
    ag_clock register_clock_listener|rcl : register clock listener callback
    ag_clock unregister_clock_listener|ucl : unregister clock listener callback
    ag_clock get_alarm_next_trigger_time|gantt : get alarm next trigger time

使用示例：

$ ag_clock rcl #监听闹钟倒计时事件
$ ag_clock gantt #主动获取下个闹钟的触发时间