20 extalk-对讲功能

一、概述

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

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

目前合宙所有的型号均需要外置音频放大器(PA)才可将音频输出。

二、核心示例

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,心跳间隔，联系人回调函数，状态回调函数

注意事项

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

参数

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)

功能

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

注意事项

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

参数

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.stop()   --  停止对讲

五、产品支持说明

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

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