设备型项目

创建物影子

物模型

创建物模型

通过物模型可以为设备定义一套属性模板,在创建物影子时可以引用该模板,实现业务的快速部署。具体操作方法如下:

  1. 登录百度智能云官网,点击右上角的“管理控制台”,快速进入控制台界面,选择“产品服务 > 物联网服务 > 物接入 IoT Hub”,选择 “进入项目列表”。
  2. 选择“创建项目”,输入项目名称、选择项目类型为「设备型」。
  3. 返回项目列表,点击刚才创建的项目名称,接入项目详情页。选择“物模型”,进入物模型卡片列表;点击“新建物模型”进入物模型配置界面。
  4. 填写物模型配置,包括名称、描述和属性。创建成功后物模型名称和属性名称无法修改,同一物模型下属性名称必须唯一。
    点击“添加属性”为物模型新增一条属性。

    完成属性配置后,点击“创建”,完成物模型创建。

管理物模型

创建物模型以后,可以对以下信息进行编辑修改,包括:

  • 物模型描述信息
  • 删除或新增属性
  • 属性描述、默认值、单位

具体修改方法如下:

  1. 选择“产品服务>物联网服务>物接入 IoT Hub”,进入“天工物联网”控制台。
  2. 点击设备型项目的项目名称,选择“物模型”,进入物模型卡片列表。
  3. 选择需要修改的物模型卡片,以物模型示例为例,点击卡片进入详情页面。
    image.png
  4. 点击“编辑”进入编辑模式,此时可对物模型进行属性编辑等操作。完成操作后点击“保存”使配置生效。
    image.png

物影子

创建物影子

在创建物影子之前,必须先创建物模型

  1. 选择“产品服务>物联网服务>物接入 IoT Hub”,进入“天工物联网”控制台。
  2. 点击设备型项目的项目名称,选择“物影子”,进入物影子卡片列表;点击“新建物影子”进入物模型配置界面。
    image.png
  3. 填写物模型配置,包括名称、描述、选择物模型和是否开启存储配置。数据存储TSDB

点击“创建”完成物影子创建。

查看影子详情

查看设备当前状态

在影子详情界面,用户可以看到以下信息

  • 模型数据,通过图表展示物模型定义的所有属性,如下图所示:
    物影子的列表页展示模型数据,在关联模型中存在的字段才展示在该页。如果用户reported了不在该物详情中的属性,通过“原始数据”查看。

通过查看“当前值”字段,可以获取设备各属性的实时数据信息。相关字段解释如下:

  • 当前值,指设备最后一次上报的该属性的值。如果没有上报则为空。
  • 修改时间,指设备最后一次更新该属性的值。
  • 期望值,指通过控制台或者应用程序性修改的desired值。如果没有。期望值则为空。
  • 发送时间,指该属性最后一次有desired值修改的时间
  • 原始数据,即设备影子的原始数据,用户可以通过原始数据查看设备状态或远程控制设备,如下图所示:

设备影子介绍

用户可通过设备影子查看实体设备的属性和状态等信息,如设备id、设备名称等。

设备影子是一个json文档,如下例所示:

"device": {

            "reported": {

                "light": "green"

            },

            "desired": {

                "light": "red"

            },

            "profileVersion": 10,

            "lastUpdatedTime": {

                "reported": {

                    "light": 1530016776000

                },

                "desired": {

                    "light": 1530516776000

                }

            }

}

“device”中的属性需要同步到设备实体。其中,“reported”表示设备端通过MQTT连接汇报到影子的设备状态。“desired”表示控制端希望控制设备变换到的目标状态。

远程控制属性

  1. 点击“编辑物影子”,编辑属性的期望值。
  2. 点击“提交”后,物影子将期望值下发至设备端。

用户也可以通过编辑原始数据desired中的属性实现设备的远程控制。

获取连接配置

创建物影子后,系统将自动生成与该物影子对应的连接配置,包括endpoint项目地址、设备名称和密钥信息。该信息将可用于将实体设备连接至物影子。具体操作如下:

  1. 进入物详情界面。
  2. 点击“连接配置”。

注意:点击“更新密钥”后,原有密钥将失效,会导致已经接入的设备断开连接。

物影子操作

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

说明

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

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

使用Baidu IoT Edge SDK

用户可以在设备端安装百度智能云提供的SDK,并配置连接信息,实现设备与百度智能云物接入的快速对接。

有关IoT Edge SDK的下载和安装,请查看:https://github.com/baidu/iot-edge-sdk-for-iot-parser/releases/tag/v1.0.1

使用开源MQTT客户端SDK

如果设备端已经调用了Paho(即MQTT Client SDK),可以通过与特定的topic通信实现与百度智能云的对接。在物接入中定义了系统topic用于物接入服务和设备端基于物接入服务以及MQTT协议进行通信。

其中,clientID填写物影子名称。

更新设备状态到设备影子

将信息推送到主题'$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
    }
}

权限管理

介绍

在物接入中设置权限管理,可以使得一个客户端的连接配置具有访问多个设备的能力。

物接入设备型权限分为普通权限超级权限

  • 普通权限:由用户自行选择添加物影子,上限100个。
  • 超级权限:默认包含用户名下所有的物影子。

如图所示:

  1. 给客户端1新建权限1,权限1内包括物影子1、2、3、4;
  2. 权限1的用户名与密钥可以向物影子1、2、3、4的topic发送消息;
  3. 根据权限1起一个连接就可以向物影子1、2、3、4对应的设备通信。

注意:
1.用户通过服务端连接物影子,订阅所有/部分设备的物影子变化状态,可以用一个mqtt客户端订阅,不需要启用n个客户端。
2.网关设备连接n个子设备,需要有一个MQTT客户端可以对网关和子设备都有访问权限,如更新shadow/获取delta等。设置权限管理后,则可避免一个网关启用n个连接来更新n个子设备的物影子。
3.一个设备最多允许属于10个权限组。

创建权限

  1. 选择“产品服务>物联网服务>物接入 IoT Hub”,进入“天工物联网”控制台。
  2. 点击设备型项目的项目名称进入详情页,选择“权限组”,接下来进行权限管理设置。
  3. 点击“创建权限“,填写基本信息,分别为名称和描述。
  4. 选择物影子,支持多选,目前上限100个。
  5. 点击“确定”,完成权限设置,并生成配置信息。
  6. 点击权限名称,进入权限管理列表。
    • 可以编辑权限描述;
    • 点击“连接配置”,可以查看配置信息。
    • 点击“修改影子”,可以重新添加物影子。

创建超级权限

  1. 选择“产品服务>物联网服务>物接入 IoT Hub”,进入“天工物联网”控制台。
  2. 点击设备型项目的项目名称进入详情页,选择“权限组”,接下来进行权限管理设置。
  3. 点击“创建超级权限“。

  1. 超级权限具有访问所有设备的权限,请妥善保管好用户名和秘钥,谨慎使用。
    • 超级权限不支持权限内物影子的增加和减少。
    • 在创建超级权限后,新创建的影子会被默认添加到超级权限内。
  2. 点击权限名称,进入权限管理列表,可以编辑权限描述;点击“连接配置”,可以查看配置信息。

设备在线状态

注意:
使用IoT Edge SDK,当使用SDK向云端发送过一次数据后,物影子即标志为『在线』。如果设备由于网络原因或自身关机等原因断开连接,物影子即显示离线,可以通过API获取。
使用MQTT开源SDK,如果使用MQTT开源SDK,请将MQTT客户端的clientid设置为物影子名称,物接入则可以监测在线和离线状态。

  1. 在物影子列表中,我们可以看到物影子设备初始默认处于离线状态
  2. 使用IoT Edge SDK,当使用SDK向云端发送过一次数据后,物影子即标志为『在线』。如果设备由于网络原因或自身关机等原因断开连接,物影子即显示离线,可以通过API获取。
  3. 使用MQTT开源SDK,如果使用MQTT开源SDK,请将MQTT客户端的clientid设置为物影子名称,物接入则可以监测在线和离线状态。

设备间相互通信

设备可以通过更新物影子来上传当前状态,在有些场景下,设备还需要相互通信。物接入默认给每个设备绑定有主题**$baidu/iot/general/#**的订阅和发布权限。

例如,设备A发布消息到主题$baidu/iot/general/a,设备B订阅主题$baidu/iot/general/a,则设备B就能收到设备A的消息。

OTA 服务

介绍

百度智能云天工OTA服务平台是致力为物联网智能设备系统安全保驾护航的固件升级服务。我们为广大设备厂商提供稳定、快速、易用、高效的固件下发服务,以保证在洞察到设备系统安全隐患后能迅速响应,降低潜在损失。

除常规的下发服务外,物接入OTA服务将逐步整合百度自主研发,业内领先的智能设备硬件安全检测与修复能力,为所覆盖的智能设备群打造安全护城河,是设备厂商最佳的智能设备系统升级和漏洞安全修复解决方案。

云端OTA操作

1. 账号体系

物接入OTA作为百度智能云天工物接入产品的功能,沿用百度账号体系,如何注册和登录详见物接入产品文档。

2. 使用前准备

在创建物模型时需要选择是否开启OTA远程升级,只有开启服务后,该物模型下面的设备才可以进行固件升级。在创建时未开启服务的物模型,也可以在物模型编辑页面开启服务。

开启OTA远程升级服务后,用户需要选择下发协议。

  • HTTPS协议:目前只有Android和Linux操作系统的设备才可以选择https。

注意: 设备的操作系统和芯片类型,这两个字段在填写后将无法修改,请慎重填写。

  • 对于Linux操作系统的设备,您可以提工单把交叉编译的环境和参数给我们,我们将针对您的设备编译相应的SDK,详情请查看跨平台OTA SDK接入文档
    • 对于Android和Linux操作系统的设备的升级任务,在设备端我们提供刷写固件、重启等功能。选择了https协议之后,您还需要填写设备的操作系统和芯片类型。
      :BLANK_LINE:* MQTT协议:对所有操作系统的设备都适用。设备可直接集成SDK,具体的SDK配置方法请阅读设备SDK集成指南

3. 上传升级包

OTA升级服务的入口在物设备型项目详情页中,左侧选择 OTA,主界面如下图所示:

具体操作方法如下:

a. 登录百度智能云官网,点击右上角的“管理控制台”,快速进入控制台界面。

b. 选择“产品服务>物联网服务>物接入 IoT Hub”,进入“天工物联网”控制台。

c. 点击设备型项目的项目名称,选择选择“OTA远程升级”,进入OTA页面;点击“添加升级包”进入添加升级包页面。

按照要求填写升级包创建信息,各字段的填写规则如下表:

字段 填写方式 说明 备注
物模型 下拉框 / 必填
选择升级包 选择文件 文件大小不超过50M 必选
版本号 填空 为了便于管理,版本号有严格的形式,只能以x.x.x的形式命名 必填
版本描述 下拉框 可填写128字以内的版本备注 选填

完成填写后,点击“确定”即可上传升级包。

上传成功后能在升级包列表页看到新创建的升级包。点击版本号可以查看升级包详情。点击物模型会跳到物模型详情页。点击“升级”可以用该升级包创建升级任务。

在升级包的详情页可以看到该升级包上传的时间、已用该升级包创建的升级任务等信息。点击具体的任务可以跳转到任务详情页。

4. 创建升级任务

在升级包列表页或者升级任务页均可以创建升级任务,进入任务信息填写:

字段 填写方式 说明 备注
任务名称 填空 3-32位字符,支持中英文和数字 必填
物模型 下拉框 选择升级哪个物模型下的设备 必选
版本号 下拉框 选择升级包的版本号 必填
任务描述 填空 128个字符以内 可选
设备筛选 单选框 全量下发、版本号筛选和上传升级设备列表三种。
全量下发:升级该物模型下的所有设备;
版本号筛选:可以选择特定版本号的设备进行升级,支持多选;
上传升级设备列表:用户可上传一个 .txt 文件,文件中罗列需要升级的设备的ID
必选

完成填写后,点击“确定”完成创建。

5. 追踪升级任务进度

在升级任务详情页可以追踪任务进度,可以看到升级耗时、升级设备总数、升级成功数和升级失败数。在设备信息栏有每台设备的任务进度。

设备端使用MQTT OTA

MQTT OTA的功能

  • 云端向设备推送固件升级信息,包括固件包的URL
  • 设备向云端上报固件升级的结果

用户需要适配自己的设备,实现固件刷写、重启等功能。

通过BAIDU IoT EDGE SDK使用MQTT OTA

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

用户可以在设备端安装百度智能云提供的SDK,并配置连接信息,实现设备与百度智能云物接入的快速对接。

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

通过MQTT客户端使用MQTT OTA

有些情况下,设备<—>云的交互需要立刻返回某种结果,或者立刻给予确认。比如设备向云查询最新的固件版本、云请求设备端开始固件升级。

除了用shadow做交互,物接入还使用了一种直接的Method调用。Method调用代表着一种请求–响应式的交互,与HTTP调用很类似。它支持设备->云和云->设备这两种请求方向。

Method的MQTT主题

设备请求物接入(cloud method)

$baidu/iot/shadow/{deviceName}/method/cloud/req // 设备向该主题发布请求,物接入订阅

$baidu/iot/shadow/{deviceName}/method/cloud/resp // 物接入向该主题发布响应,设备订阅

物接入请求设备(device method)

$baidu/iot/shadow/{deviceName}/method/device/req // 物接入向该主题发布请求,设备订阅

$baidu/iot/shadow/{deviceName}/method/device/resp // 设备向该主题发布响应,物接入订阅

作为设备端,在建立MQTT连接后,应当即刻订阅上面物接入向该主题发布响应,设备订阅物接入向该主题发布请求,设备订阅 这2个主题。

METHOD 的MQTT载荷

载荷是以Json序列化的字符串。请求和响应的格式分别如下:

请求参数

参数名称 参数类型 是否必须 说明
methodName String 必选 Method名字
requestId String 必选 请求ID
payload Object 可选 Method的参数

请求示例

{
     "methodName": "updateFirmware",
     "requestId": "993ff7e9-018b-4246-a7ba-5dddac970054",
     "payload": {
     "someField": "someOutput"
     }
}

响应参数

参数名称 参数类型 是否必须 说明
methodName String 必选 Method名字
requestId String 必选 请求ID
status int 必选 状态码,200-299表示正常
payload Object 可选 Method的结果

响应示例

{
     "methodName": "updateFirmware",
     "requestId": "993ff7e9-018b-4246-a7ba-5dddac970054",
     "status": 200,
     "payload": {
     "someField": "someOutput"
     }
}

设备与物接入交互过程简介

上报设备版本(REPORTCURRENTFIRMWAREINFO)

通过物接入OTA进行过固件升级的设备,物接入知晓它的固件版本。而对于那些从未升级过的设备,应当至少使用它一次,以让物接入知晓它的版本。

请求示例

pub $baidu/iot/shadow/{deviceName}/method/cloud/req

{
    "requestId": "12345",
    "methodName": "reportCurrentFirmwareInfo",
    "payload": {
        "firmwareVersion": "1.1.1"
    }
}

返回如下结果:

rcv $baidu/iot/shadow/{deviceName}/method/cloud/resp
{
    "requestId": "12345",
    "methodName": "reportCurrentFirmwareInfo",
    "status": 204,
}

请求参数

参数名称 参数类型 是否必须 说明
firmwareVersion String 必选 当前版本

返回参数

上报设备OTA开始事件(REPORTFIRMWAREUPDATESTART)

在真正开始固件刷写之前,设备应当向物接入汇报固件升级开始,作为整个固件升级流程跟踪的一部分。

请求示例

pub $baidu/iot/shadow/{deviceName}/method/cloud/req
{
    "requestId": "12345",
    "methodName": "reportFirmwareUpdateStart",
    "payload": {
        "jobId": "9476da26-8cf3-497d-9959-c2017a248901"
    }
}

返回示例

recv $baidu/iot/shadow/{deviceName}/method/cloud/resp
{
    "requestId": "12345",
    "methodName": "reportFirmwareUpdateStart",
    "status": 204
}

请求参数

参数名称 参数类型 是否必须 说明
jobId String 必选 任务ID

上报设备OTA结果(REPORTFIRMWAREUPDATERESULT)

在固件升级完成之后,设备向物接入汇报升级结果。Result字段可以是”success”表示成功,或者“failure”表示失败。

请求示例

pub $baidu/iot/shadow/{deviceName}/method/cloud/req
{
    "requestId": "12345",
    "methodName": "reportFirmwareUpdateResult",
    "payload": {
        "result": "success",
        "jobId": "9476da26-8cf3-497d-9959-c2017a248901"
    }

}

返回示例

recv $baidu/iot/shadow/{deviceName}/method/cloud/resp
{
    "requestId": "12345",
    "methodName": "reportFirmwareUpdateResult",
    "status": 204
}

请求参数

参数名称 参数类型 是否必须 说明
jobId String 必选 任务ID
firmwareUrl String 必选 名称
firmwareVersion String 必选 描述

跨平台OTA SDK(HTTPS)接入

跨平台 OTA 特指控制台中 HTTPS 方式所支持的 Android、Linux 系统 OTA。

术语介绍

OTA完整包:OTA包中包含了目标版本中所有文件的完整内容

OTA差分包:OTA包使用差分算法生成,其中对于目标版本和源版本中有变化的同一文件,差分包中只包含该文件的差分patch文件(.p文件)

说明:
1、特殊情况下差分包中不存在.p文件,此时表示目标版本和源版本中没有相同文件(同名、同路径)

2、完整包中只包含目标版本信息,差分包中包含源版本和目标版本信息,只有原版本与当前系统版本相同时才能执行升级

文件分段:将单个大文件按照一定的大小切分成多个小文件的过程,切分成的小文件称为分段文件

说明:
1、当待升级设备上剩余空间很小,不允许存放过大的完整升级文件时,可对大文件分段,然后依此升级每个分段文件
2、升级包制作时,对文件分段后,生成的每个分段文件对于整个升级包来说是一个独立文件,执行分片操作后,每个分段文件会单独生成一个分片OTA升级包

OTA升级包分片:使用ota生成工具的div命令,将完整OTA升级包切分成若干个分片OTA升级包的过程

完整的OTA升级包:OTA升级包中包含了本次升级中的所有升级文件及元信息

说明:
1、完整的OTA升级包是以.bdota为后缀的升级文件
2、完整的OTA升级包可以是“OTA完整包”也可以是“OTA差分包”
3、完整的OTA升级包中的升级文件可以分段,也可以不分段

分片OTA升级包:完整OTA包经过OTA升级包分片操作后生成,一个分片OTA升级包中只包含一个文件

说明:分片OTA升级包中包含的文件可以是单个完整文件,也可以是单个差分文件(.p文件),也可以是一个分段文件

OTA包结构

注意: 以下OTA包结构图均为示意图,其中不包括文件的元信息和整个OTA包的头部信息。

OTA升级包分片操作过程,及其前后的OTA升级包结构示意图如下:

OTA SDK接入流程

  1. 获取SDK的方式
    对于Android和Linux操作系统的设备的升级任务,在设备端我们提供刷写固件、重启等功能。相关SDK目前还未开源。您需要提工单把交叉编译的环境和参数给我们,我们将针对您的设备编译相应的SDK。
  2. 在物接入中创建物模型
    如下图所示,在物模型的创建页面选择下发协议为https协议,并填写好操作系统、芯片类型和相关的属性,点击“创建”即可创建物模型。
    图片
    在物模型的详情页可以得到“OTA ID”和“OTA Secret”,如下图所示:
    图片
    OTA ID是当前项目的唯一标识,在 ota_set_query_paramstr API中对应 QUERY_PARAM_PID 字段
    OTA Secret是用于SDK对数据加密的密钥,在 ota_set_query_paramstr API中对应 QUERY_PARAM_SECRET 字段
  3. 代码中接入SDK API
    根据实际需求,依此调用相应API,网络升级调用流程如下:
    图片

OTA SDK接口说明

include/bdota 目录下的头文件包含的接口均可使用,其中,与升级任务相关的SDK接口定义于 include/bdota/bdota.h 头文件,其中主要接口介绍如下:

ota_global_set_temp_path

  • 函数定义
    int ota_global_set_temp_path(const char* path);
  • 功能
    设置临时目录,该目录内容重启后可能丢失,被用作存储会被删除的临时文件。

ota_global_set_persistent_path

  • 函数定义
    int ota_global_set_persistent_path(const char* path);
  • 功能
    设置持久性目录,改目录内容重启后不会丢失,被用作存储预下载升级包、上报缓存文件等。

ota_create_update_manager

  • 函数定义
    pota_update_manager ota_create_update_manager();
  • 功能
    创建更新管理器对象指针pota_update_manager,该指针用于后续系列函数的调用。

ota_register_event_func

  • 函数定义
int ota_register_event_func (
        pota_update_manager manger, 
        const char* event_name,  // 事件名称
        func_event_callback event_func,  // 事件发生时的回调函数
        void* user_data  // 透传给event_func的参数
   );
  • 功能

    为更新管理器设置回调函数

  • 参数说明

    manger : 更新管理器对象;

    event_name : 事件名称,详细说明请参见func_event_callback回调事件部分;

    event_func : 注册的事件被触发时,该回调函数会被调用;

    user_data : 用户自定义数据,该参数会作为参数透传给event_func回调函数;

  • 返回值说明

    返回0表示成功,非0表示失败。

func_event_callback

  • 函数定义
typedef int(*func_event_callback)(
    void* user_data, // 透传参数,注册回调时指定的参数
    pbdstring* params, // 事件的参数列表指针
    size_t size, // 事件参数的个数
    pbdstring* out); // 传出参数
);
  • 功能

ota_register_event_func函数中的回调函数接口定义

  • 参数说明

user_data : 用户自定义数据,即ota_register_event_func函数调用时的user_data参数,会通过该参数透传回来;

params : 事件的参数内容,不同事件类型对应不同类型的参数内容;

size : 事件的参数内容的数量;

out : 传出参数,预留位,传null即可;

  • 返回值说明

返回OTAR_OK升级继续,其它将终止升级

  • 回调事件

支持的事件名称使用宏定义,已定义的事件宏包括:

\#define OTA\_UPDATE\_EVENT\_START "start"
\#define OTA\_UPDATE\_EVENT\_END "end"
\#define OTA\_UPDATE\_EVENT\_PROCESS\_FILE "process\_file"
\#define OTA\_UPDATE\_EVENT\_DELETE\_FILE "delete\_file"
\#define OTA\_UPDATE\_EVENT\_GET\_LOCAL\_FILE\_PATH "get\_local\_file\_path"
\#define OTA\_UPDATE\_EVENT\_SHOW\_PROGRESS "show\_progress"

不同回调事件,对应的回调函数参数含义不同,具体各事件对应的参数含义说明如下:

事件名称 事件含义 触发时机 params参数含义 out参数含义
OTA_UPDATE_EVENT_START 升级开始 SDK解析升级包,第一次遇到全局头时将调用该函数,如果没有注册,则不调用
OTA_UPDATE_EVENT_END 升级结束 升级包的全部文件都已经处理完毕后调用,业务放可以在该回调中修改写入设备的启动信息。例如对于AB系统,则要在该回调中完成切换启动主分区的操作 参数一: “0”:使用的是分段升级,当前段处理完成,但还有后续段需要处理。“1”:升级包中的所有文件已经处理完成。
OTA_UPDATE_EVENT_PROCESS_FILE 处理文件 解析升级包时,当一个文件已经在本地准备好时(该文件可能来之网络、本地升级包、本地分片升级包)调用 参数一:升级包中指定的当前文件的路径。参数二:偏移,当前文件内容在原始文件中的偏移。参数三:文件内容在本地硬盘上的路径,如果启用了分段功能,该内容可能为原始文件的一部分。参数四:当前文件内容大小。参数五:总文件大小。
OTA_UPDATE_EVENT_DELETE_FILE 删除文件或文件夹 当需要删除文件或文件夹时,调用该函数 参数一:升级包中指定的待删除的文件路径。参数二:路径标识的是文件还是目录,文件用字符串0表示,目录用字符串1表示。
OTA_UPDATE_EVENT_GET_LOCAL_FILE_PATH 返回本地文件系统中对应与升级包中的文件的全路径 升级过程中任何需要获取本地路径完整路径的时候均可能回调次函数 参数一:升级包中的文件路径 本地系统中的完整文件路径
OTA_UPDATE_EVENT_SHOW_PROGRESS 显示进度 当前版本暂未触发该事件,为后续版本保留

ota_set_query_paramstr

  • 函数定义

int ota_set_query_paramstr(pota_update_manager manager, const char* key, const char* value);

  • 功能

设置升级请求参数

  • 参数说明

manger : 更新管理器对象;

key:升级请求字段名称;

value:升级请求字段内容。

  • 返回值说明

    返回0表示成功,非0表示失败。

  • 已支持字段

    #define QUERY_PARAM_PID "pid" // 产品ID
    #define QUERY_PARAM_SECRET "acckey" // 产品密钥 
    #define QUERY_PARAM_DID "did" // 设备唯一标识符
    #define QUERY_PARAM_VER "ver" // 系统版本号,格式必须为a.b.c.d
    #define QUERY_PARAM_MANUAL_CHECK "mchk" // 请求类型, value设置字符串1表示手动升级,其它为自动升级
    

ota_query_update_info

  • 函数定义

int ota_query_update_info(pota_update_manager manager);

  • 功能

执行升级请求

  • 参数说明

manger : 更新管理器对象;

  • 返回值说明

返回0表示成功,非0表示失败。

ota_download_update_pkg

  • 函数定义

int ota_download_update_pkg(pota_update_manager manager);

  • 功能

执行预下载,此函数需要在ota_query_update_info函数调用以后被调用

  • 参数说明

manger : 更新管理器对象;

  • 返回值说明

返回0表示成功,非0表示失败。

ota_set_update_param

  • 函数定义

int ota_set_update_param(pota_update_manager manager, const char* key, const char* value);

  • 功能

设置更新程序参数

  • 参数说明

manger : 更新管理器对象;

key:参数字段名称;

value:参数字段内容。

  • 返回值说明

返回0表示成功,非0表示失败。

  • 已支持字段

    // 设置了该key,将执行本地升级,该key的value指明了本地包的文件路径
      #define OTA_UPDATE_PARAM_KEY_LOCAL_FILE "local_file"
    // 指定本地分段升级时当前处理的分片文件路径
      #define OTA_UPDATE_PARAM_KEY_SEG_FILE "seg_file"
    // 设置用于校验升级包的公钥路径
     #define OTA_UPDATE_PARAM_KEY_PUBLIC_KEY_PATH "pk"
    // 指定本地升级信息存取的文件,如果指定从本地查询升级,则读取该文件
    // 如果指定从网络查询升级,则存在升级时保存升级信息到该文件
     #define OTA_UPDATE_PARAM_KEY_LOCAL_UPDATE_INFO_PATH "localupdate_info_path"
    // 设置服务地址,一般不用使用
    #define OTA_UPDATE_PARAM_KEY_SERVICE_URL "service_url"
    // 指示升级请求是从服务器问询或者是从本地文件读取
    #define OTA_UPDATE_PARAM_KEY_SERVER_TYPE "server_type"
    // 升级请求从文件中读取,文件路径通过ota_set_update_param设置
    #define OTA_UPDATE_PARAM_KEY_SERVER_TYPE_LOCAL "local"
    // 升级请求从网络读取,服务器地址通过ota_set_update_param设置
    #define OTA_UPDATE_PARAM_KEY_SERVER_TYPE_LOCAL "net"
    

ota_do_udpate

  • 函数定义

int ota_do_udpate(pota_update_manager manager, uint32_t flag);

  • 功能

执行实际升级功能,调用此函数前需要调用ota_set_update_param函数设置更新参数

  • 参数说明

manger : 更新管理器对象;

  • 返回值说明

返回0表示成功,非0表示失败。

ota_release_update_manager

  • 函数定义

int ota_release_update_manager(pota_update_manager manager);

  • 功能

释放更新管理器对象

  • 参数说明

manger : 更新管理器对象;

  • 返回值说明

返回0表示成功,非0表示失败。

OTA SDK跨平台支持

OTA SDK v1.1

v1.1版本SDK支持Windows、Linux、Mac操作系统,其中依赖的第三方开源库包括:C标准库libcurlopenssl。如果目标平台无法使用上述开源库,则暂不支持使用v1.1版本OTA SDK

OTA SDK v2.x

v2.x版本SDK在v1.1版本基础上,为了能够适配只有C标准库的IOT设备,将使用 libcurlopenssl库的部分封装成的单独的静态库,并提供了默认的实现 platform_adapter_default.a,默认实现中使用了libcurlopenssl开源库。

  • SDK接入方法
    • 针对可以使用libcurl和openssl的设备:直接链接otasdk.alibcurl.alibssl.alibcrypto.aplatform_adapter_default.a文件即可使用。
    • 针对无法使用libcurl和openssl的设备:需要接入方根据 include\bdota\adapter 目录中的头文件ota_cipher.hota_http_stream.h文件定义的接口实现一个静态库,然后与otasdk.a一起静态链接即可。

OTA SDK示例程序

程序名称

otaupdate_explain

功能

本示例程序用于测试和体验SDK,其中使用一系列命令行参数,实现对OTA SDK中主要接口的调用。

参数介绍

用法:otaupdate_explain COMMAND [args] 
COMMAND: 
   net-update 通过网络进行升级
   write 通过本地升级文件升级

net-update命令:
   -pid  指定product ID 
   -key  用于指定验证升级包的公钥文件路径
   -pidpass  base64编码的密钥,用于连接升级服务器
   -ver  [可选] 指定当前系统版本号,默认为0.0.0.0 
   -did  [可选] 指定设备唯一id,默认为“bdtestdev” 
   -temp  [可选] 设置临时目录
   -persistent  [可选] 设置持久性目录 
   -predownload [可选] 指定使用预下载功能 
   -url  [可选] 设置升级服务器url
   -reporturl  [可选] 设置上报服务器url 
write命令: 
   用法:otaupdate_explain write -key  firstsegfile [segfile] 
   参数介绍:
   -key  <key_path> 用于指定验证升级包的公钥文件路径
   firstsegfile    如果使用本地分片OTA升级包升级:此参数为第一个分片升级包路径
                   如果使用本地完整包升级,此参数为完整包路径
   segfile         如果使用本地分片OTA升级包升级:此参数为需要升级的分片升级包路径
                   如果使用本地完整包升级,不传入此参数</key_path>

常用功能示例

  • 网络正式环境升级
    otaupdate_explain net-update -pid -key -pidpass

  • 网络测试环境升级
    otaupdate_explain net-update -pid -key -pidpass -url -reporturl

  • 使用预下载功能升级
    otaupdate_explain net-update -pid -key -pidpass -persistent -predownload

    示例程序中使用预下载文件升级时,会在查询完成后预下载完整升级包到指定的持久性目录下predownload.bdota文件,然后使用该文件进行升级,若不指定persistent参数,则下载到当前目录

  • 使用本地完整包升级
    otaupdate_explain write -key

  • 使用本地分片升级包升级

    升级包分片后所有分片OTA升级包路径表示为:seg_1 ~ seg_N ,i 从2至N,循环调用以下命令:
    otaupdate_explain write -key seg_1 seg_i

制作升级包工具

命令行参数说明

ota_gen \<PARAM...> [OPTION...]
COMMAND (选择一个):
 gen (*default)  // 根据目录生成ota包
 div             // 根据ota升级包,切分成片段升级包

gen命令支持参数:

-t, --target  <path>
      对于完整包:表示准备生成ota包的目标目录
      对于差分包:表示新版本所在目录
 -o, --output <path>
      设置输出ota包的文件路径
 -d, --desc <path> [可选]
      设置信息描述文件路径
 -i, --incremental_from <path>
      指定进行差分升级,path表示进行差分升级时旧版本所在目录
 -s, --segment <size> 设置分段升级中要求的最大文件大小
      支持k/K/m/M为单位的参数
 -k, --key <path> [可选]
      设置数字签名私钥路径</path></size></path></path></path></path>

div命令支持参数:

-t, --target  <path>
      设置ota包路径
 -o, --output <path>
      设置存储分片OTA包目录</path></path>

其他参数:

-c, --compress
      对ota包中数据进行压缩
 -h, --help 
      显示帮助信息

主要功能

本命令行工具包括两个主要功能:生成OTA升级包和OTA升级包分片

  • 生成OTA升级包:可以生成完整升级包和差分升级包两类OTA升级包。生成OTA包时,可通过参数控制以下特性:文件分段、数据压缩。

  • OTA升级包分片:将完整升级包按照其中包含的文件(单个完整文件、分段后的分段文件、差分文件),切分成若干个分片OTA升级包。

常用功能示例

  • 生成完整OTA升级包

    ota_pkg_gen gen -t <target_path> -o <output_path> -d <desc_path> -k <public_key_path>

  • 生成完整OTA升级包,对数据压缩,并对文件按照1M大小分段

    ota_pkg_gen gen -t <target_path> -o <output_path> -d <desc_path> -k <public_key_path> -c -s 1M

  • 生成差分包

    ota_pkg_gen gen -t <target_path> -o <output_path> -d <desc_path> -k <public_key_path> -i <old_ver_path>

  • OTA包切分成分片升级包

    ota_pkg_gen div -t <ota_pkg_path> -o <output_dir_path>

数据存储 TSDB

开启存储配置

物接入设备型,支持将数据存储到时序数据库TSDB。可以在创建物影子时,开启存储配置。同时,也可以在物详情获取连接配置中,开启与关闭存储配置。

开启存储配置:

  • 可修改存储配置,选择不存储,上报即存储和上报满足条件存储三种方式。
  • 可将数据存储到时序数据库中(TSDB),即需要选择相应的TSDB实例。
  • 配置生效后,物影子会在收到更新时,将更新的数据按配置条件写入时序数据库,这里需要保证时序数据库无欠费等异常情况。

存储TSDB格式

TSDB中表示每个数据点的格式如下:

TSDB实例 metric timestamp value tag1
(显示名称)
tag2
(物影子名称)
tag3
(物模型名称)
需提前创建 属性名
如temperature
属性的更新时间
如1499071119722
该属性本次更新值 “desc”=“温度” “deviceName”=“pump” “schemaName”=“template_pump”

物影子数据存储TSDB方式有两种:多域存储、单域存储。

  • 多域存储:将物影子的所有属性存入同一个度量(Metric)的多个域(Field)中,一个属性作为一个域,需要填写度量名称。
  • 单域存储:将物影子的每个属性单独存入一个度量中,作为一个域,属性名称即度量名称。

详细可参考TSDB产品介绍

物影子数据可视化

天工物可视作为可视化开发工具,无缝对接物管理数据,可以通过物可视将物管理设备数据可视化。物可视具体介绍可参考物可视产品介绍

进入物可视服务,选择新建仪表盘

image.png

进入仪表盘后,选择数据表

图片

新建数据表

图片

选择物管理作为数据源

图片

选择想要展示的属性,点击确认,就会为物可视仪表盘生成物管理数据源

图片

回到设计器页面,选取需要展示的组件,将数据配置改为之前增加的物管理数据表,即可完成物管理设备数据可视化,更多详情可参考物可视介绍

图片