excloud -Aircloud扩展库
孟伟
一、概述
本扩展库是合宙 IOT 平台的 aircloud 协议的适配，用于设备连接合宙 IOT 平台
二、核心示例
local excloud = require("excloud")
-- 初始化excloud
local ok, err_msg = excloud.setup({
device_type = 1,
auth_key = "VmhtOb81EgZau6YyuuZJzwF6oUNGCbXi",
transport = "tcp",
auto_reconnect = true,
use_getip = true, --使用getip服务
})
-- 事件回调函数
local function cloud_callback(event, data)
if event == "connect_result" then
log.info("连接结果:", data.success, data.error or "")
elseif event == "disconnect" then
log.info("连接断开")
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 "", data.sequence_num)
elseif event == "message" then
log.info("收到消息:", json.encode(data))
elseif event == "reconnect_failed" then
log.info("重连失败，次数:", data.count)
end
end
-- 注册回调
excloud.on(cloud_callback)
-- 开启服务
excloud.open()
-- 启动默认5分钟一次的心跳
excloud.start_heartbeat()
-- 发送数据示例
sys.taskInit(function()
sys.wait(5000) -- 等待连接建立
local 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
}
}
excloud.send(data, true) -- 发送数据并请求回复
end)
三、常量详解
核心库常量，由 excloud 扩展库中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用。
3.1 数据类型常量
3.1.1 excloud.DATA_TYPES.INTEGER
常量含义：整数数据类型；
数据类型：number；
取值范围：0；
示例代码：local data_type = excloud.DATA_TYPES.INTEGER
3.1.2 excloud.DATA_TYPES.FLOAT
常量含义：浮点数数据类型；
数据类型：number；
取值范围：1；
示例代码：local data_type = excloud.DATA_TYPES.FLOAT
3.1.3 excloud.DATA_TYPES.BOOLEAN
常量含义：布尔值数据类型；
数据类型：number；
取值范围：2；
示例代码：local data_type = excloud.DATA_TYPES.BOOLEAN
3.1.4 excloud.DATA_TYPES.ASCII
常量含义：ASCII字符串数据类型；
数据类型：number；
取值范围：3；
示例代码：local data_type = excloud.DATA_TYPES.ASCII
3.1.5 excloud.DATA_TYPES.BINARY
常量含义：二进制数据类型；
数据类型：number；
取值范围：4；
示例代码：local data_type = excloud.DATA_TYPES.BINARY
3.1.6 excloud.DATA_TYPES.UNICODE
常量含义：Unicode字符串数据类型；
数据类型：number；
取值范围：5；
示例代码：local data_type = excloud.DATA_TYPES.UNICODE
3.2 字段含义常量
3.2.1 控制信令类型 (16-255)
3.2.1.1 excloud.FIELD_MEANINGS.AUTH_REQUEST
常量含义：鉴权请求；
数据类型：number；
取值范围：16；
示例代码：local field = excloud.FIELD_MEANINGS.AUTH_REQUEST
3.2.1.2 excloud.FIELD_MEANINGS.AUTH_RESPONSE
常量含义：鉴权回复；
数据类型：number；
取值范围：17；
示例代码：local field = excloud.FIELD_MEANINGS.AUTH_RESPONSE
3.2.1.3 excloud.FIELD_MEANINGS.REPORT_RESPONSE
常量含义：上报回应；
数据类型：number；
取值范围：18；
示例代码：local field = excloud.FIELD_MEANINGS.REPORT_RESPONSE
3.2.1.4 excloud.FIELD_MEANINGS.CONTROL_COMMAND
常量含义：控制命令；
数据类型：number；
取值范围：19；
示例代码：local field = excloud.FIELD_MEANINGS.CONTROL_COMMAND
3.2.1.5 excloud.FIELD_MEANINGS.CONTROL_RESPONSE
常量含义：控制回应；
数据类型：number；
取值范围：20；
示例代码：local field = excloud.FIELD_MEANINGS.CONTROL_RESPONSE
3.2.1.6 excloud.FIELD_MEANINGS.IRTU_DOWN
常量含义：iRTU下行命令；
数据类型：number；
取值范围：21；
示例代码：local field = excloud.FIELD_MEANINGS.IRTU_DOWN
3.2.1.7 excloud.FIELD_MEANINGS.IRTU_UP
常量含义：iRTU上行回复；
数据类型：number；
取值范围：22；
示例代码：local field = excloud.FIELD_MEANINGS.IRTU_UP
3.2.1.8 excloud.FIELD_MEANINGS.FILE_UPLOAD_START
常量含义：文件上传开始通知；
数据类型：number；
取值范围：23；
示例代码：local field = excloud.FIELD_MEANINGS.FILE_UPLOAD_START
3.2.1.9 excloud.FIELD_MEANINGS.FILE_UPLOAD_FINISH
常量含义：文件上传完成通知；
数据类型：number；
取值范围：24；
示例代码：local field = excloud.FIELD_MEANINGS.FILE_UPLOAD_FINISH
3.2.2 传感类 (256-511)
3.2.2.1 excloud.FIELD_MEANINGS.TEMPERATURE
常量含义：温度；
数据类型：number；
取值范围：256；
示例代码：local field = excloud.FIELD_MEANINGS.TEMPERATURE
3.2.2.2 excloud.FIELD_MEANINGS.HUMIDITY
常量含义：湿度；
数据类型：number；
取值范围：257；
示例代码：local field = excloud.FIELD_MEANINGS.HUMIDITY
3.2.2.3 excloud.FIELD_MEANINGS.PARTICULATE
常量含义：颗粒数；
数据类型：number；
取值范围：258；
示例代码：local field = excloud.FIELD_MEANINGS.PARTICULATE
3.2.2.4 excloud.FIELD_MEANINGS.ACIDITY
常量含义：酸度；
数据类型：number；
取值范围：259；
示例代码：local field = excloud.FIELD_MEANINGS.ACIDITY
3.2.2.5 excloud.FIELD_MEANINGS.ALKALINITY
常量含义：碱度；
数据类型：number；
取值范围：260；
示例代码：local field = excloud.FIELD_MEANINGS.ALKALINITY
3.2.2.6 excloud.FIELD_MEANINGS.ALTITUDE
常量含义：海拔；
数据类型：number；
取值范围：261；
示例代码：local field = excloud.FIELD_MEANINGS.ALTITUDE
3.2.2.7 excloud.FIELD_MEANINGS.WATER_LEVEL
常量含义：水位；
数据类型：number；
取值范围：262；
示例代码：local field = excloud.FIELD_MEANINGS.WATER_LEVEL
3.2.2.8 excloud.FIELD_MEANINGS.ENV_TEMPERATURE
常量含义：环境温度；
数据类型：number；
取值范围：263；
示例代码：local field = excloud.FIELD_MEANINGS.ENV_TEMPERATURE
3.2.2.9 excloud.FIELD_MEANINGS.POWER_METERING
常量含义：电量计量；
数据类型：number；
取值范围：264；
示例代码：local field = excloud.FIELD_MEANINGS.POWER_METERING
3.2.3 资产管理类 (512-767)
3.2.3.1 excloud.FIELD_MEANINGS.GNSS_LONGITUDE
常量含义：GNSS经度；
数据类型：number；
取值范围：512；
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_LONGITUDE
3.2.3.2 excloud.FIELD_MEANINGS.GNSS_LATITUDE
常量含义：GNSS纬度；
数据类型：number；
取值范围：513；
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_LATITUDE
3.2.3.3 excloud.FIELD_MEANINGS.SPEED
常量含义：行驶速度；
数据类型：number；
取值范围：514；
示例代码：local field = excloud.FIELD_MEANINGS.SPEED
3.2.3.4 excloud.FIELD_MEANINGS.GNSS_CN
常量含义：最强的4颗GNSS卫星的CN；
数据类型：number；
取值范围：515；
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_CN
3.2.3.5 excloud.FIELD_MEANINGS.SATELLITES_TOTAL
常量含义：搜到的所有卫星数；
数据类型：number；
取值范围：516；
示例代码：local field = excloud.FIELD_MEANINGS.SATELLITES_TOTAL
3.2.3.6 excloud.FIELD_MEANINGS.SATELLITES_VISIBLE
常量含义：可见卫星数；
数据类型：number；
取值范围：517；
示例代码：local field = excloud.FIELD_MEANINGS.SATELLITES_VISIBLE
3.2.3.7 excloud.FIELD_MEANINGS.HEADING
常量含义：航向角；
数据类型：number；
取值范围：518；
示例代码：local field = excloud.FIELD_MEANINGS.HEADING
3.2.3.8 excloud.FIELD_MEANINGS.LOCATION_METHOD
常量含义：基站定位/GNSS定位标识；
数据类型：number；
取值范围：519；
示例代码：local field = excloud.FIELD_MEANINGS.LOCATION_METHOD
3.2.3.9 excloud.FIELD_MEANINGS.GNSS_INFO
常量含义：GNSS芯片型号和固件版本号；
数据类型：number；
取值范围：520；
示例代码：local field = excloud.FIELD_MEANINGS.GNSS_INFO
3.2.3.10 excloud.FIELD_MEANINGS.DIRECTION
常量含义：方向；
数据类型：number；
取值范围：521；
示例代码：local field = excloud.FIELD_MEANINGS.DIRECTION
3.2.4 设备参数类 (768-1023)
3.2.4.1 excloud.FIELD_MEANINGS.HEIGHT
常量含义：高度；
数据类型：number；
取值范围：768；
示例代码：local field = excloud.FIELD_MEANINGS.HEIGHT
3.2.4.2 excloud.FIELD_MEANINGS.WIDTH
常量含义：宽度；
数据类型：number；
取值范围：769；
示例代码：local field = excloud.FIELD_MEANINGS.WIDTH
3.2.4.3 excloud.FIELD_MEANINGS.ROTATION_SPEED
常量含义：转速；
数据类型：number；
取值范围：770；
示例代码：local field = excloud.FIELD_MEANINGS.ROTATION_SPEED
3.2.4.4 excloud.FIELD_MEANINGS.BATTERY_LEVEL
常量含义：电量(mV)；
数据类型：number；
取值范围：771；
示例代码：local field = excloud.FIELD_MEANINGS.BATTERY_LEVEL
3.2.4.5 excloud.FIELD_MEANINGS.SERVING_CELL
常量含义：驻留小区；
数据类型：number；
取值范围：772；
示例代码：local field = excloud.FIELD_MEANINGS.SERVING_CELL
3.2.4.6 excloud.FIELD_MEANINGS.CELL_INFO
常量含义：驻留小区和邻区；
数据类型：number；
取值范围：773；
示例代码：local field = excloud.FIELD_MEANINGS.CELL_INFO
3.2.4.7 excloud.FIELD_MEANINGS.COMPONENT_MODEL
常量含义：元器件型号；
数据类型：number；
取值范围：774；
示例代码：local field = excloud.FIELD_MEANINGS.COMPONENT_MODEL
3.2.4.8 excloud.FIELD_MEANINGS.GPIO_LEVEL
常量含义：GPIO高低电平；
数据类型：number；
取值范围：775；
示例代码：local field = excloud.FIELD_MEANINGS.GPIO_LEVEL
3.2.4.9 excloud.FIELD_MEANINGS.BOOT_REASON
常量含义：开机原因；
数据类型：number；
取值范围：776；
示例代码：local field = excloud.FIELD_MEANINGS.BOOT_REASON
3.2.4.10 excloud.FIELD_MEANINGS.BOOT_COUNT
常量含义：开机次数；
数据类型：number；
取值范围：777；
示例代码：local field = excloud.FIELD_MEANINGS.BOOT_COUNT
3.2.4.11 excloud.FIELD_MEANINGS.SLEEP_MODE
常量含义：休眠模式；
数据类型：number；
取值范围：778；
示例代码：local field = excloud.FIELD_MEANINGS.SLEEP_MODE
3.2.4.12 excloud.FIELD_MEANINGS.WAKE_INTERVAL
常量含义：定时唤醒间隔；
数据类型：number；
取值范围：779；
示例代码：local field = excloud.FIELD_MEANINGS.WAKE_INTERVAL
3.2.4.13 excloud.FIELD_MEANINGS.NETWORK_IP_TYPE
常量含义：设备入网的IP类型；
数据类型：number；
取值范围：780；
示例代码：local field = excloud.FIELD_MEANINGS.NETWORK_IP_TYPE
3.2.4.14 excloud.FIELD_MEANINGS.NETWORK_TYPE
常量含义：当前联网方式；
数据类型：number；
取值范围：781；
示例代码：local field = excloud.FIELD_MEANINGS.NETWORK_TYPE
3.2.4.15 excloud.FIELD_MEANINGS.SIGNAL_STRENGTH_4G
常量含义：4G信号强度；
数据类型：number；
取值范围：782；
示例代码：local field = excloud.FIELD_MEANINGS.SIGNAL_STRENGTH_4G
3.2.4.16 excloud.FIELD_MEANINGS.SIM_ICCID
常量含义：SIM卡ICCID；
数据类型：number；
取值范围：783；
示例代码：local field = excloud.FIELD_MEANINGS.SIM_ICCID
3.2.4.17 excloud.FIELD_MEANINGS.FILE_UPLOAD_TYPE
常量含义：文件上传类型（1:图片, 2:音频）；
数据类型：number；
取值范围：784；
示例代码：local field = excloud.FIELD_MEANINGS.FILE_UPLOAD_TYPE
3.2.4.18 excloud.FIELD_MEANINGS.FILE_NAME
常量含义：文件名称；
数据类型：number；
取值范围：785；
示例代码：local field = excloud.FIELD_MEANINGS.FILE_NAME
3.2.4.19 excloud.FIELD_MEANINGS.FILE_SIZE
常量含义：文件大小；
数据类型：number；
取值范围：786；
示例代码：local field = excloud.FIELD_MEANINGS.FILE_SIZE
3.2.4.20 excloud.FIELD_MEANINGS.UPLOAD_RESULT_STATUS
常量含义：上传结果状态；
数据类型：number；
取值范围：787；
示例代码：local field = excloud.FIELD_MEANINGS.UPLOAD_RESULT_STATUS
3.2.5 软件数据类 (1024-1279)
3.2.5.1 excloud.FIELD_MEANINGS.LUA_CORE_ERROR
常量含义：Lua核心库错误上报；
数据类型：number；
取值范围：1024；
示例代码：local field = excloud.FIELD_MEANINGS.LUA_CORE_ERROR
3.2.5.2 excloud.FIELD_MEANINGS.LUA_EXT_ERROR
常量含义：Lua扩展卡错误上报；
数据类型：number；
取值范围：1025；
示例代码：local field = excloud.FIELD_MEANINGS.LUA_EXT_ERROR
3.2.5.3 excloud.FIELD_MEANINGS.LUA_APP_ERROR
常量含义：Lua业务错误上报；
数据类型：number；
取值范围：1026；
示例代码：local field = excloud.FIELD_MEANINGS.LUA_APP_ERROR
3.2.5.4 excloud.FIELD_MEANINGS.FIRMWARE_VERSION
常量含义：固件版本号；
数据类型：number；
取值范围：1027；
示例代码：local field = excloud.FIELD_MEANINGS.FIRMWARE_VERSION
3.2.5.5 excloud.FIELD_MEANINGS.SMS_FORWARD
常量含义：SMS转发；
数据类型：number；
取值范围：1028；
示例代码：local field = excloud.FIELD_MEANINGS.SMS_FORWARD
3.2.5.6 excloud.FIELD_MEANINGS.CALL_FORWARD
常量含义：来电转发；
数据类型：number；
取值范围：1029；
示例代码：local field = excloud.FIELD_MEANINGS.CALL_FORWARD
3.2.6 设备无关数据类 (1280-1535)
3.2.6.1 excloud.FIELD_MEANINGS.TIMESTAMP
常量含义：时间；
数据类型：number；
取值范围：1280；
示例代码：local field = excloud.FIELD_MEANINGS.TIMESTAMP
3.2.6.2 excloud.FIELD_MEANINGS.RANDOM_DATA
常量含义：无意义数据；
数据类型：number；
取值范围：1281；
示例代码：local field = excloud.FIELD_MEANINGS.RANDOM_DATA
四、函数详解
4.1 excloud.setup(otps)
功能
配置 excloud 服务参数；
注意事项
必须在开启服务前调用，开启服务后再次调用会失败；
参数
otps
参数含义：配置参数表；
数据类型：table；
是否必选：是；
参数格式：
{
-- 参数含义：是否使用getip服务发现；
-- 数据类型：boolean
-- 是否必选：是；
-- 默认值：true
use_getip = ,
_-- 参数含义：设备类型；_
_-- 数据类型：number_
_-- 是否必选：是；_
_-- 参数示例：1（4G设备）或2（WIFI设备）或9虚拟设备_
device_type = ,
_-- 参数含义：传输协议；_
_-- 数据类型：string_
_-- 是否必选：是；_
_-- 参数示例："tcp"或"mqtt"_
transport = ,
_-- 参数含义：用户鉴权密钥；aircloud平台的项目key_
_-- 数据类型：string或nil_
_-- 是否必选：是；_
auth_key = ,
_-- 参数含义：协议版本；_
_-- 数据类型：number_
_-- 是否必选：否；_
_-- 默认值：1_
protocol_version = ,
_-- 参数含义：服务器地址；_
_-- 数据类型：string_
_-- 是否必选：否；_
host = ,
_-- 参数含义：服务器端口；_
_-- 数据类型：number_
_-- 是否必选：否；_
port = ,
_-- 参数含义：心跳间隔(秒)；_
_-- 数据类型：number_
_-- 是否必选：否；_
_-- 默认值：300_
keepalive = ,
_-- 参数含义：是否自动重连；_
_-- 数据类型：boolean_
_-- 是否必选：否；_
_-- 默认值：true_
auto_reconnect = ,
_-- 参数含义：重连间隔(秒)；_
_-- 数据类型：number_
_-- 是否必选：否；_
_-- 默认值：10_
reconnect_interval = ,
_-- 参数含义：最大重连次数；_
_-- 数据类型：number_
_-- 是否必选：否；_
_-- 默认值：3_
max_reconnect = ,
_-- 参数含义：超时时间(秒)；_
_-- 数据类型：number_
_-- 是否必选：否；_
_-- 默认值：30_
timeout = ,
_-- 参数含义：MQTT QoS等级；_
_-- 数据类型：number_
_-- 是否必选：否；_
_-- 默认值：0_
qos = ,
_-- 参数含义：MQTT retain标志；_
_-- 数据类型：boolean_
_-- 是否必选：否；_
_-- 默认值：false_
retain = ,
_-- 参数含义：MQTT clean session标志；_
_-- 数据类型：boolean_
_-- 是否必选：否；_
_-- 默认值：true_
clean_session = ,
_-- 参数含义：是否使用SSL；_
_-- 数据类型：boolean_
_-- 是否必选：否；_
_-- 默认值：false_
ssl = ,
_-- 参数含义：MQTT用户名；_
_-- 数据类型：string或nil_
_-- 是否必选：否；_
username = ,
_-- 参数含义：MQTT密码；_
_-- 数据类型：string或nil_
_-- 是否必选：否；_
password = ,
_-- 参数含义：UDP鉴权密钥；_
_-- 数据类型：string或nil_
_-- 是否必选：否；_
udp_auth_key =
}
返回值
local result, err = excloud.setup(params)
result
含义说明：配置是否成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示配置成功，false表示配置失败；
返回示例：true
err
含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："excloud is already open"
示例
local result, err = excloud.setup({
device_type = 1,
device_id = "867978030000001",
transport = "tcp",
host = "cloud.luatos.com",
port = 8900
})
if not result thenlog.error("配置失败:", err)
end
4.2 excloud.on(cbfunc)
功能
注册事件回调函数，用于监听和响应 excloud 服务的状态变化事件；
参数
cbfunc
含义说明：excloud事件回调函数；
数据类型：function；
取值范围：回调函数格式为 function call_back(event, data) ... end，其中：
event: string类型，事件类型，包括：
"connect_result" - 连接结果
"disconnect" - 连接断开
"auth_result" - 认证结果
"send_result" - 发送结果
"message" - 收到消息
"reconnect_failed" - 重连失败
data: table类型，事件相关数据，具体格式根据事件类型不同而不同；
"connect_result": 连接结果事件
data格式: {
success: boolean, -- 连接是否成功
error: string或nil -- 错误信息（连接失败时）
}
"disconnect": 连接断开事件
data格式: {
error: string或nil -- 断开原因（如果有）
}
"auth_result": 认证结果事件
data格式: {
success: boolean, -- 认证是否成功
message: string -- 认证结果消息
}
"send_result": 数据发送结果事件
data格式: {
success: boolean, -- 发送是否成功
error_msg: string或nil, -- 错误信息（发送失败时）
sequence_num: number -- 消息序列号
}
"message": 收到云端消息事件
data格式: {
header: table, -- 消息头信息
auth_key: string或nil, -- 认证密钥（UDP传输时）
tlvs: table -- TLV字段数组
}
其中header结构: {
device_id: string, -- 设备ID
sequence_num: number, -- 序列号
msg_length: number, -- 消息长度
protocol_version: number, -- 协议版本
need_reply: boolean, -- 是否需要回复
is_udp_transport: boolean -- 是否为UDP传输
}
其中tlvs为数组，每个元素结构: {
field: number, -- 字段含义
type: number, -- 数据类型
value: any, -- 字段值
length: number -- 数据长度
}
"reconnect_failed": 重连失败事件
data格式: {
count: number -- 重连尝试次数
}
是否必选：是；
注意事项：必须在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
含义说明：是否注册成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示注册成功，false表示注册失败；
返回示例：true
err
含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："Callback must be a function"
示例
_-- 注册回调函数示例
_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 服务，建立与云平台的连接；
注意事项
调用前需先通过 excloud.setup()进行配置，并通过 excloud.on()注册回调函数；
参数
无；
返回值
local result, err = excloud.open()
result
含义说明：是否开启成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示开启成功，false表示开启失败；
返回示例：true
err
含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："excloud is already open"
示例
-- 开启服务_
_local result, err = excloud.open()_
_if not result then_
_ log.error("开启服务失败:", err)_
_ return_
_end_
_log.info("excloud服务开启成功")
4.4 excloud.send(data, need_reply)
功能
发送数据到云平台；
注意事项
服务必须已开启并成功连接；
参数
data
参数含义：待发送的数据；
数据类型：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
参数含义：是否需要服务器回复；
数据类型：boolean；
取值范围：true或false；
是否必选：否；
注意事项：不传入时默认值为false；
参数示例：true
返回值
local result, err_msg = excloud.send(data, need_reply)
result
含义说明：是否发送成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示发送成功，false表示发送失败；
返回示例：true
err_msg
含义说明：错误信息；
数据类型：string；
取值范围：当result为false时，err_msg包含具体的错误描述；
注意事项：当result为true时，err_msg为nil；
返回示例："Not connected to server"
示例
-- 发送传感器数据示例_
_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_
_ }_
_}_
_-- 发送数据并请求回复_
_local result, err_code, err_msg = excloud.send(sensor_data, true)_
_if not result then_
_ log.error("发送失败:", err_code, err_msg)_
_else_
_ log.info("数据发送成功")_
_end_
_-- 发送数据不请求回复_
_local result, err_msg = excloud.send(sensor_data, false)_
_if not result then_
_ log.error("发送失败:", err_msg)_
_else_
_ log.info("数据发送成功")_
_end
4.5 excloud.close()
功能
关闭 excloud 服务，断开与云平台的连接；
参数
无；
返回值
local result, err = excloud.close()
result
含义说明：是否关闭成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示关闭成功，false表示关闭失败；
返回示例：true
err
含义说明：错误信息；
数据类型：string或nil；
取值范围：当result为false时，err包含具体的错误描述；
注意事项：当result为true时，err为nil；
返回示例："excloud not open"
示例
-- 关闭服务示例_
_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
含义说明：excloud服务的当前状态信息；
数据类型：table；
取值范围：包含以下字段的状态表：
{
-- 含义说明：服务是否开启；
-- 数据类型：boolean；
-- 取值范围：true或false；
-- 注意事项：true表示服务已开启，false表示服务未开启；
-- 返回示例：true
is_open = ,
-- 含义说明：是否已连接服务器；
-- 数据类型：boolean；
-- 取值范围：true或false；
-- 注意事项：true表示已建立连接，false表示未连接；
-- 返回示例：true
is_connected = ,
-- 含义说明：是否已完成认证；
-- 数据类型：boolean；
-- 取值范围：true或false；
-- 注意事项：true表示已通过云平台认证，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)
功能
启动自动心跳机制，定期向云平台发送心跳消息；
注意事项
服务必须已开启；
参数
interval
参数含义：心跳间隔时间；
数据类型：number；
是否必选：否；
注意事项：单位为秒，默认值为300秒（5分钟）；
参数示例：60
custom_data
参数含义：自定义心跳内容；
数据类型：table；
是否必选：可选；
注意事项：如果不提供，则使用默认的心跳数据（空表）；
参数示例：{
{
field_meaning = excloud.FIELD_MEANINGS.TIMESTAMP,
data_type = excloud.DATA_TYPES.INTEGER,
value = os.time()
}
}
返回值
local result = excloud.start_heartbeat(interval, custom_data)
result
含义说明：是否启动成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示启动成功，false表示启动失败；
返回示例：true
示例
-- 启动自动心跳，每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
含义说明：是否停止成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示停止成功，false表示停止失败（可能原本未启动）；
返回示例：true
示例
-- 停止自动心跳
local result = excloud.stop_heartbeat()
if result then
log.info("自动心跳已停止")
end
4.9 excloud.upload_image(file_path, file_name)
功能
上传图片文件到云平台；
注意事项
需要先通过 getip 获取图片上传配置；
参数
file_path
参数含义：图片文件路径；
数据类型：string；
是否必选：是；
注意事项：文件必须存在且可读；
参数示例："/luatdb/image.jpg"
file_name
参数含义：图片文件名称；
数据类型：string；
是否必选：否；
注意事项：如果不提供，则自动生成文件名；生成规则是"image_" .. os.time() .. ".jpg"
参数示例："device_image_123456.jpg"
返回值
local result, err_msg = excloud.upload_image(file_path, file_name)
result
含义说明：是否上传成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示上传成功，false表示上传失败；
返回示例：true
err_msg
含义说明：错误信息；
数据类型：string；
取值范围："上传成功"； "服务器返回错误: +服务器返回错误码 "；"HTTP请求失败: +code"
注意事项：当result为true时，err_msg为"上传成功"；
当result为true时，err_msg为"服务器返回错误: +服务器返回错误码 "或"HTTP请求失败: +code"；
返回示例："上传成功"
示例
-- 上传图片文件
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)
功能
上传音频文件到云平台；
注意事项
需要先通过 getip 获取音频上传配置；
参数
file_path
参数含义：音频文件路径；
数据类型：string；
是否必选：是；
注意事项：文件必须存在且可读；
参数示例："/sd/audio.mp3"
file_name
参数含义：音频文件名称；
数据类型：string；
是否必选：否；
注意事项：如果不提供，则自动生成文件名；生成规则是："audio_" .. os.time() .. ".mp3"
参数示例："device_audio.mp3"
返回值
local result, err_msg = excloud.upload_audio(file_path, file_name)
result
含义说明：是否上传成功；
数据类型：boolean；
取值范围：true或false；
注意事项：true表示上传成功，false表示上传失败；
返回示例：true
err_msg
含义说明：错误信息；
数据类型：string；
取值范围："上传成功"； "服务器返回错误: +服务器返回错误码 "；"HTTP请求失败: +code"
注意事项：当result为true时，err_msg为"上传成功"；
当result为true时，err_msg为"服务器返回错误: +服务器返回错误码 "或"HTTP请求失败: +code"；
返回示例："上传成功"
示例
-- 上传音频文件
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()
功能
获取当前服务器连接信息和文件上传配置；
参数
无；
返回值
local server_info = excloud.get_server_info()
server_info
含义说明：服务器信息；
数据类型：table；
取值范围：包含以下字段的表：
{
-- 含义说明：连接信息；
-- 数据类型：table；
-- 注意事项：包含host、port等连接参数；
conninfo = ,
-- 含义说明：图片上传信息；
-- 数据类型：table；
-- 注意事项：包含图片上传的URL、headers等配置；
imginfo = ,
-- 含义说明：音频上传信息；
-- 数据类型：table；
-- 注意事项：包含音频上传的URL、headers等配置；
audinfo =
}
注意事项：返回的信息是通过getip服务获取的，如果未获取过则为nil；
返回示例：{
"conninfo": {
"ipv4": "124.71.128.xxx",
"port": xxxx
},
"imginfo": {
"url": "https://xxx.openluat.com/iot/upload/file2",
"data_key": "f",
"data_param": {
"key": "6Rva4qFuNp5tFo151nTnkbJdXhZFtbfSUpN8EpcXjitxtgk46wyW2o1c18W2LW7UdRNX9TnMEopyiHMBvr5pFEpcYt2FXGdtXpkWbMag"
}
},
"audinfo": {
"url": "https://xxx.openluat.com/iot/upload/file2",
"data_key": "f",
"data_param": {
"key": "93tXrV5j3C2WRdn4jyXYBuyMMamCJ8jmUN2y2XeAs37iGTNgeM7YHhgcCcz1bVCwbpFtQUNDUCjz2QR4s1NwgFe2KgUt5uXf4z37yvfCdBeQ"
}
}
}
示例
-- 获取服务器信息
local server_info = excloud.get_server_info()
if server_info.conninfo then
log.info("当前服务器:", server_info.conninfo.ipv4, server_info.conninfo.port)
end
if server_info.imginfo then
log.info("图片上传URL:", server_info.imginfo.url)
end
五、产品支持说明
支持 LuatOS 开发的所有产品都支持 excloud 扩展库.