设备管理

微信平台与AbleCloud平台

微信硬件平台与AbleCloud平台都要求用户与设备建立绑定关系后才能使用设备，不过两个平台使用不用的策略来管理设备及其用户。

AbleCloud平台区分设备的管理员用户与非管理员用户。第一个绑定设备的用户就是设备的管理员用户。其他用户要绑定设备需要得到管理员用户的授权，比如通过管理员发放的分享码来绑定设备。普通用户可以也仅可以主动解除自己与设备的绑定关系。管理员用户可以解除任意用户（包括自己）与设备的绑定关系。而且，如果管理员用户解除了自己与设备的绑定关系，那么同时也会解除设备与其他所有用户的绑定关系。微信平台不区分设备用户的角色，任何人都可以平等的绑定或解绑设备。

如上所述，AbleCloud平台比微信平台提供了更丰富的设备管理策略，因此在特定情况下要求开发者执行必要的操作通知微信平台与AbleCloud平台同步设备与其用户的信息。需要通知微信平台同步信息的场景包括：

采用非微信扫描二维码功能绑定设备后需要通知微信平台同步信息。

使用微信终端时，推荐使用微信的“扫一扫”功能扫描设备的二维码（可以附加AbleCloud平台设备的管理员用户生成的分享码）来绑定设备。此时，微信平台会先完成设备绑定，然后推送消息给开发者的公众号后台。开发者可调用ACBridgeWeChat::onDeviceEventBind来处理该事件。该方法会调用AbleCloud平台相关接口绑定用户与设备，且无需额外通知双方平台同步信息。但是如果直接调用了AbleCloud平台提供的API绑定了设备，则需要通知微信平台同步信息。此时可调用ACBridgeWeChat::syncBindingsByDevice来同步信息。该方法是要求微信平台同步关于指定设备的信息。
调用AbleCloud平台的接口解除设备与用户的绑定关系后需要通知微信平台同步信息。

如前所述，如果管理员用户解除了与设备的绑定关系，那么AbleCloud平台会自动解除设备与其他用户的绑定关系。无论何时调用了AbleCloud平台提供的接口（如ACBindMgr::unbindDevice等）解除了用户与设备的绑定关系后，都需要调用ACBridgeWeChat::syncBindingsByDevice来同步信息。如ACBridgeWeChat::onDeviceEventUnbind调用了解除绑定的接口，同时也调用了syncBindingsByDevice方法来同步信息。

此外，微信平台会定期向开发者的公众号后台推送消息"device_event" - "subscribe_status"来查询设备的连接状态（仅针对WiFi设备）。开发者可以调用ACBridgeWeChat::onDeviceEventSubscribeStatus来处理该事件。微信平台推送消息"device_event" - "unsubscribe_status"时，开发者可调用ACBridgeWeChat::onDeviceEventUnsubscribeStatus来处理该事件。上述两个方法均支持选择性地调用ACBridgeWeChat::syncBindings同步当前用户的信息。注：同步数据的过程可能比较耗时。

开发者也可根据实际需求调用ACBridgeWeChat::syncBindings及ACBridgeWeChat::syncBindingsByDevice方法来同步信息。比如，周期性地在两个平台间同步数据；或者在用户遇到扫码没有反应或者其它可能跟数据不同步有关的问题时手工触发数据同步的操作。

针对用户扫描设备二维码后微信系统没有反应的情况，ACBridgeWeChat::checkAndBindDevice方法可以检查设备是否已在微信平台授权（未授权的设备不能被绑定），以及微信平台是否已经记录了设备与用户的绑定关系。如果前述两个条件均满足了，则在AbleCloud平台绑定用户与设备，并与微信平台同步该用户的信息。

独立设备

设备绑定的交互流程如下图所示：

wechat_wifi

设备绑定

微信设备授权及设备二维码

参考微信硬件平台-设备授权对硬件设备进行授权。授权完成后调用微信硬件平台-获取设备二维码接口获取设备的二维码。PHP SDK也封装了该接口，其调用方式如下：

// 实例化ACBridgeWeChat对象
$wxBridge = new ACBridgeWeChat($accessToken, $jsTicket);
// 获取设备的二维码串。
// 参数$subDomain是设备在AbleCloud平台上所属子域的名字。
// 第三个参数取值为FALSE表示不需要生成AbleCloud的设备分享码。
$qrCode = $wxBridge->getDeviceQRCode($physicalId, $subDomain, FALSE);
// 之后可使用相关工具将码串转换为二维码图片。

微信已支持在一个公众号中为多种设备提供服务。在AbleCloud平台上推荐为不同的设备配置不同的子域。上例中调用的方法（getDeviceQRCode）会在微信标准二维码后附加设备在AbleCloud平台上所属的子域信息。AbleCloud推荐开发者在设备的二维码中附带设备所属的子域信息，便于AbleCloud处理用户通过微信客户端扫描设备二维码触发的绑定设备的事件。下面是附带了子域信息的二维码的例子。其子域名为"test"。

http://we.qq.com/d/AQDjGOyOs3jzItRm4TdpIP-zZeyqVsHn6xy5B277#{"sub_domain":"test"}

下面是附带了子域信息及分享码的二维码的例子。其子域名为"test"，分享码的值为"8mRftXCMM21ZyQfzoTtHZfQWYvH1H6ni#3"。

http://we.qq.com/d/AQDjGOyOOtb6ZZA9EeWNKQ5fONgNz6fq4MXBCzBC#{"sub_domain":"test","share_code":"8mRftXCMM21ZyQfzoTtHZfQWYvH1H6ni#3"}

ACBridgeWeChat::getDeviceQRCode是以JSON格式的字符串将第三方的数据附加在微信平台标准的设备二维码的末尾。

处理用户扫描二维码的事件

微信用户扫描设备的二维码后，微信公众号平台会向开发者的公众号后台推送两条事件消息："event"-"subscribe"及"device_event"-"bind"，分别表示用户关注公众号及用户绑定了指定设备。如果用户之前已经关注过公众号，则仅推送第二条消息。

处理事件"event"-"subscribe"：

// 实例化ACBridgeWeChat对象
$wxBridge = new ACBridgeWeChat($accessToken, $jsTicket);
// $xmlMsg是微信推送的完整XML消息内容。
// $unionId是关注公众号的用户在微信平台对应的UnionID。如果不提供该参数，则无法识别同一个用户关注开发者的多个微信公众号的情况。
$user = $wxBridge->onEventSubscribe($xmlMsg, $unionId);
// 其它处理逻辑

方法ACBridgeWeChat::onEventSubscribe实现的主要功能是识别用户的OpenID，在AbleCloud平台上将该用户登记为开发者所提供服务的使用者。

处理事件"device_event"-"bind"：

// 实例化ACBridgeWeChat对象
$wxBridge = new ACBridgeWeChat($accessToken, $jsTicket);
// 参数$xmlMsg是微信推送的完整XML消息内容。
// 参数$deviceName是设备被绑定后的显示名。
// 参数$subDomain是被绑定的设备在AbleCloud平台上所属的子域的名字。
// 如果设备的二维码信息中包含了其所属子域的名字（以第三方附加数据的形式），则以二维码中的信息为准。此时$xmlMsg会包含有二维码中附加的子域的名字等第三方数据。
// 最后一个参数取值为FALSE，表示这个设备不是网关设备。
$device = $wxBridge->onDeviceEventBind($xmlMsg, $deviceName, $subDomain, FALSE);
// 其它处理逻辑

方法ACBridgeWeChat::onDeviceEventBind实现的主要功能是识别用户及设备信息，在AbleCloud平台中同步用户与设备的绑定关系。

AbleCloud将第一个绑定设备的用户作为该设备的管理员用户。其他用户只能在管理员用户的授权下才能绑定该设备。管理员可以提供设备的分享码，允许其它用户绑定设备（见下文“设备分享”）。这个分享码可以作为扩展属性附属在微信的原始设备二维码中方便用户扫码提取。方法ACBridgeWeChat::onDeviceEventBind能自动处理用户扫描包含/不包含分享码的设备二维码来绑定设备的情况。

设备激活

设备激活是指为WiFi设备配置WiFi网络，使设备连网、连接云端，从而提供在线服务能力。

对于接入微信硬件平台的设备，可以调用微信的AirKiss页面配置设备的WiFi网络。在手机连上WiFi的情况下，在AirKiss页面输入WiFi密码，等待设备连接网络。AirKiss的具体信息请参考微信硬件平台文档-AirKiss。

设备分享

设备分享是指以设备的管理员用户的身份调用AbleCloud平台的接口生成设备的分享码，其它用户凭借该分享码绑定设备。

// 实例化ACBridgeWeChat对象
$wxBridge = new ACBridgeWeChat($accessToken, $jsTicket);
// 获取包含分享码的二维码串
// 第三个参数取值为TRUE，表示需要生成设备的分享码。
$qrCode = $wxBridge->getDeviceQRCode($physicalId, $subDomain, TRUE, $openId, $timeout);
// 将码串$qrCode转换为二维码图片。其他用户使用微信扫描该二维码就可绑定设备。

设备解绑

需要在AbleCloud平台及微信平台中同步解除用户与设备的绑定关系。可以首先调用AbleCloud平台的设备解邦API，然后再执行AbleCloud平台与微信平台的信息同步操作。 AbleCloud平台区分设备的管理员用户及非管理员用户。如果管理员用户解除了与设备的绑定关系，那么AbleCloud将自动解除其他用户与设备的绑定关系。而微信硬件平台不区分用户的角色，所以某用户解绑设备后，需要通知微信硬件平台对照AbleCloud平台同步信息。

// 实例化ACBridgeWeChat对象
$wxBridge = new ACBridgeWeChat($accessToken, $jsTicket);
// 获取用户信息
$user = $wxBridge->getUser($openId);
// 实例化ACBindMgr
$bindMgr = ACClient::getBindMgr();
// 获取设备的逻辑ID。参数$subDomain表示设备在AbleCloud平台上所属子域的名字。
$deviceId = $bindMgr->getDeviceId($subDomain, $physicalId);
// 解绑设备
$bindMgr->unbindDevice($subDomain, $deviceId, $user);
// 通知微信硬件平台同步设备的绑定信息。
// 参数$deviceType是设备在微信公众号平台上对应的设备类型。
$wxBridge->syncBindingsByDevice($physicalId, $deviceType, $subDomain);