02 图片上传

AirCloud 图片上传功能

作者：孟伟

一、功能概述

AirCloud 是 LuatOS 物联网设备云服务通信协议，提供设备连接、数据上报、远程控制和文件上传等核心功能。excloud 扩展库是 AirCloud 协议的实现，通过该库设备可以快速接入aircloud云服务平台（iot.luatos.com），实现远程监控和管理。

1.1 图片上传功能介绍

图片上传是 AirCloud 的重要功能之一，允许设备将拍摄的图片或其他文件传输到云端平台，实现：

设备现场图像采集与上传
环境监控与可视化
事件触发式图像捕获
远程设备状态可视化

二、准备环境

2.1 硬件环境

参考：硬件环境清单第二章节内容，准备以及组装好硬件环境。

2.2 软件环境

在开始实践本示例之前，先筹备一下软件环境：

烧录工具： Luatools 工具；
内核固件：本demo开发测试时使用的固件为Air780EGH V2032 版本固件，本demo对固件版本没有什么特殊要求，所以你如果要测试本demo时，可以直接使用最新版本的内核固件；如果发现最新版本的内核固件测试有问题，可以使用我们开发本demo时使用的内核固件版本来对比测试；
LuatOS 需要的脚本和资源文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air780EHM_Air780EHV_Air780EGH/demo/aircloud
测试图片：准备一张测试图片，命名为 test.jpg，并上传到设备的 /luadb/ 目录。

三、API 接口说明

详细 API 文档请参考：https://docs.openluat.com/osapi/ext/excloud/

四、图片上传功能实现

4.1 核心代码示例

--[[
本demo演示了excloud扩展库的图片上传功能，包括：
1. 设备连接与认证
2. 图片文件上传
3. 上传状态监听
]]
-- 导入excloud库
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 == "disconnect" then
        log.warn("与服务器断开连接")
    elseif event == "reconnect_failed" then
        log.info("重连失败，已尝试 " .. data.count .. " 次")
    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,       -- 最大重连次数
        mtn_log_enabled = true,  -- 启用运维日志
        mtn_log_blocks = 2,      -- 日志文件块数
        mtn_log_write_way = excloud.MTN_LOG_CACHE_WRITE  -- 缓存写入方式
    })

    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("自动心跳已启动")
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)

4.2 代码解析

4.2.1 回调函数注册

回调函数用于处理 AirCloud 的各种事件，包括连接结果、认证结果等。图片上传功能本身没有特定的回调事件，但可以通过上传函数的返回值判断上传是否成功。

4.2.2 设备连接与认证

使用 excloud.setup() 配置设备参数，与数据上报功能类似，需要配置 use_getip、device_type、auth_key 等参数。

4.2.3 图片上传实现

图片上传的核心是 excloud.upload_image() 函数，它接受两个参数：

local_path: 本地图片文件路径
remote_name: 上传到云端后的文件名

4.2.4 上传时机控制

图片上传可以通过多种方式触发：

连接建立后立即上传（如示例中的 upload_image_fun）
事件触发上传（如按键触发、传感器触发、定时器循环上报等，可以在对应的中断中添加 upload_image_fun）

五、GetIP 服务

5.1 GetIP 服务简介

GetIP 服务是 AirCloud 提供的负载均衡服务，用于：

为设备分配最优的服务器节点
返回图片/音频文件上传所需的 URL 和参数，以及运维日志上报的 URL 和参数
确保上传数据的安全性和可靠性
此服务在 excloud 扩展库中自动运行，用户脚本无需干预

5.2 图片上传流程

设备通过 GetIP 服务获取上传 URL 和参数
设备使用获取的参数执行图片上传
云平台接收并处理上传的图片
图片在云平台上展示和存储

六、云平台配置

6.1 平台配置步骤

需要先登录合宙 IOT 平台，如下图所示，没有账号的，可以先注册一个。客户向合宙采购 4G 模块时，如果采购人员没有告知合宙这批模块放在 iot 平台上的哪个产品下，则合宙会以采购人的手机号为账号，默认密码 888888，创建一个"合宙标准模块"的项目，此次采购的所有模块都会放在这个项目下。
创建新项目或选择现有项目并获取项目 key (auth_key)，并将获取的项目 key 配置在代码中。