概述

微信硬件ID及微信硬件平台为硬件设备提供了身份注册和管理的能力，其目标是使微信用户能够方便快捷的连接, 控制物联网设备.

本方案提供的厂商快速接入微信硬件平台的流程是:

1. 厂商和微信硬件平台对接，厂商后台增加云端对接接口

   • 通过网站注册自己产品设备的微信硬件ID及硬件物模型
   • 厂商后台预注册自己的设备sn列表

2. 厂商小程序/APP/设备端改造，提供绑定至微信设备的路径

3. 从小程序/APP或使用其他方式发起绑定流程

4. 微信后台绑定设备和微信用户.

5. 用户通过微信客户端/小程序对设备进行控制，实现其他功能

部分名词解释

• 微信硬件平台： 微信硬件平台是微信内部承接物联网生态的底层平台，通过平台内的硬件ID实现微信与IOT设备的信息互联与设备控制

• product_id: 微信硬件平台对具体某个厂商制造的某款设备产品的标识

• SN： 厂商后台为设备生成的可对外的全局唯一设备标识, product_id范围内唯一

• ilink_im_sdk_id： 设备在微信硬件平台的唯一标识，即微信硬件ID

• ilink_device_ticket： 设备绑定临时身份凭证，五分钟有效期

• ilink_iot_user_id: 设备绑定者在微信硬件平台的身份标识

• 首次绑定: 指设备在没有绑定者时被绑定, 此时用户会成为设备管理员

物模型介绍

物模型概述

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

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

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

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

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

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

物模型定义

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

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

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

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

//pid为1000的物模型定义
class ThingModel_Pid_1000{

    //属性定义
    @Spec(name="温度",//属性名称
    access_mode="rw",//属性读写类型：只读（r）或读写（rw）
        min=16,//最小值
        max=30,//最大值
        unit="℃",//单位
        step=1//步长
    )
    int temperature; 

    @Spec(name="状态列表", access_mode="rw",
    max_size=128//最大数组长度, array类特有
    )
    int[] status_list;

    @Spec(name="位置",access_mode="rw")
    Location location;

    //服务定义, 设置模式
    SetModelResp SetModel(SetModelReq req);

    //事件定义, 上报故障事件
    void ReportEvent(FaultEvent event);
}

//结构体定义
class Location{
    @Spec(name="经度",min=-180,max=180,unit="°",step=0.01)
    double longitude;

    @Spec(name="纬度",min=-180,max=180,unit="°",step=0.01)
    double latitude;

    @Spec(name="高度",min=0,max=9999,unit="m",step=0.01)
    double altitude;
}

//服务的reqeust和response定义
class SetModelReq{
    @Spec(name="模式") 
    String model;
}

class SetModelResp{
    @Spec(name="是否成功") 
    bool succ;
}

//事件定义
@Spec(event_type=error)//事件类型分为error,alert,info
class FaultEvent{
string fault_type;
long fault_time;
}

调用格式

后台调用

是常规的调用方式, 指厂商通过微信的云接口, 云回调等进行物模型交互, 详见后文物模型管理 等接口

小程序调用

少数场景下, 厂商需要通过小程序处理物模型调用.

当前场景:

• 发送消息到设备时拉起厂商小程序（目前只支持公共多人绑定模式下，可拉起小程序）

厂商小程序获取微信传参示例

小程序里可通过wx.getEnterOptionsSync()获取微信传过来的参数（具体示例如下所示），一般在页面的onLoad方法中调用；其中可以验证场景值scene是1226，具体参数在iot字段

注意payload里的params字段是json字符串，需要再次parse成json对象来使用.

以发送文件WxStdSendMsg.WxStdSendFile为例

                           

                            
{
                            
    "path":"pages/device-discovery/device-discovery",
                            
    "query":{
                            

                            
    },
                            
    "scene":1226,
                            
    "referrerlnfo":{
                            

                            
    },
                            
    "mode":"default",
                            
    "apiCategory":"default",
                            
    "iot":{
                            
        "nonce":"3972126057",
                            
        "timestamp":"1656590248",
                            
        "signature":"e0fb1e92f5d44829379f466760ae407db683b937a54e2cadf6e69b5e1ed42195",
                            
        "params":{
                            
            "topic":"ilink/sys/wechatiot/3947/AAYAABPZmWJWW2aRAdkg-rwuVQYCzHpueK22r7DxclY@ilinkimsdk/invoke_device_service",
                            
            "payload":{
                            
                "ilink_im_sdk_id":"AAYAABPZmWJWW2aRAdkg-nwuVQYCzHpueK22r7DxclY@ilink.im.sdk",
                            
                "params":"{\"tag_base64\":\"Jsk4UJcSy9zLFVBx2qXFaQ==\",\"keybase64\":\"2rZwgqsKWAMuRdXG8DXeSGCgCNIn76NQsiSfPbEgbe0=\",\"type\":\"pdf\",\"download_url\":\"http://wxapp.tc.qq.com/272/20303/stodownload?m=b1dedad05de9ffc85f205e44224c9f02&flekey=30350201010421301f020201100402535a0410b1dedad05de9ffc85f205e44224c9f0202030390f2040d00000004627466730000000131&hy=SZ&storeid=32303232303633303139353732373030306439313566626536333466653536623631383830393030303030313130&bizid=1023\",\"ivbase64\":\"R+lGduezQMPvr4ZU\",\"encrypt_algo\":\"AEAD_AES_256_GCM\",\"name\":\"微信硬件发送文件测试case(1).pdf\"}",
                            
                "ilink_trace_id":"9952813327A8401E16B53FO18A1A5CCB",
                            
                "service_identifer":"WxStdSendMsg WxStdSendFile"
                            
            }
                            
        },
                            
        "signature_algo":"HMAC-SHA256"
                            
    }
                            
}
                           

其中的params即为物模型调用参数.

微信小程序参数的通用格式

即上文中的iot字段

                           

                            
{
                            
"params": "...",
                            
"timestamp": "12345",
                            
"nonce": "12345",
                            
"signature": "9d8ed9a3e985d2255807680ce8d450bd06fbde14",
                            
"signature_algo": "HMAC-SHA256"
                            
}
                           

对参数验签

为了防止不安全的客户端拉起小程序页面, 厂商可以在后台对参数进一步验签.

验签步骤为:

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

2. 将三个参数字符串拼接成一个字符串input

3. 计算签名, 签名=HMAC_SHA256( key=回调token, message=input )

4. 验证该签名与微信参数中的signature是否一致. 若一致则说明该请求由微信服务端发起