LuatOS扩展库API——【 excloud】AirCloud云平台控制

LuatOS一款基于 Lua 5.3 深度优化的嵌入式运行框架，轻量且高效，主要适配 4G-Cat.1、MCU 等类型的物联网终端，无需复杂编译流程，用 Lua 脚本就能完成开发。其核心围绕协程多任务构建，搭配70+核心库、70+扩展库以及1000+应用 demo，可以覆盖物联网基础开发的各类需求。。

一、概述

AirCloud 平台 iot.luatos.com 是一个物联网设备管理平台，提供设备连接、数据采集、远程控制、运维监控等功能。用户可以通过该平台：

设备管理：注册、认证、监控设备状态。
数据可视化：查看传感器数据、历史曲线。
远程控制：下发指令控制设备行为。
文件上传：支持图片、音频、日志文件上传。
运维支持：自动日志上传、故障诊断。

本扩展库是 AirCloud 平台的 aircloud 协议的适配，用于设备连接 AirCloud 平台。

excloud 扩展库实现功能：

连接管理：TCP/MQTT 连接、自动重连、状态监控
协议适配：aircloud 协议封装解析、TLV 数据格式
文件上传：支持图片、音频文件上传到平台
心跳机制：维持设备在线状态、自定义心跳数据
运维日志：设备运行日志记录和自动上传

数据流向：

上行：设备数据 → excloud 库 → 平台
下行：平台命令 → excloud 库 → 设备执行

二、核心示例

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

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

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

lua 复制代码

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({
        use_getip = true, -- 使用getip服务
        device_type = 1,   -- 4G设备
        auth_key = "VmhtOb81EgZau6YyuuZJzwF6oUNGCbXi",
        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  -- 缓存写入方式
    })

    --不使用getip服务，注意把use_getip设置为false
    -- local ok, err_msg = excloud.setup({
    --     use_getip = false,                             -- 不使用getip服务
    --     device_type = 1,                               -- 设备类型: 4G
    --     host = "112.125.89.8",                         -- 服务器地址
    --     port = 32585,                                  -- 服务器端口
    --     auth_key = "VmhtOb81EgZau6YyuuZJzwF6oUNGCbXi", -- 鉴权密钥
    --     transport = "tcp",                             -- 使用TCP传输
    --     auto_reconnect = true,                         -- 自动重连
    --     reconnect_interval = 10,                       -- 重连间隔(秒)
    --     max_reconnect = 5,                             -- 最大重连次数
    --     timeout = 30,                                  -- 超时时间(秒)
    --     mtn_log_enabled = true                         -- 启用运维日志
    -- })

    -- 配置excloud参数，虚拟设备链接
    -- local ok, err_msg = excloud.setup({
    --     use_getip = true, --使用getip服务
    --     device_type = 9,
    --     auth_key = "VmhtOb81EgZau6YyuuZJzwF6oUNGCbXi",
    --     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

lua 复制代码

常量含义：整数数据类型；
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.INTEGER

3.1.2 excloud.DATA_TYPES.FLOAT

lua 复制代码

常量含义：浮点数数据类型；
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.FLOAT

3.1.3 excloud.DATA_TYPES.BOOLEAN

lua 复制代码

常量含义：布尔值数据类型；
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.BOOLEAN

3.1.4 excloud.DATA_TYPES.ASCII

lua 复制代码

常量含义：ASCII字符串数据类型；
         是可打印的字符串，直接copy出来就可以在文本编辑器人眼查看的。每个字节的值都在0x20到0x2E之间。
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.ASCII

3.1.5 excloud.DATA_TYPES.BINARY

lua 复制代码

常量含义：二进制数据类型； binary字符串，不一定可打印， 每个字节是任意的。
数据类型：number；
示例代码：local data_type = excloud.DATA_TYPES.BINARY

3.1.6 excloud.DATA_TYPES.UNICODE

lua 复制代码

常量含义：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

lua 复制代码

常量含义：鉴权请求；
值数据类型：excloud.DATA_TYPES.BINARY
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.AUTH_REQUEST
业务说明：设备连接后首先发送鉴权请求，包含设备身份信息

3.2.1.2 excloud.FIELD_MEANINGS.AUTH_RESPONSE

lua 复制代码

常量含义：鉴权回复；
值数据类型：excloud.DATA_TYPES.BINARY
传输方向：平台→设备
示例代码：local field = excloud.FIELD_MEANINGS.AUTH_RESPONSE
业务说明：平台验证设备身份后返回认证结果

3.2.1.3 excloud.FIELD_MEANINGS.REPORT_RESPONSE

lua 复制代码

常量含义：上报回应；
值数据类型：excloud.DATA_TYPES.INTEGER
值内容：0（成功）或错误码   （这部分服务器还没实现，先这样定义）
传输方向：平台→设备
示例代码：local field = excloud.FIELD_MEANINGS.REPORT_RESPONSE
业务说明：平台确认收到设备数据上报，用于服务器对设备的上报的回应

3.2.1.4 excloud.FIELD_MEANINGS.CONTROL_COMMAND

lua 复制代码

常量含义：控制命令；
值数据类型：不做限制，平台可以选择数据格式
传输方向：平台→设备
示例代码：local field = excloud.FIELD_MEANINGS.CONTROL_COMMAND
业务说明：平台向设备下发控制命令，如开关、参数设置等

3.2.1.5 excloud.FIELD_MEANINGS.CONTROL_RESPONSE

lua 复制代码

常量含义：控制回应；
值数据类型：不做限制
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.CONTROL_RESPONSE
业务说明：设备收到控制命令后返回执行结果

3.2.1.6 excloud.FIELD_MEANINGS.IRTU_DOWN

lua 复制代码

常量含义：iRTU下行命令；
值数据类型：不做限制
传输方向：平台→设备
示例代码：local field = excloud.FIELD_MEANINGS.IRTU_DOWN
业务说明：针对iRTU设备的专用控制命令

3.2.1.7 excloud.FIELD_MEANINGS.IRTU_UP

lua 复制代码

常量含义：iRTU上行回复；
值数据类型：不做限制
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.IRTU_UP
业务说明：iRTU设备执行命令后的响应数据

3.2.1.8 excloud.FIELD_MEANINGS.FILE_UPLOAD_START

lua 复制代码

常量含义：文件上传开始通知；
值数据类型：不做限制
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.FILE_UPLOAD_START
值内容：文件元信息（文件名、大小、类型）
业务说明：设备开始上传文件前的通知消息

3.2.1.9 excloud.FIELD_MEANINGS.FILE_UPLOAD_FINISH

lua 复制代码

常量含义：文件上传完成通知；
值数据类型：不做限制
传输方向：设备→平台
值内容：上传结果
示例代码：local field = excloud.FIELD_MEANINGS.FILE_UPLOAD_FINISH
业务说明：设备完成文件上传后的确认消息

3.2.1.10 excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_REQ_SIGNAL

lua 复制代码

常量含义：运维日志上传命令
值数据类型：值为空，收到此命令就读取并上传日志内容
传输方向：平台→设备
业务说明：平台主动请求设备上传运维日志
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_REQ_SIGNAL

3.2.1.11 excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_RESP_SIGNAL

lua 复制代码

常量含义：运维日志上传响应
值数据类型：不做限制
传输方向：设备→平台
值内容：日志上传准备状态
业务说明：设备响应平台的日志上传请求
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_RESP_SIGNAL

3.2.1.12 excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_STATUS_SIGNAL

lua 复制代码

常量含义：运维日志上传状态
值数据类型：excloud.DATA_TYPES.BINARY
传输方向：设备→平台
值内容：上传进度和状态信息
业务说明：设备向平台报告日志上传的实时进度
示例代码：local field = excloud.FIELD_MEANINGS.MTN_LOG_UPLOAD_STATUS_SIGNAL

3.2.2 传感类 (256-511)

3.2.2.1 excloud.FIELD_MEANINGS.TEMPERATURE

lua 复制代码

常量含义：温度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.TEMPERATURE

3.2.2.2 excloud.FIELD_MEANINGS.HUMIDITY

lua 复制代码

常量含义：湿度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.HUMIDITY

3.2.2.3 excloud.FIELD_MEANINGS.PARTICULATE

lua 复制代码

常量含义：颗粒物浓度
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.PARTICULATE

3.2.2.4 excloud.FIELD_MEANINGS.ACIDITY

lua 复制代码

常量含义：酸度（pH值）
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.ACIDITY

3.2.2.5 excloud.FIELD_MEANINGS.ALKALINITY

lua 复制代码

常量含义：碱度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.ALKALINITY

3.2.2.6 excloud.FIELD_MEANINGS.ALTITUDE

lua 复制代码

常量含义：海拔；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.ALTITUDE

3.2.2.7 excloud.FIELD_MEANINGS.WATER_LEVEL

lua 复制代码

常量含义：水位；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.WATER_LEVEL

3.2.2.8 excloud.FIELD_MEANINGS.ENV_TEMPERATURE

lua 复制代码

常量含义：环境温度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.ENV_TEMPERATURE

3.2.2.9 excloud.FIELD_MEANINGS.POWER_METERING

lua 复制代码

常量含义：电量计量；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.POWER_METERING

3.2.3 资产管理类 (512-767)

3.2.3.1 excloud.FIELD_MEANINGS.GNSS_LONGITUDE

bash 复制代码

常量含义：GNSS经度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_LONGITUDE

3.2.3.2 excloud.FIELD_MEANINGS.GNSS_LATITUDE

lua 复制代码

常量含义：GNSS纬度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_LATITUDE

3.2.3.3 excloud.FIELD_MEANINGS.SPEED

lua 复制代码

常量含义：行驶速度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SPEED

3.2.3.4 excloud.FIELD_MEANINGS.GNSS_CN

lua 复制代码

常量含义：GNSS卫星信噪比
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_CN

3.2.3.5 excloud.FIELD_MEANINGS.SATELLITES_TOTAL

lua 复制代码

常量含义：搜索到的卫星总数
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SATELLITES_TOTAL

3.2.3.6 excloud.FIELD_MEANINGS.SATELLITES_VISIBLE

bash 复制代码

常量含义：可见卫星数；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SATELLITES_VISIBLE

3.2.3.7 excloud.FIELD_MEANINGS.HEADING

lua 复制代码

常量含义：航向角；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.HEADING

3.2.3.8 excloud.FIELD_MEANINGS.LOCATION_METHOD

lua 复制代码

常量含义：定位方式标识
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
值取值范围：0（基站定位）、1（GNSS定位）、2（混合定位）
示例代码：local field = excloud.FIELD_MEANINGS.LOCATION_METHOD

3.2.3.9 excloud.FIELD_MEANINGS.GNSS_INFO

lua 复制代码

常量含义：GNSS芯片型号和固件版本号；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_INFO

3.2.3.10 excloud.FIELD_MEANINGS.DIRECTION

lua 复制代码

常量含义：方向角
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.DIRECTION

3.2.4 设备参数类 (768-1023)

3.2.4.1 excloud.FIELD_MEANINGS.HEIGHT

lua 复制代码

常量含义：设备物理高度或安装高度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.HEIGHT

3.2.4.2 excloud.FIELD_MEANINGS.WIDTH

bash 复制代码

常量含义：设备物理宽度尺寸；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.FLOAT
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.WIDTH

3.2.4.3 excloud.FIELD_MEANINGS.ROTATION_SPEED

lua 复制代码

常量含义：转速；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.ROTATION_SPEED

3.2.4.4 excloud.FIELD_MEANINGS.BATTERY_LEVEL

lua 复制代码

常量含义：电池电压(mV)；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.BATTERY_LEVEL

3.2.4.5 excloud.FIELD_MEANINGS.SERVING_CELL

lua 复制代码

常量含义：驻留小区（服务小区信息）；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SERVING_CELL

3.2.4.6 excloud.FIELD_MEANINGS.CELL_INFO

lua 复制代码

常量含义：小区信息（服务小区+邻区）；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.BINARY
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.CELL_INFO

3.2.4.7 excloud.FIELD_MEANINGS.COMPONENT_MODEL

lua 复制代码

常量含义：元器件型号， 用于标识设备中具体元器件的型号信息；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.COMPONENT_MODEL

3.2.4.8 excloud.FIELD_MEANINGS.GPIO_LEVEL

lua 复制代码

常量含义：上报GPIO高低电平；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.GPIO_LEVEL

3.2.4.9 excloud.FIELD_MEANINGS.BOOT_REASON

lua 复制代码

常量含义：开机原因；
值数据类型：不做强制限制，建议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

lua 复制代码

常量含义：开机次数；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.BOOT_COUNT

3.2.4.11 excloud.FIELD_MEANINGS.SLEEP_MODE

lua 复制代码

常量含义：上报设备休眠模式；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
值取值范围：0（正常模式）、1（轻休眠）、3（psm+深度休眠）
示例代码：local field = excloud.FIELD_MEANINGS.SLEEP_MODE

3.2.4.12 excloud.FIELD_MEANINGS.WAKE_INTERVAL

lua 复制代码

常量含义：定时唤醒间隔，上报设备休眠定时器时间；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.WAKE_INTERVAL

3.2.4.13 excloud.FIELD_MEANINGS.NETWORK_IP_TYPE

lua 复制代码

常量含义：网络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

lua 复制代码

常量含义：网络类型，上报当前联网方式（4G/WiFi/以太网）；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.NETWORK_TYPE

3.2.4.15 excloud.FIELD_MEANINGS.SIGNAL_STRENGTH_4G

lua 复制代码

常量含义：4G信号强度；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SIGNAL_STRENGTH_4G

3.2.4.16 excloud.FIELD_MEANINGS.SIM_ICCID

lua 复制代码

常量含义：SIM卡ICCID；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
值格式：20位数字字符串
示例代码：local field = excloud.FIELD_MEANINGS.SIM_ICCID

3.2.4.17 excloud.FIELD_MEANINGS.FILE_UPLOAD_TYPE

lua 复制代码

常量含义：文件上传类型；
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
值取值范围：1（图片）、2（音频）
示例代码：local field = excloud.FIELD_MEANINGS.FILE_UPLOAD_TYPE

3.2.4.18 excloud.FIELD_MEANINGS.FILE_NAME

lua 复制代码

常量含义：文件名称；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.FILE_NAME

3.2.4.19 excloud.FIELD_MEANINGS.FILE_SIZE

lua 复制代码

常量含义：上传文件大小；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.FILE_SIZE

3.2.4.20 excloud.FIELD_MEANINGS.UPLOAD_RESULT_STATUS

lua 复制代码

常量含义：上传结果状态；
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.UPLOAD_RESULT_STATUS

3.2.4.21 excloud.FIELD_MEANINGS.MTN_LOG_FILE_INDEX

lua 复制代码

常量含义：运维日志文件序号；
常量类型：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

lua 复制代码

常量含义：运维日志文件总数；
值数据类型：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

lua 复制代码

常量含义：运维日志文件大小；
值数据类型：不做强制限制，建议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

lua 复制代码

常量含义：运维日志上传状态；
值数据类型：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

lua 复制代码

常量含义：运维日志文件名称；
值数据类型：不做强制限制，建议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

lua 复制代码

常量含义：工牌总磁盘空间；
值数据类型：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

lua 复制代码

常量含义：工牌剩余磁盘空间；
值数据类型：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

lua 复制代码

常量含义：工牌总内存；
值数据类型：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

lua 复制代码

常量含义：工牌剩余内存；
值数据类型：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

lua 复制代码

常量含义：工牌录音数量；
值数据类型：excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.BADGE_RECORD_COUNT
业务说明：用于工牌设备上报其存储的录音文件数量。

3.2.5 软件数据类 (1024-1279)

3.2.5.1 excloud.FIELD_MEANINGS.LUA_CORE_ERROR

lua 复制代码

常量含义：Lua核心库错误上报；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.LUA_CORE_ERROR

3.2.5.2 excloud.FIELD_MEANINGS.LUA_EXT_ERROR

lua 复制代码

常量含义：Lua扩展库错误
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.LUA_EXT_ERROR

3.2.5.3 excloud.FIELD_MEANINGS.LUA_APP_ERROR

lua 复制代码

常量含义：Lua业务错误；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.LUA_APP_ERROR

3.2.5.4 excloud.FIELD_MEANINGS.FIRMWARE_VERSION

lua 复制代码

常量含义：固件版本号；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.FIRMWARE_VERSION

3.2.5.5 excloud.FIELD_MEANINGS.SMS_FORWARD

lua 复制代码

常量含义：短信转发（SMS转发）；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.SMS_FORWARD

3.2.5.6 excloud.FIELD_MEANINGS.CALL_FORWARD

lua 复制代码

常量含义：来电转发；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.ASCII
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.CALL_FORWARD

3.2.6 设备无关数据类 (1280-1535)

3.2.6.1 excloud.FIELD_MEANINGS.TIMESTAMP

lua 复制代码

常量含义：时间戳
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.TIMESTAMP

3.2.6.2 excloud.FIELD_MEANINGS.RANDOM_DATA

lua 复制代码

常量含义：无意义数据；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.BINARY
传输方向：设备→平台
示例代码：local field = excloud.FIELD_MEANINGS.RANDOM_DATA

3.3 运维日志状态常量

3.3.1 excloud.MTN_LOG_STATUS.START

lua 复制代码

常量含义：运维日志开始上传状态；表示运维日志上传过程开始，设备准备上传日志文件；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER；
传输方向：设备→平台；
示例代码：local status = excloud.MTN_LOG_STATUS.START
注意事项：用户通常不需要关注运维日志上传过程，只需要在setup中配置mtn_log_enabled=true即可，运维日志上传流程底层已实现。

3.3.2 excloud.MTN_LOG_STATUS.SUCCESS

lua 复制代码

常量含义：运维日志上传成功状态；表示运维日志文件已成功上传至平台，文件传输完整且校验通过；
值数据类型：不做强制限制，建议excloud.DATA_TYPES.INTEGER；
传输方向：设备→平台；
示例代码：local status = excloud.MTN_LOG_STATUS.SUCCESS
注意事项：用户通常不需要关注运维日志上传过程，只需要在setup中配置mtn_log_enabled=true即可，运维日志上传流程底层已实现。

3.3.3 excloud.MTN_LOG_STATUS.FAILED

lua 复制代码

常量含义：运维日志上传失败状态；
值数据类型：不做强制限制，建议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

lua 复制代码

常量含义：缓存写入方式；
         日志数据先写入内存缓存区，当缓存达到一定大小或时间间隔时批量写入存储介质，适用于频繁日志记录场景，能减少存储设备磨损；
传输方向：设备内部设置选项，
         在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

lua 复制代码

常量含义：追加写入方式；
         日志数据立即追加写入存储介质文件末尾，确保日志实时持久化，适用于重要日志记录场景，但可能增加存储设备读写次数；
传输方向：设备内部设置选项，
         在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

lua 复制代码

> 参数含义：配置参数表；  
> 数据类型：table；  
> 是否必选：是；  
> 参数格式：  
> {  
> 参数含义：是否使用getip服务，getip服务介绍见链接：[https://docs.openluat.com/protocols/aircloud/addition/](https://docs.openluat.com/protocols/aircloud/addition/)；  
> 在使用的时候，不需要关注实现逻辑，getip 服务在excloud扩展库内部已做对应处理，  
> 在使用时不需要主动配置此参数，或者将此参数配置为true  
> 数据类型：boolean  
> 取值范围：true/false，*默认true*  
> 是否必选：否；  
> 默认值：true  
> 参数示例：true  
> 注意事项：无  
> 参数名称： opts.use\_getip
> 
> 参数含义：设备类型；  
> 数据类型：number  
> 是否必选：是；  
> 取值范围：1（4G设备）或2（WIFI设备）或9虚拟设备（pc模拟器使用）  
> 参数示例：1  
> 注意事项：无  
> 参数名称： opts.device\_type
> 
> 参数含义：用户鉴权密钥；iot云平台的项目key，登录iot平台创建项目后会生成一个项目key，复制到此处  
> 数据类型：string或nil  
> 是否必选：是；  
> 注意事项：无  
> 参数示例："VmhtOb81EgZau6YyuuZJzwF6oUNGCbXi"  
> 参数名称： opts.auth\_key
> 
> 参数含义：传输协议；  
> 数据类型：string  
> 是否必选：是；  
> 参数示例："tcp"或"mqtt"  
> 参数示例："tcp"  
> 注意事项：无  
> 参数名称： opts.transport
> 
> 参数含义：是否自动重连；  
> 数据类型：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标志；  
> 数据类型：boolean  
> 是否必选：否；  
> 取值范围：true/false，默认false  
> 参数示例：true  
> 注意事项：无  
> 参数名称： opts.retain
> 
> 参数含义：MQTT clean session标志；  
> 数据类型：boolean  
> 是否必选：否；  
> 取值范围：true/false，默认false  
> 参数示例：\_false  
> 注意事项：无  
> 参数名称： opts.clean\_session
> 
> 参数含义：虚拟设备手机号（设备类型为9时必填）；  
> 使用pc模拟器时候需要使用，模拟器的设备id是手机号+虚拟设备序列号  
> 数据类型：string  
> 是否必选：否；  
> 取值范围：自己iot云平台注册的手机号  
> 注意事项：无  
> 参数名称： opts.virtual\_phone\_number
> 
> 参数含义：虚拟设备序列号（0-999）；  
> 可允许1000个虚拟设备测试  
> 数据类型：number  
> 是否必选：否；  
> 取值范围：0-999，默认0  
> 参数示例：1  
> 注意事项：无  
> 参数名称： opts.virtual\_serial\_num  
> }

返回值

local result, err = excloud.setup(params)

result

lua 复制代码

含义说明：配置是否成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示配置成功，false表示配置失败；
返回示例：true

err

lua 复制代码

含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："excloud is already open"

示例

lua 复制代码

local ok, err_msg = excloud.setup({
    use_getip = true, -- 使用getip服务
    device_type = 1,   -- 4G设备
    auth_key = "VmhtOb81EgZau6YyuuZJzwF6oUNGCbXi",
    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  -- 缓存写入方式
})
if not result then
    log.error("配置失败:", err)
end

4.2 excloud.on(cbfunc)

功能

注册事件回调函数，用于监听和响应 excloud 服务的状态变化事件；

注意事项

必须在 excloud.open()之前调用；

参数

cbfunc

lua 复制代码

含义说明：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" -- 运维日志上传完成事件
         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"] = ,
                                                            },
                                                            -- 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"] = ,
                                              }

是否必选：是；
注意事项：必须在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

lua 复制代码

含义说明：是否注册成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示注册成功，false表示注册失败；
返回示例：true

err

lua 复制代码

含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："Callback must be a function"

示例

lua 复制代码

-- 注册回调函数示例
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()注册回调函数；

参数

无；

返回值

local result, err = excloud.open()

result

lua 复制代码

含义说明：是否开启成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示开启成功，false表示开启失败；
返回示例：true

err

lua 复制代码

含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："excloud is already open"

示例

lua 复制代码

-- 开启服务_
local result, err = excloud.open()
if not result then
    log.error("开启服务失败:", err)
    return
end

log.info("excloud服务开启成功")

4.4 excloud.send(data, need_reply)

功能

发送数据到 AirCloud 平台；

注意事项

服务必须已开启并成功连接；

参数

data

lua 复制代码

参数含义：待发送的数据；
数据类型：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

lua 复制代码

参数含义：是否需要服务器回复；
数据类型：boolean；
取值范围：true或false；
是否必选：否；
注意事项：不传入时默认值为false；
参数示例：true

返回值

local result, err_msg = excloud.send(data, need_reply)

result

lua 复制代码

含义说明：消息是否成功提交到发送队列；发送结果通过回调函数"send_result"事件获取。
数据类型：boolean；
取值范围：true或false；
注意事项：true表示发送成功，false表示发送失败；
返回示例：true

err_msg

lua 复制代码

含义说明：错误信息；
数据类型：string；
取值范围：当result为false时，err_msg包含具体的错误描述；
注意事项：当result为true时，err_msg为nil；
返回示例："Not connected to server"

示例

lua 复制代码

-- 发送传感器数据示例_
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

lua 复制代码

含义说明：是否关闭成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示关闭成功，false表示关闭失败；
返回示例：true

err

lua 复制代码

含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："excloud not open"

示例

lua 复制代码

-- 关闭服务示例
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

lua 复制代码

含义说明：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

lua 复制代码

参数含义：心跳间隔时间；
数据类型：number；
是否必选：否；
取值范围：大于0的整数，单位秒
         最小值：1秒（但实际应用中建议不小于30秒，避免过于频繁）
         最大值：理论上无限制，但建议不超过600秒（10分钟）
         默认值为300秒（5分钟）
参数示例：60

custom_data

bash 复制代码

参数含义：自定义心跳内容；
数据类型：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

lua 复制代码

含义说明：是否启动成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示启动成功，false表示启动失败；
返回示例：true

示例

lua 复制代码

-- 启动自动心跳，每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

lua 复制代码

含义说明：是否停止成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示停止成功，false表示停止失败（可能原本未启动）；
返回示例：true

示例

lua 复制代码

-- 停止自动心跳
local result = excloud.stop_heartbeat()
if result then
    log.info("自动心跳已停止")
end

4.9 excloud.upload_image(file_path, file_name)

功能

上传图片文件到 AirCloud 平台；

注意事项

需要打开 getip 功能才能使用此接口将文件上传到合宙 AirCloud 平台。

因为要先通过 getip 服务获取文件上传的 url；getip 服务以及文件发送流程参考可参考此链接：https://docs.openluat.com/protocols/aircloud/addition/，在调用此接口过程中不必关注文件发送逻辑，扩展库中已实现对应处理逻辑。

需要在 task 中使用。

参数

file_path

lua 复制代码

参数含义：图片文件路径；
数据类型：string；
是否必选：是；
注意事项：文件必须存在且可读；
参数示例："/luatdb/image.jpg"

file_name

lua 复制代码

参数含义：上报到合宙AirCloud平台的文件名称；用于开始http上传前先通知合宙AirCloud平台
数据类型：string；
是否必选：否；
注意事项：如果不提供，则自动生成文件名；生成规则是"image_" .. os.time() .. ".jpg"
         这个名称会用于：在文件上传开始和完成通知中发送给云平台
参数示例："image_123456.jpg"

返回值

local result, err_msg = excloud.upload_image(file_path, file_name)

result

lua 复制代码

含义说明：是否上传成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示上传成功，false表示上传失败；
         true表示文件已成功上传到云平台
         false表示上传过程中出现错误
返回示例：true

err_msg

lua 复制代码

含义说明：错误信息；
数据类型：string；
取值范围："上传成功"； "服务器返回错误: +服务器返回错误码 "；"HTTP请求失败: +code"
注意事项：当result为true时，err_msg为"上传成功"；
         当result为true时，err_msg为"服务器返回错误: +服务器返回错误码 "或"HTTP请求失败: +code"；
返回示例："上传成功"

示例

lua 复制代码

-- 上传图片文件
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_path, file_name)

功能

上传音频文件到 AirCloud 平台；

注意事项

需要打开 getip 功能才能使用此接口将文件上传到 AirCloud 平台。

因为要先通过 getip 服务获取文件上传的 url；在调用此接口过程中不必关注文件发送逻辑，扩展库中已实现对应处理逻辑。

需要在 task 中使用。

参数

file_path

lua 复制代码

参数含义：音频文件路径；
数据类型：string；
是否必选：是；
注意事项：文件必须存在且可读；
参数示例："/sd/audio.mp3"

file_name

lua 复制代码

参数含义：上报到AirCloud平台的文件名称；用于开始http上传前先通知AirCloud平台
数据类型：string；
是否必选：否；
注意事项：如果不提供，则自动生成文件名；生成规则是："audio_" .. os.time() .. ".mp3"
参数示例："device_audio.mp3"

返回值

local result, err_msg = excloud.upload_audio(file_path, file_name)

result

lua 复制代码

含义说明：是否上传成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示上传成功，false表示上传失败；
         true表示文件已成功上传到云平台
         false表示上传过程中出现错误
返回示例：true

err_msg

lua 复制代码

含义说明：错误信息；
数据类型：string；
取值范围："上传成功"； "服务器返回错误: +服务器返回错误码 "；"HTTP请求失败: +code"
注意事项：当result为true时，err_msg为"上传成功"；
         当result为true时，err_msg为"服务器返回错误: +服务器返回错误码 "或"HTTP请求失败: +code"；
返回示例："上传成功"

示例

lua 复制代码

-- 上传音频文件
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

lua 复制代码

含义说明：通过getip服务获取的服务器配置信息；
数据类型：table或nil；
取值范围：当成功获取过getip信息时返回table，否则返回nil；
         {
            -- 连接信息，数据类型table
            -- TCP连接时包含ipv4和port字段
            -- MQTT连接时包含ssl、port、username、password字段
            ["conninfo"] = {

                                -- string类型，TCP连接时的服务器IPv4地址
                                -- 示例："124.71.128.165"
                                ["ipv4"] = ,

                                -- string类型，MQTT连接时的SSL域名
                                -- 示例："mqtt.airtalk.luatos.com"
                                ["ssl"] = ,

                                -- number类型，服务器端口号
                                -- 示例：9108（TCP）或8883（MQTT）
                                ["port"] = ,

                                -- string类型，MQTT连接时的用户名模板
                                -- 示例："{imei}"，实际使用时会被设备IMEI替换
                                ["username"] = ,

                                -- string类型，MQTT连接时的密码模板
                                -- 示例："{muid}"，实际使用时会被设备MUID替换
                                ["password"] = ,
                         },

            -- 图片上传配置，数据类型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"] = ,
                                                  },
                           },
            }
注意事项：无
返回示例：{
    "msg": "ok",
    "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": ""
        }
    }
}

示例

lua 复制代码

-- 获取服务器信息
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）；
运维日志采用循环覆盖机制，不会因为存储空间满而写入失败；
日志文件存储在设备本地，需要云端主动请求才能上传；

运维日志存储机制详解

文件结构

lua 复制代码

-- 4个循环日志文件
"/hzmtn1.trc"  -- 文件1
"/hzmtn2.trc"  -- 文件2
"/hzmtn3.trc"  -- 文件3
"/hzmtn4.trc"  -- 文件4

-- 索引文件（通过fskv存储）
"hzmtnind" = 1  -- 当前写入的文件序号（1-4）

1、存储空间管理

默认大小：每个文件占用 1 个 block（通常 4KB），4 个文件共 4 个 block（16KB）

可配置：通过（在 setup 中配置 mtn_log_blocks ）调整每个文件的大小

覆盖机制：采用循环覆盖机制

2、上报逻辑

lua 复制代码

-- 设备端：等待云端触发上传
-- 云端下发信令25（MTN_LOG_UPLOAD_REQ_SIGNAL）时触发上传

-- 上传流程：
-- 1. 设备收到上传请求
-- 2. 扫描4个运维日志文件
-- 3. 按文件序号顺序上传
-- 4. 发送上传状态通知

参数

tag

bash 复制代码

参数含义：日志标识；
数据类型：string；
是否必选：是；
参数示例："net_conn"

...

lua 复制代码

参数含义：日志内容，可变参数；
数据类型：任意；
是否必选：是；
参数示例："网络连接成功", "host", "192.168.1.1", "port", 8080

返回值

local result = excloud.mtn_log(tag, ...)

result

lua 复制代码

含义说明：是否记录成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示记录成功
         false表示没有开启运维日志功能，记录失败
         由于采用循环覆盖机制，不会因为存储空间满而返回false
返回示例：true

示例

lua 复制代码

-- 记录运维日志
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

lua 复制代码

参数含义：业务字段含义；
数据类型：number；
是否必选：是；
取值范围：使用 excloud.FIELD_MEANINGS 中的常量；
参数示例：excloud.FIELD_MEANINGS.TEMPERATURE
注意事项：必须使用 excloud.FIELD_MEANINGS 中定义的常量

data_type

lua 复制代码

参数含义：数据类型字段；
数据类型：number；
是否必选：是；
取值范围：使用 excloud.DATA_TYPES 中的常量；
参数示例：excloud.DATA_TYPES.FLOAT
注意事项：必须使用预定义的数据类型常量

value

lua 复制代码

参数含义：要编码的数据；
数据类型：多种类型；
是否必选：是；
取值范围：根据 data_type 不同而不同；
参数示例：25.5
注意事项：值的类型必须与 data_type 匹配

返回值

lua 复制代码

local success, tlv_data = excloud.build_tlv(field_meaning, data_type, value)

success

lua 复制代码

含义说明：构建是否成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true 表示构建成功，false 表示构建失败；
返回示例：true

tlv_data

lua 复制代码

含义说明：构建好的 TLV 数据；
数据类型：string；
取值范围：二进制字符串；
注意事项：当 success 为 true 时返回 TLV 数据，否则为 nil；
返回示例：二进制字符串

示例

lua 复制代码

-- 构建一个温度数据的 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

lua 复制代码

参数含义：TLV 格式数据的二进制字符串；
数据类型：string；
是否必选：是；
取值范围：有效的 TLV 格式二进制数据；
参数示例：二进制字符串
注意事项：必须是完整的 TLV 格式数据

startPos

lua 复制代码

参数含义：开始解析的位置；
数据类型：number；
是否必选：否；
取值范围：1 到 #data；
默认值：1；
参数示例：1
注意事项：默认为 1，即从数据开头开始解析

返回值

lua 复制代码

local tlv_info, new_pos, error = excloud.parse_tlv(data, startPos)

tlv_info

lua 复制代码

含义说明：解析后的 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

lua 复制代码

含义说明：解析完成后的新位置，需要判断是否超过数据长度，没超过还要再次解析；
数据类型：number；
取值范围：大于 startPos 的整数；
注意事项：解析成功时返回新位置，失败时返回 startPos；
返回示例：9

error

lua 复制代码

含义说明：解析失败时的错误信息；
数据类型：string；
取值范围：错误描述；
注意事项：解析失败时返回错误信息，成功时为 nil；
返回示例："TLV data too short"

示例

lua 复制代码

-- 解析一个 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

lua 复制代码

含义说明：二维码链接信息；
数据类型：string或nil；
取值范围：成功时返回二维码链接字符串，失败时返回nil；
注意事项：无；
返回示例："https://iot.luatos.com/qrcode/xxx"

示例

lua 复制代码

-- 获取二维码链接信息
local qrinfo = excloud.get_qrinfo()
if qrinfo then
    log.info("二维码链接:", qrinfo)
else
    log.warn("未获取到二维码链接")
end

五、模组支持说明

支持 LuatOS 开发的所有产品都支持 excloud 扩展库.

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