物聯(lián)網(wǎng)設備開發(fā)中，便捷上云與穩(wěn)定數(shù)傳是核心需求，LuatOS 的 AirCloud 物聯(lián)網(wǎng)云服務通信協(xié)議可實現(xiàn)數(shù)據(jù)上報核心功能，支持七類數(shù)據(jù)的定期 / 觸發(fā)式上報。本文將講解該協(xié)議相關(guān)內(nèi)容，同時提供模組開源示例、核心代碼及配套開發(fā)硬件與教程，助力開發(fā)者快速實現(xiàn)設備接入與數(shù)據(jù)上報。

一、AirCloud數(shù)據(jù)上報功能

1.1、數(shù)據(jù)上報功能概述

數(shù)據(jù)上報是AirCloud的核心功能之一，允許設備將各種狀態(tài)數(shù)據(jù)、傳感器數(shù)據(jù)等信息定期或觸發(fā)式地傳輸?shù)皆贫似脚_，用于實現(xiàn)：

• 設備狀態(tài)實時監(jiān)控
• 傳感器數(shù)據(jù)采集與分析
• 設備運行歷史記錄
• 基于數(shù)據(jù)的業(yè)務決策

1.2、支持的數(shù)據(jù)類型

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

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

二、開源實例

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

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

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

開發(fā)者可根據(jù)實際項目需求靈活配置連接參數(shù)，實現(xiàn)設備接入與數(shù)據(jù)上報。

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

1. 設備連接與認證
2. 數(shù)據(jù)上報與接收
3. 運維日志管理
4. 文件上傳功能
5. 心跳保活機制

]]
-- 導入excloud庫
local excloud = require("excloud")
-- 注冊回調(diào)函數(shù)
function on_excloud_event(event, data)
log.info("用戶回調(diào)函數(shù)", 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)

-- 處理服務器下發(fā)的消息
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))

-- 處理控制命令并發(fā)送響應
local response_ok, err_msg = excloud.send({
{
field_meaning = excloud.FIELD_MEANINGS.CONTROL_RESPONSE,
data_type = excloud.DATA_TYPES.UNICODE,
value = "命令執(zhí)行成功"
}
}, false)

if not response_ok then
log.info("發(fā)送控制響應失敗: " .. 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("發(fā)送成功，流水號: " .. data.sequence_num)
else
log.info("發(fā)送失敗: " .. data.error_msg)
end

elseif event == "mtn_log_upload_start" then
log.info("運維日志上傳開始", "文件數(shù)量:", data.file_count)

elseif event == "mtn_log_upload_progress" then
log.info("運維日志上傳進度",
"當前文件:", data.current_file,
"總數(shù):", data.total_files,
"文件名:", data.file_name,
"狀態(tài):", data.status)

elseif event == "mtn_log_upload_complete" then
log.info("運維日志上傳完成",
"成功:", data.success_count,
"失敗:", data.failed_count,
"總計:", data.total_files)
end

end

-- 注冊回調(diào)
excloud.on(on_excloud_event)
-- 主任務函數(shù)
function excloud_task_func()
-- 如果當前時間點設置的默認網(wǎng)卡還沒有連接成功，一直在這里循環(huán)等待
while not socket.adapter(socket.dft()) do
log.warn("excloud_task_func", "wait IP_READY", socket.dft())
-- 在此處阻塞等待默認網(wǎng)卡連接成功的消息"IP_READY"
-- 或者等待1秒超時退出阻塞等待狀態(tài);
-- 注意：此處的1000毫秒超時不要修改的更長；
-- 因為當使用exnetif.set_priority_order配置多個網(wǎng)卡連接外網(wǎng)的優(yōu)先級時，會隱式的修改默認使用的網(wǎng)卡
-- 當exnetif.set_priority_order的調(diào)用時序和此處的socket.adapter(socket.dft())判斷時序有可能不匹配
-- 此處的1秒，能夠保證，即使時序不匹配，也能1秒鐘退出阻塞狀態(tài)，再去判斷socket.adapter(socket.dft())
sys.waitUntil("IP_READY", 1000)
end
-- -- 配置excloud參數(shù)
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,       -- 最大重連次數(shù)
mtn_log_enabled = true,  -- 啟用運維日志
mtn_log_blocks = 1,      -- 日志文件塊數(shù)
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", -- 鑒權(quán)密鑰
--     transport = "tcp",                             -- 使用TCP傳輸
--     auto_reconnect = true,                         -- 自動重連
--     reconnect_interval = 10,                       -- 重連間隔(秒)
--     max_reconnect = 5,                             -- 最大重連次數(shù)
--     mtn_log_enabled = true                         -- 啟用運維日志
-- })

-- 配置excloud參數(shù)，虛擬設備鏈接
-- 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分鐘一次的心跳，可配置自定義內(nèi)容
-- 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

-- 主循環(huán)：定期上報數(shù)據(jù)

while true do
-- 每30秒上報一次數(shù)據(jù)
sys.wait(30000)
-- 檢查連接狀態(tài)
local status = excloud.status()
if not status.is_connected then
log.warn("設備未連接，跳過數(shù)據(jù)上報")

else
-- 上報基礎狀態(tài)數(shù)據(jù)
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("基礎數(shù)據(jù)上報成功")
else
log.error("基礎數(shù)據(jù)上報失敗:", err_msg)
end
end
end
end

以上便是 AirCloud 數(shù)據(jù)上報的相關(guān)使用方法與核心要點，今天的分享就到這里啦！~

審核編輯 黃宇