aLiYun（阿里物联网开放平台）
# 阿里云
物联网平台提供安全可靠的设备连接通信能力，支持设备数据采集上云，规则引擎流转数据和云端数据下发设备端。此外，也提供方便快捷的设备管理能力，支持物模型定义，数据结构化存储，和远程调试、监控、运维。阿里云物联网平台为设备提供安全可靠的连接通信能力，向下连接海量设备，支撑设备数据采集上云；向上提供云端API，服务端通过调用云端API将指令下发至设备端，实现远程控制。物联网平台消息通信流程图如下。
## 简介
本文简单的讲述了LuatOS-Air进行二次开发，采用一型一密与一机一密两种认证方式连接阿里云。整体结构如图：
## API说明
| API接口 | 功能描述 |
| ----------------------- | ---------------------------------------- |
| aLiYun.setup() | 配置阿里云物联网套件的产品信息和设备信息 |
| aLiYun.setRegion() | 设置地域region id |
| aLiYun.setConnectMode() | 设置连接方式 |
| aLiYun.subscribe() | 订阅主题 |
| aLiYun.publish() | 发布一条消息 |
详细的API介绍请参见[aLiYun章节](https://doc.openluat.com/wiki/21?wiki_page_id=2264)
## 实现流程
- 注册接入服务器结果回调函数
在收到true时表示连接成功，本demo中去发布一条QOS为1的消息到阿里云
- 设置地域
配置为在阿里云创建项目时所用地区。每个地域完全独立。每个可用区完全隔离，但同一个地域内的可用区之间使用低时延链路相连。地域和可用区之间的关系如下图所示。
## 示例
相关示例程序在软件安装路径下\script_LuaTask\demo\aLiYun文件夹下，包含公共示例以及企业版示例，根据实际应用选择对应的demo进行研究。
### 阿里云操作
#### 产品操作
打开阿里云找到物联网平台，开通业务后进入控制台。
点开设备管理的产品页面，点击新建产品。根据需求和图示说明创建产品。
[具体详细介绍见阿里云页面](https://help.aliyun.com/document_detail/73728.html?spm=a2c4g.11174283.6.571.3a8b1668Vmv5CZ)
#### 设备操作
创建产品完成后就可以进入设备页面添加设备，在对应产品页面进入设备管理，按照提示添加设备
（在做正式产品时建议使用imei为devicename，方便后期维护）
[阿里云设备创建](https://help.aliyun.com/document_detail/73729.html?spm=a2c4g.11186623.6.573.55977b7bAjX04B)
#### 其他说明
阿里云文档中有SDK接入云接入等多种方式，合宙的模块接入方式不属于SDK接入也不属于云接入。目前采用文档中说明的开放协议的MQTT协议接入。模块的AT模式只提供设备接入，数据收发，LuatOS-Air模式增加了OTA，其他阿里云物联提供的功能暂不支持。开发者可根据文档与API自行开发。
### LuatOS-Air方式连接概述
LuatOS-Air连接相比AT更为简单，只需要简单的配置即可连接，还可以灵活的对数据进行处理。需要从官网或者github下载luatask的脚本包，或者使用luatoolsv2会自动下载脚本资源，在工具根目录的\script_LuaTask\demo\aLiYun中脚本资源会随官网同步更新，具体版本可能和本文不同，不过功能都是一致的。
文档中用到的API接口见[aLiYun API](https://doc.openluat.com/wiki/21?wiki_page_id=2264)章节。
#### 一机一密LuatOS-Air方式连接
一机一密需要提前按照文档阿里云操作章节先建好产品并添加设备，获取三元组供代码使用。
找到所使用的脚本版本进入demo目录找到aliyun文件夹打开testALiYun.lua
首先修改PRODUCT_KEY为自己项目的PRODUCT_KEY
```lua
local PRODUCT_KEY = "b0FMK1Ga5cp"
```
再找到getDeviceName这个函数，如果是按前文的操作直接使用的imei作为devicename那么就不需要需改，如果是其他devicename就需要注释掉第一个return删除后面的return的注释，填上自己的devicename，类型是字符串。
```lua
函数名：getDeviceName
功能 ：获取设备名称
参数 ：无
返回值：设备名称
local function getDeviceName()
--默认使用设备的IMEI作为设备名称，用户可以根据项目需求自行修改
return misc.getImei()
--用户单体测试时，可以在此处直接返回阿里云的iot控制台上注册的设备名称，例如return "862991419835241"
--return "862991419835241"
end
```
下一步找到getDeviceSecret注释掉第一个return，去掉第二个return的注释，把阿里云上的DeviceSecret替换上。
```lua
函数名：getDeviceSecret
功能 ：获取设备密钥
参数 ：无
返回值：设备密钥
local function getDeviceSecret()
--默认使用设备的SN作为设备密钥，用户可以根据项目需求自行修改
return misc.getSn()
--用户单体测试时，可以在此处直接返回阿里云的iot控制台上生成的设备密钥，例如return"y7MTCG6Gk33Ux26bbWSpANl4OaI0bg5Q"
--return "y7MTCG6Gk33Ux26bbWSpANl4OaI0bg5Q"
end
```
修改以上三个参数后保存代码下载到设备就可以连接阿里云了。下载到设备的方法见wiki相关章节。
#### 一型一密LuatOS-Air方式连接
除了需要添加产品和设备还需要在阿里云打开动态注册开关
找到ProductSecret，复制ProductSecret使用
首先修改PRODUCT_KEY为自己项目的PRODUCT_KEY
```lua
local PRODUCT_KEY = "b0FMK1Ga5cp"
```
找到demo的这个地方，把PRODUCE_SECRET的注释去掉然后替换成自己的
```lua
--采用一型一密认证方案时：
--PRODUCT_KEY和PRODUCE_SECRET为阿里云华东2站点上创建的产品的ProductKey和ProductSecret，用户根据实际值自行修改
--local PRODUCT_KEY = "b1KCi45LcCP"
--local PRODUCE_SECRET = "VWll9fiYWKiwraBk"
--除了上面的PRODUCT_KEY和PRODUCE_SECRET外，还需要提供获取DeviceName的函数、获取DeviceSecret的函数、设置DeviceSecret的函数
--设备第一次在某个product下使用时，会先去云端动态注册，获取到DeviceSecret后，调用设置DeviceSecret的函数保存DeviceSecret
```
getDeviceName()这个地方前面阿里云操作时建议使用imei作为devicename就是为了此处使用方便。直接使用demo的这个写法即可，切记不可使用固定值。如果需要自己定义devicename请通过其他逻辑实现获取。
```lua
local function getDeviceName()
--默认使用设备的IMEI作为设备名称，用户可以根据项目需求自行修改
return misc.getImei()
--用户单体测试时，可以在此处直接返回阿里云的iot控制台上注册的设备名称，例如return "862991419835241"
--return "862991419835241"
end
```
getDeviceSecret的地方也不需要修改，默认会将参数记录到sn区域。如果程序有其他地方使用到sn可修改为记录到nvm，请根据需要自行实现。
最后找到如下部分，将一机一密的代码注释，将一型一密的代码打开
```lua
--采用一机一密认证方案时：
--配置：ProductKey、获取DeviceName的函数、获取DeviceSecret的函数；其中aLiYun.setup中的第二个参数必须传入nil
--aLiYun.setup(PRODUCT_KEY,nil,getDeviceName,getDeviceSecret)
--采用一型一密认证方案时：
--配置：ProductKey、ProductSecret、获取DeviceName的函数、获取DeviceSecret的函数、设置DeviceSecret的函数
aLiYun.setup(PRODUCT_KEY,PRODUCE_SECRET,getDeviceName,getDeviceSecret,setDeviceSecret)
```
保存代码下载到设备就可以连接阿里云了。下载到设备的方法见wiki相关章节。
### 发布消息
发布消息使用的是**aLiYun.publish(topic, payload, qos, cbFnc, cbPara)**这个API
| 传入值类型 | 释义 |
| ---------- | ------------------------------------------------------------ |
| string | topic，UTF8编码的主题 |
| string | payload，负载 |
| number | **可选参数，默认为`0`**，qos，质量等级，0/1/2，默认0 |
| function | **可选参数，默认为`nil`**，cbFnc，消息发布结果的回调函数 回调函数的调用形式为：cbFnc(result,cbPara)。result为true表示发布成功，false或者nil表示订阅失败；cbPara为本接口中的第5个参数 |
| param | **可选参数，默认为`nil`**，cbPara，消息发布结果回调函数的回调参数 |
在demo里publishTest()这个函数演示了接口的操作。把第一个参数修改成自己项目的topic就可以实现每20s向阿里云推送一条消息。
```lua
--发布一条QOS为1的消息
function publishTest()
if sConnected then
--注意：在此处自己去控制payload的内容编码，aLiYun库中不会对payload的内容做任何编码转换 aLiYun.publish("/"..PRODUCT_KEY.."/"..getDeviceName().."/update","qos1data",1,publishTestCb,"publishTest_"..publishCnt)
end
end
```
### 订阅消息
订阅使用的是**aLiYun.subscribe(topic, qos)**
| 传入值类型 | 释义 |
| ---------- | ------------------------------------------------------------ |
| param | topic，string或者table类型，一个主题时为string类型，多个主题时为table类型，主题内容为UTF8编码 |
| param | qos，number或者nil，topic为一个主题时，qos为number类型(0/1/2，默认0)；topic为多个主题时，qos为nil |
demo的一下代码就是订阅的操作
```lua
--- 连接结果的处理函数
-- @bool result，连接结果，true表示连接成功，false或者nil表示连接失败
local function connectCbFnc(result)
log.info("testALiYun.connectCbFnc",result)
sConnected = result
if result then
--订阅主题，不需要考虑订阅结果，如果订阅失败，aLiYun库中会自动重连
aLiYun.subscribe({["/"..PRODUCT_KEY.."/"..getDeviceName().."/get"]=0, ["/"..PRODUCT_KEY.."/"..getDeviceName().."/get"]=1})
--注册数据接收的处理函数
aLiYun.on("receive",rcvCbFnc)
--PUBLISH消息测试
publishTest()
end
end
```
首先使用aLiYun.subscribe订阅了两个topic，然后 aLiYun.on("receive",rcvCbFnc)注册接收消息处理的回调函数。回调中将消息进行打印。如果需要处理消息就可以在这里操作。
```lua
local function rcvCbFnc(topic,qos,payload)
log.info("testALiYun.rcvCbFnc",topic,qos,payload)
end
```
### OTA升级
1. 建立项目并接入阿里云
2. require"aLiYunOta"
3. 制作差分升级文件包 [生成差分包详细步骤](https://hmi.wiki.luatos.com/doc/65042949/e6zPC3k9/Sud8hTJ4#nav_14 "生成差分包详细步骤")
下图是ALIYU 2.0.1和 2.0.0版本差分包生成示意图
.jpg)
4. 阿里云平台上传差分包
5. 升级包验证
6. 平台查看升级结果
# 常见问题
[阿里云如何向模块批量写入DeviceSecret呢？](https://doc.openluat.com/article/421)