物聯網設備開發過程中，便捷實現云端接入、保障數據穩定傳輸是兩大核心訴求。LuatOS 的 AirCloud 物聯網云服務通信協議，可實現設備數據上報核心功能，還支持七類數據的定期或觸發式上報。本文將解析該協議相關內容，同時提供模組開源示例、核心代碼，以及配套的開發硬件與教程，為開發者實現設備快速上云與數據上報提供實操指引。

一、AirCloud數據上報功能

1.1、數據上報功能概述

數據上報是AirCloud的核心功能之一，允許設備將各種狀態數據、傳感器數據等信息定期或觸發式地傳輸到云端平臺，用于實現：

設備狀態實時監控
傳感器數據采集與分析
設備運行歷史記錄
基于數據的業務決策

1.2、支持的數據類型

AirCloud支持上報多種類型的數據，通過excloud擴展庫的excloud.FIELD_MEANINGS常量定義，主要包括以下幾大類：

傳感器數據如：溫度、濕度、酸堿度、顆粒物濃度、環境溫度、電量計量等。
定位與運動數據如：GNSS經緯度、行駛速度、GNSS衛星信噪比、搜索到的衛星總數、航向角、方向角、定位方式標識等。
設備狀態數據如：電池電壓、4G 信號強度、SIM卡ICCID、設備休眠模式、定時喚醒間隔等。
設備參數數據如：設備物理高度/寬度、轉速、駐留小區、小區信息、元器件型號等。
軟件與系統數據如：固件版本、系統錯誤信息、短信轉發、來電轉發等。
通用數據如：時間戳、無意義數據等。
控制與響應數據如：控制命令/回應、鑒權請求/回復等。

二、開源實例

針對各模組型號提供開源示例demo，并持續更新配套教程，開發者可以掌握AirCloud數據上報功能的使用方法。

以Air780EHV系列為例，可選用配套核心板或開發板實操驗證。
Air780EHV 是 Air780Exx 系列的 4G Cat.1 全網通模組，有 3.3V/1.8V 兩種 IO 電平版本，內置 ES8311 音頻芯片，支持 VoLTE高清通話、TTS 語音合成等語音功能，外設接口豐富且支持 485、CAN、以太網等工業常用配置，支持低功耗，功耗最低3uA，僅支持 LuatOS 二次開發，適用于智能語音交互、工業物聯網等低功耗物聯網場景。

核心代碼如下圖示，完整demo詳見源碼倉庫最新文件。

開發者可根據實際項目需求靈活配置連接參數，實現設備接入與數據上報。

本demo演示了excloud擴展庫的完整使用流程，包括：

設備連接與認證
數據上報與接收
運維日志管理
文件上傳功能
心跳保活機制

]]
-- 導入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 == "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.UNICODE,
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 = "Qqn2TH50319ELOuO0rhPgF5fOxNVNhNW",
transport = "udp",       -- 使用TCP傳輸
auto_reconnect = true,   -- 自動重連
reconnect_interval = 10, -- 重連間隔(秒)
max_reconnect = 5,       -- 最大重連次數
mtn_log_enabled = true,  -- 啟用運維日志
mtn_log_blocks = 1,      -- 日志文件塊數
mtn_log_write_way = excloud.MTN_LOG_ADD_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 = "Qqn2TH50319ELOuO0rhPgF5fOxNVNhNW", -- 鑒權密鑰
--     transport = "tcp",                             -- 使用TCP傳輸
--     auto_reconnect = true,                         -- 自動重連
--     reconnect_interval = 10,                       -- 重連間隔(秒)
--     max_reconnect = 5,                             -- 最大重連次數
--     mtn_log_enabled = true                         -- 啟用運維日志
-- })

-- 配置excloud參數，虛擬設備鏈接
-- local ok, err_msg = excloud.setup({
--     use_getip = true, --使用getip服務
--     device_type = 9,
--     auth_key = "Qqn2TH50319ELOuO0rhPgF5fOxNVNhNW",
--     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")
-- 獲取并打印二維碼信息
local qrinfo = excloud.get_qrinfo()
if qrinfo and qrinfo.url then
log.info("二維碼URL:", qrinfo.url)
else
log.info("未獲取到二維碼信息")
end

-- 主循環：定期上報數據

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