Creating and managing virtual device mirror

The latest service changes have not yet been reflected in this content. We will update the content as soon as possible. Please refer to the Korean version for information on the latest updates.

Available in Classic and VPC

The following describes how to create and manage virtual device mirrors and the principles of operating the update of virtual device mirrors.

Create virtual device mirror

The following describes how to create a virtual device mirror.

1. Click Services > Internet of Things > Cloud IoT Core > Virtual Devices on the NAVER Cloud Platform console.
2. Create a virtual device.
   • For how to create a virtual device, refer to Creating virtual device.
3. Select the virtual device to create a mirror for, and click [Edit].
4. Click [Add] from the mirror settings area.
5. Enter a name for the mirror.
6. Select the mirror, and click [Details].
7. When the pop-up window appears, check the mirror status and click [OK].
8. Click [Complete].

Modify virtual device mirrors

The following describes how to modify the virtual devices on the NAVER Cloud Platform console.

1. Click Services > Internet of Things > Cloud IoT Core > Virtual Devices on the NAVER Cloud Platform console.
2. Select the virtual device and then click [Edit].
3. Select the mirror to be modified in the Mirror Settings area, and click [Details].
4. When the pop-up window appears, edit the mirror status and click [OK].
5. When the mirror settings are completed, click [Complete] on the virtual device editing page.

The following describes how to create or modify a virtual device mirror by MQTT message.

1. Send an MQTT message.
   • Designate a topic to meet the rules for exclusive topic for virtual device mirror MQTT.
   • When it is updated, designate $ncp/device/{virtual device name}/mirror/update, and for payload, send the message matching the virtual device mirror update payload format.
2. $ncp/device/{virtual device name}/mirror/update/accepted Subscribe the topic and check if the creation and editing are complete.

<Example>
$ncp/device/{virtual device name}/mirror/update/accepted The example of subscribing the topic is as below.

 $ncp/device/air_conditioner/mirror/update/accepted 
{
  "state": {
    "reported": {
      "temperature": 20
    }
  },
  "metadata": {                             -- (1)
    "reported": {
      "temperature": {
        "timestamp": 1616090000
      }
    }
  },
  "timestamp": 1616090000,                  -- (2)
  "version": 3                              -- (3)
}

• The content of $ncp/device/{virtual device name}/mirror/update/accepted does not show the content of the currently saved mirror. Rather, it indicates the content of the MQTT message payload details for when update is requested. For example, even if the value of desired is saved on the mirror, when you update it only with the value of reported on update payload, $ncp/device/{virtual device name}/mirror/update/accepted message only shows the content for reported.
• Use payload to transfer the clientToken.
• metadata is the timestamp (the time elapsed from the UTC at 00:00:00 on January 1st, 1970 converted into seconds and indicated as an integer) of the time when the mirror was stored, and has the same structure as that of the state JSON message of the update payload.
• timestamp is the timestamp of the time when the accepted message was published. It is the same as the time when the mirror was saved.
• version is the version value of the saved mirror.

Check the virtual device mirror

The following describes how to check the information of the virtual device mirror on the NAVER Cloud Platform console.

1. Click Services > Internet of Things > Cloud IoT Core > Virtual Devices on the NAVER Cloud Platform console.
2. Select the virtual device to which the mirror belongs, and then click [Edit].
3. Select the mirror to be modified in the Mirror Settings area, and click [Details].
4. When the Mirror information pop-up window appears, check the saved mirror status and metadata information.

The following describes how to check the virtual device mirror information by MQTT message.

1. Check if a virtual device and a virtual device mirror exist.
2. Send an MQTT message.
   • Designate a topic to meet the rules for exclusive topic for virtual device mirror MQTT.
   • If it is get, designate $ncp/device/{virtual device name}/mirror/get and transmit the message without inputting payload.
3. Subscribe the ncp/device/{virtual device name}/mirror/get/accepted topic and check the saved mirror content.

<Example>
ncp/device/air_conditioner/mirror/get/accepted The example of subscribing the topic is as below.

$ncp/device/air_conditioner/mirror/get/accepted 
{
  "state": {
    "desired": {
      "temperature": 17
    },
    "reported": {
      "temperature": 20,
      "list" : ["a", "b", {"c" : 2}]
    },
    "delta": {                        
      "temperature": 20
    }
  },
  "metadata": {                       
    "desired": {
      "temperature": {
        "timestamp": 1616010000
      }
    },
    "reported": {
      "temperature": {
        "timestamp": 1616060000
      },
      "list" : [ {"timestamp": 1616060000}, {"timestamp": 1616060000}, {"c" : {"timestamp": 1616060000}} ]
    }
  }
  "timestamp": 1616090000,              
  "version": 3                        
}

• When delta exists, you can check it in state's delta.
• Use payload to transfer the clientToken.
• metadata is the timestamp (the time elapsed from the UTC at 00:00:00 on January 1st, 1970 converted into seconds and indicated as an integer) of the time when the mirror was stored. state has the same structure as the JSON message. For your reference, there is no timestamp belonging to the delta message on the metadata.
• timestamp is the timestamp of the time when the accepted message was published. It is the same as the time when the mirror was saved.
• version shows the version of the saved mirror.

Delete virtual device mirrors

The following describes how to delete a virtual device mirror on the NAVER Cloud Platform console.

1. Click Services > Internet of Things > Cloud IoT Core > Virtual Devices on the NAVER Cloud Platform console.
2. Select the virtual device to which the mirror to be deleted belongs, and then click [Edit].
3. Select the mirror to delete from the Mirror settings area, and then click [Delete].
4. Click [Save] on the virtual device editing page.

The following describes how to delete virtual device mirror by MQTT message.

1. Send an MQTT message.
   • Designate a topic to meet the rules for exclusive topic for virtual device mirror MQTT.
   • If it is delete, designate $ncp/device/{virtual device name}/mirror/delete and transmit the message without entering payload.
2. $ncp/device/{virtual device name}/mirror/delete/accepted Subscribe the topic and check if the deletion process is completed.

<Example>
ncp/device/air_conditioner/mirror/delete/accepted The example of subscribing the topic is as below.

$ncp/device/air_conditioner/mirror/delete/accepted 
{
  "timestamp": 1616090000,     
  "version": 3                                       
}

• Use payload to transfer the clientToken.
• The highest-ranked timestamp value accepted indicates the timestamp issued with the message.
• version refers to the last saved version of the mirror.

Operation principles of Update of the virtual device mirror

In case of update, the key value of payload is added or changed. If you update key2 message with key1, the value of key2 is modified, and if there is no key2, a new key2 value is added. To delete the key, update to "key" : null. JSON list is considered as a value and therefore entirely transposed.

<currently saved mirror>
{
"state": {
  "repoted" : {
     "key1" : 1
   }
 }
}
<update message>
{
"state": {
  "repoted" : {
     "key2" : "string2"
   }
 }
}
<finally saved mirror>
{
"state": {
  "repoted" : {
     "key1" : 1 
     "key2" : "string2"
   }
 }
}

<currently saved mirror>
{
"state": {
  "repoted" : {
     "key1" : ["a","b", {"nested" : 1} ]
   }
 }
}
<update message>
{
"state": {
  "repoted" : {
     "key1" : []
   }
 }
}
<finally saved mirror>
{
"state": {
  "repoted" : {
     "key1" : []
   }
 }
}

Delta message published for updates

During updates, Cloud IoT Core may additionally publish $ncp/device/{virtual device name}/mirror/update/delta message. Delta refers to the difference between the desired (the status where the virtual device is requested) in the state and the reported (the current status of the virtual device) obtained after the two values are sent to the virtual device mirror. Check the delta, and then you can make embedded programming for setting the IoT device to be the same status as the desired status.

• Condition for publishing delta message: During updates, if there is a difference in the same key value between desired and reported of the saved mirror, the delta value is saved in the virtual device mirror, and Cloud IoT Core publishes $ncp/device/{virtual device name}/mirror/update/delta message. If you subscribe delta message, you can check there has occurred a difference between desired and reported.
• If there is a key value in reported but not in desired, delta does not occur.
• It also compares the differences in the lower-level values.
• If the values are in the JSON list structure, the delta message occurs unless their forms are identical.

$ncp/device/air_conditioner/mirror/update 전달
{
  "state": {
    "desired": {
       "temperature" : 17,
       "id" : {
            "main" : 1 
       }
    },
    "reported": {
       "temperature" : 20,
        "id" : {
            "main" : 2,
            "sub" : 1
        },
       "another" : "ignored"
    }
  }
}


<delta message example>

$ncp/device/air_conditioner/mirror/update/delta
{
  "state": {
    "temperature": 17,   --- (1) Delta occurs due to the difference in temperature values,
                         --- (2) The delta message does not occur since the reported section has another key but the desired section doesn't..
     "id" : {
            "main" : 2
      }                    
  },
  "metadata": {
    "temperature": {
      "timestamp": 1616090000
    },
    "id" : {
         "main" : {
             "timestamp": 1616090000
         }
      }  
  },
  "timestamp": 1616090000,
  "version": 3
}

• metadata is the timestamp (the time elapsed from the UTC at 00:00:00 on January 1st, 1970 converted into seconds and indicated as an integer) of the time when the mirror was stored.
• timestamp is the time when the $ncp/device/{virtual device name}/mirror/update/delta was published.
• version refers to the last saved version of the mirror.
• The keys of desired with differences in delta MQTT messages are all indicated on state.

Document message published for updates

During updates, Cloud IoT Core publishes $ncp/device/{virtual device name}/mirror/update/documents message. documents is a message containing the content of mirror saved in previous and the content of mirror saved in current together.

<Example>

 $ncp/device/air_conditioner/mirror/update/documents
{
  "previous": { 
    "state": {
      "reported": {
        "temperature": 20
      }
    },
    "metadata": {
      "reported": {
        "temperature": {
          "timestamp": 1616010000
        }
      }
    },
    "version": 2
  },
  "current": {
    "state": {
      "desired": {
        "temperature": 17
      },
      "reported": {
        "temperature": 20
      },
      "delta" : {
        "temperature" : 17
      }
    },
    "metadata": {
      "desired": {
        "temperature": {
          "timestamp": 1616090000
        }
      },
      "reported": {
        "temperature": {
          "timestamp": 1616010000
        }
      }
    },
    "version": 3
  },
  "timestamp": 1616090000
}

• timestamp is the time when the $ncp/device/{virtual device name}/mirror/update/documents was published.

Update payload format of the virtual device mirror

The update payload format of the virtual device mirror must be a JSON-type string, and must be transmitted with the message format below. Otherwise, Cloud IoT Core publishes $ncp/device/{virtual device name}/mirror/{action name}/rejected message.

{  
"state" : {
       "reported" : {
          "light" : "on",
          "id_list" : ["sn01", 110, "b10"]
       },
       "desired" : {
          "light" : "off"
       }
   },
  "clientToken" : "ThisIsTokenLengthMaximun1-64byte",          -- (1) option
  "version" : 1                                                -- (2) option
}

• The whole document be in JSON format, and the highest part must be JSON Object ({ } brace).
• The highest-ranked document must include the state, and the value must be JSON Object.
• The keys other than desires and reported are not allowed under the state,
• desired and reported are not required but optional. But all of them must be JSON Object.
• The content of the JSON Object under the desired and reported may have a free format.
• The JSON (Nested JSON) below the desired and reported is allowed up to 6 levels.
• clientToken and version must be both optional.

 {
   "state": {
      "reported": {
         "1": { "2": { "3": { "4": { "5": {
                      "6": {    }           -- Rejected if exceeding the maximum sub level,
                      "6-1": "value"        -- Accepted for the maximum sub level
          } } } } }
        }
    }
}

• Put clientToken into the payload and send the message to check the same clientToken written in the message when subscribing to the accepted message. It is used to identify which device has sent the mirror message that sparked the accepted message. The character string value must be from 1 to 64 bytes. You can create a payload including a clientToken in the get and delete messages, as with update.
• Put version into the payload, and you can check if it matches the version of current mirror and modify or delete the mirror. version must be an integer greater than 0, and if the transmitted version differs from the saved mirror version, the console publishes the rejected message. Like update, you can create a payload including a version in the delete message.