设备影子应用场景示例

本文以扫地机器人实际业务为例，说明设备、设备影子以及应用程序之间的通信，结合设备影子的通讯方式，看如何应用业务中。

设备影子Topic

场景一：机器人所处网络不稳定，但设置必须最终达到。如：电池失效处理

为增强安全性需要增加鉴权，服务对服务的请求均走【HTTP开放接口】对接，设备影子服务再按照设备影子的协议转发该消息，原理相同。鉴权方法如下0. 创建应用与应用鉴权。

1. 【设备】发起获取设备影子最新状态

设备发送主动获取设备影子消息到Topic：/${productId}/${deviceId}/shadow/update ，发送的消息格式：

{
    "method":"get",
    "messageId":"157065985"
}

messageId一定由请求发起方生成，设备影子服务会透传这个参数，用于保证单次请求的唯一性。

2. 【设备影子服务】查询设备影子最新状态

设备影子服务接收到请求并验证请求格式通过后，查询最新的设备影子文档

3. 【设备影子服务】下发设备影子最新状态

设备影子服务发送设备影子最新状态到Topic: /${productId}/${deviceId}/shadow/get ，发送的消息格式：

{
    "method":"reply",
    "messageId":"157065985",
    "payload":{
        "code":0,
        "state":{

        },
        "metadata":{

        }
    },
    "timestamp":0
}

此时由于是设备第一次请求，期望值desired、当前值reported均为空。这一步请求是为了获取设备影子当前版本（version）和文档更新时间，用于上报影子最新状态。

4. 【设备】上报电池失效状态、电池SN

设备完成前置实现后，上报所有当前状态到 Topic：/${productId}/${deviceId}/shadow/update。发送的JSON消息格式：

{
    "method":"update",
    "messageId":"157889065985",
    "state":{
        "reported":{
            "CurrentBatteryFailure":"False",
            "BatterySN":"1234567A"
        }
    },
    "timestamp":0
}

• 这一步以仅电池失效状态、电池SN接入设备影子为例，若有多个业务多个业务参数应当在设备离线重联后上报所有业务参数至设备影子；同理在设备影子服务下发设备最新状态时，也会将所有业务参数返回。
• 传递的timestamp为设备影子下发的当前更新时间，设备影子服务在收到更新请求后。先进行判断是否等于设备影子最新时间戳，不等于则判断是否大于等于该上报字段的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行保存。

5. 【设备影子服务】更新设备当前状态至设备影子文档

设备影子收到更新请求后，进行验证更新，更新通过后更新云端的设备影子文档如下：

{
    "state":{
        "desired":{
        },
        "reported":{
            "CurrentBatteryFailure":"False",
            "BatterySN":"1234567A"
         }
    },
    "metadata":{
        "desired":{
        },
        "reported":{
            "CurrentBatteryFailure":{
                "timestamp":1678017660000
            },
            "BatterySN":{
                "timestamp":1678017660000
            }
        }
    },
    "timestamp":1678017660000
}

这一步假定在【2023-03-05 20:01:00 - (Unix时间戳: 1678017660000)】设备影子服务收到并验证更新完成文档

6. 【电池管理平台】发起获取设备影子最新状态

当电池管理平台的操作人员发现问题要设置电池失效时，发送主动获取设备影子消息到Topic：/${productId}/${deviceId}/shadow/update ，发送的消息格式：

{
    "method":"get",
    "messageId":"157065985123123"
}

7. 【设备影子服务】查询设备影子最新状态

设备影子服务接收到请求并验证请求格式通过后，查询最新的设备影子文档

8. 【设备影子服务】下发设备影子最新状态

设备影子服务发送设备影子最新状态到Topic: /${productId}/${deviceId}/shadow/get ，发送的消息格式：

{
    "method":"reply",
    "messageId":"157065985123123",
    "payload":{
        "code":0,
        "state":{
            "desired":{

            },
            "reported":{
                "CurrentBatteryFailure":"False",
                "BatterySN":"1234567A"
            }
        },
        "metadata":{
            "desired":{

            }
        },
        "reported":{
            "CurrentBatteryFailure":{
                "timestamp":1678017660000
            },
            "BatterySN":{
                "timestamp":1678017660000
            }
        }
    },
    "timestamp":1678017660000
}

• 广播设备影子的最新状态和最新更新时间，用于更新期望值时传递。
• metadate内数据标识当前状态的更新时间

9. 【电池管理平台】设置设备电池失效期望值、电池SN期望值

电池管理平台通过HTTP开放接口更新期望状态，设备影子服务使用Topic: /${productId}/${deviceId}/shadow/update 上报期望值。发送JSON消息格式如下：

{
    "method":"update",
    "messageId":"157889065984",
    "state":{
        "desired":{
            "CurrentBatteryFailure":"True",
            "BatterySN":"1234567A"
        }
    },
    "timestamp":1678017660000
}

• 此时是第二次请求，需要重新生成messageId
• 电池SN参数原样返回，用于实现”机器人匹配指令SN与当前SN是否一致，如果一致则5分钟后设定电池失效“的业务逻辑

10. 【设备影子服务】保存至设备期望状态

设备影子接到应用上报的期望值数据，校验格式并通过后更新云端的设备影子文

{
    "state":{
        "desired":{
            "CurrentBatteryFailure":"True",
            "BatterySN":"1234567A"
        },
        "reported":{
            "CurrentBatteryFailure":"False",
            "BatterySN":"1234567A"
        }
    },
    "metadata":{
        "desired":{
            "CurrentBatteryFailure":{
                "timestamp":1678017720000
            },
            "BatterySN":{
                "timestamp":1678017720000
            }
        },
        "reported":{
            "CurrentBatteryFailure":{
                "timestamp":1678017660000
            },
            "BatterySN":{
                "timestamp":1678017660000
            }
        }
    },
    "timestamp":1678017720000
}

假定校验通过时间为【2023-03-05 20:02:00 - (Unix时间戳: 1678017720000)】此时metadate·dsired·CurrentBatteryFailure/BatterSN、timestamp·version的时间戳均更新为1678017720000

11. 【设备影子服务】下发电池失效状态、电池SN期望

设备影子收到更新请求后，进行验证更新，通过后结果发送到Topic：/${productId}/${deviceId}/shadow/get。发送内容格式为：

{
    "method":"control",
    "messageId":"157889065984",
    "payload":{
        "code":0,
        "state":{
            "desired":{
                "CurrentBatteryFailure":"True",
                "BatterySN":"1234567A"
            }
        },
        "metadata":{
            "desired":{
                "CurrentBatteryFailure":{
                    "timestamp":1678017720000
                },
                "BatterySN":{
                    "timestamp":1678017720000
                }
            }
        }
    },
    "timestamp":1678017720000
}

设备影子在下发期望值时，会将全量期望值一起下发。

12. 【设备】根据业务要求，执行电池失效业务

机器人收到电池失效指令以后匹配指令SN与当前SN是否一致。

13. 【设备】上报电池失效状态及当前电池SN

本地业务处理完成后上报当前状态到 Topic：/${productId}/${deviceId}/shadow/update。发送的JSON消息格式：

{
    "method":"update",
    "messageId":"157889065986",
    "state":{
        "reported":{
            "CurrentBatteryFailure":"True",
            "BatterySN":"1234567A"
        }
    },
    "timestamp":1678017720000
}

• 目前业务逻辑是如果一致则延迟5分钟设定电池失效，不一致还要回复一个ACK给电池管理平台。但是实际没必要，因为如果不一致则上报的当前电池SN也足以让电池管理平台判断不一致。
• 此时仅需要上报部分业务数据即可。
• messageId由设备生成，timestamp为获取的当前影子更新时间。

14. 【设备影子服务】更新设备当前状态至设备影子文档

设备影子收到更新请求后，进行验证更新，更新通过后更新云端的设备影子文档如下：

{
    "state":{
        "reported":{
            "CurrentBatteryFailure":"True",
            "BatterySN":"1234567A"
        }
    },
    "metadata":{
        "desired":{
            "CurrentBatteryFailure":{
                "timestamp":1678017720000
            },
            "BatterySN":{
                "timestamp":1678017720000
            }
        },
        "reported":{
            "CurrentBatteryFailure":{
                "timestamp":1678017780000
            },
            "BatterySN":{
                "timestamp":1678017780000
            }
        }
    },
    "timestamp":1678017780000
}

假定验证通过时间为【2023-03-05 20:03:00 - (Unix时间戳:1678017780000)】此时metadate·reported·CurrentBatteryFailure/BatterSN、timestamp·version的时间戳均更新为1678017780000
设备影子服务在接受到设备上报值时，会去查找上报更新的值是否有期望值，如果有切期望值与上报值相等，则会移除该属性的期望值

15. 【设备影子服务】下发电池失效状态、电池SN更新

设备影子文档更新后，结果发送到Topic： /${productId}/${deviceId}/shadow/get。消息内容格式如下：

{
    "method":"update",
    "messageId":"157889065986",
    "payload":{
        "code":0,
        "state":{
            "reported":{
                "CurrentBatteryFailure":"True",
                "BatterySN":"1234567A"
            }
        },
        "metadata":{
            "reported":{
                "CurrentBatteryFailure":{
                    "timestamp":1678017780000
                },
                "BatterySN":{
                    "timestamp":1678017780000
                }
            }
        }
    },
    "timestamp":1678017780000
}

如果设备仅上报部分属性，设备影子服务针对本次请求，也应当仅下发这部分属性的当前值。

16. 【电池管理平台】生成电池失效记录

电池管理平台订阅 Topic：/${productId}/${deviceId}/shadow/get。感知到电池已成功失效和设备上报的当前电池SN，即可生产电池失效处理记录。

场景二：APP耗材管理