物接入IoT Hub

    物影子操作

    您可通过多种方式建立与物影子的连接。包括使用 Baidu IoT Edge SDK、标准 MQTT 客户端(如 Paho 项目)、HTTP Post(仅支持Pub)等。

    说明

    推荐用户优先使用百度智能云提供的SDK。

    百度智能云提供的SDK封装了MQTT客户端SDK,屏蔽了MQTT客户端SDK的细节和topic信息,可以帮助用户实现业务的快速部署。

    使用Baidu IoT SDK C

    用户可以在设备端集成天工提供的设备侧SDK,并配置连接信息,实现设备与物接入的快速对接。

    有关IoT SDK C 的下载和安装,请查看:https://github.com/baidu/iot-sdk-c

    使用开源MQTT客户端

    如果设备端已经集成了Paho或其他MQTT Client(如模组自带 MQTT 客户端),可以通过连接信息中的配置及特定的topic通信实现与百度智能云的对接。在物接入中定义了系统topic用于物接入服务和设备端基于物接入服务以及MQTT协议进行通信。

    其中,连接用户名密码可在并配置连接信息中查看,clientID填写物影子名称;连接后可使用如下 topic。

    更新设备状态到设备影子

    将信息推送到主题'$baidu/iot/shadow/{deviceName}/update',可实现将设备状态更新到设备影子。

    示例:

    pub $baidu/iot/shadow/myDeviceName/update
    {
        "requestId": "{requestId}",
        "reported": {
            "memoryFree": "32MB",
            "light": "green"
        },
        "desired": {
            "rotate": 100
        },
        "profileVersion": 5,
        "lastUpdatedTime": {
            "reported": {
                "light": 1494904250
            },
            "desired": {
                "rotate": 1494904250
            }
        }
    }
    • "requestId"为请求的唯一标识符,每一个请求的requestId是唯一的,可随机生成。
    • reported为可选字段,代表物影子中设备上报的最新状态。服务端能通过MQTT或HTTP从reported字段中拿到物影子的最新状态。
    • desired为可选字段,代表控制端期望设备变换到的目标状态。设备端通过MQTT从desired字段中拿到某个属性的期望值(如”light”:”red"),就收到了控制端期望执行的操作,硬件即可执行相关操作。硬件执行相关操作后,应该把对应的值上报到reported字段上。用户可以通过判断repoeted与desired的差别来判断是否反控成功。
    • “profileVersion”为可选字段,当未指定profileVersion时,物接入接收设备影子更新请求后,会将profileVersion自动加1;若指定profileVersion,物接入会检查请求中的profileVersion是否大于当前的profileVersion。只有在大于的情况,物接入才会接受设备端的请求,更新设备影子,并将profileVersion更新到相应的版本。
    • "lastUpdatedTime"为可选字段,"lastUpdatedTime.reported"和"lastUpdatedTime.desired"中的时间表示属性("reported"和"desired")的更新时间,如果没有相应字段,则更新时间由系统时间决定。注意只有当相应位置的属性键值对存在于本次请求中,且请求更新时间为非负整数(毫秒为单位),相应的时间更新有效,无效的更新时间会被替换为系统时间。此外,若本次请求中属性的更新时间早于系统中该属性已存储的更新时间,则该属性的本次更新时间判断为过时,不予更新。

    更新设备影子适用于两种应用场景:

    1. 设备同步状态到物接入服务。设备在状态发生变化时,将实时的状态同步到物接入服务,包括状态的自动变化以及设备反控后状态的变化。更新设备状态,通常更新"reported"字段中的相关属性。对于反控后更新状态,设备可以用实时状态同时更新该属性的“reported”和“desired”中的值。
    2. 通过MQTT协议反控设备状态。如果需要通过MQTT协议反控设备属性,可以通过更新"desired"字段实现。当物影子接收到"desired"相关属性的更新后,会diff设备影子中"reported"和“desired”相关字段,将diff后的结果发送到delta主题。设备端通过订阅delta主题,可将设备状态同步到“desired”的状态。状态反控后,更新设备影子,使"reported"和"desired"的值一致。物影子对设备的反控请参考通过设备影子控制设备状态。

    订阅主题获取设备影子更新成功后的结果:

    sub $baidu/iot/shadow/myDeviceName/update/accepted
    {
        "requestId": "{requestId}",
        "reported": {
            "firewareVersion": "1.0.0",
            "light": "green"
        },
        "desired": {
            "light": "red"
        },
        "lastUpdatedTime": {
            "reported": {
                "firewareVersion": 1494904250,
                "light": 1494904250
            },
            "desired": {
                "light": 1494904250
            }
        },
        "profileVersion": 10
    }

    订阅主题获取设备影子更新失败后的结果:

    sub $baidu/iot/shadow/myDeviceName/update/rejected
    {
        "requestId": "{requestId}",
        "code": "{errorCode}",
        "message": "{errorMessage}"
    }

    从设备影子获取设备状态

    发送请求到主题'$baidu/iot/shadow/{deviceName}/get',可以获取该设备在设备影子中的所有状态信息。

    示例:

    pub $baidu/iot/shadow/myDeviceName/get
    {
    	"requestId": "{requestId}"
    }

    订阅主题获取设备影子:

    sub $baidu/iot/shadow/myDeviceName/get/accepted
    {
        "requestId": "{requestId}",
        "reported": {
            "firewareVersion": "1.0.0",
            "light": "green"
        },
        "desired": {
            "light": "red"
        },
        "lastUpdatedTime": {
            "reported": {
                "firewareVersion": 1494904250,
                "light": 1494904250
            },
            "desired": {
                "light": 1494904250
            }
        },
        "profileVersion": 10
    }

    同时,可以订阅获取设备影子失败的相关消息:

    sub $baidu/iot/shadow/myDeviceName/get/rejected
    {
        "requestId": "{requestId}",
        "code": "{errorCode}",
        "message": "{errorMessage}"
    }

    通过设备影子控制设备状态

    控制端可以通过MQTT协议更新设备影子中的‘desired’字段,达到反控设备的目的。物影子在接受到‘desired’字段更新后,会比较'reported'和‘desired’之间的差异,并将diff结果发送到主题'$baidu/iot/shadow/{deviceName}/delta'。

    例如,当前‘reported’中的‘light’字段为green,控制端将'desired'中的'light'字段更新为'red',此时物影子会通过delta主题反控设备:

    sub $baidu/iot/shadow/myDeviceName/delta
    {
        "requestId": "{requestId}",
        "desired": {
            "light": "red"
        }
    }

    若设备更新状态失败,可将相关错误信息发送到物影子:

    pub $baidu/iot/shadow/myDeviceName/delta/rejected
     
    {
    	"requestId": "{requestId}",
    	"code": "{errorCode}",
    	"message": "{errorMessage}"
    }

    清空设备影子

    支持通过MQTT主题‘$baidu/iot/shadow/{deviceName}/delete’清空设备影子。

    示例:

    pub $baidu/iot/shadow/myDeviceName/delete
    {
    	"requestId": "{requestId}"
    }

    通过订阅‘$baidu/iot/shadow/{deviceName}/delete/accepted’可以获取设备影子清空成功后的response。

    sub $baidu/iot/shadow/myDeviceName/delete/accepted
    {
        "requestId": "{requestId}",
        "reported": {
            "firewareVersion": "1.0.0",
            "light": "green"
        },
        "desired": {
            "light": "red"
        },
        "lastUpdatedTime": {
            "reported": {
                "firewareVersion": 1494904250,
                "light": 1494904250
            },
            "desired": {
                "light": 1494904250
            }
        },
        "profileVersion": 10
    }

    主题'$baidu/iot/shadow/{deviceName}/delete/rejected'推送清空设备影子失败后的相关信息

    sub $baidu/iot/shadow/myDeviceName/delete/rejected
    {
        "requestId": "{requestId}",
        "code": "{errorCode}",
        "message": "{errorMessage}"
    }

    订阅设备影子的变化

    可以通过主题"$baidu/iot/shadow/{deviceName}/update/documents"订阅设备影子中reported字段内容的变化。物接入在收到设备影子的update请求、并成功更新后,如果reported字段内容有变(变化条件包括:增加属性、减少属性、属性值有变化),会把reported字段中更新属性的当前值和更新前的值发送到“documents”主题。

    示例:

    sub $baidu/iot/shadow/{deviceName}/update/documents
    {
        "requestId": "{requestId}",
        "profileVersion": 10,
        "current": {
            "light": "green"
        },
        "previous": {
            "light": "red"
        }
    }

    订阅设备快照

    documents topic只反映了reported字段内容中发生变化的属性状态,如在reported字段内容变化时,需要订阅设备的全量的属性状态,可以通过主题"$baidu/iot/shadow/{deviceName}/update/snapshot"获取。该主题内容会包括shadow的reported字段的全部属性,此外还包含相应的lastUpdatedTime、profileVersion字段内容。

    示例:

    sub $baidu/iot/shadow/{deviceName}/update/snapshot
    {
        "requestId": "{requestId}",
        "profileVersion": 10,
        "reported": {
            "light": "green"
        },
        "lastUpdatedTime": {
            "reported": {
                "light": 1494904250
            }
        }
    }

    Device Profile

    Device Profile由Device Registry和Device Shadow两部分组成。

    {
        "name": "test",  //设备名称
        "id": "098f6bcd4621d373cade4e832627b4f6",   //设备ID
        "description": "测试设备",              //设备描述
        "state": "online",                   //设备状态,online/offline/unknown
        "templateId": "123456",             //设备模板ID
        "templatedName": "TestTemplate",    //设备模板名称
        "createTime": 1494904250,         //创建时间
        "lastActiveTime": 149490300,    //最后一次设备影子(reported)更新时间
        "attributes": { 
            "region": "Shanghai"        //设备Tag
        },
        "device": {                    //设备影子
            "reported": {
                "firewareVersion": "1.0.0",
                "light": "green"
            },
            "desired": {
                "light": "red"
            },
            "lastUpdatedTime": {
                "reported": {
                    "firewareVersion": 1494904250,
                    "light": 1494904250
                },
                "desired": {
                    "light": 1494904250
                }
            },
            "profileVersion": 10
        }
    }
    上一篇
    创建物影子
    下一篇
    权限管理