开发者中心

名词解释

  • 微信硬件平台: 微信硬件平台是微信内部承接物联网生态的底层平台,通过平台内的硬件ID实现微信与IOT设备的信息互联与设备控制
  • product_id: 微信硬件平台对具体某个厂商制造的某款设备产品的标识
  • SN: 厂商后台为设备生成的可对外的全局唯一设备标识, product_id范围内唯一
  • ilink_imsdk_id: 设备在微信硬件平台的唯一标识,即微信硬件ID
  • ilink_device_ticket: 设备绑定临时身份凭证,五分钟有效期
  • ilink_iotuser_id: 设备绑定者在微信硬件平台的身份标识
  • 首次绑定: 指设备在没有绑定者时被绑定, 此时用户会成为设备管理员

概述

为了方便已有小程序或APP的厂商将设备快速接入微信硬件平台,在此提供了针对厂商小程序及APP的快速绑定接入方案:通过厂商小程序/APP,拉起手机微信客户端内的相关页面,进行硬件设备的绑定和解绑

注:上图中流程以厂商小程序为例,厂商APP流程与此相同

相关参数的获取可以查阅后文流程接口部分

小程序接入设备

概念说明

对于已经开发过小程序的厂商,厂商可使用小程序跳转接口拉起绑定和解绑的相关页面,相关名词解释如下:
设备:接入微信硬件平台的智能硬件设备
sdkid:即微信硬件平台设备id, 获取方式见流程接口中的注册设备SN章节
ticket:设备绑定凭证,获取方式见流程接口中的设备绑定章节

跳转appid

appid:wxd930c3b7cf7c92e6

微信硬件页提供功能

目前厂商跳转微信硬件页面,可以完成的主要功能有:绑定设备、解绑设备

跳转页面说明

跳转参数需放在extraData(json对象)里
1.跳转绑定页
页面路径:/pages/bind-device/bind-device
传递参数:{"ticket": "xxxxx", "openid": "xxxx"}, ticket--从ilink后台获取的绑定凭证, openid--用户openid(可选)

注意:接入发送消息至设备或微信运动能力的设备,跳转绑定页路径跳转路径如下,并需要带上from参数
页面路径:/pages/discover-new/discover-new
传递参数:{"from": "xxx", "ticket": "xxxxx", "openid": "xxxx"}, from--添加设备标识符,ticket--从ilink后台获取的绑定凭证, openid--用户openid(可选)
接入发送消息至设备能力from参数需填写wxprint;接入微信运动能力from参数需填写wxsport:

2.跳转解绑设备页
页面路径:/pages/delete-devices/delete-devices
传递参数:{"sdkIdList": ["xxx1", "xxx2", "xxx3"]}, 要解绑的设备sdkId列表
回跳参数也放在extraData里:{from: 'wx-iot', "successList": ["xxx1", "xxx2"], "failList": ["xxx3"]}, 里面放的是sdkid列表,表明哪些成功,哪些失败

设备管理页跳转厂商小程序控制面板

微信设备页中,点击设备可支持跳转至厂商小程序中的设备控制页面,厂商需要在产品注册时选择小程序控制面板,并提供:appid 与 page_path,跳转过去所带参数放在extraData里,目前为sdkid参数:{from: 'wx-iot', sdkid: xxxx}
此外需要注意的是如果操作流程是厂商小程序——管理小程序——厂商小程序,则管理小程序会使用wx.navigateBackMiniProgram来跳转,相关参数会放在extraData里,如:

  1. extraData: {
  2. from: 'wx-iot',
  3. sdkid: device.deviceInfo.sdkILinkId,
  4. path: minfo.path
  5. }

APP接入设备

概念说明

厂商使用APP接入硬件,需先至微信开放平台,申请移动应用,获得移动应用AppID后,进行后续开发。
其中,ticket为设备绑定凭证,获取方式见流程接口中的绑定小节;sdkid为微信硬件平台设备id, 获取方式见流程接口中的注册设备SN小节。

Android开发示例

开发前需下载Android开发工具包(SDK),可前往下载https://developers.weixin.qq.com/doc/oplatform/Downloads/Android_Resource.html
调用接口:WXLaunchMiniProgram
移动应用跳转到微信设备页示例:

  1. String appId = "wxdxxxxxxxx"; // 厂商填移动应用(App)的 AppId
  2. IWXAPI api = WXAPIFactory.createWXAPI(context, appId);
  3. WXLaunchMiniProgram.Req req = new WXLaunchMiniProgram.Req();
  4. req.userName = "gh_471f5f7b25a9"// 注意这是微信硬件的username,不需要改动
  5. req.path = path
  6. //以绑定为例,路径示例:"/pages/bind-device/bind-device?ticket=234234",内部字符串不需要引号
  7. //注意:接入发送消息至设备或微信运动能力的设备,需使用如下绑定路径,并带上from=wxprint(发送消息至设备)或from=wxsport(微信运动)参数,路径示例:"pages/discover-new/discover-new?from=wxxxxx&&ticket=234234"
  8. req.miniprogramType = WXLaunchMiniProgram.Req.MINIPTOGRAM_TYPE_RELEASE;//注意这里可选不同版本TEST(测试版)/PREVIEW(体验版)/RELEASE(线上版),正常测试时使用体验版,正式上线时需切换至线上正式版
  9. api.sendReq(req);
  10. //解绑设备需替换:
  11. req.path = path
  12. //路径示例:"pages/delete-devices/delete-devices?sdkIdList=sdkid列表",内部字符串不需要引号,sdkid列表为json数组列表字符串

回调说明:

  1. WXEntryActivity
  2. public void onResp(BaseResp resp) {
  3. if (resp.getType() == ConstantsAPI.COMMAND_LAUNCH_WX_MINIPROGRAM) {
  4. WXLaunchMiniProgram.Resp launchMiniProResp = (WXLaunchMiniProgram.Resp) resp;
  5. String extraData =launchMiniProResp.extMsg; //对应组件 <button open-type="launchApp"> 中的 app-parameter 属性
  6. }

iOS开发示例

开发前需下载iOS开发工具包(SDK),前往下载https://developers.weixin.qq.com/doc/oplatform/Downloads/iOS_Resource.html
移动应用跳转到微信设备页示例:

  1. WXLaunchMiniProgramReq *launchMiniProgramReq = [WXLaunchMiniProgramReq object];
  2. launchMiniProgramReq.userName = gh_471f5f7b25a9; // 注意这是微信硬件的username,不需要改动
  3. launchMiniProgramReq.path = path;
  4. //以绑定为例,路径示例:"/pages/bind-device/bind-device?ticket=234234",内部字符串不需要引号;
  5. //注意:接入发送消息至设备或微信运动能力的设备,需使用如下绑定路径,并带上from=wxprint(发送消息至设备)或from=wxsport(微信运动)参数,路径示例:"pages/discover-new/discover-new?from=wxxxx&&ticket=234234"
  6. launchMiniProgramReq.miniProgramType = miniProgramType; //注意这里不同版本TEST(测试版)/PREVIEW(体验版)/RELEASE(线上版),正常测试时使用体验版,正式上线时需切换至线上正式版
  7. return [WXApi sendReq:launchMiniProgramReq];
  8. //解绑设备需替换:
  9. launchMiniProgramReq.path = path;
  10. //路径示例:"pages/delete-devices/delete-devices?sdkIdList=sdkid列表",内部字符串不需要引号

回调说明:

  1. -(void)onResp:(BaseResp *)resp
  2. {
  3. if ([resp isKindOfClass:[WXLaunchMiniProgramResp class]])
  4. {
  5. NSString *string = resp.extMsg;
  6. // 对应JsApi navigateBackApplication中的extraData字段数据
  7. }
  8. }

权限管理

云端接口调用规范

  1. 无特殊说明时, 微信提供的接口超时为5s
  2. 无特殊说明时, 不要对接口调用进行自动重试. 大量的自动重试可能导致对应appid被暂时屏蔽

获取access_token

接口说明:
通过微信开放平台调用微信内部接口时,需要使用appid与secret换取调用凭证access_token
具体参见: https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Get_access_token.html
请求地址:

  1. GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=xxx&secret=xxx

请求参数:

属性类型必填说明
grant_typestring填写 client_credential
appidstring小程序唯一凭证,即 AppID,可在「微信公众平台 - 设置 - 开发 设置」页中获得。(需要已经成为开发者,且帐号没有异常状态)
secretstring小程序唯一凭证密钥,即 AppSecret,获取方式同 appid

返回值:

属性名类型说明
access_tokenstring获取到的凭证
expires_innumber凭证有效时间,单位:秒。目前是7200秒之内的值。
errcodenumber错误码, 0为成功
errmsgstring错误信息

设备注册

厂商注册SN流程

1.厂商在设备绑定前,到微信硬件平台注册设备SN

2.注册成功,微信硬件平台返回该设备在平台的身份标识ilink_im_sdk_id.

注册SN的时机目前比较灵活, 可以选择在设备激活前离线批量注册, 也可以选择在设备被用户激活时再去注册

厂商应该记录SN与ilink_im_sdk_id的对应关系, 在与微信对接时将统一使用ilink_im_sdk_id

同一个product_id + SN不能多次注册

厂商注册SN接口

设备SN注册

接口说明:

每一个设备绑定前,需要到微信硬件平台注册信息

请求地址:

  1. POST https://api.weixin.qq.com/ilink/api/cloud_register_device?access_token=xxx

请求参数:

  1. {
  2. "product_id": 123,
  3. "iot_device_list": [
  4. {
  5. "sn": "xx1",
  6. },
  7. {
  8. "sn": "xx2",
  9. }
  10. ]
  11. }
属性类型必填说明
product_idnumber设备产品唯一标识
snstring厂商分配的设备唯一序列号

单次接口调用,sn个数上线是100,超限将返回错误

产品上线前, 只能注册20个sn

返回值:

  1. {
  2. "errcode":0,
  3. "errmsg":"xxx",
  4. "iot_device_list": [
  5. {
  6. "sn": "abcpatric",
  7. "ilink_im_sdk_id":"xxx@ilink.im.sdk",
  8. },
  9. {
  10. "sn": "abcpatric1",
  11. "ilink_im_sdk_id":"xxx@ilink.im.sdk",
  12. }
  13. ]
  14. }
属性类型说明
errcodenumber返回码,0为成功
errmsgstring错误信息
snstring厂商分配的设备唯一序列号
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识

设备绑定

绑定设备流程

设备通过小程序/APP绑定流程

其中厂商自实现步骤有一些自由度, 下文给出一些参考实现方案.

小程序/APP获取ticket的参考实现1

该方案通过设备拉取ticket近场传递给小程序/APP, 安全性高, 但可能要修改设备端逻辑

小程序/APP获取ticket的参考实现2

该方案通过小程序/APP直接拉取ticket, 无需修改现有设备, 但依赖小程序/APP端逻辑, 安全性稍低.

设备绑定接口

拉取设备绑定凭证

接口说明:

设备绑定时,厂商后台到微信硬件平台拉取该台设备的绑定凭证,传递给小程序端

请求地址:

  1. POST https://api.weixin.qq.com/ilink/api/get_device_ticket?access_token=xxx

请求参数:

  1. {
  2. "ilink_im_sdk_id": "xxx@ilink.im.sdk",
  3. "user_openid":"xxx"
  4. }
属性类型必填说明
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识
user_openidstring绑定设备用户的openid,选填,填了后将在真正绑定时限制用户只能为所填openid对应用户

返回值:

  1. {
  2. "errcode":0,
  3. "errmsg":"xxx",
  4. "ilink_device_ticket":""
  5. }
属性类型说明
errcodenumber返回码,0为成功
errmsgstring错误信息
ilink_device_ticketstring微信硬件平台设备绑定凭证

(回调厂商)设备绑定回调

接口说明:

当小程序管理端绑定设备时,微信硬件平台回调厂商后台进行绑定. 厂商可以在绑定回调时进行自己的绑定管理和权限校验.

请注意该接口的可用性, 如果回调失败, 绑定流程也将失败

请求参数:

  1. {
  2. "topic": "/ilink/sys/wechat_iot/$product_id/$ilink_im_sdk_id/bind",
  3. "payload": {
  4. "binder_type": 1,
  5. "binder_info":{
  6. "ilink_iot_user_id": "xxx"
  7. },
  8. "device_info":{
  9. "ilink_im_sdk_id": "xxx"
  10. },
  11. "ilink_device_ticket": "xxx"
  12. }
  13. }
属性类型必填说明
binder_typeint绑定者类型. 0=普通绑定者, 1=管理员
ilink_iot_user_idstring微信硬件平台分配的绑定者身份标识
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识
ilink_device_ticketstring绑定ticket, 厂商在快速对接场景下可以通过该ticket关联微信用户与自有用户. 其他绑定场景不一定有该字段, 请勿使用

返回值:

  1. {
  2. "errcode":0,
  3. "errmsg":"xxx",
  4. }

设备解绑

解绑设备流程

设备通过小程序/APP解绑流程

(回调厂商)设备解绑回调

接口说明:

当用户在微信硬件页解绑设备或小程序管理端解绑设备时,厂商可以在解绑回调时进行自己的绑定管理和权限校验.

请注意该接口的可用性, 如果回调失败, 解绑流程也将失败

请求参数:

  1. {
  2. "topic": "/ilink/sys/wechat_iot/$product_id/$ilink_im_sdk_id/unbind",
  3. "payload": {
  4. "binder_type": 1,
  5. "binder_info":{
  6. "ilink_iot_user_id": "xxx"
  7. },
  8. "device_info":{
  9. "ilink_im_sdk_id": "xxx"
  10. }
  11. }
  12. }
属性类型必填说明
binder_typeint绑定者类型. 0=普通绑定者, 1=管理员
ilink_iot_user_idstring微信硬件平台分配的绑定者身份标识
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识

返回值:

  1. {
  2. "errcode":0,
  3. "errmsg":"xxx",
  4. }

设备重置

重置设备流程

厂商后台在进行自有的重置逻辑时, 也应调用微信硬件平台的设备重置, 确保两边都重置了设备, 都清理了相关数据

重置设备接口

接口说明:

重置设备,清空设备的绑定数据, 状态, 属性等各类数据。ilink_im_sdk_id不作废

请求地址:

  1. POST https://api.weixin.qq.com/ilink/api/reset_device?access_token=xxx

请求参数:

  1. {
  2. "ilink_im_sdk_id": "xxxx@ilink.im.sdk",
  3. }
属性类型说明
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识

返回值:

  1. {
  2. "errcode": 0,
  3. "errmsg": ""
  4. }

回调接口说明

厂商对请求的验证

流程1:厂商在微信硬件平台配置回调地址callback_url、签名材料token

流程2:当回调接收服务收到请求时,计算签名,并与请求签名比对

微信硬件平台请求的url为:

  1. POST http://$callback_url?signature=xxx&timestamp=xxx&nonce=xxx

验签算法为

  1. 将token、timestamp、nonce三个参数进行字典序排序

  2. 将三个参数字符串拼接成一个字符串进行sha1加密

  3. 开发者获得加密后的字符串可与signature对比,标识该请求来源于微信

  1. private function checkSignature()
  2. {
  3. $signature = $_GET["signature"];//示例: b14e347e5ad26180d5fdb60cef903b0211349a7a
  4. $timestamp = $_GET["timestamp"];//示例: 1609434061
  5. $nonce = $_GET["nonce"];//示例: 123456
  6. $token = TOKEN;
  7. $tmpArr = array($token, $timestamp, $nonce);
  8. sort($tmpArr, SORT_STRING);
  9. $tmpStr = implode( $tmpArr );
  10. $tmpStr = sha1( $tmpStr );
  11. if( $tmpStr == $signature ){
  12. return true;
  13. }else{
  14. return false;
  15. }
  16. }

回调接口格式说明

回调接口请求包采用如下格式

  1. {
  2. "topic": "/ilink/sys/...",
  3. "payload": {
  4. ...
  5. }
  6. }
属性类型说明
topicstring请求topic
payloadobject请求体

返回值

  1. {
  2. "errcode": 0,
  3. "errmsg": "",
  4. }

回调中返回的错误码

错误码含义
0调用成功
-50001服务内部错误
-50002参数错误
-50003权限错误
-50004签名校验错误
-50005设备离线
-50100其他错误

建议在errmsg中附带错误原因, 请求的唯一id等信息, 方便追踪问题.

常见错误码

微信API常见错误码

错误码含义
0调用成功
-1服务内部错误
-2参数错误
-20009请求包反序列化错误, 通常是字段类型填错, 如数字填成了字符串
-40005云接口appid无权限, 请检查access_token对应的appid是否和官网注册appid一致
-40060测试sn数量达到上限

物模型介绍

物模型概述

物模型是一种描述产品功能的模型, 它描述了设备具有哪些功能, 具备哪些属性.

物模型将产品功能分为: 属性,服务

属性: 设备的运行状态. 如当前温度, 或者某个开关的开启关闭

服务: 设备能对外提供的功能.

事件: 设备产生的事件. 如摄像头有人经过, 运动产生步数等

服务与属性的差别: 一个功能可能不适合描述成状态改变, 比如钟表启用时间校准功能, 或者对话机器人翻译一段话. 或者这个功能需要复杂的参数, 比如打印机打印文件时需要发送文件内容和复杂的打印配置. 此时这个功能适合描述为一个服务. 但类似"开门","开灯"这种状态的改变更适合设置为属性.

物模型定义

下文给出一个伪代码来描述一个物模型.

  • 属性采用类的成员变量表示

  • 服务采用类的成员函数, 以及相应的Request, Response表示

  • 事件采用一个特定的的成员函数ReportEvent(XxxEvent), 以及一个XxxEvent定义表示

  1. //pid为1000的物模型定义
  2. class ThingModel_Pid_1000{
  3. //属性定义
  4. @Spec(name="温度",//属性名称
  5. access_mode="rw",//属性读写类型:只读(r)或读写(rw)
  6. min=16,//最小值
  7. max=30,//最大值
  8. unit="℃",//单位
  9. step=1//步长
  10. )
  11. int temperature;
  12. @Spec(name="状态列表", access_mode="rw",
  13. max_size=128//最大数组长度, array类特有
  14. )
  15. int[] status_list;
  16. @Spec(name="位置",access_mode="rw")
  17. Location location;
  18. //服务定义, 设置模式
  19. SetModelResp SetModel(SetModelReq req);
  20. //事件定义, 上报故障事件
  21. void ReportEvent(FaultEvent event);
  22. }
  23. //结构体定义
  24. class Location{
  25. @Spec(name="经度",min=-180,max=180,unit="°",step=0.01)
  26. double longitude;
  27. @Spec(name="纬度",min=-180,max=180,unit="°",step=0.01)
  28. double latitude;
  29. @Spec(name="高度",min=0,max=9999,unit="m",step=0.01)
  30. double altitude;
  31. }
  32. //服务的reqeust和response定义
  33. class SetModelReq{
  34. @Spec(name="模式")
  35. String model;
  36. }
  37. class SetModelResp{
  38. @Spec(name="是否成功")
  39. bool succ;
  40. }
  41. //事件定义
  42. @Spec(event_type=error)//事件类型分为error,alert,info
  43. class FaultEvent{
  44. string fault_type;
  45. long fault_time;
  46. }

调用格式

以上文的物模型为例, 设置属性时, 会将物模型中的属性转化为json请求的properties字段回调厂商. 具体实例如下:

<!--```json

{

"topic": "/ilink/sys/wechat_iot/$product_id/$ilink_im_sdk_id/set_device_property",

"payload":{

"ilink_im_sdk_id": "xxxx@ilink.im.sdk",

"properties": [{

"temperature": 26,

}

"location": {

"longitude": 10.0,

"latitude": 10.0,

"altitude": 10.0

}]

}

}

}

-->

  1. {
  2. "topic": "/ilink/sys/wechat_iot/$product_id/$ilink_im_sdk_id/set_device_property",
  3. "payload": {
  4. "ilink_im_sdk_id": "xxxx@ilink.im.sdk",
  5. "properties":
  6. [
  7. {
  8. "property_identifier": "temperature",
  9. "value": 26
  10. },
  11. {
  12. "property_identifier": "WxStdSwitch.switch_on",
  13. "value": true
  14. },
  15. {
  16. "property_identifier": "location",
  17. "value": {
  18. "longitude": 10.0,
  19. "latitude": 10.0,
  20. "altitude": 10.0
  21. }
  22. }
  23. ]
  24. }
  25. }

调用服务时, 会将服务的参数对象转化为params字段. 具体实例如下:

  1. {
  2. "topic": "/ilink/sys/wechat_iot/$product_id/$ilink_im_sdk_id/invoke_device_service",
  3. "payload":{
  4. "ilink_im_sdk_id": "xxxx@ilink.im.sdk",
  5. "service_identifier": "SetModel",
  6. "params": {
  7. "mode": "cooling"
  8. }
  9. }
  10. }

属性上报也类似. 详见后文物模型管理中的 设置设备属性, 调用设备服务, 上报设备属性

标准物模型

概念介绍

本节介绍了微信标准的物模型. 如果厂商接入了标准的物模型, 可以获得微信的一些快捷能力.

标准物模型类似于编程语言中的"接口", 厂商物模型可以实现多个标准物模型

标准物模型: 开关

接入后可获得"设备页"的开关按钮能力. 开关通常指设备本身的开启和关闭. 类似电子锁的"开锁/关锁", 电子闸门的"开闸/关闸"不属于开关.

  1. class WxStdSwitch{
  2. @Spec(name="开关",access_mode="rw")
  3. bool switch_on;
  4. }

标准物模型: 健康设备

  1. class WxStdHealthDevice{
  2. void ReportEvent(DailySummaryEvent event);
  3. void ReportEvent(SportsEvent event);
  4. }
  5. @Spec(event_type=info)
  6. class DailySummaryEvent{
  7. @Spec(name="今日步数")
  8. int today_step;
  9. @Spec(name="今日卡路里")
  10. int today_calorie;
  11. @Spec(name="上报时间")
  12. int report_timestamp;
  13. }
  14. @Spec(event_type=info)
  15. class SportsEvent{
  16. @Spec(name="运动类型")
  17. int sports_type;
  18. @Spec(name="运动距离", unit="米")
  19. int distance;
  20. @Spec(name="运动个数")
  21. int number;
  22. @Spec(name="运动开始时间戳")
  23. int start_timestamp;
  24. @Spec(name="运动结束时间戳")
  25. int end_timestamp;
  26. @Spec(name="卡路里")
  27. int calorie;
  28. @Spec(name="平均心率")
  29. int average_heart_rate;
  30. }

标准物模型: 发送消息到设备

接入后可获得长按微信消息->打开->发送到设备的能力

  1. class WxStdSendMsg{
  2. WxStdSendFileResp WxStdSendFile( WxStdSendFileReq req );
  3. WxStdSendPoiResp WxStdSendPoi( WxStdSendPoiReq req );
  4. }
  5. class WxStdSendFileReq{
  6. @Spec(name="文件类型")
  7. String type;//如"pdf","docx"
  8. @Spec(name="文件名")
  9. String name;//如"文件.pdf"
  10. @Spec(name="下载链接")
  11. String download_url;//下载的内容经过加密, 需要厂商解密
  12. @Spec(name="加密算法")
  13. String encrypt_algo;//目前仅支持AEAD_AES_256_GCM
  14. @Spec(name="秘钥base64")
  15. String key_base64;
  16. @Spec(name="iv base64")
  17. String iv_base64;//解密的初始向量
  18. @Spec(name="tag base64")
  19. String tag_base64;
  20. }
  21. class WxStdSendFileResp{
  22. }
  23. class WxStdSendPoiReq{
  24. @Spec(name="纬度")
  25. double latitude ;
  26. @Spec(name="经度")
  27. double longitude ;
  28. double scale;
  29. @Spec(name="地点标签")
  30. String label;// xx省xx市xx区xx路xx号
  31. @Spec(name="地点名称")
  32. String name;// xxx动物园
  33. }
  34. class WxStdSendPoiResp{
  35. }

出于安全性考虑, download_url下载的内容经过了加密, 算法为AEAD_AES_256_GCM. 厂家需要通过请求中的key_base64,iv,tag_base64等作为参数, 将下载内容解密得到明文. 目前大部分编程语言都支持了AEAD_AES_256_GCM算法

标准物模型参数格式

一个标准物模型的属性,服务或事件名, 有可能和自定义物模型或其他标准物模型重复. 因此在物模管理中的设置设备属性, 调用设备服务, 上报设备属性 等接口传参时会带一个前缀, 具体格式如下:

参数名参数格式举例
属性property_identifier{标准物模型}.{属性名}
服务service_identifier{标准物模型}.{服务名}
事件event_identifier{标准物模型}.{事件名}

物模型管理

物模型管理流程说明

上报设备状态

接口说明:
设备主动向后台上报状态, 状态是一些通用的设备信息, 没有在物模型中显式定义. 如上线,下线等

请求地址:

  1. POST https://api.weixin.qq.com/ilink/api/report_device_status?access_token=xxx

请求参数:

  1. {
  2. "ilink_im_sdk_id": "xxxx@ilink.im.sdk",
  3. "status": "online"
  4. }
属性类型说明
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识
statusstring设备状态, 有online,offline

返回值:

  1. {
  2. "errcode": 0,
  3. "errmsg": ""
  4. }

上报设备属性(需接入物模型)

接口说明:

设备向后台上报属性

请求地址:

  1. POST https://api.weixin.qq.com/ilink/api/report_device_property?access_token=xxx

请求参数:

  1. {
  2. "ilink_im_sdk_id": "xxxx@ilink.im.sdk",
  3. "properties": [
  4. {
  5. "property_identifier": "temperature",
  6. "value": 26
  7. },
  8. {
  9. "property_identifier": "mode",
  10. "value": "cooling"
  11. }
  12. ]
  13. }
属性类型说明
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识
propertiesarray要上报的属性列表。属性在物模型中定义过,或者是引用的标准物模型中的属性

返回值:

  1. {
  2. errcode: 0,
  3. errmsg: "",
  4. }

(回调厂商)设置设备属性(需接入物模型)

接口说明:
设置设备属性. 厂商异步下发给设备即可.
请求参数:

  1. {
  2. "topic": "/ilink/sys/wechat_iot/$product_id/$ilink_im_sdk_id/set_device_property",
  3. "payload":{
  4. "ilink_im_sdk_id": "xxxx@ilink.im.sdk",
  5. "properties": [
  6. {
  7. "property_identifier": "temperature",
  8. "value": 26
  9. },
  10. {
  11. // 引用的标准物模型WxStdSwitch中的属性switch_on
  12. "property_identifier": "WxStdSwitch.switch_on",
  13. "value": true
  14. },
  15. {
  16. "property_identifier": "location",
  17. "value": {
  18. "longitude": 10.0,
  19. "latitude": 10.0,
  20. "altitude": 10.0
  21. }
  22. }
  23. ]
  24. }
  25. }
属性类型说明
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识
propertiesarray要设置的属性列表。属性在物模型中定义过,或者是引用的标准物模型中的属性

返回值:

  1. {
  2. "errcode":0,
  3. "errmsg":"xxx",
  4. }
属性类型说明
errcodenumber返回码,0为成功
errmsgstring错误信息

(回调厂商)调用设备服务 (需接入物模型)

接口说明:
调用设备服务. 厂商异步下发给设备即可.

调用物模型自定义的服务custom_service时,"service_identifier"的值为"custom_service"
调用物模型引用的标准物模型WxStdXXX的服务WxStdYYY时,"service_identifier"的值为"WxStdXXX.WxStdYYY"
请求参数:

  1. {
  2. "topic": "/ilink/sys/wechat_iot/$product_id/$ilink_im_sdk_id/invoke_device_service",
  3. "payload":{
  4. "ilink_im_sdk_id": "xxxx@ilink.im.sdk",
  5. "service_identifier": "服务标识符",
  6. "params": {
  7. "temperature": 26,
  8. "mode": "cooling"
  9. },
  10. "ilink_trace_id": "XXXXXX",
  11. }
  12. }
属性类型说明
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识
service_identifierstring服务标识符, 在物模型中, 或被引用的标准物模型中定义过
paramsobject服务的参数. 在物模型中定义过
ilink_trace_idstring一个用来追踪请求调用的id, 设备完成服务后可以回传该id给微信,作为这次服务调用的响应

返回值:

  1. {
  2. "errcode":0,
  3. "errmsg":"xxx",
  4. }
属性类型说明
errcodenumber返回码,0为成功
errmsgstring错误信息

响应服务调用(需接入物模型, 可选)

接口说明:

设备完成服务调用的操作后, 将响应发给微信. 当某些服务在控制端需要知道调用结果时, 可调用此接口上报设备调用结果.

请求地址:

  1. POST https://api.weixin.qq.com/ilink/api/reply_device_service?access_token=xxx

请求参数:

  1. {
  2. "ilink_trace_id": "一段字符串",
  3. "ilink_im_sdk_id": "xxxx@ilink.im.sdk",
  4. "errcode": 0,
  5. "errmsg": "",
  6. "output": {
  7. "temperature": 26,
  8. "mode": "cooling"
  9. }
  10. }
属性类型说明
ilink_trace_idstring调用设备服务时的traceid
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识
errcodeint调用设备服务的错误码
errmsgstring调用设备服务的错误信息
outputobject设置设备属性的结果

返回值:

  1. {
  2. "errcode": 0,
  3. "errmsg": "",
  4. }

上报设备事件(需接入物模型)

接口说明:

设备向后台上报事件,一天之内, 同个request_event_id只能上报一次, 重复上报则微信不再上报, 直接返回成功

请求地址:

  1. POST https://api.weixin.qq.com/ilink/api/report_device_event?access_token=xxx

请求参数:

  1. {
  2. "ilink_im_sdk_id": "xxxx@ilink.im.sdk",
  3. "event_identifier": "事件标识符", //如WxStdHealthDevice.SportsEvent
  4. "params": {
  5. "temperature": 26,
  6. "mode": "cooling"
  7. },
  8. "request_event_id": "request_event_id"
  9. }
属性类型说明
ilink_im_sdk_idstring微信硬件平台分配的设备唯一标识
event_identifierstring事件标识符, 在物模型中, 或被引用的标准物模型中定义过
paramsobject事件的参数. 在物模型中, 或被引用的标准物模型中定义过
request_event_idstring上报事件请求的标识串. 长度小于等于64,由ascii可见字符组成

返回值:

  1. {
  2. "errcode":0,
  3. "errmsg":"xxx",
  4. }
属性类型说明
errcodenumber返回码,0为成功
errmsgstring错误信息

1. 概述

微信硬件平台为硬件设备提供了连接微信用户的能力和身份。接入微信硬件平台的设备,可添加至用户的设备页中,微信用户可以在设备列表里查看和控制设备。

2. 微信运动

运动类设备,如运动手表、运动手环等,接入微信硬件平台后,用户可通过设备向微信传入运动数据,运动数据将在微信运动排行榜页、个人详情页及微信设备页进行展示,并显示数据来源。

3. 发送消息到设备

硬件设备接入微信硬件平台后,可接入发送消息到设备能力,用户在聊天界面中长按特殊类型的消息,可通过“打开”入口向设备发送此消息。目前已支持向硬件设备发送文件、图片类消息,详见开发文档。

1. 注册厂商信息

厂商首次接入时,需在首页中点击注册,填写厂商账号的信息并进行注册,此部分信息一经注册,不可修改。等待微信硬件平台审核通过,即可使用此账号登录,进行设备产品的注册。

2. 注册产品信息

填写产品基本信息

产品名称将在微信客户端设备页等页面内展示给用户,厂商需注意尽量使用简短的产品名称,不得包含与硬件无关的内容。注意,此部分产品信息一经注册,无法修改。

填写产品开发信息

首次注册产品时,需要填写回调地址与云端数据通讯APPID(此APPID用于访问微信硬件平台云接口,由微信公众平台或开放平台分配,可以使用厂商公众号、小程序、移动应用所分配的APPID其中之一;此APPID与回调地址在注册之后,可以在账号信息中进行修改)。

云快速接入方式支持厂商小程序或APP发起添加和解绑设备的流程。

若选择无自有小程序,则需要填写发起添加绑定的APP所对应的移动应用appid(微信开放平台注册并分配)。

若选择自有小程序接入,需填写对应的发起添加绑定的小程序所对应的appid(微信公众平台注册并分配)及跳转路径,绑定设备后,在微信客户端的设备页点击设备,可跳转至厂商小程序此路径的页面,进行设备相关的控制(跳转会携带设备参数,详见开发者文档)。

选择产品能力信息

根据设备类型及开发信息,选择接入的产品能力,功能介绍详见添加产品页面。

3. 申请设备上线

产品信息审核通过之后,厂商需先完成设备功能的开发和功能自测,之后可根据pid寄送测试样机至微信硬件平台,提交设备上线申请,微信测试验收通过后,厂商即可上线功能与设备。