Python SDK（beta）
更新时间：2018-03-23 17:26:00
概述
本文结合Link Develop，详细介绍如何基于Python SDK，实现物联网设备的设备注册、属性上报、事件上报、远程服务调用以及网关子设备关联、OTA升级等功能。
SDK提供了示例Python 脚本，可以便捷的在Mac OS和安装Unix虚拟机的Windows PC上，以虚拟设备的方式，模拟真实设备运行，相关功能可以便捷地移植到真实运行的Linux设备上。
工具既利用 Python 的强大功能，也利用于了脚本无需编译的特性，方便开发者在真实设备量产前进行开发调试，验证设备功能。
SDK下载：点击下载
关键词
终端设备：
终端设备泛指集成有IoT-SDK的所有设备统称，终端设备通过所连接的网关设备直接或间接连接到云平台。从而完成业务属性上报、事件上报、服务调用，最终实现云端集中智能控制。网关设备：
网关设备是一种特殊的终端设备，网关设备除具备普通终端通用业务属性上报、事件上报、服务调用等业务外，最典型的区别在于网关设备需向其他非网关类终端设备提供消息路由服务。通过本服务，非网关类终端设备直接或间接连接到云平台，完成消息上报等业务。设备激活凭证：
设备在云端预注册后颁发的设备认证证书，包含三元组(ProductKey,DeviceName,DeviceSecret)。开发者可以下载到本地（excel文件），用于产线批量烧录，设备上线时根据该凭据进行认证鉴权。
在Link Develop中的位置
Python SDK 示例代码包内容
Readme.md #使用说明文档
install.sh #shell命令行下安装执行脚本
iot_device.py #Python脚本：终端设备相关类定义文件
iot_gateway.py #Python脚本：网关设备相关类定义文件
packages #Python脚本依赖的包文件
run_device.py #Python脚本：虚拟终端设备调用实现脚本
run_device.sh #Shell脚本： 调用run_device.py脚本
run_gateway.py #Python脚本：虚拟网关设备调用实现脚本
run_gateway.sh #Shell脚本： 调用run_gateway.py脚本
环境准备
硬件和系统
准备可以运行Linux系统的硬件设备（如树莓派），或是Mac OS设备，或者可以提供Unix虚拟机（如VirtualBox）的Windows PC。本SDK的示例脚本运行在Mac和Windows电脑上，就可以虚拟一个物联网设备和云端的通信功能，调试完成后，可以便捷移植到实际运行Linux系统和Python的真实设备上，并根据设备特性进行功能开发。
Python
要求Python版本在2.7及以上，您可以根据您的具体硬件设备，从Python官网按照提示下载和安装Python，官网链接
开发指引
1. 前置操作
- Link Develop设备信息注册
登录Link Develop，在设备管理中注册设备后，获取设备激活凭证信息。
- Python虚拟设备脚本设备激活凭据修改
在脚本run_device.py或run_gateway.py中找出以下定义。并将上述设备激活凭据更新到Python脚本中对应的product_key/device_name/device_secret中。
a) run_device.py脚本中设备激活凭据修改点如下：
device_conf = {
"product_key":"p19VcFBtktc",
"device_name":"qb3Yn9Lj5LZ98qNzUaSi",
"device_secret":"2617sMMipK2abhMlcr4JwnlYG6nFagiN",
"version": "1.1.0"
}
b) run_gateway.py脚本中设备激活凭据修改点如下：
gateway_conf = {
"product_key":"p1mss07zfBI",
"device_name":"CpeS8a91rAwUmucYJZuG",
"device_secret":"EDw0KPmsHT8vRfNCQTrSPYJoflCdRHPV",
"version": "1.0.0",
"sub_devices":[
{
"product_key": "p1SSWdyVniJ",
"device_name": "LiEFm2vYLDiqLZHArrhp",
"device_secret": "M7CKY1Sj40bMArRz9t39kTcGQ32hMVbD",
"version": "1.0.0"
},
{
"product_key": "p1SSWdyVniJ",
"device_name": "Ao52ntDJHJ9Nqhr2rGFn",
"device_secret": "6BehgXUtTEkmHJ5NarbaJ3Otn7BbfmYS",
"version": "1.0.0"
},
{
"product_key": "p19IEpd9vEQ",
"device_name": "nxnolgr7QA7UAc7GcnwO",
"device_secret": "WumzMkUAzCiD5S0eNaEZJgfo8XNc5caC",
"version": "1.0.0"
}
]
}
注意：只修改主设备激活凭据信息（如需用到多个子设备，则需同步将已注册的子设备激活凭据更新到sub_devices
设备激活凭据列表信息中)
2. 设备属性上报
所有终端设备（含网关）均会用到本上报业务。模拟属性上报过程如下：
1）在当前设备对应的设备类开中，找到类型所对应的属性模板。
选择模板中，所需要模拟上报的属性。本例中选取必须和用户自定义两个属性（LightStatus/Property_aaa）为例进行上报示范：
2）修改脚本配置如下：
# device random_msg config
device_random_data = {
"LightStatus":"{{random_int(0, 1)}}",
"property_aaa":"{{random_int(0, 1)}}"
}
3）运行./run_device.sh,查看设备运行状态如下；
3. 设备属性设置
所有终端设备（含网关）均会用到属性设置业务。模拟属性设置过程如下：
- 选择设备开发，选择待调试设备。 点击”调试“，进入调试模式。
2）选择调试功能下拉菜单中选取待调试属性。
选择方法“设置”，并编辑Json脚本。
点击发送指令即可。
4. 设备事件上报
所有终端设备（含网关）均会用到事件上报业务。模拟事件上报过程如下：
1）选取需模拟上报的事件信息。本例以lightEvent_AAA为例。
2）修改Python脚本
# device random_msg config
device_random_data = {
"LightStatus":"{{random_int(0, 1)}}",
"property_aaa":"{{random_int(0, 1)}}",
":events": {
"lightEvent_AAA":{}
}
}
注：lightEvent_AAA事件的内容以实际模板定义格式为准进行上报。否则出现上报异常。
- 查看事件管理 正常模拟设备事件上报。
5. 设备服务调用
所有终端设备（含网关）均会用到服务远程调用。服务调用是平台向终端设备发起的调用。模拟服务远程调用过程如下：
1）选择终端设备模板中待模拟调用的服务。
本例选取服务lightAAA作为示范：
2）修改Python脚本
# device random_msg config
device_random_data = {
":services": {
"lightAAA":{}
}
}
3）在WEB控制台向Python虚拟设备发起服务调用。
a. 在产品开发中，选择设备开发。
b. 选择模拟的设备进行调试。
点击调试按钮。
c.选择对应的灯服务进行调试。
如上图所示：WEB控制台正常下发服务调用指令。
设备端正常接收服务调用指令。
6. OTA升级
所有终端设备（含网关）均会用到OTA升级服务。OTA升级服务按设备端的角度分为主动升级与被动升级两种。
- 主动升级：
主动升级是指由设备端主动触发，向OTA服务器请求当前设备类型最新版本。并从请求结果中提取版本号进行比较；若与本地版本号一致，则当前设备端固件已是最新版本，无需升级；
- 若不一致，则从请求结果中固件URL下载固件，check MD5进行升级。*
（当前mqtt方式不支持主动升级）
- 被动升级：
被动升级是由OTA平台驱动设备端下载升级的方式。
本升级方式具体过程如下：
a. 设备端上电启动，向OTA服务端上报本地版本号。
b. 服务端Check设备端上报的版本号，是否是当前设备种类最新固件。
若相同，则OTA服务端不做任何处理；
若不同，则OTA服务端向设备端推动升级信息（含固件URL、MD5、固件size等）。
- 设备端解析升级推送消息，正式进入升级流程。*
（所有终端设备均支持本升级方式）
下面具体介绍Python虚拟设备模拟OTA升级过程。
1）在Link Develop固件管理分组新建本设备类型升级策略，并对固件进行验证。
a. 添加新固件及版本相关信息。
b. 验证固件
如下图所示，当前固件已验证成功。固件验证状态已由“未验证”变成“已验证”。
c. 发布批量升级策略
（注：只有发布批量升级策略，符合条件的在线设备或非在线设备在开机会均能收到升级推送）
2）修改Python虚拟设备中固件版本号。
注意，此时的Python虚拟设备中固件版本号需设置为与1）中版本号（1.2.1）不一致，以便构造升级条件。
修改点如下：
# device config
device_conf = {
"product_key":"p19VcFBtktc",
"device_name":"langmu",
"device_secret":"oR1HT7k7hbev5ILKHkRctdVUjE5RugCv",
"version": "1.1.0"
}
（修改version字段即可；OTA服务端是根据字符串模式匹配比较一致性的，非数字的大小比较。）
3）运行Python虚拟设备脚本。
Python虚拟设备端收到升级推送进行升级，并上报升级进度。烧录完成后，上报更新后的最新固件版本号。升级流程结束。
7. 子设备关联
子设备关联是==网关设备==所特有的业务。网关设备发现子设备后，提取子设备相关信息进行上报。此时管理平台即可感知当前设备间的从属关系。
1）注册网关设备
注册网关设备，获取网关设备激活凭据信息。
2）获取待模拟的网关子设备激活凭据信息。
3）更新脚本
脚本run_gateway.py修改点如下：
# gateway and sub devices config
gateway_conf = {
"product_key":"b13tmXEuE2L",
"device_name":"BUq8Bd9ycK3hDuR3hzxu",
"device_secret":"L4DqpgmG4J6vgIA52mUbR8wl5j50IkFK",
"version": "1.1.0",
"sub_devices":[
{
"product_key":"p19VcFBtktc",
"device_name":"qb3Yn9Lj5LZ98qNzUaSi",
"device_secret":"2617sMMipK2abhMlcr4JwnlYG6nFagiN",
"version": "1.1.0",
}
]
}
（更新对应的网关设备及其子设备的设备激活凭据信息）
4）执行run_gateway.sh进行子设备关联。
查看Link Develop中，网关与对应设备的关联关系。
子设备关联成功。
8. 注意事项
1）注册产品时，数据格式必须选择为ALINK方式；否则无法进行调试。
2）OTA升级前，必须先建立升级策略。并对策略中的固件进行升级前的验证；只有“已验证”状态的固件才能执行固件升级。