github.com/jingruilea/kubeedge@v1.2.0-beta.0.0.20200410162146-4bb8902b3879/docs/modules/edge/devicetwin.md (about) 1 # DeviceTwin 2 3 4 ## Overview 5 6 DeviceTwin module is responsible for storing device status, dealing with device attributes, handling device twin operations, creating a membership 7 between the edge device and edge node, syncing device status to the cloud and syncing the device twin information between edge and cloud. 8 It also provides query interfaces for applications. Device twin consists of four sub modules (namely membership module, communication 9 module, device module and device twin module) to perform the responsibilities of device twin module. 10 11 12 ## Operations Performed By Device Twin Controller 13 14 The following are the functions performed by device twin controller :- 15 16 - Sync metadata to/from db ( Sqlite ) 17 - Register and Start Sub Modules 18 - Distribute message to Sub Modules 19 - Health Check 20 21 22 ### Sync Metadata to/from db ( Sqlite ) 23 24 For all devices managed by the edge node , the device twin performs the below operations :- 25 26 - It checks if the device in the device twin context (the list of devices are stored inside the device twin context), if not it adds a mutex to the context. 27 - Query device from database 28 - Query device attribute from database 29 - Query device twin from database 30 - Combine the device, device attribute and device twin data together into a single structure and stores it in the device twin context. 31 32 33 ### Register and Start Sub Modules 34 35 Registers the four device twin modules and starts them as separate go routines 36 37 38 ### Distribute Message To Sub Modules 39 40 1. Continuously listen for any device twin message in the beehive framework. 41 2. Send the received message to the communication module of device twin 42 3. Classify the message according to the message source, i.e. whether the message is from eventBus, edgeManager or edgeHub, 43 and fills the action module map of the module (ActionModuleMap is a map of action to module) 44 4. Send the message to the required device twin module 45 46 47 ### Health Check 48 49 The device twin controller periodically ( every 60 s ) sends ping messages to submodules. Each of the submodules updates the timestamp in a map for itself once it receives a ping. 50 The controller checks if the timestamp for a module is more than 2 minutes old and restarts the submodule if true. 51 52 53 ## Modules 54 55 DeviceTwin consists of four modules, namely :- 56 57 - Membership Module 58 - Twin Module 59 - Communication Module 60 - Device Module 61 62 ### Membership Module 63 64 The main responsibility of the membership module is to provide membership to the new devices added through the cloud to the edge node. 65 This module binds the newly added devices to the edge node and creates a membership between the edge node and the edge devices. 66 67 The major functions performed by this module are:- 68 69 1. Initialize action callback map which is a map[string]Callback that contains the callback functions that can be performed 70 2. Receive the messages sent to membership module 71 3. For each message the action message is read and the corresponding function is called 72 4. Receive heartbeat from the heartbeat channel and send a heartbeat to the controller 73 74 The following are the action callbacks which can be performed by the membership module :- 75 76 - dealMembershipGet 77 - dealMembershipUpdated 78 - dealMembershipDetail 79 80 **dealMembershipGet**: dealMembershipGet() gets the information about the devices associated with the particular edge node, from the cache. 81 - The eventbus first receives a message on its subscribed topic (membership-get topic). 82 - This message arrives at the devicetwin controller, which further sends the message to membership module. 83 - The membership module gets the devices associated with the edge node from the cache (context) and sends the information to the communication module. 84 It also handles errors that may arise while performing the aforementioned process and sends the error to the communication module instead of device details. 85 - The communication module sends the information to the eventbus component which further publishes the result on the 86 specified MQTT topic (get membership result topic). 87 88  89 90 91 **dealMembershipUpdated**: dealMembershipUpdated() updates the membership details of the node. 92 It adds the devices, that were newly added, to the edge group and removes the devices, that were removed, 93 from the edge group and updates device details, if they have been altered or updated. 94 - The edgehub module receives the membership update message from the cloud and forwards the message 95 to devicetwin controller which further forwards it to the membership module. 96 - The membership module adds devices that are newly added, removes devices that have been recently 97 deleted and also updates the devices that were already existing in the database as well as in the cache. 98 - After updating the details of the devices a message is sent to the communication module of the device twin, which sends the message to eventbus module to be published on the given MQTT topic. 99 100  101 102 103 **dealMembershipDetail**: dealMembershipDetail() provides the membership details of the edge node, providing information 104 about the devices associated with the edge node, after removing the membership details of 105 recently removed devices. 106 - The eventbus module receives the message that arrives on the subscribed topic,the message is then forwarded to the 107 devicetwin controller which further forwards it to the membership module. 108 - The membership module adds devices that are mentioned in the message, removes 109 devices that that are not present in the cache. 110 - After updating the details of the devices a message is sent to the communication module of the device twin. 111 112  113 114 115 ### Twin Module 116 117 The main responsibility of the twin module is to deal with all the device twin related operations. It can perform 118 operations like device twin update, device twin get and device twin sync-to-cloud. 119 120 The major functions performed by this module are:- 121 122 1. Initialize action callback map (which is a map of action(string) to the callback function that performs the requested action) 123 2. Receive the messages sent to twin module 124 3. For each message the action message is read and the corresponding function is called 125 4. Receive heartbeat from the heartbeat channel and send a heartbeat to the controller 126 127 The following are the action callbacks which can be performed by the twin module :- 128 129 - dealTwinUpdate 130 - dealTwinGet 131 - dealTwinSync 132 133 **dealTwinUpdate**: dealTwinUpdate() updates the device twin information for a particular device. 134 - The devicetwin update message can either be received by edgehub module from the cloud or from 135 the MQTT broker through the eventbus component (mapper will publish a message on the device twin update topic) . 136 - The message is then sent to the device twin controller from where it is sent to the device twin module. 137 - The twin module updates the twin value in the database and sends the update result message to the communication module. 138 - The communication module will in turn send the publish message to the MQTT broker through the eventbus. 139 140  141 142 143 **dealTwinGet**: dealTwinGet() provides the device twin information for a particular device. 144 - The eventbus component receives the message that arrives on the subscribed twin get topic and forwards the message to devicetwin controller, which further sends the message to twin module. 145 - The twin module gets the devicetwin related information for the particular device and sends it to the communication module, it also handles errors that arise when the device is not found or if any internal problem occurs. 146 - The communication module sends the information to the eventbus component, which publishes the result on the topic specified . 147 148  149 150 151 **dealTwinSync**: dealTwinSync() syncs the device twin information to the cloud. 152 - The eventbus module receives the message on the subscribed twin cloud sync topic . 153 - This message is then sent to the devicetwin controller from where it is sent to the twin module. 154 - The twin module then syncs the twin information present in the database and sends the synced twin results to the communication module. 155 - The communication module further sends the information to edgehub component which will in turn send the updates to the cloud through the websocket connection. 156 - This function also performs operations like publishing the updated twin details document, delta of the device twin as well as the update result (in case there is some error) to a specified topic through the communication module, 157 which sends the data to edgehub, which will send it to eventbus which publishes on the MQTT broker. 158 159  160 161 ### Communication Module 162 163 The main responsibility of communication module is to ensure the communication functionality between device twin and the other components. 164 165 The major functions performed by this module are:- 166 167 1. Initialize action callback map which is a map[string]Callback that contains the callback functions that can be performed 168 2. Receive the messages sent to communication module 169 3. For each message the action message is read and the corresponding function is called 170 4. Confirm whether the actions specified in the message are completed or not, if the action is not completed then redo the action 171 5. Receive heartbeat from the heartbeat channel and send a heartbeat to the controller 172 173 The following are the action callbacks which can be performed by the communication module :- 174 175 - dealSendToCloud 176 - dealSendToEdge 177 - dealLifeCycle 178 - dealConfirm 179 180 181 **dealSendToCloud**: dealSendToCloud() is used to send data to the cloudHub component. 182 This function first ensures that the cloud is connected, then sends the message to the edgeHub module (through the beehive framework), 183 which in turn will forward the message to the cloud (through the websocket connection). 184 185 **dealSendToEdge**: dealSendToEdge() is used to send data to the other modules present at the edge. 186 This function sends the message received to the edgeHub module using beehive framework. 187 The edgeHub module after receiving the message will send it to the required recipient. 188 189 **dealLifeCycle**: dealLifeCycle() checks if the cloud is connected and the state of the twin is disconnected, it then changes the status 190 to connected and sends the node details to edgehub. If the cloud is disconnected then, it sets the state of the twin 191 as disconnected. 192 193 **dealConfirm**: dealConfirm() is used to confirm the event. It checks whether the type of the message is right and 194 then deletes the id from the confirm map. 195 196 197 ### Device Module 198 199 The main responsibility of the device module is to perform the device related operations like dealing with device state updates 200 and device attribute updates. 201 202 The major functions performed by this module are :- 203 204 1. Initialize action callback map (which is a map of action(string) to the callback function that performs the requested action) 205 2. Receive the messages sent to device module 206 3. For each message the action message is read and the corresponding function is called 207 4. Receive heartbeat from the heartbeat channel and send a heartbeat to the controller 208 209 The following are the action callbacks which can be performed by the device module :- 210 211 - dealDeviceUpdated 212 - dealDeviceStateUpdate 213 214 **dealDeviceUpdated**: dealDeviceUpdated() deals with the operations to be performed when a device attribute update is encountered. 215 It updates the changes to the device attributes, like addition of attributes, updation of attributes and deletion of attributes 216 in the database. It also sends the result of the device attribute update to be published to the eventbus component. 217 - The device attribute updation is initiated from the cloud, which sends the update to edgehub. 218 - The edgehub component sends the message to the device twin controller which forwards the message to the device module. 219 - The device module updates the device attribute details into the database after which, the device module sends the result of the device attribute update to be published 220 to the eventbus component through the communicate module of devicetwin. The eventbus component further publishes the result on the specified topic. 221 222  223 224 **dealDeviceStateUpdate**: dealDeviceStateUpdate() deals with the operations to be performed when a device status update is encountered. 225 It updates the state of the device as well as the last online time of the device in the database. 226 It also sends the update state result, through the communication module, to the cloud through the edgehub module and to the eventbus module which in turn 227 publishes the result on the specified topic of the MQTT broker. 228 - The device state updation is initiated by publishing a message on the specified topic which is being subscribed by the eventbus component. 229 - The eventbus component sends the message to the device twin controller which forwards the message to the device module. 230 - The device module updates the state of the device as well as the last online time of the device in the database. 231 - The device module then sends the result of the device state update to the eventbus component and edgehub component through the communicate module of devicetwin. The eventbus component further publishes the result on the specified topic, while the 232 edgehub component sends the device status update to the cloud. 233 234  235 236 237 ## Tables 238 239 DeviceTwin module creates three tables in the database, namely :- 240 241 - Device Table 242 - Device Attribute Table 243 - Device Twin Table 244 245 246 ### Device Table 247 248 Device table contains the data regarding the devices added to a particular edge node. 249 The following are the columns present in the device table : 250 251 |Column Name | Description | 252 |---|---| 253 | **ID** | This field indicates the id assigned to the device | 254 | **Name** | This field indicates the name of the device | 255 | **Description** | This field indicates the description of the device | 256 | **State** | This field indicates the state of the device | 257 | **LastOnline** | This fields indicates when the device was last online | 258 259 **Operations Performed :-** 260 261 The following are the operations that can be performed on this data :- 262 263 - **Save Device**: Inserts a device in the device table 264 265 - **Delete Device By ID**: Deletes a device by its ID from the device table 266 267 - **Update Device Field**: Updates a single field in the device table 268 269 - **Update Device Fields**: Updates multiple fields in the device table 270 271 - **Query Device**: Queries a device from the device table 272 273 - **Query Device All**: Displays all the devices present in the device table 274 275 - **Update Device Multi**: Updates multiple columns of multiple devices in the device table 276 277 - **Add Device Trans**: Inserts device, device attribute and device twin in a single transaction, if any of these operations fail, 278 then it rolls back the other insertions 279 280 - **Delete Device Trans**: Deletes device, device attribute and device twin in a single transaction, if any of these operations fail, 281 then it rolls back the other deletions 282 283 284 ### Device Attribute Table 285 286 Device attribute table contains the data regarding the device attributes associated with a particular device in the edge node. 287 The following are the columns present in the device attribute table : 288 289 | Column Name | Description | 290 |----------------|--------------------------| 291 | **ID** | This field indicates the id assigned to the device attribute | 292 | **DeviceID** | This field indicates the device id of the device associated with this attribute | 293 | **Name** | This field indicates the name of the device attribute | 294 | **Description** | This field indicates the description of the device attribute | 295 | **Value** | This field indicates the value of the device attribute | 296 | **Optional** | This fields indicates whether the device attribute is optional or not | 297 | **AttrType** | This fields indicates the type of attribute that is referred to | 298 | **Metadata** |This fields describes the metadata associated with the device attribute | 299 300 301 **Operations Performed :-** 302 303 The following are the operations that can be performed on this data : 304 305 - **Save Device Attr**: Inserts a device attribute in the device attribute table 306 307 - **Delete Device Attr By ID**: Deletes a device attribute by its ID from the device attribute table 308 309 - **Delete Device Attr**: Deletes a device attribute from the device attribute table by filtering based on device id and device name 310 311 - **Update Device Attr Field**: Updates a single field in the device attribute table 312 313 - **Update Device Attr Fields**: Updates multiple fields in the device attribute table 314 315 - **Query Device Attr**: Queries a device attribute from the device attribute table 316 317 - **Update Device Attr Multi**: Updates multiple columns of multiple device attributes in the device attribute table 318 319 - **Delete Device Attr Trans**: Inserts device attributes, deletes device attributes and updates device attributes in a single transaction. 320 321 322 ### Device Twin Table 323 324 Device twin table contains the data related to the device device twin associated with a particular device in the edge node. 325 The following are the columns present in the device twin table : 326 327 328 | Column Name | Description | 329 |---|---| 330 | **ID** | This field indicates the id assigned to the device twin | 331 | **DeviceID** | This field indicates the device id of the device associated with this device twin | 332 | **Name** | This field indicates the name of the device twin | 333 | **Description** | This field indicates the description of the device twin | 334 | **Expected** | This field indicates the expected value of the device | 335 | **Actual** | This field indicates the actual value of the device | 336 | **ExpectedMeta** | This field indicates the metadata associated with the expected value of the device | 337 | **ActualMeta** | This field indicates the metadata associated with the actual value of the device | 338 | **ExpectedVersion** | This field indicates the version of the expected value of the device | 339 | **ActualVersion** | This field indicates the version of the actual value of the device | 340 | **Optional** | This fields indicates whether the device twin is optional or not | 341 | **AttrType** | This fields indicates the type of attribute that is referred to | 342 | **Metadata** | This fields describes the metadata associated with the device twin | 343 344 345 **Operations Performed :-** 346 347 The following are the operations that can be performed on this data :- 348 349 - **Save Device Twin**: Inserts a device twin in the device twin table 350 351 - **Delete Device Twin By Device ID**: Deletes a device twin by its ID from the device twin table 352 353 - **Delete Device Twin**: Deletes a device twin from the device twin table by filtering based on device id and device name 354 355 - **Update Device Twin Field**: Updates a single field in the device twin table 356 357 - **Update Device Twin Fields**: Updates multiple fields in the device twin table 358 359 - **Query Device Twin**: Queries a device twin from the device twin table 360 361 - **Update Device Twin Multi**: Updates multiple columns of multiple device twins in the device twin table 362 363 - **Delete Device Twin Trans**: Inserts device twins, deletes device twins and updates device twins in a single transaction. 364