网关及子设备开发指南
更新时间：2019-01-23 10:39:42
术语约定
网关设备：也叫主设备，是指可以挂载子设备的直连设备，网关具有子设备管理模块，维持子设备的拓扑关系，并且可以将拓扑关系同步到云端；
子设备：不能直接连接到云端，只能通过挂接到网关上，通过网关间接连云的设备，比如使用zigbee协议联网的设备；
设备ID：设备句柄，在网关SDK中用于标识一个具体的设备；
设备标识三元组：设备标识三元组指设备的productKey、deviceName和deviceSecret，用于在阿里IoT云中唯一标识设备；
动态注册：子设备无需烧录一机一密（三元组），只需要烧录ProductKey、ProductSecret，然后基于子设备的唯一标识作为三元组中的deviceName（例如SN），再使用网关SDK到云端动态注册获取deviceSecret，从而得到完整的三元组。这样，子设备就可以使用三元组到云端进行设备身份认证，并进而被云端管理。
TSL：Thing Specification Language，基于JSON格式，用于描述设备所具备的功能和能力，详细说明请参阅《物的模型TSL》。
网关开发流程
网关产品的开发流程如下图所示：
注：本文档以C语言Link Kit SDK的2.3.0版本为例进行编写
从此处下载嵌入式C Link Kit SDK
说明：
- 商家后台定义网关产品的过程请参见前面章节的“注册产品”描述，创建网关产品时可以选择“所属分类”->“网络设备”中的“网关”，确保其后在“新建产品”页面的“节点类型”中选择选项“网关”，并指定该款网关支持的下联协议类型（可以多选），目前商家后台露出的下联协议包括“Zigbee”、“其它”，如果网关支持zigbee子设备接入则选择zigbee，否则选择“其它”；
- 底色为蓝色的步骤表示该步骤中的功能完全由网关厂商自己定义与实现
- 网关如何去发现以及连接子设备是由网关厂商与子设备厂商去协商和定义的，平台并不参与网关与子设备之间的通信过程和数据格式定义。但是当网关添加一个子设备后，需要使用平台提供的 子设备验证机制 来验证子设备的合法性；
- 当手机APP对子设备进行控制时，命令将会通过手机发送到云端、再由云端发送到网关设备后转发给子设备。网关与子设备之间的数据格式由网关厂商和子设备厂商定义，因此网关需要进行数据格式从平台格式到厂商数据格式的转换；
- 平台提供的网关SDK并不包含网关如何获取IP地址的功能。网关可能使用以太网、WiFi、或者蜂窝网技术（GRPS、3G、4G等）方式连接路由器，网关上如何通过DHCP获取IP地址、域名服务器地址、下一跳路由器的IP地址等功能由网关厂商实现；
- 如果网关使用WiFi接入网络，并且网关具有串口、或者web server这样的功能可以让用户输入WiFi热点的SSID/密码，那么网关厂商可以不用适配与集成阿里的WiFi配网功能。
终端用户添加子设备的交互示意图
本节介绍用户添加子设备的整个交互示意，以让网关厂商了解子设备是添加到云端的整体过程。设备用户购买了网关和子设备之后，需要先添加网关，然后再将子设备添加到网关，之后才能对子设备进行控制。下面是网关已添加后，添加子设备的多端交互如下所示：
当用户发起子设备添加时，手机将会向云端发送PermitJoin命令，之后云端会将该命令转发给网关，此时网关需要去发现与连接子设备，++网关如何去发现与连接子设备是由网关厂商与子设备厂商来定义和实现的++。当网关收到PermitJoin后，将发现的子设备上报到云端。
注：如果网关没有收到来自云端的permitJoin消息，即使子设备已连接到网关，也不要向云端添加子设备；可以等到收到permitJoin之后再将已连接的子设备通知云端。
云端与网关之间 数据格式由阿里云IoT定义，网关与子设备之间的数据格式是网关厂商与子设备厂商定义，因此网关需要实现数据格式在阿里云IoT数据格式与子设备之间数据格式的转换工作。
当云端添加子设备到网关之后，将会发送消息到手机端，从而让用户可以看见添加的子设备，继而对子设备进行控制。
网关开发过程
注：网关集成Link Kit SDK后首先连接到阿里云物联网，继而为多个业务平台所用，包括“智能生活开放平台”、“城市物联网平台”等等。下面有的开发文档链接将会跳转到Link Kit SDK的文档中心，在风格上存在细微的差别。
SDK应用于网关时的推荐配置
解压获取到的sdk包后，在主目录下有一个make.settings文件，其中定义功能模块的需求，下面是针对网关的推荐配置：
- 网关使用WiFi接口上行时的推荐配置
请参见“开发WiFi单品设备”中的配置
- 网关使用以太网接口上行的推荐配置
请参见“开发以太网单品设备”中的配置
- 网关使用蜂窝网接口上行的推荐配置
请参见“开发蜂窝网单品设备”中的配置
除了上面因为上联接口的不同进行的配置之外，还需要使能下面的配置：
FEATURE_DEVICE_MODEL_GATEWAY=y
FEATURE_DEPRECATED_LINKKIT=n
注：
- 2.3.0版本以前的版本使用的网关的编程接口与2.3.0的接口不一样，如果希望在版本2.3.0中使用旧接口，需要进行下面的配置以将旧接口编译到sdk的链接库中
FEATURE_DEVICE_MODEL_GATEWAY=y
FEATURE_DEPRECATED_LINKKIT=y
- 若希望在版本2.3.0中使用网关编程API的旧接口，或者用户希望继续使用低于2.3.0的SDK版本开发网关，请参考此历史文档。
HAL适配
请参照下面的文档进行HAL的实现：
WiFi配网HAL的适配
若未选择集成阿里提供的WiFi配网功能，可以不用适配这些HAL-
如果网关使用蜂窝网接口上行，不需要适配本地通信的HAL 线程相关HAL的适配
如果未选择WiFi配网、也未选择本地通信功能，可以不用适配线程相关的HAL
交叉编译配置
请参考“交叉编译示例”中的过程了解如何实现Link Kit SDK的交叉编译。
选择网关的认证模式
网关连接阿里云物联网平台时，可以使用预置三元组的方式进行网关的身份认证，也可以采用动态注册方式得到完整的三元组再进行身份认证，请参考“设备认证”了解编程细节。
网关编程
请参考“子设备管理”了解如何进行网关的初始化、如何添加子设备、如何上报子设备的在线状态、以及对子设备进行管理。
注：
C SDK v2.3.0以前的版本使用了另外一套编程接口，若用户使用的版本低于2.3.0，可以访问历史文档了解如何使用这套接口进行编程
若SDK的版本是2.3.0，但是仍然希望使用版本2.3.0以前的网关编程接口，可以通过修改make.settings将以前的接口编译到sdk的库文件中进行使用
子设备产品开发
子设备产品开发流程
说明：
- 每个子设备也需要在智能生活平台上创建一个产品，并定义该产品支持的属性、事件、服务；
- 子设备产品的注册方式需要设置为“动态注册”
- 每个子设备都需要一个有效且唯一的阿里IoT激活码，目前该激活码不需要烧写到子设备上，但是子设备厂商需要为每个产品申请激活码
- 子设备的激活码的DeviceName需要由子设备厂商指定，并上传到智能生活开放平台，请参考“设备激活码”了解步骤。
注意事项
只有网关的Owner可以发起子设备的添加操作
网关的Owner把网关分享给用户B，用户B并不能添加子设备
网关的Owner把网关分享给用户B，网关连接的子设备并没有分享给B，如果用户B需要控制子设备，需要Owner把子设备单独分享给B
当网关的Owner解绑子设备之后，子设备与网关的拓扑关系也会被解除，该子设备需要重新发起子设备添加过程来添加到一个网关
目前一个网关最多可以添加的子设备的数量限制为200