一、概述

extalk 是基于 airtalk 音频框架开发的扩展库，旨在简化 airtalk 的使用方法，扩展其应用场景，并提供更稳定的通信体验。该库封装了复杂的 MQTT 通信、音频流处理和状态管理逻辑，为开发者提供简洁易用的 API 接口，便于快速实现设备间的语音对讲功能。

仅 Air780EHV 内置音频编解码芯片，其他支持音频的功能需要外置音频编解码芯片。

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/airtalk

local extalk = require "extalk"
-- 配置并初始化
extalk.setup({
    key = "your_product_key",
    heart_break_time = 30,
    contact_list_cbfnc = function(dev_list) end,
    state_cbfnc = function(state) end
})
-- 发起对讲
extalk.start("remote_device_id")
-- 结束对讲
extalk.stop()

三、常量详解

扩展库常量，由 excloud 扩展库中定义的、不可重新赋值或修改的固定值；

3.1 extalk.START

常量含义：当对讲发起成功后将产生这个回调，代表通话开始状态；
数据类型：number；
示例代码：if event_table.state == extalk.START then
            log.info("对讲开始")
         end

3.2 extalk.STOP

常量含义：当对讲结束时将产生这个回调，代表通话结束状态；
数据类型：number；
注意事项：对讲结束的场景有管理平台发送停止对讲指令、对端挂断、
            MQTT断开连接、长时间没有收到音频数据、主动结束对讲等情况下都会触发此回调。
示例代码：elseif event_table.state == extalk.STOP then
            log.info("对讲结束")
         end

3.3 extalk.UNRESPONSIVE

常量含义：对端未响应；当发起对讲请求后，对端没有响应将产生这个回调事件。
数据类型：number；
注意事项：一对一呼叫时对方无响应才会触发此回调
示例代码：elseif event_table.state == extalk.UNRESPONSIVE then
            log.info("对端未响应")
         end

3.4 extalk.ONE_ON_ONE

常量含义：一对一来电回调，当接收到一对一来电请求时，产生此回调事件
数据类型：number；
示例代码：elseif event_table.state == extalk.ONE_ON_ONE then
            log.info("已连接到指定设备")
          end

3.5 extalk.BROADCAST

常量含义：收到其他设备的广播请求，产生此回调事件
数据类型：number；
注意事项：当收到其他设备的广播请求时才产生此事件，如果是调用extalk.start() 发起广播时，成功后会触发 extalk.START 回调，而非 extalk.BROADCAST
示例代码：elseif event_table.state == extalk.BROADCAST then
            log.info("已进入广播接收模式")
          end

四、函数详解

extalk.setup(configs)

功能

初始化 airtalk,配置项目 KEY,心跳间隔，联系人回调函数，状态回调函数

注意事项

1. 该接口只能也只需启动一次
2. 项目 key,通过 https://iot.openluat.com/ 网站获取，需要和 main.lua 的 PRODUCT_KEY，保持一致，可用来升级，建立群组等
3. 心跳间隔，定期会发送电池电量，以及信号值的信息

参数

configs

> 参数含义：音频的参数配置,参数为table类型，table内容格式说明如下：  
> {  
> 参数含义：此项目的识别号  
> 数据类型：string；  
> 取值范围：无；  
> 是否必选：必选传入此参数；  
> 注意事项：需要和main.lua 的PRODUCT\_KEY，保持一致  
> 参数名称： configs.key
> 
> 参数含义：心跳上报时间(单位s)；  
> 数据类型：number；  
> 取值范围：>0  
> 是否必选：必选；  
> 注意事项：间隔过短，会引起功耗上升  
> 参数名称： configs.heart\_break\_time
> 
> 参数含义：联系人列表的回调函数，当设备列表更新时触发，用于获取当前可用的联系人列表；  
> 数据类型：function；  
> 取值范围：无  
> 是否必选：必须；  
> 注意事项：必须等到联系人列表返回，才可进行呼叫业务  
> 回调函数参数：dev\_list ：设备列表数组，每个元素为设备信息表，包含以下字段：  
> id ：设备唯一标识符（字符串，通常为IMEI）  
> name ：设备名称（字符串，可选）  
> online ：设备在线状态（布尔值，可选）  
> 触发时机：设备首次成功连接并鉴权后、系统定期更新设备列表时、有新设备加入或设备状态变化时  
> 使用示例：  
> \-- 定义联系人列表回调函数  
> local function handle\_contact\_list(dev\_list)  
> \-- 打印获取到的设备列表  
> print("联系人列表更新，共" .. #dev\_list .. "个设备")  
> for i, dev in ipairs(dev\_list) do  
> print("设备" .. i .. ": ID=" .. dev.id .. ", 名称=" .. (dev.name or "未命名") .. ", 在线状态=" .. (dev.online and "在线" or "离线"))  
> end  
> 
> \-- 可以将设备列表保存到全局变量，供后续使用  
> g\_devices = dev\_list  
> 
> \-- 标记设备列表已获取，可以开始呼叫业务  
> g\_contact\_list\_ready = true  
> end  
> 参数名称： configs.contact\_list\_cbfnc
> 
> 参数含义：对讲状态的回调函数，当对讲状态变化时触发，用于通知应用层当前的通话状态；  
> 数据类型：function；  
> 取值范围：无  
> 是否必选：必须；  
> 注意事项：回调的参数，可见上方的常量参数  
> 回调函数参数：state ：状态信息表，包含以下字段：  
> state ：状态类型（常量），可能的取值：  
> extalk.START ：通话开始  
> extalk.STOP ：通话结束  
> extalk.UNRESPONSIVE ：呼叫未响应  
> extalk.ONE\_ON\_ONE ：一对一来电  
> extalk.BROADCAST ：广播来电  
> id ：来电设备ID（字符串，可选，仅在来电时提供）  
> 触发时机：发起呼叫后对方响应成功时、发起呼叫后超时未响应时、通话结束时、收到来自其他设备的呼叫时  
> 使用示例：  
> \-- 定义状态回调函数  
> local function handle\_call\_state(state)  
> \-- 根据状态类型处理不同的业务逻辑  
> if state.state == extalk.START then  
> print("通话已开始")  
> elseif state.state == extalk.STOP then  
> print("通话已结束")  
> elseif state.state == extalk.UNRESPONSIVE then  
> print("呼叫超时，对方未响应")  
> elseif state.state == extalk.ONE\_ON\_ONE then  
> print("收到来自" .. state.id .. "的一对一呼叫")  
> elseif state.state == extalk.BROADCAST then  
> print("收到来自" .. state.id .. "的广播呼叫")  
> end  
> end  
> 参数名称： configs.state\_cbfnc  
> }
> 
> 数据类型：table；  
> 取值范围：参考参数含义内各字段说明  
> 是否必选：可选传入此参数；  
> 注意事项：暂无；  

返回值

local result = extalk.setup(configs)

result

含义说明：初始化extalk是否成功；
数据类型：boolean；
取值范围：返回true ,表示成功，返回false 表示失败；
注意事项：暂无；
返回示例：true 表示初始化成功

示例

-- extalk配置参数
local extalk_configs = {
    key = PRODUCT_KEY,
    heart_break_time = 120,  -- 心跳间隔(单位秒)
    contact_list_cbfnc = contact_list_callback,
    state_cbfnc = speech_state_callback,
}
if extalk.setup(extalk_configs) then
    log.info("airtalk初始化成功")
end

extalk.start(id)

功能

开始一对一呼叫，或者一对多呼叫

注意事项

1. 设备未初始化或初始化失败时，无法呼叫
2. 如果当前正在通话，将无法呼叫

参数

id

-- 参数含义：如果填入可以呼叫的对端ID,则进行一对一的单独通话，如果不填入或者填入nil 则对整个群组全部广播；
-- 数据类型：number/nil；
-- 取值范围： 无
-- 是否必选：非必须；
-- 注意事项：如果需要一对一通话，填入的数据只能是extalk.setup 的contact_list_cbfnc 回调函数返回ID

返回值

local result = extalk.start(id)

result

含义说明：呼叫是否成功；
数据类型：boolean；
取值范围：返回true ,表示成功，返回false 表示失败；
注意事项：true ：发起成功，具体包括以下情况：
            设备处于空闲状态，成功发起一对一对讲
            设备处于空闲状态，成功发起广播对讲
        false ：发起失败，具体包括以下情况：
            设备当前正在对讲中（非空闲状态），无法发起新的对讲
            尝试向本机（相同ID）发起对讲，系统不允许
            设备未正确初始化或处于离线状态
        如果对方成功响应， state_cbfnc 回调会被触发，状态为 extalk.START
        如果超时未收到响应， state_cbfnc 回调会被触发，状态为 extalk.UNRESPONSIVE
返回示例：true 表示呼叫成功

示例

extalk.start("868123457234234")   --  一对一单呼
extalk.start()   --  对群组内所有设备进行广播

extalk.stop()

功能

停止一对一或广播对讲

注意事项

无

参数

无

返回值

local result = extalk.stop()

result

含义说明：停止对讲；
数据类型：boolean；
取值范围：返回true ,表示成功，返回false 表示失败；
注意事项：true ：结束成功，具体包括以下情况：
             设备正在发起对讲（连接中状态），成功取消发起
             设备正在对讲中（已连接状态），成功结束对讲
         false ：结束失败，具体包括以下情况：
             设备当前没有正在进行的对讲（空闲状态）
             设备处于离线状态，无法执行结束操作
            设备未正确初始化
返回示例：true 表示停止成功

示例

五、模组支持说明

extalk 功能支持如下模块，Air700ECH/Air780EHN/EHU/EHM/EHV/EGH/EGG/8000 系列。

注意：LuatOS 内核固件需要支持 airtalk 功能

今天的分享就到这里了啦~~~