8 excloud-AirCloud云平台控制
作者：马梦阳 | 最后修改：2026-09-01
一、概述
合宙 AirCloud 平台 iot.luatos.com 是一个物联网设备管理平台，提供设备连接、数据采集、远程控制、运维监控等功能。用户可以通过该平台：
- 设备管理：注册、认证、监控设备状态。
- 数据可视化：查看传感器数据、历史曲线。
- 远程控制：下发指令控制设备行为。
- 文件上传：支持图片、音频、日志文件上传。
- 运维支持：自动日志上传、故障诊断。
本扩展库是合宙 AirCloud 平台的 aircloud 协议的适配，用于设备连接合宙 AirCloud 平台。aircloud 协议如下：https://docs.openluat.com/protocols/aircloud/
excloud 扩展库实现功能：
- 连接管理：TCP/MQTT 连接、自动重连、状态监控
- 协议适配：aircloud 协议封装解析、TLV 数据格式
- 文件上传：支持图片、音频、日志文件上传到平台
- 心跳机制：维持设备在线状态、自定义心跳数据
- 运维日志：设备运行日志记录和自动上传
- getip 服务：自动发现服务器地址、端口及鉴权信息
数据流向：
- 上行：设备数据 → excloud 库 → 平台
- 下行：平台命令 → excloud 库 → 设备执行
二、核心示例
1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/aircloud
local excloud = require("excloud")
-- 注册回调函数
-- 注册回调函数
function on_excloud_event(event, data)
log.info("用户回调函数", event, json.encode(data))
if event == "connect_result" then
if data.success then
log.info("连接成功")
sys.publish("aircloud_connected")
else
log.info("连接失败: " .. (data.error or "未知错误"))
end
elseif event == "auth_result" then
if data.success then
log.info("认证成功")
else
log.info("认证失败: " .. data.message)
end
elseif event == "message" then
log.info("收到消息, 流水号: " .. data.header.sequence_num)
-- 处理服务器下发的消息
for _, tlv in ipairs(data.tlvs) do
log.info("TLV字段", "含义:", tlv.field, "类型:", tlv.type, "值:", tlv.value)
if tlv.field == excloud.FIELD_MEANINGS.CONTROL_COMMAND then
log.info("收到控制命令: " .. tostring(tlv.value))
-- 处理控制命令并发送响应
local response_ok, err_msg = excloud.send({
{
field_meaning = excloud.FIELD_MEANINGS.CONTROL_RESPONSE,
data_type = excloud.DATA_TYPES.ASCII,
value = "命令执行成功"
}
}, false)
if not response_ok then
log.info("发送控制响应失败: " .. err_msg)
end
end
end
elseif event == "disconnect" then
log.warn("与服务器断开连接")
elseif event == "reconnect_failed" then
log.info("重连失败，已尝试 " .. data.count .. " 次")
elseif event == "send_result" then
if data.success then
log.info("发送成功，流水号: " .. data.sequence_num)
else
log.info("发送失败: " .. data.error_msg)
end
elseif event == "mtn_log_upload_start" then
log.info("运维日志上传开始", "文件数量:", data.file_count)
elseif event == "mtn_log_upload_progress" then
log.info("运维日志上传进度",
"当前文件:", data.current_file,
"总数:", data.total_files,
"文件名:", data.file_name,
"状态:", data.status)
elseif event == "mtn_log_upload_complete" then
log.info("运维日志上传完成",
"成功:", data.success_count,
"失败:", data.failed_count,
"总计:", data.total_files)
end
end
-- 注册回调
excloud.on(on_excloud_event)
-- 主任务函数
function excloud_task_func()
-- 如果当前时间点设置的默认网卡还没有连接成功，一直在这里循环等待
while not socket.adapter(socket.dft()) do
log.warn("excloud_task_func", "wait IP_READY", socket.dft())
-- 在此处阻塞等待默认网卡连接成功的消息"IP_READY"
-- 或者等待1秒超时退出阻塞等待状态;
-- 注意：此处的1000毫秒超时不要修改的更长；
-- 因为当使用exnetif.set_priority_order配置多个网卡连接外网的优先级时，会隐式的修改默认使用的网卡
-- 当exnetif.set_priority_order的调用时序和此处的socket.adapter(socket.dft())判断时序有可能不匹配
-- 此处的1秒，能够保证，即使时序不匹配，也能1秒钟退出阻塞状态，再去判断socket.adapter(socket.dft())
sys.waitUntil("IP_READY", 1000)
end
-- 配置excloud参数
local ok, err_msg = excloud.setup({
transport = "tcp", -- 使用TCP传输
auto_reconnect = true, -- 自动重连
reconnect_interval = 10, -- 重连间隔(秒)
max_reconnect = 5, -- 最大重连次数
timeout = 30, -- 超时时间(秒)
mtn_log_enabled = true, -- 启用运维日志
mtn_log_blocks = 2, -- 日志文件块数
mtn_log_write_way = excloud.MTN_LOG_CACHE_WRITE -- 缓存写入方式
})
-- 配置excloud参数，虚拟设备链接
-- local ok, err_msg = excloud.setup({
-- virtual_phone_number = "15893470522", -- 11位手机号
-- virtual_serial_num = 1, -- 序列号（0-999）
-- transport = "tcp", -- 由于mqtt链接需要使用imei,虚拟设备没有,所以只能使用TCP传输
-- mtn_log_enabled = true
-- })
if not ok then
log.info("初始化失败: " .. err_msg)
return
end
log.info("excloud初始化成功")
-- 开启excloud服务
local ok, err_msg = excloud.open()
if not ok then
log.info("开启excloud服务失败: " .. err_msg)
return
end
log.info("excloud服务已开启")
-- 启动自动心跳，默认5分钟一次的心跳
excloud.start_heartbeat()
log.info("自动心跳已启动")
-- 启动3分钟一次的心跳，可配置自定义内容
-- excloud.start_heartbeat(180, {
-- { field_meaning = excloud.FIELD_MEANINGS.TIMESTAMP,
-- data_type = excloud.DATA_TYPES.INTEGER,
-- value = os.time() }
-- })
-- 停止自动心跳
--excloud.stop_heartbeat()
-- 记录启动日志
--excloud.mtn_log("system", "设备启动完成", "version", "1.0.0")
-- 主循环：定期上报数据
while true do
-- 每30秒上报一次数据
sys.wait(30000)
-- 检查连接状态
local status = excloud.status()
if not status.is_connected then
log.warn("设备未连接，跳过数据上报")
else
-- 上报基础状态数据
local ok, err_msg = excloud.send({
{
field_meaning = excloud.FIELD_MEANINGS.SIGNAL_STRENGTH_4G,
data_type = excloud.DATA_TYPES.INTEGER,
value = 22 -- 信号强度
},
{
field_meaning = excloud.FIELD_MEANINGS.SIM_ICCID,
data_type = excloud.DATA_TYPES.ASCII,
value = "89860118801012345678" -- SIM卡ICCID
},
{
field_meaning = excloud.FIELD_MEANINGS.TIMESTAMP,
data_type = excloud.DATA_TYPES.INTEGER,
value = os.time()
}
}, false)
if ok then
log.info("基础数据上报成功")
else
log.error("基础数据上报失败:", err_msg)
end
end
end
end
-- 启动主任务
sys.taskInit(excloud_task_func)
--上传图片示例
function upload_image_fun()
-- 等待连接建立
sys.waitUntil("aircloud_connected", 10000)
-- 上传图片
log.info("开始上传图片")
if not excloud.status().is_connected then
log.info("设备未连接，跳过图片上传")
return
end
if io.exists("/luadb/test.jpg") then
local ok, err = excloud.upload_image("/luadb/test.jpg", "test.jpg")
if ok then
log.info("图片上传成功")
else
log.error("图片上传失败:", err)
end
else
log.warn("测试图片文件不存在")
end
end
sys.taskInit(upload_image_fun)
-- 运维日志测试示例
function mtnlog_test_task()
local test_count = 0
while true do
test_count = test_count + 1
excloud.mtn_log("mtn_test", test_count)
-- 每30秒记录一次
sys.wait(1000)
end
end
sys.taskInit(mtnlog_test_task)
三、常量详解
扩展库常量，由 excloud 扩展库中定义的、不可重新赋值或修改的固定值；
3.1 数据类型常量
3.1.1 excloud.DATA_TYPES.INTEGER
常量含义：整数数据类型；
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.INTEGER
3.1.2 excloud.DATA_TYPES.FLOAT
常量含义：浮点数数据类型；
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.FLOAT
3.1.3 excloud.DATA_TYPES.BOOLEAN
常量含义：布尔值数据类型；
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.BOOLEAN
3.1.4 excloud.DATA_TYPES.ASCII
常量含义：ASCII字符串数据类型；
是可打印的字符串，直接copy出来就可以在文本编辑器人眼查看的。每个字节的值都在0x20到0x2E之间。
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.ASCII
3.1.5 excloud.DATA_TYPES.BINARY
常量含义：二进制数据类型； binary字符串，不一定可打印， 每个字节是任意的。
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.BINARY
3.1.6 excloud.DATA_TYPES.UNICODE
常量含义：Unicode字符串数据类型；UTF-8编码方式。
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.UNICODE
3.2 字段含义常量
3.2.1 控制信令类型 (16-255)
3.2.1.1 excloud.FIELD_MEANINGS.AUTH_REQUEST
常量含义：鉴权请求；
值数据类型：excloud.DATA_TYPES.BINARY
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.AUTH_REQUEST
业务说明：设备连接后首先发送鉴权请求，包含设备身份信息
3.2.1.2 excloud.FIELD_MEANINGS.AUTH_RESPONSE
常量含义：鉴权回复；
值数据类型：excloud.DATA_TYPES.BINARY
传输方向：平台→设备
示例代码：local field = excloud.FIELD_MEANINGS.AUTH_RESPONSE
业务说明：平台验证设备身份后返回认证结果
3.2.1.3 excloud.FIELD_MEANINGS.REPORT_RESPONSE
常量含义：上报回应；
值数据类型：excloud.DATA_TYPES.INTEGER
值内容：0（成功）或错误码 （这部分服务器还没实现，先这样定义）
传输方向：平台→设备
示例代码：local field = excloud.FIELD_MEANINGS.REPORT_RESPONSE
业务说明：平台确认收到设备数据上报，用于服务器对设备的上报的回应
3.2.1.4 excloud.FIELD_MEANINGS.CONTROL_COMMAND
常量含义：控制命令；
值数据类型：不做限制，平台可以选择数据格式
传输方向：平台→设备
示例代码：local field = excloud.FIELD_MEANINGS.CONTROL_COMMAND
业务说明：平台向设备下发控制命令，如开关、参数设置等
3.2.1.5 excloud.FIELD_MEANINGS.CONTROL_RESPONSE
常量含义：控制回应；
值数据类型：不做限制
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.CONTROL_RESPONSE
业务说明：设备收到控制命令后返回执行结果
3.2.1.6 excloud.FIELD_MEANINGS.IRTU_DOWN
常量含义：iRTU下行命令；
值数据类型：不做限制
传输方向：平台→设备
示例代码：local field = excloud.FIELD_MEANINGS.IRTU_DOWN
业务说明：针对iRTU设备的专用控制命令
3.2.1.7 excloud.FIELD_MEANINGS.IRTU_UP
常量含义：iRTU上行回复；
值数据类型：不做限制
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.IRTU_UP
业务说明：iRTU设备执行命令后的响应数据
3.2.1.8 excloud.FIELD_MEANINGS.FILE_UPLOAD_START
常量含义：文件上传开始通知；
值数据类型：不做限制
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.FILE_UPLOAD_START
值内容：文件元信息（文件名、大小、类型）
业务说明：设备开始上传文件前的通知消息
3.2.1.9 excloud.FIELD_MEANINGS.FILE_UPLOAD_FINISH
常量含义：文件上传完成通知；
值数据类型：不做限制
传输方向：设备→平台
值内容：上传结果
示例代码：local field = excloud.FIELD_MEANINGS.FILE_UPLOAD_FINISH
业务说明：设备完成文件上传后的确认消息
3.2.1.10 excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_REQ_SIGNAL
常量含义：运维日志上传命令
值数据类型：值为空，收到此命令就读取并上传日志内容
传输方向：平台→设备
业务说明：平台主动请求设备上传运维日志
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_REQ_SIGNAL
3.2.1.11 excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_RESP_SIGNAL
常量含义：运维日志上传响应
值数据类型：不做限制
传输方向：设备→平台
值内容：日志上传准备状态
业务说明：设备响应平台的日志上传请求
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_RESP_SIGNAL
3.2.1.12 excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_STATUS_SIGNAL
常量含义：运维日志上传状态
值数据类型：excloud.DATA_TYPES.BINARY
传输方向：设备→平台
值内容：上传进度和状态信息
业务说明：设备向平台报告日志上传的实时进度
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_STATUS_SIGNAL
3.2.1.13 excloud.FIELD_MEANINGS.SMS_SEND
常量含义：短信发送请求；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：平台→设备
业务说明：平台向设备下发短信发送指令，包含短信接收方号码和短信内容
示例代码：local field = excloud.FIELD_MEANINGS.SMS_SEND
3.2.1.14 excloud.FIELD_MEANINGS.SMS_SEND_RSP
常量含义：短信发送请求回复；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
业务说明：设备对平台短信发送指令的回复
示例代码：local field = excloud.FIELD_MEANINGS.SMS_SEND_RSP
3.2.1.15 excloud.FIELD_MEANINGS.SMS_REPORT
常量含义：短信投递状态上报；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
业务说明：设备向平台上报短信的投递状态
示例代码：local field = excloud.FIELD_MEANINGS.SMS_REPORT
3.2.1.16 excloud.FIELD_MEANINGS.SMS_REPORT_RSP
常量含义：短信投递状态上报回复；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：平台→设备
业务说明：平台对设备短信投递状态上报的回复
示例代码：local field = excloud.FIELD_MEANINGS.SMS_REPORT_RSP
3.2.2 传感类 (256-511)
3.2.2.1 excloud.FIELD_MEANINGS.TEMPERATURE
常量含义：温度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.TEMPERATURE
3.2.2.2 excloud.FIELD_MEANINGS.HUMIDITY
常量含义：湿度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.HUMIDITY
3.2.2.3 excloud.FIELD_MEANINGS.PARTICULATE
常量含义：颗粒物浓度
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.PARTICULATE
3.2.2.4 excloud.FIELD_MEANINGS.ACIDITY
常量含义：酸度（pH值）
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.ACIDITY
3.2.2.5 excloud.FIELD_MEANINGS.ALKALINITY
常量含义：碱度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.ALKALINITY
3.2.2.6 excloud.FIELD_MEANINGS.ALTITUDE
常量含义：海拔；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.ALTITUDE
3.2.2.7 excloud.FIELD_MEANINGS.WATER_LEVEL
常量含义：水位；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.WATER_LEVEL
3.2.2.8 excloud.FIELD_MEANINGS.ENV_TEMPERATURE
常量含义：环境温度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.ENV_TEMPERATURE
3.2.2.9 excloud.FIELD_MEANINGS.POWER_METERING
常量含义：电量计量；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.POWER_METERING
3.2.2.10 excloud.FIELD_MEANINGS.WORK_STATUS
常量含义：工作状态；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.WORK_STATUS
3.2.3 资产管理类 (512-767)
3.2.3.1 excloud.FIELD_MEANINGS.GNSS_LONGITUDE
常量含义：GNSS经度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_LONGITUDE
3.2.3.2 excloud.FIELD_MEANINGS.GNSS_LATITUDE
常量含义：GNSS纬度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_LATITUDE
3.2.3.3 excloud.FIELD_MEANINGS.SPEED
常量含义：行驶速度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SPEED
3.2.3.4 excloud.FIELD_MEANINGS.GNSS_CN
常量含义：GNSS卫星信噪比
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_CN
3.2.3.5 excloud.FIELD_MEANINGS.SATELLITES_TOTAL
常量含义：搜索到的卫星总数
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SATELLITES_TOTAL
3.2.3.6 excloud.FIELD_MEANINGS.SATELLITES_VISIBLE
常量含义：可见卫星数；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SATELLITES_VISIBLE
3.2.3.7 excloud.FIELD_MEANINGS.HEADING
常量含义：航向角；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.HEADING
3.2.3.8 excloud.FIELD_MEANINGS.LOCATION_METHOD
常量含义：定位方式标识
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
值取值范围：0（基站定位）、1（GNSS定位）、2（混合定位）
示例代码：local field = excloud.FIELD_MEANINGS.LOCATION_METHOD
3.2.3.9 excloud.FIELD_MEANINGS.GNSS_INFO
常量含义：GNSS芯片型号和固件版本号；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_INFO
3.2.3.10 excloud.FIELD_MEANINGS.DIRECTION
常量含义：方向角
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.DIRECTION
3.2.4 设备参数类 (768-1023)
3.2.4.1 excloud.FIELD_MEANINGS.HEIGHT
常量含义：设备物理高度或安装高度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.HEIGHT
3.2.4.2 excloud.FIELD_MEANINGS.WIDTH
常量含义：设备物理宽度尺寸；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.WIDTH
3.2.4.3 excloud.FIELD_MEANINGS.ROTATION_SPEED
常量含义：转速；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.ROTATION_SPEED
3.2.4.4 excloud.FIELD_MEANINGS.BATTERY_LEVEL
常量含义：电池电压(mV)；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.BATTERY_LEVEL
3.2.4.5 excloud.FIELD_MEANINGS.SERVING_CELL
常量含义：驻留小区（服务小区信息）；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SERVING_CELL
3.2.4.6 excloud.FIELD_MEANINGS.CELL_INFO
常量含义：小区信息（服务小区+邻区）；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.BINARY
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.CELL_INFO
3.2.4.7 excloud.FIELD_MEANINGS.COMPONENT_MODEL
常量含义：元器件型号， 用于标识设备中具体元器件的型号信息；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.COMPONENT_MODEL
3.2.4.8 excloud.FIELD_MEANINGS.GPIO_LEVEL
常量含义：上报GPIO高低电平；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.GPIO_LEVEL
3.2.4.9 excloud.FIELD_MEANINGS.BOOT_REASON
常量含义：开机原因；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
值取值范围：是pm.lastReson()接口返回的值，详细见https://docs.openluat.com/osapi/core/pm/#45-pmlastreson
示例代码：local field = excloud.FIELD_MEANINGS.BOOT_REASON
3.2.4.10 excloud.FIELD_MEANINGS.BOOT_COUNT
常量含义：开机次数；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.BOOT_COUNT
3.2.4.11 excloud.FIELD_MEANINGS.SLEEP_MODE
常量含义：上报设备休眠模式；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
值取值范围：0（正常模式）、1（轻休眠）、3（psm+深度休眠）
示例代码：local field = excloud.FIELD_MEANINGS.SLEEP_MODE
3.2.4.12 excloud.FIELD_MEANINGS.WAKE_INTERVAL
常量含义：定时唤醒间隔，上报设备休眠定时器时间；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.WAKE_INTERVAL
3.2.4.13 excloud.FIELD_MEANINGS.NETWORK_IP_TYPE
常量含义：网络IP类型，设备入网的IPV4/IPV6标志；
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
值取值范围：0（IPv4）、1（IPv6）
示例代码：local field = excloud.FIELD_MEANINGS.NETWORK_IP_TYPE
3.2.4.14 excloud.FIELD_MEANINGS.NETWORK_TYPE
常量含义：网络类型，上报当前联网方式（4G/WiFi/以太网）；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.NETWORK_TYPE
3.2.4.15 excloud.FIELD_MEANINGS.SIGNAL_STRENGTH_4G
常量含义：4G信号强度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SIGNAL_STRENGTH_4G
3.2.4.16 excloud.FIELD_MEANINGS.SIM_ICCID
常量含义：SIM卡ICCID；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
值格式：20位数字字符串
示例代码：local field = excloud.FIELD_MEANINGS.SIM_ICCID
3.2.4.17 excloud.FIELD_MEANINGS.FILE_UPLOAD_TYPE
常量含义：文件上传类型；
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
值取值范围：1（图片）、2（音频）
示例代码：local field = excloud.FIELD_MEANINGS.FILE_UPLOAD_TYPE
3.2.4.18 excloud.FIELD_MEANINGS.FILE_NAME
常量含义：文件名称；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.FILE_NAME
3.2.4.19 excloud.FIELD_MEANINGS.FILE_SIZE
常量含义：上传文件大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.FILE_SIZE
3.2.4.20 excloud.FIELD_MEANINGS.UPLOAD_RESULT_STATUS
常量含义：上传结果状态；
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.UPLOAD_RESULT_STATUS
3.2.4.21 excloud.FIELD_MEANINGS.MTN_LOG_FILE_INDEX
常量含义：运维日志文件序号；
常量类型：number（字段标识）
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
值取值范围：1、2、3、4，四个日志文件中的某个。
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_FILE_INDEX
注意事项：用户通常不需要关注运维日志上传过程，只需要在setup中配置mtn_log_enabled=true即可，运维日志上传流程底层已实现。
3.2.4.22 excloud.FIELD_MEANINGS.MTN_LOG_FILE_TOTAL
常量含义：运维日志文件总数；
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
值取值范围：0~4
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_FILE_TOTAL
注意事项：用户通常不需要关注运维日志上传过程，只需要在setup中配置mtn_log_enabled=true即可，运维日志上传流程底层已实现。
3.2.4.23 excloud.FIELD_MEANINGS.MTN_LOG_FILE_SIZE
常量含义：运维日志文件大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_FILE_SIZE
注意事项：用户通常不需要关注运维日志上传过程，只需要在setup中配置mtn_log_enabled=true即可，运维日志上传流程底层已实现。
3.2.4.24 excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_STATUS_FIELD
常量含义：运维日志上传状态；
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
值取值范围：0（开始上传）、1（上传成功）、2（上传失败）
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_STATUS_FIELD
注意事项：用户通常不需要关注运维日志上传过程，只需要在setup中配置mtn_log_enabled=true即可，运维日志上传流程底层已实现。
3.2.4.25 excloud.FIELD_MEANINGS.MTN_LOG_FILE_NAME
常量含义：运维日志文件名称；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_FILE_NAME
注意事项：用户通常不需要关注运维日志上传过程，只需要在setup中配置mtn_log_enabled=true即可，运维日志上传流程底层已实现。
3.2.4.26 excloud.FIELD_MEANINGS.BADGE_TOTAL_DISK
常量含义：工牌总磁盘空间；
值数据类型：excloud.DATA_TYPES.ASCII 或 excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.BADGE_TOTAL_DISK
业务说明：用于工牌设备上报其总磁盘空间容量，单位可以是字节或者带单位的字符串。
3.2.4.27 excloud.FIELD_MEANINGS.BADGE_AVAILABLE_DISK
常量含义：工牌剩余磁盘空间；
值数据类型：excloud.DATA_TYPES.ASCII 或 excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.BADGE_AVAILABLE_DISK
业务说明：用于工牌设备上报其剩余磁盘空间容量，单位可以是字节或者带单位的字符串。
3.2.4.28 excloud.FIELD_MEANINGS.BADGE_TOTAL_MEM
常量含义：工牌总内存；
值数据类型：excloud.DATA_TYPES.ASCII 或 excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.BADGE_TOTAL_MEM
业务说明：用于工牌设备上报其总内存容量，单位可以是字节或者带单位的字符串。
3.2.4.29 excloud.FIELD_MEANINGS.BADGE_AVAILABLE_MEM
常量含义：工牌剩余内存；
值数据类型：excloud.DATA_TYPES.ASCII 或 excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.BADGE_AVAILABLE_MEM
业务说明：用于工牌设备上报其剩余内存容量，单位可以是字节或者带单位的字符串。
3.2.4.30 excloud.FIELD_MEANINGS.BADGE_RECORD_COUNT
常量含义：工牌录音数量；
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.BADGE_RECORD_COUNT
业务说明：用于工牌设备上报其存储的录音文件数量。
3.2.4.31 excloud.FIELD_MEANINGS.DEVICE_ID
常量含义：设备号（4G模块使用IMEI，WiFi/蓝牙模块使用MAC地址）；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.DEVICE_ID
3.2.4.32 excloud.FIELD_MEANINGS.VOLTAGE
常量含义：电压；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.VOLTAGE
3.2.4.33 excloud.FIELD_MEANINGS.SET_VOLTAGE
常量含义：设置电压；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.SET_VOLTAGE
3.2.5 软件 & 短信日志类 (1024-1279)
3.2.5.1 excloud.FIELD_MEANINGS.LUA_CORE_ERROR
常量含义：Lua核心库错误上报；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.LUA_CORE_ERROR
3.2.5.2 excloud.FIELD_MEANINGS.LUA_EXT_ERROR
常量含义：Lua扩展库错误
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.LUA_EXT_ERROR
3.2.5.3 excloud.FIELD_MEANINGS.LUA_APP_ERROR
常量含义：Lua业务错误；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.LUA_APP_ERROR
3.2.5.4 excloud.FIELD_MEANINGS.FIRMWARE_VERSION
常量含义：固件版本号；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.FIRMWARE_VERSION
3.2.5.5 excloud.FIELD_MEANINGS.SMS_FORWARD
常量含义：短信转发（SMS转发）；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_FORWARD
3.2.5.6 excloud.FIELD_MEANINGS.CALL_FORWARD
常量含义：来电转发；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.CALL_FORWARD
3.2.5.7 excloud.FIELD_MEANINGS.SYSTEM_MEM_TOTAL
常量含义：系统总内存大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SYSTEM_MEM_TOTAL
3.2.5.8 excloud.FIELD_MEANINGS.SYSTEM_MEM_CURRENT_USED
常量含义：系统当前已使用内存大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SYSTEM_MEM_CURRENT_USED
3.2.5.9 excloud.FIELD_MEANINGS.SYSTEM_MEM_MAX_USED
常量含义：系统历史最高已使用内存大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SYSTEM_MEM_MAX_USED
3.2.5.10 excloud.FIELD_MEANINGS.LUA_MEM_TOTAL
常量含义：Lua 虚拟机总内存大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.LUA_MEM_TOTAL
3.2.5.11 excloud.FIELD_MEANINGS.LUA_MEM_CURRENT_USED
常量含义：Lua 虚拟机当前已使用内存大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.LUA_MEM_CURRENT_USED
3.2.5.12 excloud.FIELD_MEANINGS.LUA_MEM_MAX_USED
常量含义：Lua 虚拟机历史最高已使用内存大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.LUA_MEM_MAX_USED
3.2.5.13 excloud.FIELD_MEANINGS.PSRANM_MEM_TOTAL
常量含义：PSRANM 总内存大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.PSRANM_MEM_TOTAL
3.2.5.14 excloud.FIELD_MEANINGS.PSRANM_MEM_CURRENT_USED
常量含义：PSRANM 当前已使用内存大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.PSRANM_MEM_CURRENT_USED
3.2.5.15 excloud.FIELD_MEANINGS.PSRANM_MEM_MAX_USED
常量含义：PSRANM 历史最高已使用内存大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.PSRANM_MEM_MAX_USED
3.2.5.16 excloud.FIELD_MEANINGS.SMS_SEQ
常量含义：SMS 流水号；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_SEQ
3.2.5.17 excloud.FIELD_MEANINGS.SMS_CALLEE
常量含义：SMS 短信接收方号码；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_CALLEE
3.2.5.18 excloud.FIELD_MEANINGS.SMS_CONTENT
常量含义：SMS 短信内容；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_CONTENT
3.2.5.19 excloud.FIELD_MEANINGS.SMS_STATUS
常量含义：SMS 短信状态码；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_STATUS
3.2.5.20 excloud.FIELD_MEANINGS.SMS_CALLER
常量含义：SMS 短信发送方号码；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_CALLER
3.2.5.21 excloud.FIELD_MEANINGS.SMS_LONG_FLAG
常量含义：SMS 长短信标志；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_LONG_FLAG
3.2.5.22 excloud.FIELD_MEANINGS.SMS_LONG_TOTAL
常量含义：SMS 长短信分片总数；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_LONG_TOTAL
3.2.5.23 excloud.FIELD_MEANINGS.SMS_LONG_INDEX
常量含义：SMS 长短信当前分片序号；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_LONG_INDEX
3.2.5.24 excloud.FIELD_MEANINGS.SMS_MSG_REF
常量含义：运营商消息参考号；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_MSG_REF
3.2.5.25 excloud.FIELD_MEANINGS.SMS_STATUS_RAW
常量含义：SMS 状态码原始值；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_STATUS_RAW
3.2.6 通用测试数据类 (1280-1535)
3.2.6.1 excloud.FIELD_MEANINGS.TIMESTAMP
常量含义：时间戳
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.TIMESTAMP
3.2.6.2 excloud.FIELD_MEANINGS.RANDOM_DATA
常量含义：无意义数据；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.BINARY
传输方向：设备⇄平台
示例代码：local field = excloud.FIELD_MEANINGS.RANDOM_DATA
3.2.6.3 excloud.FIELD_MEANINGS.BUSINESS_SN
常量含义：业务SN；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.BUSINESS_SN
3.2.6.4 excloud.FIELD_MEANINGS.HEARTBEAT_COUNT
常量含义：心跳次数；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.HEARTBEAT_COUNT
3.2.6.5 excloud.FIELD_MEANINGS.ONLINE_DURATION
常量含义：在线时长；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.ONLINE_DURATION
3.3 运维日志状态常量
3.3.1 excloud.MTN_LOG_STATUS.START
常量含义：运维日志开始上传状态；表示运维日志上传过程开始，设备准备上传日志文件；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER；
传输方向：设备→平台；
示例代码：local status = excloud.MTN_LOG_STATUS.START
注意事项：用户通常不需要关注运维日志上传过程，只需要在setup中配置mtn_log_enabled=true即可，运维日志上传流程底层已实现。
3.3.2 excloud.MTN_LOG_STATUS.SUCCESS
常量含义：运维日志上传成功状态；表示运维日志文件已成功上传至平台，文件传输完整且校验通过；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER；
传输方向：设备→平台；
示例代码：local status = excloud.MTN_LOG_STATUS.SUCCESS
注意事项：用户通常不需要关注运维日志上传过程，只需要在setup中配置mtn_log_enabled=true即可，运维日志上传流程底层已实现。
3.3.3 excloud.MTN_LOG_STATUS.FAILED
常量含义：运维日志上传失败状态；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER；
传输方向：设备→平台；
示例代码：local status = excloud.MTN_LOG_STATUS.FAILED
注意事项：用户通常不需要关注运维日志上传过程，只需要在setup中配置mtn_log_enabled=true即可，运维日志上传流程底层已实现。
3.4 运维日志写入方式常量
3.4.1 excloud.MTN_LOG_CACHE_WRITE
常量含义：缓存写入方式；
日志数据先写入内存缓存区，当缓存达到一定大小或时间间隔时批量写入存储介质，适用于频繁日志记录场景，能减少存储设备磨损；
传输方向：设备内部设置选项，
在setup中通过mtn_log_write_way配置，比如mtn_log_write_way = excloud.MTN_LOG_CACHE_WRITE
示例代码：mtn_log_write_way = excloud.MTN_LOG_CACHE_WRITE
3.4.2 excloud.MTN_LOG_ADD_WRITE
常量含义：追加写入方式；
日志数据立即追加写入存储介质文件末尾，确保日志实时持久化，适用于重要日志记录场景，但可能增加存储设备读写次数；
传输方向：设备内部设置选项，
在setup中通过mtn_log_write_way配置，比如mtn_log_write_way = excloud.MTN_LOG_ADD_WRITE
示例代码：mtn_log_write_way = excloud.MTN_LOG_ADD_WRITE
四、函数详解
4.1 excloud.setup(otps)
功能
配置 excloud 服务参数；
注意事项
必须在调用 excloud.open()开启服务前调用，开启服务后再次调用会失败；
参数
otps
参数含义：配置参数表；
数据类型：table；
是否必选：是；
参数格式：
{
参数含义：传输协议；
数据类型：string
是否必选：是；
参数示例："tcp"或"mqtt"
参数示例："tcp"
注意事项：无
参数名称： opts.transport参数含义：服务器地址；
数据类型：string
是否必选：否；
取值范围：IP地址或域名，如"124.71.128.165"；默认不配置，由getip自动获取
参数示例："124.71.128.165"
注意事项：仅当use_getip=false时需要手动配置，此时必须配置host和port；使用getip服务时无需配置
参数名称： opts.host参数含义：服务器端口；
数据类型：number
是否必选：否；
取值范围：1-65535，默认不配置，由getip自动获取
参数示例：9108
注意事项：仅当use_getip=false时需要手动配置，此时必须配置host和port；使用getip服务时无需配置
参数名称： opts.port参数含义：用户项目密钥；
数据类型：string
是否必选：否；
取值范围：不填则通过getip自动获取
参数示例：自定义密钥
注意事项：手动配置的auth_key优先使用，getip返回的auth_key不会覆盖用户配置；
getip请求中的key字段使用固定占位符（unusedkey-设备ID）构造，不再使用用户配置的auth_key，后台不校验该key内容
参数名称： opts.auth_key参数含义：是否自动重连；
数据类型：boolean
是否必选：否；
取值范围：true/false，默认true
参数示例：_true
注意事项：无
参数名称： opts.auto_reconnect参数含义：重连间隔(秒)；
数据类型：number
是否必选：否；
取值范围：不做限制，建议使用默认值，默认10秒
参数示例：10
注意事项：无
参数名称： opts.reconnect_interval参数含义：最大重连次数；
数据类型：number
是否必选：否；
取值范围：不做限制，建议使用默认值，默认3
参数示例：3
注意事项：无
参数名称： opts.max_reconnect参数含义：是否启用运维日志；
数据类型：boolean
是否必选：否；
取值范围：true/false，默认false
参数示例：true
注意事项：无
参数名称： opts.mtn_log_enabled参数含义：每个文件的块数；
n == 0 ：关闭日志文件，
n ≥ 1：每个日志文件设置的block数量，一个block大小为4k，保存4个日志文件。
默认为1，即每个文件一个block 4k，总共为4个文件16k
每次设置文件大小前会检查是否已经往运维日志写了数据，已经写数据则会将之前的运维日志都清空
数据类型：number
是否必选：否；
默认值：1
参数示例：
注意事项：无
参数名称： opts.mtn_log_blocks参数含义：写入方式；
数据类型：number
是否必选：否；
取值范围：excloud.MTN_LOG_CACHE_WRITE或excloud.MTN_LOG_ADD_WRITE，
默认excloud.MTN_LOG_CACHE_WRITE
参数示例：excloud.MTN_LOG_CACHE_WRITE
注意事项：无
参数名称： opts.mtn_log_write_way参数含义：MQTT发布所有消息的 QoS等级；
数据类型：number
是否必选：否；
取值范围：0，1，默认0
参数示例：0
注意事项：无
参数名称： opts.qos参数含义：mqtt连接心跳间隔(秒)；
数据类型：number
是否必选：否；
取值范围：默认300
最小值：15秒（若传入小于15的值，会被强制设为15秒）；
最大值：600秒（若传入大于600的值，会被强制设为600秒）；
参数示例：300
注意事项：无
参数名称： opts.keepalive参数含义：MQTT retain标志；
数据类型：number
是否必选：否；
取值范围：0或1，默认0（0表示不保留消息，1表示保留消息）
参数示例：0
注意事项：无
参数名称： opts.retain参数含义：MQTT clean session标志；
数据类型：boolean
是否必选：否；
取值范围：true/false，默认true
参数示例：_true
注意事项：无
参数名称： opts.clean_session参数含义：虚拟设备手机号（设备类型为9时必填）；
使用pc模拟器时候需要使用，模拟器的设备id是手机号+虚拟设备序列号
数据类型：string
是否必选：否；
取值范围：自己iot云平台注册的手机号
注意事项：无
参数名称： opts.virtual_phone_number参数含义：虚拟设备序列号（0-999）；
可允许1000个虚拟设备测试
数据类型：number
是否必选：否；
取值范围：0-999，默认0
参数示例：1
注意事项：无
参数名称： opts.virtual_serial_num参数含义：连接超时时间(秒)；
数据类型：number
是否必选：否；
取值范围：不做限制，默认30秒
参数示例：30
注意事项：无
参数名称： opts.timeout参数含义：SSL/TLS配置（同时控制TCP和MQTT通道）；
数据类型：boolean或table
是否必选：否；
取值范围：true/false或SSL配置表，默认false
TCP传输时仅作开关使用：传true开启SSL，传SSL配置表也视为开启（证书通过server_cert/client_cert/client_key/client_password单独配置）
MQTT传输时支持布尔或SSL配置表，配置表字段参考mqtt.create的ssl参数
参数示例：true
注意事项：UDP传输不受该参数影响
参数名称： opts.ssl参数含义：MQTT客户端标识；
数据类型：string
是否必选：否；
取值范围：不填则自动获取（设备ID）
参数示例：自定义客户端标识
注意事项：无
参数名称： opts.client_id参数含义：MQTT用户名；
数据类型：string
是否必选：否；
取值范围：不填则自动获取（同客户端标识）
参数示例：自定义用户名
注意事项：无
参数名称： opts.username参数含义：MQTT密码；
数据类型：string
是否必选：否；
取值范围：不填则自动获取（设备MUID）
参数示例：自定义密码
注意事项：无
参数名称： opts.password参数含义：UDP鉴权密钥；
数据类型：string
是否必选：否；
取值范围：使用UDP传输时必填，不填则通过getip获取
参数示例：UDP鉴权密钥字符串
注意事项：无
参数名称： opts.udp_auth_key参数含义：MQTT鉴权发布主题；
数据类型：string
是否必选：否；
取值范围：不填则使用默认值/AirCloud/up/{设备标识}/auth
参数示例：自定义鉴权发布主题
注意事项：无
参数名称： opts.mqtt_pub_auth_topic参数含义：MQTT数据发布主题；
数据类型：string
是否必选：否；
取值范围：不填则使用默认值/AirCloud/up/{设备标识}/all
参数示例：自定义数据发布主题
注意事项：无
参数名称： opts.mqtt_pub_data_topic参数含义：MQTT鉴权订阅主题；
数据类型：string
是否必选：否；
取值范围：不填则使用默认值/AirCloud/down/{设备标识}/auth
参数示例：自定义鉴权订阅主题
注意事项：无
参数名称： opts.mqtt_sub_auth_topic参数含义：MQTT数据订阅主题；
数据类型：string
是否必选：否；
取值范围：不填则使用默认值/AirCloud/down/{设备标识}/all
参数示例：自定义数据订阅主题
注意事项：无
参数名称： opts.mqtt_sub_data_topic参数含义：MQTT遗嘱消息主题；
数据类型：string
是否必选：否；
取值范围：不填则不设置遗嘱消息
参数示例：自定义遗嘱主题
注意事项：需同时配置will_payload才生效
参数名称： opts.will_topic参数含义：MQTT遗嘱消息内容；
数据类型：string
是否必选：否；
取值范围：不填则不设置遗嘱消息
参数示例：自定义遗嘱消息内容
注意事项：需同时配置will_topic才生效
参数名称： opts.will_payload参数含义：MQTT遗嘱消息QoS等级；
数据类型：number
是否必选：否；
取值范围：0、1、2，默认0
参数示例：0
注意事项：无
参数名称： opts.will_qos参数含义：MQTT遗嘱消息retain标志；
数据类型：number
是否必选：否；
取值范围：0或1，默认0
参数示例：0
注意事项：无
参数名称： opts.will_retain参数含义：MQTT接收缓冲区大小(字节)；
数据类型：number
是否必选：否；
取值范围：默认32*1024
参数示例：32768
注意事项：无
参数名称： opts.mqtt_rx_size参数含义：MQTT连接超时时间(秒)；
数据类型：number
是否必选：否；
取值范围：默认30秒
参数示例：30
注意事项：无
参数名称： opts.mqtt_conn_timeout参数含义：本地端口；
数据类型：number
是否必选：否；
取值范围：nil表示自动分配
参数示例：0
注意事项：无
参数名称： opts.local_port参数含义：TCP keepalive空闲时间；
数据类型：number
是否必选：否；
取值范围：nil表示使用系统默认值
参数示例：60
注意事项：无
参数名称： opts.keep_idle参数含义：TCP keepalive探测间隔；
数据类型：number
是否必选：否；
取值范围：nil表示使用系统默认值
参数示例：10
注意事项：无
参数名称： opts.keep_interval参数含义：TCP keepalive探测次数；
数据类型：number
是否必选：否；
取值范围：nil表示使用系统默认值
参数示例：3
注意事项：无
参数名称： opts.keep_cnt参数含义：服务器CA证书；
数据类型：string
是否必选：否；
取值范围：证书路径或内容，nil表示使用默认
参数示例："/luatdb/ca.crt"
注意事项：无
参数名称： opts.server_cert参数含义：客户端证书；
数据类型：string
是否必选：否；
取值范围：证书路径或内容，nil表示不使用
参数示例："/luatdb/client.crt"
注意事项：无
参数名称： opts.client_cert参数含义：客户端私钥；
数据类型：string
是否必选：否；
取值范围：私钥路径或内容，nil表示不使用
参数示例："/luatdb/client.key"
注意事项：无
参数名称： opts.client_key参数含义：客户端私钥口令；
数据类型：string
是否必选：否；
取值范围：私钥加密口令，nil表示无口令
参数示例：自定义口令
注意事项：无
参数名称： opts.client_password参数含义：是否使用getip服务发现；
数据类型：boolean
是否必选：否；
取值范围：true/false，默认true
true表示通过getip服务自动获取服务器地址、端口及鉴权信息
false表示手动配置host/port，此时必须手动配置host和port
参数示例：true
注意事项：无
参数名称： opts.use_getip参数含义：getip服务地址；
数据类型：string
是否必选：否；
取值范围：默认https://api.luatos.com/iot/getip，可配置为第三方getip服务器地址
参数示例："https://third-party.getip.example.com/iot/getip"
注意事项：仅当use_getip=true时生效，配置后getip请求将发往该地址
参数名称： opts.getip_url参数含义：是否优先IPv6；
数据类型：boolean
是否必选：否；
取值范围：true/false，默认false
参数示例：false
注意事项：无
参数名称： opts.ipv6参数含义：getip最大重试次数；
数据类型：number
是否必选：否；
取值范围：默认3
参数示例：3
注意事项：无
参数名称： opts.max_getip_retry参数含义：手动配置图片上传信息；
数据类型：table
是否必选：否；
取值范围：包含url、data_key、data_param等字段的上传配置表，不填则通过getip获取
参数示例：{url = "https://xxxxx", data_key = "f", data_param = {key = "xxx", tip = ""}}
注意事项：手动配置优先于getip获取的配置；若配置有opts.imginfo_from_luat = true，则手动参数无效，固定使用合宙平台返回的上传参数
参数名称： opts.current_imginfo参数含义：手动配置音频上传信息；
数据类型：table
是否必选：否；
取值范围：包含url、data_key、data_param等字段的上传配置表，不填则通过getip获取
参数示例：{url = "https://xxxxx", data_key = "f", data_param = {key = "xxx", tip = ""}}
注意事项：手动配置优先于getip获取的配置；若配置有opts.audinfo_from_luat = true，则手动参数无效，固定使用合宙平台返回的上传参数
参数名称： opts.current_audinfo参数含义：手动配置运维日志上传信息；
数据类型：table
是否必选：否；
取值范围：包含url、data_key、data_param等字段的上传配置表，不填则通过getip获取
参数示例：{url = "https://xxxxx", data_key = "f", data_param = {key = "xxx", tip = ""}}
注意事项：手动配置优先于getip获取的配置；若配置有opts.mtninfo_from_luat = true，则手动参数无效，固定使用合宙平台返回的上传参数
参数名称： opts.current_mtninfo参数含义：图片上传是否指定使用合宙平台参数；
数据类型：boolean
是否必选：否；
取值范围：true/false，默认false
true表示upload_image()上传图片时，强制使用合宙平台返回的上传参数；
参数示例：true
注意事项：与current_imginfo手动配置二者选其一；
参数名称： opts.imginfo_from_luat参数含义：音频上传是否指定使用合宙平台参数；
数据类型：boolean
是否必选：否；
取值范围：true/false，默认false
true表示upload_audio()上传音频时，强制使用合宙平台返回的上传参数；
参数示例：true
注意事项：与current_audinfo手动配置二者选其一；
参数名称： opts.audinfo_from_luat参数含义：运维日志上传是否指定使用合宙平台参数；
数据类型：boolean
是否必选：否；
取值范围：true/false，默认false
true表示upload_mtnlog()上传运维日志时，强制使用合宙平台返回的上传参数；
参数示例：true
注意事项：与current_mtninfo手动配置二者选其一；
参数名称： opts.mtninfo_from_luat参数含义：是否启用AirCloud运维日志；
数据类型：boolean
是否必选：否；
取值范围：true/false，默认false
true表示在excloud服务启动/关闭时记录系统运维日志
参数示例：true
注意事项：需同时开启mtn_log_enabled
参数名称： opts.aircloud_mtn_log_enabled参数含义：调试模式；
数据类型：boolean
是否必选：否；
取值范围：true/false，默认false
参数示例：true
注意事项：开启后输出更多调试日志，包括收发HEX日志（默认不打印）
参数名称： opts.debug }
返回值
local result, err = excloud.setup(params)
result
含义说明：配置是否成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示配置成功，false表示配置失败；
返回示例：true
err
含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："excloud is already open"
示例
excloud.setup() 支持多种配置场景，常见的示例如下：
-- 场景一：TCP传输（默认），自动通过getip获取服务器信息，最简单用法
local ok, err_msg = excloud.setup({
transport = "tcp", -- 使用TCP传输
})
if not ok then
log.error("配置失败:", err_msg)
return
end
-- 场景二：TCP传输 + 自动重连 + 启用运维日志（本地记录 + AirCloud上传）
local ok, err_msg = excloud.setup({
transport = "tcp", -- 使用TCP传输
auto_reconnect = true, -- 自动重连
reconnect_interval = 10, -- 重连间隔(秒)
max_reconnect = 5, -- 最大重连次数
mtn_log_enabled = true, -- 启用本地运维日志记录
mtn_log_blocks = 2, -- 日志文件块数
mtn_log_write_way = excloud.MTN_LOG_CACHE_WRITE, -- 缓存写入方式
aircloud_mtn_log_enabled = true, -- 启用AirCloud运维日志上传
})
if not ok then
log.error("配置失败:", err_msg)
return
end
-- 场景三：MQTT传输，自定义客户端标识与主题（可选，不配置则自动生成）
local ok, err_msg = excloud.setup({
transport = "mqtt", -- 使用MQTT传输
client_id = "my_device_001", -- MQTT客户端标识（可选）
mqtt_pub_auth_topic = "iot/pub/auth/001", -- 自定义鉴权发布主题（可选）
mqtt_sub_auth_topic = "iot/sub/auth/001", -- 自定义鉴权订阅主题（可选）
mqtt_pub_data_topic = "iot/pub/data/001", -- 自定义数据发布主题（可选）
mqtt_sub_data_topic = "iot/sub/data/001", -- 自定义数据订阅主题（可选）
})
if not ok then
log.error("配置失败:", err_msg)
return
end
-- 场景四：UDP传输
local ok, err_msg = excloud.setup({
transport = "udp", -- 使用UDP传输
})
if not ok then
log.error("配置失败:", err_msg)
return
end
-- 场景五：关闭getip，手动指定服务器地址和端口
local ok, err_msg = excloud.setup({
use_getip = false, -- 关闭getip服务自动发现
host = "124.71.128.165", -- 手动指定服务器地址
port = 9108, -- 手动指定服务器端口
})
if not ok then
log.error("配置失败:", err_msg)
return
end
-- 场景六：虚拟设备测试（配合平台虚拟设备功能）
local ok, err_msg = excloud.setup({
virtual_phone_number = "15893470522", -- 虚拟设备手机号（11位）
virtual_serial_num = 1, -- 虚拟设备序列号（0-999）
})
if not ok then
log.error("配置失败:", err_msg)
return
end
-- 场景七：手动配置文件上传信息（不通过getip获取上传配置）
local ok, err_msg = excloud.setup({
current_imginfo = {
url = "https://gps.openluat.com/iot/aircloud/upload/image", -- 图片上传URL
data_key = "f", -- 文件表单字段键名
data_param = { key = "xxxxxxx", tip = "" }, -- 上传附加参数
},
})
if not ok then
log.error("配置失败:", err_msg)
return
end
-- 场景八：getip 使用第三方服务器获取连接信息，运维日志上传使用合宙云平台
local ok, err_msg = excloud.setup({
getip_url = "https://third-party.getip.example.com/iot/getip", -- getip使用第三方服务器获取连接信息
mtn_log_enabled = true, -- 启用本地运维日志记录
mtn_log_blocks = 2, -- 日志文件块数
mtn_log_write_way = excloud.MTN_LOG_CACHE_WRITE, -- 缓存写入方式
aircloud_mtn_log_enabled = true, -- 启用AirCloud运维日志上传
mtninfo_from_luat = true, -- 运维日志上传使用合宙云平台
})
if not ok then
log.error("配置失败:", err_msg)
return
end
4.2 excloud.on(cbfunc)
功能
注册事件回调函数，用于监听和响应 excloud 服务的状态变化事件；
注意事项
必须在 excloud.open()之前调用；
参数
cbfunc
含义说明：excloud事件回调函数；
数据类型：function；
取值范围：回调函数格式为 function call_back(event, data) ... end，其中：
event: string类型，事件类型，包括：
"connect_result" -- 连接结果
"disconnect" -- 连接断开
"auth_result" -- 认证结果
"send_result" -- excloud.send()发送结果
"message" -- 收到云端消息
"reconnect_failed" -- 开启自动重连后，如果重连失败会返回此消息
"mtn_log_upload_start" --运维日志上传开始事件
"mtn_log_upload_progress" -- 运维日志上传进度事件
"mtn_log_upload_complete" -- 运维日志上传完成事件
"auth_key_error" -- getip获取auth_key失败事件
"file_upload" -- 文件上传异常事件（如ZBUFF内存不足时触发）
data: table类型，事件相关数据，具体格式根据事件类型不同而不同；
"connect_result": 连接结果事件
data格式: {
--boolean类型，连接是否成功
-- true表示连接成功，false表示连接失败
["success"] = ,
-- 连接成功时，为nil
-- 连接失败时，为string类型，表示错误信息
["error"] = ,
}
"disconnect": 连接断开事件
data格式: {
-- string或nil类型
-- 断开原因，可能为nil
["error"] = ,
}
"auth_result": 认证结果事件
data格式: {
-- boolean类型，认证是否成功
-- true表示认证成功，false表示认证失败
["success"] = ,
-- string类型，认证结果消息
["message"] = ,
}
"send_result": 数据发送结果事件
data格式: {
-- boolean类型，发送是否成功
-- true表示发送成功，false表示发送失败
["success"] = ,
-- string或nil类型
-- 发送成功时，为表示成功的string类型字符串
-- 发送失败时，为string类型，表示错误信息
["error_msg"] = ,
-- number类型，消息流水号
["sequence_num"] = ,
}
"message": 收到云端消息事件
data格式: {
-- table类型，消息头信息
["header"] = {
-- string类型，设备ID（十六进制字符串）
["device_id"] = ,
-- number类型，序列号
["sequence_num"] = ,
-- number类型，消息长度
["msg_length"] = ,
-- number类型，协议版本
["protocol_version"] = ,
-- boolean类型，是否需要回复
["need_reply"] = ,
-- boolean类型，是否为UDP承载
["is_udp"] = ,
-- boolean类型，是否包含auth_key
["has_auth_key"] = ,
},
-- string或nil类型
-- UDP传输时存在，为认证密钥
-- TCP/MQTT传输时没有此字段
["auth_key"] = ,
-- boolean类型，UDP认证密钥是否匹配
-- UDP传输时存在，为true表示匹配，false表示不匹配
-- TCP/MQTT传输时没有此字段
["udp_auth_key_matched"] = ,
-- table类型，TLV字段数组
["tlvs"] = {
{
-- number类型，字段含义（对应FIELD_MEANINGS常量）
["field"] = ,
-- number类型，数据类型（对应DATA_TYPES常量）
["type"] = ,
-- any类型，字段值（已解码）
["value"] = ,
-- number类型，数据长度
["length"] = ,
},...},
}
}
"reconnect_failed": 重连失败事件
data格式: {
-- number类型，重连尝试次数
["count"] = ,
-- number类型，最大重连次数
["max_reconnect"] = ,
-- boolean或nil类型
-- 是否getip失败，可能为nil
["getip_failed"] = ,
}
"mtn_log_upload_start"：运维日志上传开始事件
data格式: {
-- number类型，总文件数
["file_count"] = ,
}
"mtn_log_upload_progress"：运维日志上传进度事件
data格式: {
-- number类型，当前文件序号
["current_file"] = ,
-- number类型，总文件数
["total_files"] = ,
-- string类型，当前文件名
["file_name"] = ,
-- number类型，当前文件大小
["file_size"] = ,
-- string类型，状态
-- "start"表示开始上传
-- "success"表示上传成功
-- "failed"表示上传失败
["status"] = ,
-- string或nil类型
-- 上传失败时，为string类型，表示错误信息
-- 上传成功时，为nil
["error_msg"] = ,
}
"mtn_log_upload_complete"： 运维日志上传完成事件
data格式: {
-- number类型，成功数量
["success_count"] = ,
-- number类型，失败数量
["failed_count"] = ,
-- number类型，总文件数
["total_files"] = ,
}
"auth_key_error"：getip获取auth_key失败事件
data格式: {
-- string类型，错误信息
["error"] = ,
}
"file_upload"：文件上传异常事件
data格式: {
-- boolean类型，是否成功（固定为false）
["success"] = ,
-- string类型，错误信息
["error"] = ,
}
是否必选：是；
注意事项：必须在excloud.open()之前调用；
参数示例：
local function cloud_callback(event, data)
if event == "connect_result" then
log.info("连接结果:", data.success, data.error or "")
end
end
返回值
local result, err = excloud.on(cbfunc)
result
含义说明：是否注册成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示注册成功，false表示注册失败；
返回示例：true
err
含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："Callback must be a function"
示例
-- 注册回调函数示例
local function cloud_callback(event, data)
if event == "connect_result" then
log.info("连接结果:", data.success, data.error or "")
elseif event == "auth_result" then
log.info("认证结果:", data.success, data.message or "")
elseif event == "send_result" then
log.info("发送结果:", data.success, data.error_msg or "")
elseif event == "message" then
log.info("收到云端消息")
end
end
local result, err = excloud.on(cloud_callback)
if not result then
log.error("注册回调失败:", err)
end
4.3 excloud.open()
功能
开启 excloud 服务，发起连接合宙 AirCloud 平台 的动作；
注意事项
必须在 task 中使用
调用前需先通过 excloud.setup()进行配置，并通过 excloud.on()注册回调函数；
当 setup 中配置 use_getip=true（默认）时，open() 内部会自动调用 getip 服务获取服务器地址、端口及鉴权信息；若获取 auth_key 失败，会触发 "auth_key_error" 事件并返回错误；当 use_getip=false 时，必须在 setup 中手动配置 host 和 port；
参数
无；
返回值
local result, err = excloud.open()
result
含义说明：是否开启成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示开启成功，false表示开启失败；
返回示例：true
err
含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："excloud is already open"
示例
-- 开启服务_
local result, err = excloud.open()
if not result then
log.error("开启服务失败:", err)
return
end
log.info("excloud服务开启成功")
4.4 excloud.send(data, need_reply, is_auth_msg)
功能
发送数据到合宙 AirCloud 平台；
注意事项
服务必须已开启并成功连接；
参数
data
参数含义：待发送的数据；
数据类型：table；
取值范围：包含一个或多个字段的表，每个字段是一个包含以下键的表：
field_meaning: number类型，字段含义，使用FIELD_MEANINGS常量
data_type: number类型，数据类型，使用DATA_TYPES常量
value: 任意类型，数据值，类型需与data_type匹配
是否必选：是；
注意事项：数据值类型必须与指定的数据类型一致；
参数示例：
{
{
field_meaning = excloud.FIELD_MEANINGS.TEMPERATURE,
data_type = excloud.DATA_TYPES.FLOAT,
value = 25.6
}
}
need_reply
参数含义：是否需要服务器回复；
数据类型：boolean；
取值范围：true或false；
是否必选：否；
注意事项：不传入时默认值为false；
参数示例：true
is_auth_msg
参数含义：是否为鉴权消息（仅MQTT传输有效）；
数据类型：boolean；
取值范围：true或false；
是否必选：否；
注意事项：不传入时默认值为false；
true表示发送到鉴权主题（mqtt_pub_auth_topic）
false表示发送到数据主题（mqtt_pub_data_topic）
参数示例：false
返回值
local result, err_msg = excloud.send(data, need_reply, is_auth_msg)
result
含义说明：消息是否成功提交到发送队列；发送结果通过回调函数"send_result"事件获取。
数据类型：boolean；
取值范围：true或false；
注意事项：true表示发送成功，false表示发送失败；
返回示例：true
err_msg
含义说明：错误信息；
数据类型：string；
取值范围：当result为false时，err_msg包含具体的错误描述；
注意事项：当result为true时，err_msg为nil；
返回示例："Not connected to server"
示例
-- 发送传感器数据示例
local sensor_data = {
{
field_meaning = excloud.FIELD_MEANINGS.TEMPERATURE,
data_type = excloud.DATA_TYPES.FLOAT,
value = 25.6
},
{
field_meaning = excloud.FIELD_MEANINGS.HUMIDITY,
data_type = excloud.DATA_TYPES.FLOAT,
value = 65.3
},
{
field_meaning = excloud.FIELD_MEANINGS.BATTERY_LEVEL,
data_type = excloud.DATA_TYPES.INTEGER,
value = 3800
}
}
-- 发送数据并请求回复
excloud.send(sensor_data, true)
-- 发送数据不请求回复
--excloud.send(sensor_data, false)
4.5 excloud.close()
功能
关闭 excloud 服务，断开与合宙 AirCloud 平台的连接；
参数
无；
返回值
local result, err = excloud.close()
result
含义说明：是否关闭成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示关闭成功，false表示关闭失败；
返回示例：true
err
含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："excloud not open"
示例
-- 关闭服务示例
local result, err = excloud.close()
if not result then
log.error("关闭服务失败:", err)
else
log.info("excloud服务已关闭")
end
4.6 excloud.status()
功能
获取当前 excloud 服务的状态信息；
参数
无；
返回值
local status = excloud.status()
status
含义说明：excloud服务的当前状态信息；
数据类型：table；
取值范围：包含以下字段的状态表：
{
-- 含义说明：服务是否开启；
-- 数据类型：boolean；
-- 取值范围：true或false；
-- 注意事项：true表示服务已开启，false表示服务未开启；
-- 返回示例：true
is_open = ,
-- 含义说明：是否已连接服务器；
-- 数据类型：boolean；
-- 取值范围：true或false；
-- 注意事项：true表示已建立连接，false表示未连接；
-- 返回示例：true
is_connected = ,
-- 含义说明：是否已完成认证；
-- 数据类型：boolean；
-- 取值范围：true或false；
-- 注意事项：true表示已通过iot云平台认证，false表示未认证或认证失败；
-- 返回示例：true
is_authenticated = ,
-- 含义说明：当前消息序列号；
-- 数据类型：number；
-- 取值范围：0-65535；
-- 注意事项：用于消息顺序控制，每发送一条消息自动递增；
-- 返回示例：15
sequence_num = ,
-- 含义说明：当前重连次数；
-- 数据类型：number；
-- 取值范围：大于等于0的整数；
-- 注意事项：记录自服务开启以来的重连尝试次数；
-- 返回示例：2
reconnect_count = ,
-- 含义说明：待发送消息数量；
-- 数据类型：number；
-- 取值范围：大于等于0的整数；
-- 注意事项：当连接断开时，新发送的消息会暂存到待发送队列；
-- 返回示例：3
pending_messages =
}
注意事项：返回的表包含服务的完整状态信息，可用于监控和调试；
返回示例：
{
is_open = true,
is_connected = true,
is_authenticated = true,
sequence_num = 15,
reconnect_count = 0,
pending_messages = 0
}
4.7 excloud.start_heartbeat(interval, custom_data)
功能
启动自动心跳机制，定期向合宙 AirCloud 平台发送心跳消息；
注意事项
服务必须已开启；
参数
interval
参数含义：心跳间隔时间；
数据类型：number；
是否必选：否；
取值范围：大于0的整数，单位秒
最小值：1秒（但实际应用中建议不小于30秒，避免过于频繁）
最大值：理论上无限制，但建议不超过600秒（10分钟）
默认值为300秒（5分钟）
参数示例：60
custom_data
参数含义：自定义心跳内容；
数据类型：table；
是否必选：可选；
取值范围：一个符合tlv格式的表格，也可以为nil。
参数示例：{
{
field_meaning = excloud.FIELD_MEANINGS.TIMESTAMP,
data_type = excloud.DATA_TYPES.INTEGER,
value = os.time()
}
}
返回值
local result = excloud.start_heartbeat(interval, custom_data)
result
含义说明：是否启动成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示启动成功，false表示启动失败；
返回示例：true
示例
-- 启动自动心跳，每60秒发送一次
local result = excloud.start_heartbeat(60)
if result then
log.info("自动心跳已启动")
end
-- 启动带自定义数据的自动心跳
local custom_data = {
{
field_meaning = excloud.FIELD_MEANINGS.TIMESTAMP,
data_type = excloud.DATA_TYPES.INTEGER,
value = os.time()
}
}
excloud.start_heartbeat(120, custom_data)
4.8 excloud.stop_heartbeat()
功能
停止自动心跳机制；
参数
无；
返回值
local result = excloud.stop_heartbeat()
result
含义说明：是否停止成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示停止成功，false表示停止失败（可能原本未启动）；
返回示例：true
示例
-- 停止自动心跳
local result = excloud.stop_heartbeat()
if result then
log.info("自动心跳已停止")
end
4.9 excloud.upload_image(file_data, file_name)
功能
上传图片文件到合宙 AirCloud 平台；
注意事项
文件上传前需要先获取上传配置（上传 URL 及表单参数），上传配置的来源有两种： 1. 在 excloud.setup() 中手动配置 current_imginfo 参数，配置后优先使用，不再调用 getip； 2. 默认通过 getip 服务自动获取。
如果本地尚未缓存上传配置，扩展库会自动调用 getip 服务（带重试机制）重新获取，获取失败时上传失败并返回错误信息。getip 服务以及文件发送流程可参考此链接：https://docs.openluat.com/protocols/aircloud/，在调用此接口过程中不必关注文件发送逻辑，扩展库中已实现对应处理逻辑。
需要在 task 中使用。
参数
file_data
参数含义：图片文件数据；
数据类型：string或ZBUFF对象；
是否必选：是；
注意事项：string类型为图片文件路径，文件必须存在且可读；
ZBUFF类型为图片文件的内存数据，上传前需先写入数据
参数示例："/luatdb/image.jpg" 或 zbuff.create(1024)
file_name
参数含义：上报到合宙AirCloud平台的文件名称；用于开始http上传前先通知合宙AirCloud平台
数据类型：string；
是否必选：否；
注意事项：如果不提供，则自动生成文件名；生成规则是"image_" .. os.time() .. ".jpg"
这个名称会用于：在文件上传开始和完成通知中发送给云平台
参数示例："image_123456.jpg"
返回值
local result, err_msg = excloud.upload_image(file_data, file_name)
result
含义说明：是否上传成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示上传成功，false表示上传失败；
true表示文件已成功上传到云平台
false表示上传过程中出现错误
返回示例：true
err_msg
含义说明：错误信息；
数据类型：string；
取值范围："上传成功"； "服务器返回错误: +服务器返回错误码 "；"HTTP请求失败: +code"
注意事项：当result为true时，err_msg为"上传成功"；
当result为true时，err_msg为"服务器返回错误: +服务器返回错误码 "或"HTTP请求失败: +code"；
返回示例："上传成功"
示例
-- 上传图片文件
local result, err_msg = excloud.upload_image("/sd/capture.jpg", "capture.jpg")
if result then
log.info("图片上传成功")
else
log.error("图片上传失败:", err_msg)
end
4.10 excloud.upload_audio(file_data, file_name)
功能
上传音频文件到合宙 AirCloud 平台；
注意事项
文件上传前需要先获取上传配置（上传 URL 及表单参数），上传配置的来源有两种： 1. 在 excloud.setup() 中手动配置 current_audinfo 参数，配置后优先使用，不再调用 getip； 2. 默认通过 getip 服务自动获取。
如果本地尚未缓存上传配置，扩展库会自动调用 getip 服务（带重试机制）重新获取，获取失败时上传失败并返回错误信息。getip 服务以及文件发送流程可参考此链接：https://docs.openluat.com/protocols/aircloud/，在调用此接口过程中不必关注文件发送逻辑，扩展库中已实现对应处理逻辑。
需要在 task 中使用。
参数
file_data
参数含义：音频文件数据；
数据类型：string或ZBUFF对象；
是否必选：是；
注意事项：string类型为音频文件路径，文件必须存在且可读；
ZBUFF类型为音频文件的内存数据，上传前需先写入数据
参数示例："/sd/audio.mp3" 或 zbuff.create(1024)
file_name
参数含义：上报到合宙AirCloud平台的文件名称；用于开始http上传前先通知合宙AirCloud平台
数据类型：string；
是否必选：否；
注意事项：如果不提供，则自动生成文件名；生成规则是："audio_" .. os.time() .. ".mp3"
参数示例："device_audio.mp3"
返回值
local result, err_msg = excloud.upload_audio(file_data, file_name)
result
含义说明：是否上传成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示上传成功，false表示上传失败；
true表示文件已成功上传到云平台
false表示上传过程中出现错误
返回示例：true
err_msg
含义说明：错误信息；
数据类型：string；
取值范围："上传成功"； "服务器返回错误: +服务器返回错误码 "；"HTTP请求失败: +code"
注意事项：当result为true时，err_msg为"上传成功"；
当result为true时，err_msg为"服务器返回错误: +服务器返回错误码 "或"HTTP请求失败: +code"；
返回示例："上传成功"
示例
-- 上传音频文件
local result, err_msg = excloud.upload_audio("/sd/record.mp3", "device_record.mp3")
if result then
log.info("音频上传成功")
else
log.error("音频上传失败:", err_msg)
end
4.11 excloud.get_server_info()
功能
获取通过 getip 服务获取的当前服务器连接信息和文件上传配置；
应用场景
调试和监控：查看当前连接的服务器地址和文件上传配置
故障排查：当连接或上传出现问题时，检查服务器配置是否正确
参数
无；
返回值
local server_info = excloud.get_server_info()
server_info
含义说明：通过getip服务获取的服务器配置信息；
数据类型：table或nil；
取值范围：当成功获取过getip信息时返回table，否则返回nil；
{
-- 连接信息，数据类型table
-- 字段与传输协议相关，TCP时通常包含ipv4和port；
-- UDP时额外包含key（udp鉴权key）；
-- MQTT时额外包含ssl、username、password；
-- 若为turnkey项目，还会包含auth_key
["conninfo"] = {
-- string类型，服务器IPv4地址
-- 示例："124.71.128.165"
["ipv4"] = ,
-- string类型，MQTT连接时的SSL域名（仅MQTT时存在）
-- 示例："mqtt.airtalk.luatos.com"
["ssl"] = ,
-- number类型，服务器端口号
-- 示例：9108（TCP）或8883（MQTT）
["port"] = ,
-- string类型，UDP连接时的鉴权key（仅UDP时存在）
-- 示例："xxxxxxxx"
["key"] = ,
-- string类型，MQTT连接时的用户名模板（仅MQTT时存在）
-- 示例："{imei}"，实际使用时会被设备IMEI替换
["username"] = ,
-- string类型，MQTT连接时的密码模板（仅MQTT时存在）
-- 示例："{muid}"，实际使用时会被设备MUID替换
["password"] = ,
-- string类型，turnkey项目自动获取的鉴权key
-- 示例："xxxxxxx"
["auth_key"] = ,
},
-- 图片上传配置，数据类型table
["imginfo"] = {
-- string类型，图片上传的URL地址
-- 示例："https://gps.openluat.com/iot/aircloud/upload/image"
["url"] = ,
-- string类型，上传表单中文件字段的键名
-- 示例："f"
["data_key"] = ,
-- table类型，上传时需要附加的参数
["data_param"] = {
-- string类型，上传认证密钥
-- 示例："WMAdWPuR4fHPJXSvCwkTdMBsFmjHHXMYVobb5J"
["key"] = ,
-- string类型，提示信息（通常为空字符串）
-- 示例：""
["tip"] = ,
},
},
-- 音频上传配置，数据类型table，结构与imginfo相同
["audinfo"] = {
-- string类型，音频上传的URL地址
-- 示例："https://gps.openluat.com/iot/aircloud/upload/image"
["url"] = ,
-- string类型，上传表单中文件字段的键名
-- 示例："f"
["data_key"] = ,
-- table类型，上传时需要附加的参数
["data_param"] = {
-- string类型，上传认证密钥
-- 示例："WMAdWPuR4fHPJXSvCwkTdMBsFmjHHXMYVobb5J"
["key"] = ,
-- string类型，提示信息（通常为空字符串）
-- 示例：""
["tip"] = ,
},
},
-- 运维日志上传配置，数据类型table，结构与imginfo相同
["mtninfo"] = {
-- string类型，运维日志上传的URL地址
-- 示例："https://gps.openluat.com/iot/aircloud/upload/image"
["url"] = ,
-- string类型，上传表单中文件字段的键名
-- 示例："f"
["data_key"] = ,
-- table类型，上传时需要附加的参数
["data_param"] = {
-- string类型，上传认证密钥
-- 示例："WMAdWPuR4fHPJXSvCwkTdMBsFmjHHXMYVobb5J"
["key"] = ,
-- string类型，提示信息（通常为空字符串）
-- 示例：""
["tip"] = ,
},
},
-- 二维码链接信息，数据类型string或nil
-- 通过getip获取，未获取到时为nil
["qrinfo"] = ,
}
注意事项：无
返回示例：{
"conninfo": {
"ipv4": "124.71.128.165",
"port": 9108
},
"imginfo": {
"url": "https://gps.openluat.com/iot/aircloud/upload/image",
"data_key": "f",
"data_param": {
"key": "WMAdWPuR4fHPJXSvCwkTdMBsFmjHHXMYcM8RDa",
"tip": ""
}
},
"audinfo": {
"url": "https://gps.openluat.com/iot/aircloud/upload/audio",
"data_key": "f",
"data_param": {
"key": "WMAdWPuR4fHPJXSvCwkTdMBsFmjHHXMYcM8RDa",
"tip": ""
}
},
"mtninfo": {
"url": "https://gps.openluat.com/iot/aircloud/upload/file",
"data_key": "f",
"data_param": {
"key": "WMAdWPuR4fHPJXSvCwkTdMBsFmjHHXMYcM8RDa",
"tip": ""
}
},
"qrinfo": "https://iot.luatos.com/qrcode/xxx"
}
示例
-- 获取服务器信息
local server_info = excloud.get_server_info()
if server_info.conninfo then
log.info("当前tcp服务器:", server_info.conninfo.ipv4, server_info.conninfo.port)
end
if server_info.imginfo then
log.info("图片上传URL:", server_info.imginfo.url)
end
4.12 excloud.mtn_log(tag, ...)
功能
记录运维日志到本地循环存储文件；
注意事项
- 需要先启用运维日志功能（在 setup 中配置 mtn_log_enabled=true）；
- 运维日志采用循环覆盖机制，不会因为存储空间满而写入失败；
- 日志文件存储在设备本地，需要云端主动请求才能上传；
运维日志存储机制详解
- 文件结构
-- 4个循环日志文件
"/hzmtn1.trc" -- 文件1
"/hzmtn2.trc" -- 文件2
"/hzmtn3.trc" -- 文件3
"/hzmtn4.trc" -- 文件4
-- 索引文件（通过fskv存储）
"hzmtnind" = 1 -- 当前写入的文件序号（1-4）
- 存储空间管理
默认大小：每个文件占用 1 个 block（通常 4KB），4 个文件共 4 个 block（16KB）
可配置：通过（在 setup 中配置 mtn_log_blocks ）调整每个文件的大小
覆盖机制：采用循环覆盖机制
- 上报逻辑
-- 设备端：等待云端触发上传
-- 云端下发信令25（MTN_LOG_UPLOAD_REQ_SIGNAL）时触发上传
-- 上传流程：
-- 1. 设备收到上传请求
-- 2. 扫描4个运维日志文件
-- 3. 按文件序号顺序上传
-- 4. 发送上传状态通知
参数
tag
参数含义：日志标识；
数据类型：string；
是否必选：是；
参数示例："net_conn"
...
参数含义：日志内容，可变参数；
数据类型：任意；
是否必选：是；
参数示例："网络连接成功", "host", "192.168.1.1", "port", 8080
返回值
local result = excloud.mtn_log(tag, ...)
result
含义说明：是否记录成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示记录成功
false表示没有开启运维日志功能，记录失败
由于采用循环覆盖机制，不会因为存储空间满而返回false
返回示例：true
示例
-- 记录运维日志
excloud.mtn_log("net_conn", "网络连接成功", "host", "192.168.1.1", "port", 8080)
4.13 excloud.build_tlv(field_meaning, data_type, value)
功能
构建 TLV (Type-Length-Value) 格式的字段，用于设备与云端之间的数据传输。
注意事项
- 该函数用于构建单个 TLV 字段，多个字段需要分别构建后拼接。
- 字段含义和数据类型必须使用 excloud.FIELD_MEANINGS 和 excloud.DATA_TYPES 中定义的常量。
参数
field_meaning
参数含义：业务字段含义；
数据类型：number；
是否必选：是；
取值范围：使用 excloud.FIELD_MEANINGS 中的常量；
参数示例：excloud.FIELD_MEANINGS.TEMPERATURE
注意事项：必须使用 excloud.FIELD_MEANINGS 中定义的常量
data_type
参数含义：数据类型字段；
数据类型：number；
是否必选：是；
取值范围：使用 excloud.DATA_TYPES 中的常量；
参数示例：excloud.DATA_TYPES.FLOAT
注意事项：必须使用预定义的数据类型常量
value
参数含义：要编码的数据；
数据类型：多种类型；
是否必选：是；
取值范围：根据 data_type 不同而不同；
参数示例：25.5
注意事项：值的类型必须与 data_type 匹配
返回值
local success, tlv_data = excloud.build_tlv(field_meaning, data_type, value)
success
含义说明：构建是否成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true 表示构建成功，false 表示构建失败；
返回示例：true
tlv_data
含义说明：构建好的 TLV 数据；
数据类型：string；
取值范围：二进制字符串；
注意事项：当 success 为 true 时返回 TLV 数据，否则为 nil；
返回示例：二进制字符串
示例
-- 构建一个温度数据的 TLV 字段
local success, tlv_data = excloud.build_tlv(
excloud.FIELD_MEANINGS.TEMPERATURE,
excloud.DATA_TYPES.FLOAT,
25.5
)
4.14 excloud.parse_tlv(data, startPos)
功能
解析 TLV (Type-Length-Value) 格式的字段，用于解析设备从云端接收到的数据。
注意事项
- 该函数用于解析按照 TLV 格式编码的二进制数据，解析后会返回解析完成的位置，可用于继续解析后续的 TLV 字段。
- 解析的数据必须是有效的 TLV 格式二进制字符串。
- 解析结果中的 value 字段已经根据 excloud.DATA_TYPES 进行了解码。
参数
data
参数含义：TLV 格式数据的二进制字符串；
数据类型：string；
是否必选：是；
取值范围：有效的 TLV 格式二进制数据；
参数示例：二进制字符串
注意事项：必须是完整的 TLV 格式数据
startPos
参数含义：开始解析的位置；
数据类型：number；
是否必选：否；
取值范围：1 到 #data；
默认值：1；
参数示例：1
注意事项：默认为 1，即从数据开头开始解析
返回值
local tlv_info, new_pos, error = excloud.parse_tlv(data, startPos)
tlv_info
含义说明：解析后的 TLV 信息表；
数据类型：table；
取值范围：包含 field、type、value 和 length 字段的表；
{
--参数含义：字段含义，对应 excloud.FIELD_MEANINGS 中的常量；
--数据类型：number；
--取值范围：与 excloud.FIELD_MEANINGS 常量对应；
--注意事项：表示该 TLV 字段的业务含义；
field,
--参数含义：数据类型，对应 excloud.DATA_TYPES 中的常量；
--数据类型：number；
--取值范围：与 excloud.DATA_TYPES 常量对应；
--注意事项：表示该 TLV 字段的编码类型；
type,
--参数含义：字段值，已根据数据类型解码；
--数据类型：根据 type 字段不同而不同；
--取值范围：与字段类型对应的值范围；
--注意事项：解析后直接可用的字段值；
value,
--参数含义：数据长度，value 字段的原始字节长度；
--数据类型：number；
--取值范围：大于 0 的整数；
--注意事项：表示该 TLV 字段中 value 部分的字节长度；
length,
}
注意事项：解析成功时返回信息表，失败时为 nil；
返回示例：{field=256, type=1, value=25.5, length=4}
new_pos
含义说明：解析完成后的新位置，需要判断是否超过数据长度，没超过还要再次解析；
数据类型：number；
取值范围：大于 startPos 的整数；
注意事项：解析成功时返回新位置，失败时返回 startPos；
返回示例：9
error
含义说明：解析失败时的错误信息；
数据类型：string；
取值范围：错误描述；
注意事项：解析失败时返回错误信息，成功时为 nil；
返回示例："TLV data too short"
示例
-- 解析一个 TLV 格式数据的二进制字符串
local data = "..." -- 包含 TLV 数据的二进制字符串
local pos = 1
while pos <= #data do
local tlv, new_pos, err = excloud.parse_tlv(data, pos)
if not tlv then
log.error("解析TLV失败:", err)
break
end
-- 根据字段含义处理解析出的数据
log.info("数据字段、数据类型以及值:", tlv.field, tlv.type, tlv.value)
-- 更新解析位置，继续解析下一个 TLV 字段
pos = new_pos
end
4.15 excloud.get_qrinfo()
功能
获取二维码链接信息；
注意事项
无；
参数
无；
返回值
local qrinfo = excloud.get_qrinfo()
qrinfo
含义说明：二维码链接信息；
数据类型：string或nil；
取值范围：成功时返回二维码链接字符串，失败时返回nil；
注意事项：无；
返回示例："https://iot.luatos.com/qrcode/xxx"
示例
-- 获取二维码链接信息
local qrinfo = excloud.get_qrinfo()
if qrinfo then
log.info("二维码链接:", qrinfo)
else
log.warn("未获取到二维码链接")
end
4.16 excloud.version()
功能 获取库文件版本信息
参数
无参数
返回值
local version= excloud.version()
log.info("excloud", "version -> " .. version)
version
含义说明：库文件版本信息，string类型的年月日时分；
数据类型：string；
取值范围：12位数字；
返回示例："202609011645"
示例
--返回string类型的年月日时分，例如："202609011645"
excloud.version()
4.17 excloud.upload_mtnlog(file_data, file_name)
功能
上传运维日志文件到合宙 AirCloud 平台；
注意事项
如果当前未获取到文件上传配置（未通过 getip 获取且未在 setup 中手动配置 mtninfo），扩展库会自动调用 getip 服务获取文件上传的 URL；在调用此接口过程中不必关注文件发送逻辑，扩展库中已实现对应处理逻辑。
需要在 task 中使用。
参数
file_data
参数含义：运维日志文件数据；
数据类型：string或ZBUFF对象；
是否必选：是；
注意事项：string类型为日志文件路径，文件必须存在且可读；
ZBUFF类型为日志文件的内存数据，上传前需先写入数据
参数示例："/hzmtn1.trc" 或 zbuff.create(1024)
file_name
参数含义：上报到合宙AirCloud平台的文件名称；
数据类型：string；
是否必选：否；
注意事项：如果不提供，则自动生成文件名；生成规则是"mtnlog_" .. os.time() .. ".trc"
参数示例："mtn_log_123456.trc"
返回值
local result, err_msg = excloud.upload_mtnlog(file_data, file_name)
result
含义说明：是否上传成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示上传成功，false表示上传失败；
返回示例：true
err_msg
含义说明：错误信息；
数据类型：string；
取值范围：错误描述字符串；
注意事项：当result为false时，err_msg包含具体的错误描述；
返回示例："文件不存在: /hzmtn1.trc"
示例
-- 上传运维日志文件
local result, err_msg = excloud.upload_mtnlog("/hzmtn1.trc", "mtn_log.trc")
if result then
log.info("运维日志上传成功")
else
log.error("运维日志上传失败:", err_msg)
end
4.18 excloud.set_upload_callback(cb)
功能
设置文件上传回调函数，用于在文件上传完成（或异常）时获取上传结果通知；
注意事项
无；
参数
cb
参数含义：文件上传回调函数；
数据类型：function；
是否必选：是；
注意事项：回调函数格式为 function call_back(file_type, file_name, result_ok, result_msg) ... end，其中：
file_type: number类型，文件类型（1=图片，2=音频，3=运维日志）
file_name: string类型，文件名
result_ok: boolean类型，上传是否成功（true表示成功，false表示失败）
result_msg: string类型，上传结果消息
参数示例：
local function upload_cb(file_type, file_name, result_ok, result_msg)
log.info("上传结果:", file_type, file_name, result_ok, result_msg)
end
返回值
local result, err = excloud.set_upload_callback(cb)
result
含义说明：是否设置成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示设置成功，false表示设置失败；
返回示例：true
err
含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："Callback must be a function"
示例
-- 设置文件上传回调函数
local function upload_cb(file_type, file_name, result_ok, result_msg)
log.info("上传结果:", file_type, file_name, result_ok, result_msg)
end
local result, err = excloud.set_upload_callback(upload_cb)
if not result then
log.error("设置回调失败:", err)
end
4.19 excloud.get_mtn_log_status()
功能
获取运维日志的状态信息；
参数
无；
返回值
local status = excloud.get_mtn_log_status()
status
含义说明：运维日志状态信息；
数据类型：table；
取值范围：包含以下字段的状态表：
{
-- 含义说明：运维日志功能是否启用；
-- 数据类型：boolean；
-- 取值范围：true或false；
-- 注意事项：未启用时仅返回enabled=false和message字段；
enabled = ,
-- 含义说明：提示信息；
-- 数据类型：string；
-- 注意事项：未启用时为"运维日志功能已禁用"；
message = ,
-- 含义说明：运维日志配置信息；
-- 数据类型：table；
-- 注意事项：通过exmtn.get_config()获取；
config = ,
-- 含义说明：本地日志文件数量；
-- 数据类型：number；
file_count = ,
-- 含义说明：本地日志文件总大小(字节)；
-- 数据类型：number；
total_size = ,
-- 含义说明：本地日志文件列表；
-- 数据类型：table；
-- 注意事项：每个元素包含文件路径和大小等信息；
files = ,
-- 含义说明：最近一次错误信息；
-- 数据类型：string或nil；
last_error = ,
}
注意事项：无；
返回示例：{enabled = true, file_count = 4, total_size = 16384}
示例
-- 获取运维日志状态
local status = excloud.get_mtn_log_status()
if status.enabled then
log.info("运维日志文件数:", status.file_count, "总大小:", status.total_size)
else
log.warn("运维日志:", status.message)
end
4.20 excloud.heartbeat(custom_data, need_reply)
功能
手动发送一次心跳消息到合宙 AirCloud 平台；
注意事项
不传 custom_data 时，使用 excloud.start_heartbeat() 设置的自定义心跳数据；若从未设置，则发送空心跳（无TLV字段）；
参数
custom_data
参数含义：自定义心跳内容；
数据类型：table或nil；
是否必选：否；
取值范围：符合TLV格式的表格，nil表示使用已设置的心跳数据；
参数示例：{
{
field_meaning = excloud.FIELD_MEANINGS.TIMESTAMP,
data_type = excloud.DATA_TYPES.INTEGER,
value = os.time()
}
}
need_reply
参数含义：是否需要服务器回复；
数据类型：boolean；
是否必选：否；
取值范围：true或false；
注意事项：不传入时默认值为false；
参数示例：false
返回值
local result, err_msg = excloud.heartbeat(custom_data, need_reply)
result
含义说明：心跳消息是否成功提交到发送队列；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示发送成功，false表示发送失败；
返回示例：true
err_msg
含义说明：错误信息；
数据类型：string；
取值范围：当result为false时，err_msg包含具体的错误描述；
注意事项：当result为true时，err_msg为nil；
返回示例："未连接到服务器"
示例
-- 发送一次自定义心跳
local result, err_msg = excloud.heartbeat({
{
field_meaning = excloud.FIELD_MEANINGS.TIMESTAMP,
data_type = excloud.DATA_TYPES.INTEGER,
value = os.time()
}
})
if not result then
log.error("心跳发送失败:", err_msg)
end
4.21 excloud.upload_mtnlogs()
功能
主动上传本地运维日志循环文件到合宙 AirCloud 平台；
注意事项
- 需要先启用运维日志功能（在 setup 中配置 mtn_log_enabled=true）；
- 与云端信令25（MTN_LOG_UPLOAD_REQ_SIGNAL）触发的上传流程共用同一套上传逻辑；
- 需要在 task 中使用；
参数
无；
返回值
local result, err_msg = excloud.upload_mtnlogs()
result
含义说明：是否有日志文件上传成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示至少有一个文件上传成功，false表示没有文件上传成功；
返回示例：true
err_msg
含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err_msg包含具体的错误描述；
"mtn log uploading"表示已有上传任务进行中
"no mtn log files"表示没有可上传的日志文件
"all mtn log upload failed"表示所有文件上传失败
注意事项：当result为true时，err_msg为nil；
返回示例："no mtn log files"
示例
-- 主动上传本地运维日志
local result, err_msg = excloud.upload_mtnlogs()
if not result then
log.error("运维日志上传失败:", err_msg)
end
五、版本更新说明
版本号：202609011645
1、更新时间：2026-09-01 16:45
2、更新内容
- getip请求key构造不再覆盖用户配置的auth_key，key字段使用固定占位符（unusedkey-设备ID）
- socket.config参数简化，直接从config读取证书和keepalive参数
版本号：202609010914
1、更新时间：2026-09-01 09:14
2、更新内容
- ssl默认值改为false，不再默认开启加密
- 收发HEX日志增加config.debug限制，默认不打印
版本号：202608311500
1、更新时间：2026-08-31 15:00
2、更新内容
- auth_key改为支持用户配置，不再被setup()拦截
版本号：202608281700
1、更新时间：2026-08-28 17:00
2、更新内容
- setup()精简特殊参数处理，删除use_getip/imginfo/audinfo/mtninfo的特殊分支
- 文件上传支持指定使用合宙平台参数，新增imginfo_from_luat/audinfo_from_luat/mtninfo_from_luat配置
版本号：202608271800
1、更新时间：2026-08-27 18:00
2、更新内容
- getip和getip_with_retry改为内部函数，不再对外暴露
- protocol_version不允许用户配置，setup()中拦截并忽略
- 完善对外接口列表
版本号：202608262000
1、更新时间：2026-08-26 20:00
2、更新内容
- 调整默认配置项，新增MQTT客户端标识、自定义主题等参数
- 更新getip服务地址，优化配置覆盖逻辑，手动配置优先于getip
- 扩充协议字段定义，新增短信相关、内存统计等多类消息类型
- 重构MQTT连接与设备认证逻辑，适配多类型设备
- 移除手动IP禁止上传文件的限制，优化日志与错误提示
版本号：202608071400
1、更新时间：2026-08-07 14:00
2、更新内容
- 新增SMS收发/投递相关字段
版本号：202607091431
1、更新时间：2026-07-09 14:31
2、更新内容
- 修复“设备为MCU主控类型Air1601/1601/1780系列产品时，报文中设备id编码出错”的问题
版本号：202607031547
1、更新时间：2026-07-03 15:47
2、更新内容
- 不再需要用户在应用脚本中主动设置device_type，而是excloud内部根据模组型号自动判断
版本号：202607021200
1、更新时间：2026-07-02 12:00
2、更新内容
- 新增excloud.version()接口
- 支持excloud库文件版本号管理功能，版本号的格式为：yyyymmddhhmm，表示yyyy年mm月dd日hh时mm分发布的版本
六、产品支持说明
支持 LuatOS 开发的所有产品都支持 excloud 扩展库.