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

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

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

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

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

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

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

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

二、開源實(shí)例

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

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

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

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

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

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

]]
-- 導(dǎo)入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 "未知錯(cuò)誤"))
end
elseif event == "auth_result" then
if data.success then
log.info("認(rèn)證成功")
else
log.info("認(rèn)證失敗: " .. data.message)
end
elseif event == "message" then
log.info("收到消息, 流水號: " .. data.header.sequence_num)

-- 處理服務(wù)器下發(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ā)送響應(yīng)
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ā)送控制響應(yīng)失敗: " .. err_msg)
end
end
end
elseif event == "disconnect" then
log.warn("與服務(wù)器斷開連接")
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("運(yùn)維日志上傳開始", "文件數(shù)量:", data.file_count)

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

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

end

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

--不使用getip服務(wù)，注意把use_getip設(shè)置為false
-- local ok, err_msg = excloud.setup({
--     use_getip = false,                             -- 不使用getip服務(wù)
--     device_type = 1,                               -- 設(shè)備類型: 4G
--     host = "112.125.89.8",                         -- 服務(wù)器地址
--     port = 32585,                                  -- 服務(wù)器端口
--     auth_key = "Qqn2TH50319ELOuO0rhPgF5fOxNVNhNW", -- 鑒權(quán)密鑰
--     transport = "tcp",                             -- 使用TCP傳輸
--     auto_reconnect = true,                         -- 自動(dòng)重連
--     reconnect_interval = 10,                       -- 重連間隔(秒)
--     max_reconnect = 5,                             -- 最大重連次數(shù)
--     mtn_log_enabled = true                         -- 啟用運(yùn)維日志
-- })

-- 配置excloud參數(shù)，虛擬設(shè)備鏈接
-- local ok, err_msg = excloud.setup({
--     use_getip = true, --使用getip服務(wù)
--     device_type = 9,
--     auth_key = "Qqn2TH50319ELOuO0rhPgF5fOxNVNhNW",
--     virtual_phone_number = "15893470522",  -- 11位手機(jī)號
--     virtual_serial_num = 1,                -- 序列號（0-999）
--     transport = "tcp", -- 由于mqtt鏈接需要使用imei,虛擬設(shè)備沒有,所以只能使用TCP傳輸
--     mtn_log_enabled = true
-- })

if not ok then
log.info("初始化失敗: " .. err_msg)
return
end
log.info("excloud初始化成功")

-- 開啟excloud服務(wù)
local ok, err_msg = excloud.open()
if not ok then
log.info("開啟excloud服務(wù)失敗: " .. err_msg)
return
end
log.info("excloud服務(wù)已開啟")
-- 啟動(dòng)自動(dòng)心跳，默認(rèn)5分鐘一次的心跳
excloud.start_heartbeat()
log.info("自動(dòng)心跳已啟動(dòng)")

-- 啟動(dòng)3分鐘一次的心跳，可配置自定義內(nèi)容
-- excloud.start_heartbeat(180, {
--     { field_meaning = excloud.FIELD_MEANINGS.TIMESTAMP,
--     data_type = excloud.DATA_TYPES.INTEGER,
--     value = os.time() }
-- })

-- 停止自動(dòng)心跳
--excloud.stop_heartbeat()
-- 記錄啟動(dòng)日志
--excloud.mtn_log("system", "設(shè)備啟動(dòng)完成", "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)：定期上報(bào)數(shù)據(jù)

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

else
-- 上報(bào)基礎(chǔ)狀態(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  -- 信號強(qiáng)度
},
{
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("基礎(chǔ)數(shù)據(jù)上報(bào)成功")
else
log.error("基礎(chǔ)數(shù)據(jù)上報(bào)失敗:", err_msg)
end
end
end
end

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

審核編輯 黃宇