- 인쇄
- PDF
가상 디바이스 미러 생성 및 관리
- 인쇄
- PDF
Classic/VPC 환경에서 이용 가능합니다.
가상 디바이스 미러의 생성 및 관리 방법과 가상 디바이스 미러 Update 작동 원리에 대해 설명합니다.
가상 디바이스 미러 생성 및 수정 시 오류가 발생할 경우, Cloud IoT Core 문제 해결을 확인해 주십시오.
가상 디바이스 미러 생성
가상 디바이스 미러를 생성하는 방법은 다음과 같습니다.
- 네이버 클라우드 플랫폼 콘솔에서 Services > Internet of Things > Cloud IoT Core > Virtual Devices를 클릭해 주십시오.
- 가상 디바이스를 생성해 주십시오.
- 가상 디바이스를 생성하는 방법은 가상 디바이스 생성을 참고해 주십시오.
- 미러를 생성할 가상 디바이스를 선택한 후 [수정] 버튼을 클릭해 주십시오.
- 미러 설정 영역에서 [추가] 버튼을 클릭해 주십시오.
- 미러 이름을 입력해 주십시오.
- 미러를 선택한 후 [상세 보기] 버튼을 클릭해 주십시오.
- 팝업 창이 나타나면 미러 상태를 확인하고 [확인] 버튼을 클릭해 주십시오.
- [완료] 버튼을 클릭해 주십시오.
콘솔에서 미러를 생성할 경우, Cloud IoT Core에서 $ncp/device/{가상디바이스이름}/mirror/update/accepted
MQTT 메시지를 발행합니다.
가상 디바이스 미러 수정
네이버 클라우드 플랫폼 콘솔에서 가상 디바이스 미러를 수정하는 방법은 다음과 같습니다.
- 네이버 클라우드 플랫폼 콘솔에서 Services > Internet of Things > Cloud IoT Core > Virtual Devices를 클릭해 주십시오.
- 가상 디바이스를 선택한 후 [수정] 버튼을 클릭해 주십시오.
- 미러 설정 영역에서 수정할 미러를 선택한 후 [상세 보기] 버튼을 클릭해 주십시오.
- 팝업 창이 나타나면 미러 상태를 수정한 후 [확인] 버튼을 클릭해 주십시오.
- 미러 설정이 완료되면 가상 디바이스 수정 페이지의 [완료] 버튼을 클릭해 주십시오.
MQTT 메시지로 가상 디바이스 미러를 생성하거나 수정하는 방법은 다음과 같습니다.
- MQTT 메시지를 전송해 주십시오.
- 토픽은 가상 디바이스 미러 MQTT 전용 토픽 규칙에 맞게 지정해 주십시오.
- update인 경우
$ncp/device/{가상디바이스이름}/mirror/update
로 지정하고 payload는 가상 디바이스 미러 update payload 형식에 맞는 메시지를 전송합니다.
$ncp/device/{가상디바이스이름}/mirror/update/accepted
토픽을 구독하여 생성 및 수정이 완료되었는지 확인해 주십시오.
- MQTT 메시지가 아닌 콘솔에서 가상 디바이스 미러를 수정할 경우에도 Cloud IoT Core에서
$ncp/device/{가상디바이스이름}/mirror/update/accepted
MQTT 메시지를 발행합니다. - MQTT 메시지로 가상 디바이스 미러 생성 시 update를 활용합니다. update 시 미러가 존재하지 않으면 미러가 생성되고 미러가 존재할 경우 해당 미러가 수정됩니다.
- 가상 디바이스 미러 최초 생성 시 버전은 1부터 시작하며, 미러가 수정될 때마다 버전의 숫자가 1씩 증가합니다.
<예시>
$ncp/device/{가상디바이스이름}/mirror/update/accepted
토픽을 구독한 예시는 다음과 같습니다.
$ncp/device/air_conditioner/mirror/update/accepted
{
"state": {
"reported": {
"temperature": 20
}
},
"metadata": { -- (1)
"reported": {
"temperature": {
"timestamp": 1616090000
}
}
},
"timestamp": 1616090000, -- (2)
"version": 3 -- (3)
}
$ncp/device/{가상디바이스이름}/mirror/update/accepted
의 내용은 현재 저장되어 있는 미러의 내용이 아니라 update 요청 시 MQTT 메시지 payload의 내용을 그대로 나타냅니다.
예를 들어, 미러에 desired의 값이 저장되어 있더라도 update payload에 reported 값만 작성하여 update할 경우$ncp/device/{가상디바이스이름}/mirror/update/accepted
메시지에는 reported에 대한 내용만 나타납니다.- payload 사용하여 clientToken을 전달할 수 있습니다.
metadata
는 미러가 저장된 시각의 timestamp(1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 초로 환산하여 정수로 나타낸 것)로 update payload의state
JSON 메시지와 동일한 구조로 되어 있습니다.timestamp
는 accepted 메시지가 발행된 timestamp입니다. 미러가 저장된 시간과 동일합니다.version
은 저장된 미러의 version 값입니다.
가상 디바이스 미러 확인
네이버 클라우드 플랫폼 콘솔에서 가상 디바이스 미러의 정보를 확인하는 방법은 다음과 같습니다.
- 네이버 클라우드 플랫폼 콘솔에서 Services > Internet of Things > Cloud IoT Core > Virtual Devices를 클릭해 주십시오.
- 미러가 속한 가상 디바이스를 선택한 후 [수정] 버튼을 클릭해 주십시오.
- 미러 설정 영역에서 수정할 미러를 선택한 후, [상세 보기] 버튼을 클릭해 주십시오.
- 미러 정보 팝업 창이 나타나면 저장된 미러 상태 및 메타데이터 정보를 확인해 주십시오.
MQTT 메시지로 가상 디바이스 미러의 정보를 확인하는 방법은 다음과 같습니다.
- 가상 디바이스와 가상 디바이스 미러가 있는지 확인해 주십시오.
- MQTT 메시지를 전송해 주십시오.
- 토픽은 가상 디바이스 미러 MQTT 전용 토픽 규칙에 맞게 지정해 주십시오.
- get인 경우
$ncp/device/{가상디바이스이름}/mirror/get
로 지정하고 payload 입력 없이 메시지를 전송합니다.
ncp/device/{가상디바이스이름}/mirror/get/accepted
토픽을 구독하여 저장된 미러 내용을 확인해 주십시오.
<예시>
ncp/device/air_conditioner/mirror/get/accepted
토픽을 구독한 예시는 다음과 같습니다.
$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
}
delta
가 존재할 경우,state
의delta
에서 확인할 수 있습니다.- payload 사용하여 clientToken을 전달할 수 있습니다.
metadata
는 미러가 저장된 시각의 timestamp(1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 초로 환산하여 정수로 나타낸 것)로 값이 저장된 시간입니다.state
JSON 메시지와 동일한 구조로 되어있습니다. 참고로 metadata에서 delta 메시지에 해당하는 timestamp는 없습니다.timestamp
는 accepted 메시지가 발행된 timestamp입니다. 미러가 저장된 시간과 동일합니다.version
은 저장된 미러의 version 값을 나타냅니다.
가상 디바이스 미러 삭제
네이버 클라우드 플랫폼의 콘솔에서 가상 디바이스 미러를 삭제하는 방법은 다음과 같습니다.
- 네이버 클라우드 플랫폼 콘솔에서 Services > Internet of Things > Cloud IoT Core > Virtual Devices를 클릭해 주십시오.
- 삭제할 미러가 속한 가상 디바이스를 선택한 후, [수정] 버튼을 클릭해 주십시오.
- 미러 설정 영역에서 삭제할 미러를 선택한 후, [삭제] 버튼을 클릭해 주십시오.
- 가상 디바이스 수정 페이지의 [저장] 버튼을 클릭해 주십시오.
MQTT 메시지로 가상 디바이스 미러를 삭제하는 방법은 다음과 같습니다.
- MQTT 메시지를 전송해 주십시오.
- 토픽은 가상 디바이스 미러 MQTT 전용 토픽 규칙에 맞게 지정해 주십시오.
- delete인 경우
$ncp/device/{가상디바이스이름}/mirror/delete
로 지정하고 payload 입력 없이 메시지를 전송합니다.
$ncp/device/{가상디바이스이름}/mirror/delete/accepted
토픽을 구독하여 삭제가 완료되었는지 확인해 주십시오.
네이버 클라우드 플랫폼의 콘솔에서 가상 디바이스 미러를 삭제하는 경우에도 Cloud IoT Core에서 $ncp/device/{가상디바이스이름}/mirror/delete/accepted
MQTT 메시지를 발행합니다.
<예시>
ncp/device/air_conditioner/mirror/delete/accepted
토픽을 구독한 예시는 다음과 같습니다.
$ncp/device/air_conditioner/mirror/delete/accepted
{
"timestamp": 1616090000,
"version": 3
}
- payload 사용하여 clientToken을 전달할 수 있습니다.
- 최상위
timestamp
값은accepted
메시지가 발행된 timestamp를 나타냅니다. version
은 마지막으로 저장된 미러의 version 값을 나타냅니다.
가상 디바이스 미러의 Update 작동 원리
update 시 payload의 key 값이 추가되거나 변경됩니다. key1이 있는 상태에서 key2 메시지를 update하면 key2의 값이 수정되고, key2가 없는 경우에는 key2 값이 새로 추가됩니다. key를 삭제하려면 "key" : null로 update합니다. JSON list는 값으로 취급하여 전체가 치환됩니다.
<저장되어 있는 미러>
{
"state": {
"repoted" : {
"key1" : 1
}
}
}
<update 메시지>
{
"state": {
"repoted" : {
"key2" : "string2"
}
}
}
<최종 저장되는 미러>
{
"state": {
"repoted" : {
"key1" : 1
"key2" : "string2"
}
}
}
<저장되어 있는 미러>
{
"state": {
"repoted" : {
"key1" : ["a","b", {"nested" : 1} ]
}
}
}
<update 메시지>
{
"state": {
"repoted" : {
"key1" : []
}
}
}
<최종 저장되는 미러>
{
"state": {
"repoted" : {
"key1" : []
}
}
}
Update 시 발행되는 delta 메시지
Update 시 Cloud IoT Core에서 $ncp/device/{가상디바이스이름}/mirror/update/delta
메시지가 추가로 발행될 수 있습니다. delta란 state 내부의 desired(가상 디바이스가 요구된 상태)와 reported(가상 디바이스의 현재 상태)를 가상 디바이스 미러에 전송한 후 얻은 두 값의 차이를 말합니다. delta를 확인하고 desired 상태와 동일한 상태로 IoT 기기를 설정하는 임베디드 프로그래밍을 만들수 있습니다.
- delta 메시지 발행 조건 : Update 시 저장된 미러의 desired와 reported에서 동일한 키 값에 차이가 있을 경우, 가상 디바이스 미러에 delta 값이 저장되며 Cloud IoT Core에서
$ncp/device/{가상디바이스이름}/mirror/update/delta
메시지가 발행됩니다. delta 메시지를 구독하면 desired와 reported의 차이가 발생했음을 확인할 수 있습니다. reported
에는 키 값이 있지만desired
에 키 값이 없다면 delta가 발생하지 않습니다.- 하위 레벨 값의 차이도 비교합니다.
- 값이 JSON List 구조일 경우, 완전히 같은 형태가 아니라면 delta가 발생합니다.
$ncp/device/air_conditioner/mirror/update 전달
{
"state": {
"desired": {
"temperature" : 17,
"id" : {
"main" : 1
}
},
"reported": {
"temperature" : 20,
"id" : {
"main" : 2,
"sub" : 1
},
"another" : "ignored"
}
}
}
<delta 메시지 예시>
$ncp/device/air_conditioner/mirror/update/delta
{
"state": {
"temperature": 17, --- (1) temperature의 값이 달라 delta 발생,
--- (2) another key는 reported에만 있고 desired에 없어 delta 발생하지 않음.
"id" : {
"main" : 2
}
},
"metadata": {
"temperature": {
"timestamp": 1616090000
},
"id" : {
"main" : {
"timestamp": 1616090000
}
}
},
"timestamp": 1616090000,
"version": 3
}
metadata
는 미러가 저장된 시각의 timestamp(1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 초로 환산하여 정수로 나타낸 것)로 값이 저장된 시간입니다.timestamp
는$ncp/device/{가상디바이스이름}/mirror/update/delta
가 발행된 시각입니다.version
은 마지막으로 저장된 미러의 version을 나타냅니다.- delta MQTT 메시지에서 차이가 발생한
desired
의 key는 모두state
에 표시됩니다.
Update 시 발행되는 documents 메시지
Update 시 Cloud IoT Core에서 $ncp/device/{가상디바이스이름}/mirror/update/documents
메시지가 발행됩니다. documents
란 이전(previous)에 저장된 미러의 내용과 현재(current) 저장된 미러 내용을 함께 담은 메시지입니다.
<예시>
$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
는$ncp/device/{가상디바이스이름}/mirror/update/documents
가 발행된 시각입니다.
가상 디바이스 미러의 update payload 형식
가상 디바이스 미러의 update payload 형식은 JSON 형식의 문자열이어야 하며, 다음과 같은 메시지 형태를 갖추고 전송해야 합니다. 그렇지 않으면 Cloud IoT Core에서 $ncp/device/{가상디바이스이름}/mirror/{액션명}/rejected
메시지를 발행합니다.
{
"state" : {
"reported" : {
"light" : "on",
"id_list" : ["sn01", 110, "b10"]
},
"desired" : {
"light" : "off"
}
},
"clientToken" : "ThisIsTokenLengthMaximun1-64byte", -- (1) option
"version" : 1 -- (2) option
}
- 문서 전체는 JSON 형식이어야 하며, 최상위는 JSON Object({} 중괄호)여야 합니다.
- 최상위에
state
는 반드시 존재해야 하며, 값은 반드시 JSON Object여야 합니다. state
하위에 desired와 reported 이외의 key는 허용하지 않습니다.desired
와reported
는 필수가 아닌 선택 사항입니다. 다만 모두 JSON Object여야 합니다.desired
와reported
하위 JSON Object의 내용은 자유 형식입니다.desired
와reported
의 하위 단계 JSON(Nested JSON)은 최대 6단계까지 허용합니다.clientToken
과version
은 모두 선택 사항(option)입니다.
{
"state": {
"reported": {
"1": { "2": { "3": { "4": { "5": {
"6": { } -- 최대 하위 레벨 초과 rejected,
"6-1": "value" -- 최대 하위 레벨 허용 accepted
} } } } }
}
}
}
- payload에
clientToken
을 넣어 메시지를 전송하면 accepted 메시지로 구독할 때 동일한 clientToken이 기입된 메시지를 확인할 수 있습니다. 사용 목적은 어떤 기기가 미러 메시지를 전송하여 accepted가 발생한 것인지 식별하기 위함입니다. String 값은 1 Byte~64 Byte의 문자열이어야 하며,update
처럼get
,delete
메시지에도clientToken
를 포함한 payload를 만들 수 있습니다. - payload에
version
을 넣어 메시지를 전송하면 현재 미러의 version과 일치하는지 확인하고 미러를 수정하거나 삭제할 수 있습니다.version
은 0보다 큰 정수여야 하며, 전달된 version이 저장된 미러의 version과 다를 경우 콘솔에서rejected
메시지를 발행합니다. update처럼 delete 메시지에도 version을 포함한 payload를 만들 수 있습니다.