IoT 플러그 앤 플레이 규칙

아티클
02/26/2024

IoT 플러그 앤 플레이 디바이스는 IoT Hub와 메시지를 교환할 때 규칙 집합을 따라야 합니다. IoT 플러그 앤 플레이 디바이스는 MQTT 프로토콜을 사용하여 IoT Hub와 통신합니다. IoT Hub는 일부 IoT 디바이스 SDK에서 사용할 수 있는 AMQP 프로토콜도 지원합니다.

디바이스는 모듈을 포함하거나 IoT Edge 런타임에서 호스팅하는 IoT Edge 모듈에서 구현될 수 있습니다.

IoT 플러그 앤 플레이 디바이스가 DTDL(디지털 트윈 정의 언어)모델을 사용하여 구현하는 원격 분석, 속성 및 명령을 설명합니다. 이 문서에서 참조하는 모델에는 두 가지 형식이 있습니다.

구성 요소 없음 - 구성 요소가 없는 모델입니다. 모델은 기본 인터페이스의 콘텐츠 섹션에서 원격 분석, 속성 및 명령을 최상위 요소로 선언합니다. Azure IoT 탐색기 도구에서 이 모델은 단일 기본 구성 요소로 표시됩니다.
다중 구성 요소 - 두 개 이상의 인터페이스로 구성된 모델입니다. 원격 분석, 속성 및 명령을 사용하여 기본 구성 요소로 표시되는 기본 인터페이스입니다. 더 많은 원격 분석, 속성 및 명령이 있는 구성 요소로 선언된 하나 이상의 인터페이스입니다.

자세한 내용은 IoT 플러그 앤 플레이 모델링 가이드를 참조하세요.

모델 식별

구현하는 모델을 알리기 위해 IoT 플러그 앤 플레이 디바이스 또는 모듈은 USERNAME 필드에 model-id을 추가하여 MQTT 연결 패킷에 모델 ID가 포함합니다.

디바이스 또는 모듈에서 구현하는 모델을 식별하기 위해 서비스는 다음에서 모델 ID를 가져올 수 있습니다.

디바이스 쌍 modelId 필드입니다.
디지털 트윈 $metadata.$model 필드입니다.
디지털 트윈 변경 알림입니다.

원격

구성 요소가 없는 디바이스에서 전송된 원격 분석에는 추가 메타데이터가 필요하지 않습니다. 시스템이 dt-dataschema 특성을 추가합니다.
구성 요소를 사용하여 디바이스에서 보낸 원격 분석은 구성 요소 이름을 원격 분석 메시지에 추가해야 합니다.
MQTT를 사용하면 구성 요소 이름을 포함한 $.sub 속성이 원격 분석 토픽에 추가되는 경우, 시스템에서 dt-subject 속성을 추가합니다.
AMQP를 사용하면 구성 요소 이름을 포함한 dt-subject 속성을 메시지 주석으로 추가합니다.

참고 항목

구성 요소의 원격 분석에는 구성 요소당 하나의 메시지가 필요합니다.

더 많은 원격 분석 예제는 페이로드 > 원격 분석을 참조하세요.

읽기 전용 속성

디바이스는 읽기 전용 속성을 설정한 다음, 백 엔드 애플리케이션에 보고합니다.

구성 요소가 없는 읽기 전용 속성 샘플

디바이스 또는 모듈은 DTDL 규칙을 따르는 유효한 JSON을 보낼 수 있습니다.

인터페이스에서 속성을 정의하는 DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:example: Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "temperature",
      "schema": "double"
    }
  ]
}

reported 속성 페이로드 샘플:

"reported" :
{
  "temperature" : 21.3
}

다중 구성 요소 읽기 전용 속성 샘플

디바이스 또는 모듈은 요소가 구성 요소를 참조함을 표시하기 위해 {"__t": "c"} 마커를 추가해야 합니다.

구성 요소를 참조하는 DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "contents": [
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1"
    }
  ]
}

구성 요소를 정의하는 DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "temperature",
      "schema": "double"
    }
  ]
}

reported 속성 페이로드 샘플:

"reported": {
  "thermostat1": {
    "__t": "c",
    "temperature": 21.3
  }
}

더 많은 읽기 전용 속성 예제는 페이로드 > 속성을 참조하세요.

쓰기 가능한 속성

백 엔드 애플리케이션은 IoT Hub가 디바이스에 보내는 쓰기 가능한 속성을 설정합니다.

디바이스 또는 모듈은 reported 속성을 전송하여 속성을 받았는지 확인해야 합니다. reported 속성에는 다음이 포함되어야 합니다.

value - 속성의 실제 값(일반적으로 수신된 값이지만 디바이스가 다른 값을 보고하도록 결정할 수 있음).
ac - HTTP 상태 코드를 사용하는 승인 코드입니다.
av - desired 속성의 $version을 참조하는 승인 버전입니다. 이 값은 desired 속성 JSON 페이로드에서 찾을 수 있습니다.
ad - 선택적 승인 설명입니다.

승인 응답

쓰기 가능한 속성을 보고할 때 디바이스는 다음 표에 설명된 대로 이전 목록의 4개 필드를 사용하여 승인 메시지를 작성하여 실제 디바이스 상태를 나타내야 합니다.

상태(ac)	버전(av)	값(value)	설명(av)
200	원하는 버전	원하는 값	원하는 속성 값 허용됨
202	원하는 버전	디바이스에서 허용하는 값	원하는 속성 값이 허용됨, 업데이트 진행 중(200으로 완료)
203	0	디바이스에서 설정한 값	원하는 것을 반영하지 않고 디바이스에서 설정된 속성
400	원하는 버전	디바이스에서 사용하는 실제 값	원하는 속성 값이 허용되지 않음
500	원하는 버전	디바이스에서 사용하는 실제 값	속성을 적용할 때 예외

디바이스가 시작되면 디바이스 쌍을 요청하고 쓰기 가능한 속성 업데이트를 확인해야 합니다. 디바이스가 오프라인일 때 쓰기 가능한 속성의 버전이 증가하면 디바이스는 reported 속성 응답을 보내 업데이트를 받았음을 확인해야 합니다.

디바이스를 처음 시작하는 경우 IoT 허브에서 초기 desired 속성을 받지 못하는 경우 reported 속성에 대한 초기 값을 보낼 수 있습니다. 이 경우 디바이스는 av에서 0 및 ac에서 203을 포함하는 기본값을 보낼 수 있습니다. 예시:

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 203,
    "av": 0,
    "ad": "initialize"
  }
}

디바이스는 reported 속성을 사용하여 허브에 다른 정보를 제공할 수 있습니다. 예를 들어 디바이스는 다음과 같은 일련의 진행 중인 메시지를 사용하여 응답할 수 있습니다.

"reported": {
  "targetTemperature": {
    "value": 35.0,
    "ac": 202,
    "av": 3,
    "ad": "In-progress - reporting current temperature"
  }
}

디바이스가 대상 온도에 도달하면 다음 메시지를 보냅니다.

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 200,
    "av": 4,
    "ad": "Reached target temperature"
  }
}

디바이스는 다음과 같은 오류를 보고할 수 있습니다.

"reported": {
  "targetTemperature": {
    "value": 120.0,
    "ac": 500,
    "av": 3,
    "ad": "Target temperature out of range. Valid range is 10 to 99."
  }
}

Object type

쓰기 가능 속성이 개체로 정의된 경우 서비스는 디바이스에 전체 개체를 보내야 합니다. 디바이스는 업데이트에 대해 디바이스가 어떻게 작동했는지 이해하기 위해 서비스에 충분한 정보를 다시 전송하여 업데이트를 승인해야 합니다. 이 응답에는 다음이 포함될 수 있습니다.

전체 개체.
디바이스가 업데이트한 필드만.
필드의 하위 집합.

큰 개체의 경우 승인에 포함하는 개체의 크기를 최소화하는 것이 좋습니다.

다음 예제에서는 4개의 필드가 있는 Object로 정의된 쓰기 가능한 속성을 보여줍니다.

DTDL:

{
  "@type": "Property",
  "name": "samplingRange",
  "schema": {
    "@type": "Object",
    "fields": [
      {
        "name": "startTime",
        "schema": "dateTime"
      },
      {
        "name": "lastTime",
        "schema": "dateTime"
      },
      {
        "name": "count",
        "schema": "integer"
      },
      {
        "name": "errorCount",
        "schema": "integer"
      }
    ]
  },
  "displayName": "Sampling range"
  "writable": true
}

이 쓰기 가능한 속성을 업데이트하려면 서비스에서 다음 예와 같은 전체 개체를 보냅니다.

{
  "samplingRange": {
    "startTime": "2021-08-17T12:53:00.000Z",
    "lastTime": "2021-08-17T14:54:00.000Z",
    "count": 100,
    "errorCount": 5
  }
}

디바이스는 다음 예와 같은 승인으로 응답합니다.

{
  "samplingRange": {
    "ac": 200,
    "av": 5,
    "ad": "Weighing status updated",
    "value": {
      "startTime": "2021-08-17T12:53:00.000Z",
      "lastTime": "2021-08-17T14:54:00.000Z",
      "count": 100,
      "errorCount": 5
    }
  }
}

구성 요소가 없는 쓰기 가능한 속성 샘플

디바이스가 단일 페이로드에 보고된 여러 속성을 수신하는 경우 reported 속성 응답을 여러 페이로드를 통해 보내거나 응답을 단일 페이로드로 결합할 수 있습니다.

디바이스 또는 모듈은 DTDL 규칙을 따르는 유효한 JSON을 보낼 수 있습니다.

DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:example: Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "targetTemperature",
      "schema": "double",
      "writable": true
    },
    {
      "@type": "Property",
      "name": "targetHumidity",
      "schema": "double",
      "writable": true
    }
  ]
}

desired 속성 페이로드 샘플:

"desired" :
{
  "targetTemperature" : 21.3,
  "targetHumidity" : 80,
  "$version" : 3
}

reported 속성 첫 번째 페이로드 샘플:

"reported": {
  "targetTemperature": {
    "value": 21.3,
    "ac": 200,
    "av": 3,
    "ad": "complete"
  }
}

reported 속성 두 번째 페이로드 샘플:

"reported": {
  "targetHumidity": {
    "value": 80,
    "ac": 200,
    "av": 3,
    "ad": "complete"
  }
}

참고 항목

이러한 두 개의 보고된 속성 페이로드를 단일 페이로드로 결합하도록 선택할 수 있습니다.

다중 구성 요소 쓰기 가능 속성 샘플

디바이스 또는 모듈은 요소가 구성 요소를 참조함을 표시하기 위해 {"__t": "c"} 마커를 추가해야 합니다.

마커는 구성 요소에 정의된 속성에 대한 업데이트에 대해서만 전송됩니다. 기본 구성 요소에 정의된 속성 업데이트에는 마커가 포함되지 않습니다. 구성 요소가 없는 쓰기 가능한 속성 샘플을 참조하세요.

디바이스가 단일 페이로드에 여러 reported 속성을 수신하는 경우 reported 속성 응답을 여러 페이로드를 통해 보내거나 응답을 단일 페이로드로 결합할 수 있습니다.

디바이스 또는 모듈은 reported 속성을 전송하여 속성을 받았는지 확인해야 합니다.

구성 요소를 참조하는 DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "contents": [
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1"
    }
  ]
}

구성 요소를 정의하는 DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "targetTemperature",
      "schema": "double",
      "writable": true
    }
  ]
}

desired 속성 페이로드 샘플:

"desired": {
  "thermostat1": {
    "__t": "c",
    "targetTemperature": 21.3,
    "targetHumidity": 80,
    "$version" : 3
  }
}

reported 속성 첫 번째 페이로드 샘플:

"reported": {
  "thermostat1": {
    "__t": "c",
    "targetTemperature": {
      "value": 23,
      "ac": 200,
      "av": 3,
      "ad": "complete"
    }
  }
}

reported 속성 두 번째 페이로드 샘플:

"reported": {
  "thermostat1": {
    "__t": "c",
    "targetHumidity": {
      "value": 80,
      "ac": 200,
      "av": 3,
      "ad": "complete"
    }
  }
}

참고 항목

이러한 두 개의 보고된 속성 페이로드를 단일 페이로드로 결합하도록 선택할 수 있습니다.

쓰기 가능한 속성 예제를 더 보려면 페이로드 > 속성을 참조하세요.

명령

접두사 없이 명령 이름을 사용하는 구성 요소 인터페이스는 없습니다.

디바이스 또는 모듈에서 다중 구성 요소 인터페이스는 componentName*commandName 형식의 명령 이름을 사용합니다.

더 많은 원격 명령 예제는 페이로드 > 명령을 참조하세요.

팁

IoT Central에는 장기 실행 명령 및 오프라인 명령을 구현하기 위한 자체 규칙이 있습니다.

다음 단계

이제 IoT 플러그 앤 플레이 규칙에 대해 배웠으므로 다음은 몇 가지 다른 리소스입니다.

IoT 플러그 앤 플레이 규칙

모델 식별

원격

읽기 전용 속성

구성 요소가 없는 읽기 전용 속성 샘플

다중 구성 요소 읽기 전용 속성 샘플

쓰기 가능한 속성

승인 응답

Object type

구성 요소가 없는 쓰기 가능한 속성 샘플

다중 구성 요소 쓰기 가능 속성 샘플

명령

다음 단계

추가 리소스