IoT 플러그 앤 플레이 디바이스 개발자 가이드
IoT 플러그 앤 플레이를 통해 Azure IoT 어플리케이션에 기능을 알리는 IoT 디바이스를 구축할 수 있습니다. IoT 플러그 앤 플레이 디바이스는 고객이 IoT Central과 같은 IoT 플러그 앤 플레이 지원 애플리케이션에 연결할 때 수동 구성이 필요하지 않습니다.
모듈을 사용하거나 IoT Edge 모듈을 사용하여 IoT 디바이스를 직접 구현할 수 있습니다.
이 가이드에서는 IoT 플러그 앤 플레이 방식을 따르는 디바이스, 모듈 또는 IoT Edge 모듈을 만드는 데 필요한 기본 단계에 대해 설명합니다.
IoT 플러그 앤 플레이 디바이스, 모듈 또는 IoT Edge 모듈을 구축하려면 다음 단계를 수행합니다:
- 디바이스가 MQTT 또는 Websocket을 통한 MQTT 프로토콜을 사용하여 Azure IoT Hub에 연결하는지 확인합니다.
- 디바이스를 설명하는 Digital Twins 정의어(DTDL) 모델을 만듭니다. 자세한 내용은 IoT 플러그 앤 플레이 모델의 구성 요소 이해를 참조하십시오.
- 디바이스 연결의 일부를 알리기 위해 디바이스 또는 모듈을 업데이트
model-id합니다. - IoT 플러그 앤 플레이 방식을 따르는 원격 분석, 속성 및 명령 구현
디바이스 또는 모듈 구현이 준비되면 Azure IoT 탐색기를 사용하여 디바이스가 IoT 플러그 앤 플레이 방식을 따르는지 확인합니다.
모델 ID 알림
모델 ID를 알리려면 디바이스가 연결 정보에 해당 ID를 포함해야 합니다.
static const char g_ThermostatModelId[] = "dtmi:com:example:Thermostat;1";
IOTHUB_DEVICE_CLIENT_LL_HANDLE deviceHandle = NULL;
deviceHandle = CreateDeviceClientLLHandle();
iothubResult = IoTHubDeviceClient_LL_SetOption(
deviceHandle, OPTION_MODEL_ID, g_ThermostatModelId);
팁
모듈 및 IoT Edge의 경우 IoTHubModuleClient_LL 대신 IoTHubDeviceClient_LL를 사용합니다.
팁
디바이스가 모델 ID를 설정할 수 있는 유일한 시간이며 디바이스가 연결된 후에는 업데이트할 수 없습니다.
DPS 페이로드
DPS(Device Provisioning Service)를 사용하는 디바이스에는 다음 JSON 페이로드를 사용하는 프로비저닝 프로세스 중에 사용할 modelId가 포함될 수 있습니다.
{
"modelId" : "dtmi:com:example:Thermostat;1"
}
구성 요소 사용
IoT 플러그 앤 플레이 모델의 구성 요소 이해에 설명된 대로 구성 요소를 사용하여 디바이스를 설명할지 결정해야 합니다. 구성 요소를 사용하는 경우 디바이스는 다음 섹션에 설명된 규칙을 따라야 합니다.
원격
기본 구성 요소에는 원격 분석 메시지에 추가된 특수 속성이 필요하지 않습니다.
중첩된 구성 요소를 사용하는 경우 디바이스는 구성 요소 이름으로 메시지 속성을 설정해야 합니다.
void PnP_ThermostatComponent_SendTelemetry(
PNP_THERMOSTAT_COMPONENT_HANDLE pnpThermostatComponentHandle,
IOTHUB_DEVICE_CLIENT_LL_HANDLE deviceClientLL)
{
PNP_THERMOSTAT_COMPONENT* pnpThermostatComponent = (PNP_THERMOSTAT_COMPONENT*)pnpThermostatComponentHandle;
IOTHUB_MESSAGE_HANDLE messageHandle = NULL;
IOTHUB_CLIENT_RESULT iothubResult;
char temperatureStringBuffer[32];
if (snprintf(
temperatureStringBuffer,
sizeof(temperatureStringBuffer),
g_temperatureTelemetryBodyFormat,
pnpThermostatComponent->currentTemperature) < 0)
{
LogError("snprintf of current temperature telemetry failed");
}
else if ((messageHandle = PnP_CreateTelemetryMessageHandle(
pnpThermostatComponent->componentName, temperatureStringBuffer)) == NULL)
{
LogError("Unable to create telemetry message");
}
else if ((iothubResult = IoTHubDeviceClient_LL_SendEventAsync(
deviceClientLL, messageHandle, NULL, NULL)) != IOTHUB_CLIENT_OK)
{
LogError("Unable to send telemetry message, error=%d", iothubResult);
}
IoTHubMessage_Destroy(messageHandle);
}
// ...
PnP_ThermostatComponent_SendTelemetry(g_thermostatHandle1, deviceClient);
읽기 전용 속성
기본 구성 요소에서 속성을 보고하는 데 특별한 구문이 필요하지 않습니다.
static const char g_maxTemperatureSinceRebootFormat[] = "{\"maxTempSinceLastReboot\":%.2f}";
char maxTemperatureSinceRebootProperty[256];
snprintf(
maxTemperatureSinceRebootProperty,
sizeof(maxTemperatureSinceRebootProperty),
g_maxTemperatureSinceRebootFormat,
38.7);
IOTHUB_CLIENT_RESULT iothubClientResult = IoTHubDeviceClient_LL_SendReportedState(
deviceClientLL,
(const unsigned char*)maxTemperatureSinceRebootProperty,
strlen(maxTemperatureSinceRebootProperty), NULL, NULL));
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"maxTempSinceLastReboot" : 38.7
}
}
중첩된 구성 요소를 사용하는 경우 속성을 구성 요소 이름 내에 생성하며 마커를 포함합니다.
STRING_HANDLE PnP_CreateReportedProperty(
const char* componentName,
const char* propertyName,
const char* propertyValue
)
{
STRING_HANDLE jsonToSend;
if (componentName == NULL)
{
jsonToSend = STRING_construct_sprintf(
"{\"%s\":%s}",
propertyName, propertyValue);
}
else
{
jsonToSend = STRING_construct_sprintf(
"{\"""%s\":{\"__t\":\"c\",\"%s\":%s}}",
componentName, propertyName, propertyValue);
}
if (jsonToSend == NULL)
{
LogError("Unable to allocate JSON buffer");
}
return jsonToSend;
}
void PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(
PNP_THERMOSTAT_COMPONENT_HANDLE pnpThermostatComponentHandle,
IOTHUB_DEVICE_CLIENT_LL_HANDLE deviceClientLL)
{
PNP_THERMOSTAT_COMPONENT* pnpThermostatComponent =
(PNP_THERMOSTAT_COMPONENT*)pnpThermostatComponentHandle;
char maximumTemperatureAsString[32];
IOTHUB_CLIENT_RESULT iothubClientResult;
STRING_HANDLE jsonToSend = NULL;
if (snprintf(maximumTemperatureAsString, sizeof(maximumTemperatureAsString),
"%.2f", pnpThermostatComponent->maxTemperature) < 0)
{
LogError("Unable to create max temp since last reboot string for reporting result");
}
else if ((jsonToSend = PnP_CreateReportedProperty(
pnpThermostatComponent->componentName,
g_maxTempSinceLastRebootPropertyName,
maximumTemperatureAsString)) == NULL)
{
LogError("Unable to build max temp since last reboot property");
}
else
{
const char* jsonToSendStr = STRING_c_str(jsonToSend);
size_t jsonToSendStrLen = strlen(jsonToSendStr);
if ((iothubClientResult = IoTHubDeviceClient_LL_SendReportedState(
deviceClientLL,
(const unsigned char*)jsonToSendStr,
jsonToSendStrLen, NULL, NULL)) != IOTHUB_CLIENT_OK)
{
LogError("Unable to send reported state, error=%d", iothubClientResult);
}
else
{
LogInfo("Sending maximumTemperatureSinceLastReboot property to IoTHub for component=%s",
pnpThermostatComponent->componentName);
}
}
STRING_delete(jsonToSend);
}
// ...
PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(g_thermostatHandle1, deviceClient);
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1" : {
"__t" : "c",
"maxTemperature" : 38.7
}
}
}
쓰기 가능한 속성
이러한 속성은 디바이스에서 설정하거나 백엔드 애플리케이션에서 업데이트할 수 있습니다. 백엔드 애플리케이션에서 속성을 업데이트하면 클라이언트는 DeviceClient 또는 ModuleClient에서 콜백으로 알림을 받습니다. IoT 플러그 앤 플레이 규칙을 따르려면 디바이스에서 속성이 성공적으로 수신되었음을 서비스에 알려야 합니다.
속성 형식이 Object인 경우 서비스는 개체 필드의 하위 집합만 업데이트하는 경우에도 디바이스에 완전한 개체를 보내야 합니다. 디바이스가 보내는 승인은 완전한 개체일 수도 있습니다.
쓰기 가능한 속성 보고
디바이스에서 쓰기 가능한 속성을 보고하는 경우 규칙에 정의된 ack 값을 포함해야 합니다.
기본 구성 요소에서 쓰기 가능한 속성을 보고하려면 다음을 수행합니다.
IOTHUB_CLIENT_RESULT iothubClientResult;
char targetTemperatureResponseProperty[256];
snprintf(
targetTemperatureResponseProperty,
sizeof(targetTemperatureResponseProperty),
"{\"targetTemperature\":{\"value\":%.2f,\"ac\":%d,\"av\":%d,\"ad\":\"%s\"}}",
23.2, 200, 3, "Successfully updated target temperature");
iothubClientResult = IoTHubDeviceClient_LL_SendReportedState(
deviceClientLL,
(const unsigned char*)targetTemperatureResponseProperty,
strlen(targetTemperatureResponseProperty), NULL, NULL);
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "Successfully updated target temperature"
}
}
}
중첩된 구성 요소에서 쓰기 가능한 속성을 보고하려면 트윈에 표식이 있어야 합니다.
STRING_HANDLE PnP_CreateReportedPropertyWithStatus(const char* componentName,
const char* propertyName, const char* propertyValue,
int result, const char* description, int ackVersion
)
{
STRING_HANDLE jsonToSend;
if (componentName == NULL)
{
jsonToSend = STRING_construct_sprintf(
"{\"%s\":{\"value\":%s,\"ac\":%d,\"ad\":\"%s\",\"av\":%d}}",
propertyName, propertyValue,
result, description, ackVersion);
}
else
{
jsonToSend = STRING_construct_sprintf(
"{\"""%s\":{\"__t\":\"c\",\"%s\":{\"value\":%s,\"ac\":%d,\"ad\":\"%s\",\"av\":%d}}}",
componentName, propertyName, propertyValue,
result, description, ackVersion);
}
if (jsonToSend == NULL)
{
LogError("Unable to allocate JSON buffer");
}
return jsonToSend;
}
// ...
char targetTemperatureAsString[32];
IOTHUB_CLIENT_RESULT iothubClientResult;
STRING_HANDLE jsonToSend = NULL;
snprintf(targetTemperatureAsString,
sizeof(targetTemperatureAsString),
"%.2f",
23.2);
jsonToSend = PnP_CreateReportedPropertyWithStatus(
"thermostat1",
"targetTemperature",
targetTemperatureAsString,
200,
"complete",
3);
const char* jsonToSendStr = STRING_c_str(jsonToSend);
size_t jsonToSendStrLen = strlen(jsonToSendStr);
iothubClientResult = IoTHubDeviceClient_LL_SendReportedState(
deviceClientLL,
(const unsigned char*)jsonToSendStr,
jsonToSendStrLen, NULL, NULL);
STRING_delete(jsonToSend);
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1": {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
}
원하는 속성 업데이트 구독
서비스는 연결된 디바이스에 대한 알림을 트리거하는 원하는 속성을 업데이트할 수 있습니다. 이 알림에는 업데이트를 식별하는 버전 번호를 포함하여 업데이트된 원하는 속성이 포함됩니다. 디바이스는 서비스로 다시 전송된 ack 메시지에 이 버전 번호를 포함해야 합니다.
기본 구성 요소는 단일 속성을 보고 수신된 버전으로 보고된 ack를 만듭니다.
static void Thermostat_DeviceTwinCallback(
DEVICE_TWIN_UPDATE_STATE updateState,
const unsigned char* payload,
size_t size,
void* userContextCallback)
{
// The device handle associated with this request is passed as the context,
// since we will need to send reported events back.
IOTHUB_DEVICE_CLIENT_LL_HANDLE deviceClientLL =
(IOTHUB_DEVICE_CLIENT_LL_HANDLE)userContextCallback;
char* jsonStr = NULL;
JSON_Value* rootValue = NULL;
JSON_Object* desiredObject;
JSON_Value* versionValue = NULL;
JSON_Value* targetTemperatureValue = NULL;
jsonStr = CopyTwinPayloadToString(payload, size));
rootValue = json_parse_string(jsonStr));
desiredObject = GetDesiredJson(updateState, rootValue));
targetTemperatureValue = json_object_get_value(desiredObject, "targetTemperature"));
versionValue = json_object_get_value(desiredObject, "$version"));
json_value_get_type(versionValue);
json_value_get_type(targetTemperatureValue);
double targetTemperature = json_value_get_number(targetTemperatureValue);
int version = (int)json_value_get_number(versionValue);
// ...
// The device needs to let the service know that it has received the targetTemperature desired property.
SendTargetTemperatureReport(deviceClientLL, targetTemperature, 200, version, "Successfully updated target temperature");
json_value_free(rootValue);
free(jsonStr);
}
// ...
IOTHUB_CLIENT_RESULT iothubResult;
iothubResult = IoTHubDeviceClient_LL_SetDeviceTwinCallback(
deviceHandle, Thermostat_DeviceTwinCallback, (void*)deviceHandle))
중첩된 구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"targetTemperature": 23.2,
"$version" : 3
},
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "Successfully updated target temperature"
}
}
}
중첩된 구성 요소는 구성 요소 이름으로 래핑된 원하는 속성을 받고 ack에 의해 보고된 속성을 다시 보고해야 합니다.
bool PnP_ProcessTwinData(
DEVICE_TWIN_UPDATE_STATE updateState,
const unsigned char* payload,
size_t size, const char** componentsInModel,
size_t numComponentsInModel,
PnP_PropertyCallbackFunction pnpPropertyCallback,
void* userContextCallback)
{
char* jsonStr = NULL;
JSON_Value* rootValue = NULL;
JSON_Object* desiredObject;
bool result;
jsonStr = PnP_CopyPayloadToString(payload, size));
rootValue = json_parse_string(jsonStr));
desiredObject = GetDesiredJson(updateState, rootValue));
result = VisitDesiredObject(
desiredObject, componentsInModel,
numComponentsInModel, pnpPropertyCallback,
userContextCallback);
json_value_free(rootValue);
free(jsonStr);
return result;
}
// ...
static const char g_thermostatComponent1Name[] = "thermostat1";
static const size_t g_thermostatComponent1Size = sizeof(g_thermostatComponent1Name) - 1;
static const char g_thermostatComponent2Name[] = "thermostat2";
static const char* g_modeledComponents[] = {g_thermostatComponent1Name, g_thermostatComponent2Name};
static const size_t g_numModeledComponents = sizeof(g_modeledComponents) / sizeof(g_modeledComponents[0]);
static void PnP_TempControlComponent_DeviceTwinCallback(
DEVICE_TWIN_UPDATE_STATE updateState,
const unsigned char* payload,
size_t size,
void* userContextCallback
)
{
PnP_ProcessTwinData(
updateState, payload,
size, g_modeledComponents,
g_numModeledComponents,
PnP_TempControlComponent_ApplicationPropertyCallback,
userContextCallback);
}
중첩된 구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"thermostat1" : {
"__t" : "c",
"targetTemperature": 23.2,
}
"$version" : 3
},
"reported": {
"thermostat1" : {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
}
명령
기본 구성 요소는 서비스에서 호출된 명령 이름을 받습니다.
중첩된 구성 요소는 구성 요소 이름과 * 구분 기호가 접두사로 붙은 명령 이름을 받습니다.
void PnP_ParseCommandName(
const char* deviceMethodName,
unsigned const char** componentName,
size_t* componentNameSize,
const char** pnpCommandName
)
{
const char* separator;
if ((separator = strchr(deviceMethodName, "*")) != NULL)
{
*componentName = (unsigned const char*)deviceMethodName;
*componentNameSize = separator - deviceMethodName;
*pnpCommandName = separator + 1;
}
else
{
*componentName = NULL;
*componentNameSize = 0;
*pnpCommandName = deviceMethodName;
}
}
static int PnP_TempControlComponent_DeviceMethodCallback(
const char* methodName,
const unsigned char* payload,
size_t size,
unsigned char** response,
size_t* responseSize,
void* userContextCallback)
{
(void)userContextCallback;
char* jsonStr = NULL;
JSON_Value* rootValue = NULL;
int result;
unsigned const char *componentName;
size_t componentNameSize;
const char *pnpCommandName;
*response = NULL;
*responseSize = 0;
// Parse the methodName into its componentName and CommandName.
PnP_ParseCommandName(methodName, &componentName, &componentNameSize, &pnpCommandName);
// Parse the JSON of the payload request.
jsonStr = PnP_CopyPayloadToString(payload, size));
rootValue = json_parse_string(jsonStr));
if (componentName != NULL)
{
if (strncmp((const char*)componentName, g_thermostatComponent1Name, g_thermostatComponent1Size) == 0)
{
result = PnP_ThermostatComponent_ProcessCommand(g_thermostatHandle1, pnpCommandName, rootValue, response, responseSize);
}
else if (strncmp((const char*)componentName, g_thermostatComponent2Name, g_thermostatComponent2Size) == 0)
{
result = PnP_ThermostatComponent_ProcessCommand(g_thermostatHandle2, pnpCommandName, rootValue, response, responseSize);
}
else
{
LogError("PnP component=%.*s is not supported by TemperatureController", (int)componentNameSize, componentName);
result = PNP_STATUS_NOT_FOUND;
}
}
else
{
LogInfo("Received PnP command for TemperatureController component, command=%s", pnpCommandName);
if (strcmp(pnpCommandName, g_rebootCommand) == 0)
{
result = PnP_TempControlComponent_InvokeRebootCommand(rootValue);
}
else
{
LogError("PnP command=s%s is not supported by TemperatureController", pnpCommandName);
result = PNP_STATUS_NOT_FOUND;
}
}
if (*response == NULL)
{
SetEmptyCommandResponse(response, responseSize, &result);
}
json_value_free(rootValue);
free(jsonStr);
return result;
}
// ...
PNP_DEVICE_CONFIGURATION g_pnpDeviceConfiguration;
g_pnpDeviceConfiguration.deviceMethodCallback = PnP_TempControlComponent_DeviceMethodCallback;
deviceClient = PnP_CreateDeviceClientLLHandle(&g_pnpDeviceConfiguration);
요청 및 응답 페이로드
명령은 형식을 사용하여 요청 및 응답 페이로드를 정의합니다. 디바이스는 들어오는 입력 매개 변수를 역직렬화하고 응답을 직렬화해야 합니다.
다음 예제에서는 페이로드에 정의된 복합 형식을 사용하여 명령을 구현하는 방법을 보여줍니다.
{
"@type": "Command",
"name": "getMaxMinReport",
"displayName": "Get Max-Min report.",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"request": {
"name": "since",
"displayName": "Since",
"description": "Period to return the max-min report.",
"schema": "dateTime"
},
"response": {
"name" : "tempReport",
"displayName": "Temperature Report",
"schema": {
"@type": "Object",
"fields": [
{
"name": "maxTemp",
"displayName": "Max temperature",
"schema": "double"
},
{
"name": "minTemp",
"displayName": "Min temperature",
"schema": "double"
},
{
"name" : "avgTemp",
"displayName": "Average Temperature",
"schema": "double"
},
{
"name" : "startTime",
"displayName": "Start Time",
"schema": "dateTime"
},
{
"name" : "endTime",
"displayName": "End Time",
"schema": "dateTime"
}
]
}
}
}
다음 코드 조각은 직렬화 및 역직렬화를 활성화하는 데 사용되는 형식을 포함하여 디바이스가 이 명령 정의를 구현하는 방법을 보여줍니다.
static const char g_maxMinCommandResponseFormat[] = "{\"maxTemp\":%.2f,\"minTemp\":%.2f,\"avgTemp\":%.2f,\"startTime\":\"%s\",\"endTime\":\"%s\"}";
// ...
static bool BuildMaxMinCommandResponse(
PNP_THERMOSTAT_COMPONENT* pnpThermostatComponent,
unsigned char** response,
size_t* responseSize)
{
int responseBuilderSize = 0;
unsigned char* responseBuilder = NULL;
bool result;
char currentTime[TIME_BUFFER_SIZE];
BuildUtcTimeFromCurrentTime(currentTime, sizeof(currentTime));
responseBuilderSize = snprintf(NULL, 0, g_maxMinCommandResponseFormat,
pnpThermostatComponent->maxTemperature,
pnpThermostatComponent->minTemperature,
pnpThermostatComponent->allTemperatures /
pnpThermostatComponent->numTemperatureUpdates,
g_programStartTime, currentTime));
responseBuilder = calloc(1, responseBuilderSize + 1));
responseBuilderSize = snprintf(
(char*)responseBuilder, responseBuilderSize + 1, g_maxMinCommandResponseFormat,
pnpThermostatComponent->maxTemperature,
pnpThermostatComponent->minTemperature,
pnpThermostatComponent->allTemperatures / pnpThermostatComponent->numTemperatureUpdates,
g_programStartTime,
currentTime));
*response = responseBuilder;
*responseSize = (size_t)responseBuilderSize;
return true;
}
팁
유선을 통해 전송되는 직렬화된 페이로드에 요청 및 응답 이름이 없습니다.
SDK
이 문서의 코드 조각은 Eclipse ThreadX용 Azure IoT 미들웨어 추가 기능을 사용하는 샘플을 기반으로 합니다. 추가 기능은 Eclipse ThreadX와 Embedded C용 Azure SDK 사이의 바인딩 계층입니다.
이 문서의 코드 조각은 다음 샘플을 기반으로 합니다.
모델 ID 알림
모델 ID를 알리려면 디바이스가 연결 정보에 해당 ID를 포함해야 합니다.
#include "nx_azure_iot_hub_client.h"
// ...
#define SAMPLE_PNP_MODEL_ID "dtmi:com:example:Thermostat;1"
// ...
status = nx_azure_iot_hub_client_model_id_set(iothub_client_ptr, (UCHAR *)SAMPLE_PNP_MODEL_ID, sizeof(SAMPLE_PNP_MODEL_ID) - 1);
팁
디바이스가 모델 ID를 설정할 수 있는 유일한 시간이며 디바이스가 연결된 후에는 업데이트할 수 없습니다.
DPS 페이로드
DPS(Device Provisioning Service)를 사용하는 디바이스에는 다음 JSON 페이로드를 사용하는 프로비저닝 프로세스 중에 사용할 modelId가 포함될 수 있습니다.
{
"modelId" : "dtmi:com:example:Thermostat;1"
}
샘플에서는 다음 코드를 사용하여 이 페이로드를 보냅니다.
#include "nx_azure_iot_provisioning_client.h"
// ...
#define SAMPLE_PNP_MODEL_ID "dtmi:com:example:Thermostat;1"
#define SAMPLE_PNP_DPS_PAYLOAD "{\"modelId\":\"" SAMPLE_PNP_MODEL_ID "\"}"
// ...
status = nx_azure_iot_provisioning_client_registration_payload_set(prov_client_ptr, (UCHAR *)SAMPLE_PNP_DPS_PAYLOAD, sizeof(SAMPLE_PNP_DPS_PAYLOAD) - 1);
구성 요소 사용
IoT 플러그 앤 플레이 모델의 구성 요소 이해에 설명된 대로 구성 요소를 사용하여 디바이스를 설명할지 결정해야 합니다. 구성 요소를 사용하는 경우 디바이스는 다음 섹션에 설명된 규칙을 따라야 합니다. 구성 요소에 대한 IoT 플러그 앤 플레이 규칙 작업을 간소화하기 위해 샘플은 nx_azure_iot_hub_client.h의 도우미 함수를 사용합니다.
원격
기본 구성 요소에는 원격 분석 메시지에 추가된 특수 속성이 필요하지 않습니다.
중첩된 구성 요소를 사용하는 경우 디바이스는 구성 요소 이름으로 메시지 속성을 설정해야 합니다. 다음 코드 조각에서 component_name_ptr은 thermostat1과 같은 구성 요소의 이름입니다. nx_azure_iot_pnp_helpers.h에 정의된 도우미 함수 nx_azure_iot_pnp_helper_telemetry_message_create는 구성 요소 이름으로 메시지 속성을 추가합니다.
#include "nx_azure_iot_pnp_helpers.h"
// ...
static const CHAR telemetry_name[] = "temperature";
// ...
UINT sample_pnp_thermostat_telemetry_send(SAMPLE_PNP_THERMOSTAT_COMPONENT *handle, NX_AZURE_IOT_HUB_CLIENT *iothub_client_ptr)
{
UINT status;
NX_PACKET *packet_ptr;
NX_AZURE_IOT_JSON_WRITER json_writer;
UINT buffer_length;
// ...
/* Create a telemetry message packet. */
if ((status = nx_azure_iot_pnp_helper_telemetry_message_create(iothub_client_ptr, handle -> component_name_ptr,
handle -> component_name_length,
&packet_ptr, NX_WAIT_FOREVER)))
{
// ...
}
// ...
if ((status = nx_azure_iot_hub_client_telemetry_send(iothub_client_ptr, packet_ptr,
(UCHAR *)scratch_buffer, buffer_length, NX_WAIT_FOREVER)))
{
// ...
}
// ...
return(status);
}
읽기 전용 속성
기본 구성 요소에서 속성을 보고하는 데 특별한 구문이 필요하지 않습니다.
#include "nx_azure_iot_hub_client.h"
#include "nx_azure_iot_json_writer.h"
// ...
static const CHAR reported_max_temp_since_last_reboot[] = "maxTempSinceLastReboot";
// ...
static UINT sample_build_reported_property(NX_AZURE_IOT_JSON_WRITER *json_builder_ptr, double temp)
{
UINT ret;
if (nx_azure_iot_json_writer_append_begin_object(json_builder_ptr) ||
nx_azure_iot_json_writer_append_property_with_double_value(json_builder_ptr,
(UCHAR *)reported_max_temp_since_last_reboot,
sizeof(reported_max_temp_since_last_reboot) - 1,
temp, DOUBLE_DECIMAL_PLACE_DIGITS) ||
nx_azure_iot_json_writer_append_end_object(json_builder_ptr))
{
ret = 1;
printf("Failed to build reported property\r\n");
}
else
{
ret = 0;
}
return(ret);
}
// ...
if ((status = sample_build_reported_property(&json_builder, device_max_temp)))
{
// ...
}
reported_properties_length = nx_azure_iot_json_writer_get_bytes_used(&json_builder);
if ((status = nx_azure_iot_hub_client_device_twin_reported_properties_send(&(context -> iothub_client),
scratch_buffer,
reported_properties_length,
&request_id, &response_status,
&reported_property_version,
(5 * NX_IP_PERIODIC_RATE))))
{
// ...
}
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"maxTempSinceLastReboot" : 38.7
}
}
중첩된 구성 요소를 사용하는 경우 속성은 구성 요소 이름 내에 생성되어야 하며 마커를 포함해야 합니다. 다음 코드 조각에서 component_name_ptr은 thermostat1과 같은 구성 요소의 이름입니다. nx_azure_iot_pnp_helpers.h에 정의된 도우미 함수 nx_azure_iot_pnp_helper_build_reported_property는 보고되는 속성을 올바른 형식으로 만듭니다.
#include "nx_azure_iot_pnp_helpers.h"
// ...
static const CHAR reported_max_temp_since_last_reboot[] = "maxTempSinceLastReboot";
UINT sample_pnp_thermostat_report_max_temp_since_last_reboot_property(SAMPLE_PNP_THERMOSTAT_COMPONENT *handle, NX_AZURE_IOT_HUB_CLIENT *iothub_client_ptr)
{
UINT reported_properties_length;
UINT status;
UINT response_status;
UINT request_id;
NX_AZURE_IOT_JSON_WRITER json_builder;
ULONG reported_property_version;
// ...
if ((status = nx_azure_iot_pnp_helper_build_reported_property(handle -> component_name_ptr,
handle -> component_name_length,
append_max_temp, (VOID *)handle,
&json_builder)))
{
// ...
}
reported_properties_length = nx_azure_iot_json_writer_get_bytes_used(&json_builder);
if ((status = nx_azure_iot_hub_client_device_twin_reported_properties_send(iothub_client_ptr,
scratch_buffer,
reported_properties_length,
&request_id, &response_status,
&reported_property_version,
(5 * NX_IP_PERIODIC_RATE))))
{
// ...
}
// ...
}
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1" : {
"__t" : "c",
"maxTemperature" : 38.7
}
}
}
쓰기 가능한 속성
이러한 속성은 디바이스에서 설정하거나 백엔드 애플리케이션에서 업데이트할 수 있습니다. IoT 플러그 앤 플레이 규칙을 따르려면 디바이스에서 속성이 성공적으로 수신되었음을 서비스에 알려야 합니다.
쓰기 가능한 속성 보고
디바이스에서 쓰기 가능한 속성을 보고하는 경우 규칙에 정의된 ack 값을 포함해야 합니다.
기본 구성 요소에서 쓰기 가능한 속성을 보고하려면 다음을 수행합니다.
#include "nx_azure_iot_hub_client.h"
#include "nx_azure_iot_json_writer.h"
// ...
static const CHAR reported_temp_property_name[] = "targetTemperature";
static const CHAR reported_value_property_name[] = "value";
static const CHAR reported_status_property_name[] = "ac";
static const CHAR reported_version_property_name[] = "av";
static const CHAR reported_description_property_name[] = "ad";
// ...
static VOID sample_send_target_temperature_report(SAMPLE_CONTEXT *context, double current_device_temp_value,
UINT status, UINT version, UCHAR *description_ptr,
UINT description_len)
{
NX_AZURE_IOT_JSON_WRITER json_builder;
UINT bytes_copied;
UINT response_status;
UINT request_id;
ULONG reported_property_version;
// ...
if (nx_azure_iot_json_writer_append_begin_object(&json_builder) ||
nx_azure_iot_json_writer_append_property_name(&json_builder,
(UCHAR *)reported_temp_property_name,
sizeof(reported_temp_property_name) - 1) ||
nx_azure_iot_json_writer_append_begin_object(&json_builder) ||
nx_azure_iot_json_writer_append_property_with_double_value(&json_builder,
(UCHAR *)reported_value_property_name,
sizeof(reported_value_property_name) - 1,
current_device_temp_value, DOUBLE_DECIMAL_PLACE_DIGITS) ||
nx_azure_iot_json_writer_append_property_with_int32_value(&json_builder,
(UCHAR *)reported_status_property_name,
sizeof(reported_status_property_name) - 1,
(int32_t)status) ||
nx_azure_iot_json_writer_append_property_with_int32_value(&json_builder,
(UCHAR *)reported_version_property_name,
sizeof(reported_version_property_name) - 1,
(int32_t)version) ||
nx_azure_iot_json_writer_append_property_with_string_value(&json_builder,
(UCHAR *)reported_description_property_name,
sizeof(reported_description_property_name) - 1,
description_ptr, description_len) ||
nx_azure_iot_json_writer_append_end_object(&json_builder) ||
nx_azure_iot_json_writer_append_end_object(&json_builder))
{
// ...
}
else
// ...
}
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "success"
}
}
}
중첩된 구성 요소에서 쓰기 가능한 속성을 보고하려면 트윈에 표식이 포함되어야 하며 구성 요소 이름 내에 속성을 만들어야 합니다. 다음 코드 조각에서 component_name_ptr은 thermostat1과 같은 구성 요소의 이름입니다. nx_azure_iot_pnp_helpers.h에 정의된 도우미 함수 nx_azure_iot_pnp_helper_build_reported_property_with_status는 보고되는 속성 페이로드를 만듭니다.
#include "nx_azure_iot_pnp_helpers.h"
// ...
static VOID sample_send_target_temperature_report(SAMPLE_PNP_THERMOSTAT_COMPONENT *handle,
NX_AZURE_IOT_HUB_CLIENT *iothub_client_ptr, double temp,
INT status_code, UINT version, const CHAR *description)
{
UINT bytes_copied;
UINT response_status;
UINT request_id;
NX_AZURE_IOT_JSON_WRITER json_writer;
ULONG reported_property_version;
// ...
if (nx_azure_iot_pnp_helper_build_reported_property_with_status(handle -> component_name_ptr, handle -> component_name_length,
(UCHAR *)target_temp_property_name,
sizeof(target_temp_property_name) - 1,
append_temp, (VOID *)&temp, status_code,
(UCHAR *)description,
strlen(description), version, &json_writer))
{
// ...
}
else
{
// ...
}
// ...
}
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1": {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "success"
}
}
}
}
원하는 속성 업데이트 구독
서비스는 연결된 디바이스에 대한 알림을 트리거하는 원하는 속성을 업데이트할 수 있습니다. 이 알림에는 업데이트된 원하는 속성과 업데이트를 식별하는 버전 번호가 포함됩니다. 디바이스는 서비스로 다시 전송된 ack 메시지에 이 버전 번호를 포함해야 합니다.
기본 구성 요소는 단일 속성을 보고 수신된 버전으로 보고된 ack를 만듭니다.
#include "nx_azure_iot_hub_client.h"
#include "nx_azure_iot_json_writer.h"
// ...
static const CHAR temp_response_description[] = "success";
// ...
static UINT sample_parse_desired_temp_property(SAMPLE_CONTEXT *context,
NX_AZURE_IOT_JSON_READER *json_reader_ptr,
UINT is_partial)
{
double parsed_value;
UINT version;
NX_AZURE_IOT_JSON_READER copy_json_reader;
UINT status;
// ...
copy_json_reader = *json_reader_ptr;
if (sample_json_child_token_move(©_json_reader,
(UCHAR *)desired_version_property_name,
sizeof(desired_version_property_name) - 1) ||
nx_azure_iot_json_reader_token_int32_get(©_json_reader, (int32_t *)&version))
{
// ...
}
// ...
sample_send_target_temperature_report(context, current_device_temp, 200,
(UINT)version, (UCHAR *)temp_response_description,
sizeof(temp_response_description) - 1);
// ...
}
중첩된 구성 요소는 구성 요소 이름으로 래핑된 원하는 속성을 수신하고 수신된 버전으로 보고된 ack를 생성합니다.
#include "nx_azure_iot_pnp_helpers.h"
// ...
static const CHAR target_temp_property_name[] = "targetTemperature";
static const CHAR temp_response_description_success[] = "success";
static const CHAR temp_response_description_failed[] = "failed";
// ...
UINT sample_pnp_thermostat_process_property_update(SAMPLE_PNP_THERMOSTAT_COMPONENT *handle,
NX_AZURE_IOT_HUB_CLIENT *iothub_client_ptr,
UCHAR *component_name_ptr, UINT component_name_length,
UCHAR *property_name_ptr, UINT property_name_length,
NX_AZURE_IOT_JSON_READER *property_value_reader_ptr, UINT version)
{
double parsed_value = 0;
INT status_code;
const CHAR *description;
// ...
if (property_name_length != (sizeof(target_temp_property_name) - 1) ||
strncmp((CHAR *)property_name_ptr, (CHAR *)target_temp_property_name, property_name_length) != 0)
{
// ...
}
else if (nx_azure_iot_json_reader_token_double_get(property_value_reader_ptr, &parsed_value))
{
status_code = 401;
description = temp_response_description_failed;
}
else
{
status_code = 200;
description = temp_response_description_success;
// ...
}
sample_send_target_temperature_report(handle, iothub_client_ptr, parsed_value,
status_code, version, description);
// ...
}
중첩된 구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"thermostat1" : {
"__t" : "c",
"targetTemperature": 23.2,
}
"$version" : 3
},
"reported": {
"thermostat1" : {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "success"
}
}
}
}
명령
기본 구성 요소는 서비스에서 호출된 명령 이름을 받습니다.
중첩된 구성 요소는 구성 요소 이름과 * 구분 기호가 접두사로 붙은 명령 이름을 받습니다. 다음 코드 조각에서 nx_azure_iot_pnp_helpers.h에 정의된 도우미 함수 nx_azure_iot_pnp_helper_command_name_parse는 디바이스가 서비스에서 수신하는 메시지에서 구성 요소 이름과 명령 이름을 구문 분석합니다.
#include "nx_azure_iot_hub_client.h"
#include "nx_azure_iot_pnp_helpers.h"
// ...
static VOID sample_direct_method_action(SAMPLE_CONTEXT *sample_context_ptr)
{
NX_PACKET *packet_ptr;
UINT status;
USHORT method_name_length;
const UCHAR *method_name_ptr;
USHORT context_length;
VOID *context_ptr;
UINT component_name_length;
const UCHAR *component_name_ptr;
UINT pnp_command_name_length;
const UCHAR *pnp_command_name_ptr;
NX_AZURE_IOT_JSON_WRITER json_writer;
NX_AZURE_IOT_JSON_READER json_reader;
NX_AZURE_IOT_JSON_READER *json_reader_ptr;
UINT status_code;
UINT response_length;
// ...
if ((status = nx_azure_iot_hub_client_direct_method_message_receive(&(sample_context_ptr -> iothub_client),
&method_name_ptr, &method_name_length,
&context_ptr, &context_length,
&packet_ptr, NX_WAIT_FOREVER)))
{
// ...
}
// ...
if ((status = nx_azure_iot_pnp_helper_command_name_parse(method_name_ptr, method_name_length,
&component_name_ptr, &component_name_length,
&pnp_command_name_ptr,
&pnp_command_name_length)) != NX_AZURE_IOT_SUCCESS)
{
// ...
}
// ...
else
{
// ...
if ((status = sample_pnp_thermostat_process_command(&sample_thermostat_1, component_name_ptr,
component_name_length, pnp_command_name_ptr,
pnp_command_name_length, json_reader_ptr,
&json_writer, &status_code)) == NX_AZURE_IOT_SUCCESS)
{
// ...
}
else if ((status = sample_pnp_thermostat_process_command(&sample_thermostat_2, component_name_ptr,
component_name_length, pnp_command_name_ptr,
pnp_command_name_length, json_reader_ptr,
&json_writer, &status_code)) == NX_AZURE_IOT_SUCCESS)
{
// ...
}
else if((status = sample_pnp_temp_controller_process_command(component_name_ptr, component_name_length,
pnp_command_name_ptr, pnp_command_name_length,
json_reader_ptr, &json_writer,
&status_code)) == NX_AZURE_IOT_SUCCESS)
{
// ...
}
else
{
printf("Failed to find any handler for method %.*s\r\n", method_name_length, method_name_ptr);
status_code = SAMPLE_COMMAND_NOT_FOUND_STATUS;
response_length = 0;
}
// ...
}
}
요청 및 응답 페이로드
명령은 형식을 사용하여 요청 및 응답 페이로드를 정의합니다. 디바이스는 들어오는 입력 매개 변수를 역직렬화하고 응답을 직렬화해야 합니다.
다음 예제에서는 페이로드에 정의된 복합 형식을 사용하여 명령을 구현하는 방법을 보여줍니다.
{
"@type": "Command",
"name": "getMaxMinReport",
"displayName": "Get Max-Min report.",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"request": {
"name": "since",
"displayName": "Since",
"description": "Period to return the max-min report.",
"schema": "dateTime"
},
"response": {
"name" : "tempReport",
"displayName": "Temperature Report",
"schema": {
"@type": "Object",
"fields": [
{
"name": "maxTemp",
"displayName": "Max temperature",
"schema": "double"
},
{
"name": "minTemp",
"displayName": "Min temperature",
"schema": "double"
},
{
"name" : "avgTemp",
"displayName": "Average Temperature",
"schema": "double"
},
{
"name" : "startTime",
"displayName": "Start Time",
"schema": "dateTime"
},
{
"name" : "endTime",
"displayName": "End Time",
"schema": "dateTime"
}
]
}
}
}
다음 코드 조각은 직렬화 및 역직렬화를 활성화하는 데 사용되는 형식을 포함하여 디바이스가 이 명령 정의를 구현하는 방법을 보여줍니다.
#include "nx_azure_iot_pnp_helpers.h"
// ...
static const CHAR report_max_temp_name[] = "maxTemp";
static const CHAR report_min_temp_name[] = "minTemp";
static const CHAR report_avg_temp_name[] = "avgTemp";
static const CHAR report_start_time_name[] = "startTime";
static const CHAR report_end_time_name[] = "endTime";
static const CHAR fake_start_report_time[] = "2020-01-10T10:00:00Z";
static const CHAR fake_end_report_time[] = "2023-01-10T10:00:00Z";
// ...
static UINT sample_get_maxmin_report(SAMPLE_PNP_THERMOSTAT_COMPONENT *handle,
NX_AZURE_IOT_JSON_READER *json_reader_ptr,
NX_AZURE_IOT_JSON_WRITER *out_json_builder_ptr)
{
UINT status;
UCHAR *start_time = (UCHAR *)fake_start_report_time;
UINT start_time_len = sizeof(fake_start_report_time) - 1;
UCHAR time_buf[32];
// ...
/* Build the method response payload */
if (nx_azure_iot_json_writer_append_begin_object(out_json_builder_ptr) ||
nx_azure_iot_json_writer_append_property_with_double_value(out_json_builder_ptr,
(UCHAR *)report_max_temp_name,
sizeof(report_max_temp_name) - 1,
handle -> maxTemperature,
DOUBLE_DECIMAL_PLACE_DIGITS) ||
nx_azure_iot_json_writer_append_property_with_double_value(out_json_builder_ptr,
(UCHAR *)report_min_temp_name,
sizeof(report_min_temp_name) - 1,
handle -> minTemperature,
DOUBLE_DECIMAL_PLACE_DIGITS) ||
nx_azure_iot_json_writer_append_property_with_double_value(out_json_builder_ptr,
(UCHAR *)report_avg_temp_name,
sizeof(report_avg_temp_name) - 1,
handle -> avgTemperature,
DOUBLE_DECIMAL_PLACE_DIGITS) ||
nx_azure_iot_json_writer_append_property_with_string_value(out_json_builder_ptr,
(UCHAR *)report_start_time_name,
sizeof(report_start_time_name) - 1,
(UCHAR *)start_time, start_time_len) ||
nx_azure_iot_json_writer_append_property_with_string_value(out_json_builder_ptr,
(UCHAR *)report_end_time_name,
sizeof(report_end_time_name) - 1,
(UCHAR *)fake_end_report_time,
sizeof(fake_end_report_time) - 1) ||
nx_azure_iot_json_writer_append_end_object(out_json_builder_ptr))
{
status = NX_NOT_SUCCESSFUL;
}
else
{
status = NX_AZURE_IOT_SUCCESS;
}
return(status);
}
팁
유선을 통해 전송되는 직렬화된 페이로드에 요청 및 응답 이름이 없습니다.
모델 ID 알림
모델 ID를 알리려면 디바이스가 연결 정보에 해당 ID를 포함해야 합니다.
DeviceClient.CreateFromConnectionString(
connectionString,
TransportType.Mqtt,
new ClientOptions() { ModelId = modelId })
연결을 초기화하는 데 사용되는 모든 DeviceClient 메서드에서 새 ClientOptions 오버로드를 사용할 수 있습니다.
팁
모듈 및 IoT Edge의 경우 ModuleClient 대신 DeviceClient를 사용합니다.
팁
디바이스가 모델 ID를 설정할 수 있는 유일한 시간이며 디바이스가 연결된 후에는 업데이트할 수 없습니다.
DPS 페이로드
DPS(Device Provisioning Service)를 사용하는 디바이스에는 다음 JSON 페이로드를 사용하는 프로비저닝 프로세스 중에 사용할 modelId가 포함될 수 있습니다.
{
"modelId" : "dtmi:com:example:Thermostat;1"
}
구성 요소 사용
IoT 플러그 앤 플레이 모델의 구성 요소 이해에 설명된 대로 구성 요소를 사용하여 디바이스를 설명할지 결정해야 합니다. 구성 요소를 사용하는 경우 디바이스는 다음 섹션에 설명된 규칙을 따라야 합니다.
원격
기본 구성 요소에는 원격 분석 메시지에 추가된 특수 속성이 필요하지 않습니다.
중첩된 구성 요소를 사용하는 경우 디바이스는 구성 요소 이름으로 메시지 속성을 설정해야 합니다.
public async Task SendComponentTelemetryValueAsync(string componentName, string serializedTelemetry)
{
var message = new Message(Encoding.UTF8.GetBytes(serializedTelemetry));
message.ComponentName = componentName;
message.ContentType = "application/json";
message.ContentEncoding = "utf-8";
await client.SendEventAsync(message);
}
읽기 전용 속성
기본 구성 요소에서 속성을 보고하는 데 특별한 구문이 필요하지 않습니다.
TwinCollection reportedProperties = new TwinCollection();
reportedProperties["maxTemperature"] = 38.7;
await client.UpdateReportedPropertiesAsync(reportedProperties);
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"maxTemperature" : 38.7
}
}
중첩된 구성 요소를 사용하는 경우 속성을 구성 요소 이름 내에 생성하며 마커를 포함합니다.
TwinCollection reportedProperties = new TwinCollection();
TwinCollection component = new TwinCollection();
component["maxTemperature"] = 38.7;
component["__t"] = "c"; // marker to identify a component
reportedProperties["thermostat1"] = component;
await client.UpdateReportedPropertiesAsync(reportedProperties);
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1" : {
"__t" : "c",
"maxTemperature" : 38.7
}
}
}
쓰기 가능한 속성
이러한 속성은 디바이스에서 설정하거나 백엔드 애플리케이션에서 업데이트할 수 있습니다. 백엔드 애플리케이션에서 속성을 업데이트하면 클라이언트는 DeviceClient 또는 ModuleClient에서 콜백으로 알림을 받습니다. IoT 플러그 앤 플레이 규칙을 따르려면 디바이스에서 속성이 성공적으로 수신되었음을 서비스에 알려야 합니다.
속성 형식이 Object인 경우 서비스는 개체 필드의 하위 집합만 업데이트하는 경우에도 디바이스에 완전한 개체를 보내야 합니다. 디바이스가 보내는 승인도 완전한 개체여야 합니다.
쓰기 가능한 속성 보고
디바이스에서 쓰기 가능한 속성을 보고하는 경우 규칙에 정의된 ack 값을 포함해야 합니다.
기본 구성 요소에서 쓰기 가능한 속성을 보고하려면 다음을 수행합니다.
TwinCollection reportedProperties = new TwinCollection();
TwinCollection ackProps = new TwinCollection();
ackProps["value"] = 23.2;
ackProps["ac"] = 200; // using HTTP status codes
ackProps["av"] = 0; // not readed from a desired property
ackProps["ad"] = "reported default value";
reportedProperties["targetTemperature"] = ackProps;
await client.UpdateReportedPropertiesAsync(reportedProperties);
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
중첩된 구성 요소에서 쓰기 가능한 속성을 보고하려면 트윈에 표식이 있어야 합니다.
TwinCollection reportedProperties = new TwinCollection();
TwinCollection component = new TwinCollection();
TwinCollection ackProps = new TwinCollection();
component["__t"] = "c"; // marker to identify a component
ackProps["value"] = 23.2;
ackProps["ac"] = 200; // using HTTP status codes
ackProps["av"] = 0; // not read from a desired property
ackProps["ad"] = "reported default value";
component["targetTemperature"] = ackProps;
reportedProperties["thermostat1"] = component;
await client.UpdateReportedPropertiesAsync(reportedProperties);
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1": {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
}
원하는 속성 업데이트 구독
서비스는 연결된 디바이스에 대한 알림을 트리거하는 원하는 속성을 업데이트할 수 있습니다. 이 알림에는 업데이트를 식별하는 버전 번호를 포함하여 업데이트된 원하는 속성이 포함됩니다. 디바이스는 서비스로 다시 전송된 ack 메시지에 이 버전 번호를 포함해야 합니다.
기본 구성 요소는 단일 속성을 보고 수신된 버전으로 보고된 ack를 만듭니다.
await client.SetDesiredPropertyUpdateCallbackAsync(async (desired, ctx) =>
{
JValue targetTempJson = desired["targetTemperature"];
double targetTemperature = targetTempJson.Value<double>();
TwinCollection reportedProperties = new TwinCollection();
TwinCollection ackProps = new TwinCollection();
ackProps["value"] = targetTemperature;
ackProps["ac"] = 200;
ackProps["av"] = desired.Version;
ackProps["ad"] = "desired property received";
reportedProperties["targetTemperature"] = ackProps;
await client.UpdateReportedPropertiesAsync(reportedProperties);
}, null);
중첩된 구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"targetTemperature": 23.2,
"$version" : 3
},
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
중첩된 구성 요소는 구성 요소 이름으로 래핑된 원하는 속성을 받고 ack에 의해 보고된 속성을 다시 보고해야 합니다.
await client.SetDesiredPropertyUpdateCallbackAsync(async (desired, ctx) =>
{
JObject thermostatComponent = desired["thermostat1"];
JToken targetTempProp = thermostatComponent["targetTemperature"];
double targetTemperature = targetTempProp.Value<double>();
TwinCollection reportedProperties = new TwinCollection();
TwinCollection component = new TwinCollection();
TwinCollection ackProps = new TwinCollection();
component["__t"] = "c"; // marker to identify a component
ackProps["value"] = targetTemperature;
ackProps["ac"] = 200; // using HTTP status codes
ackProps["av"] = desired.Version; // not readed from a desired property
ackProps["ad"] = "desired property received";
component["targetTemperature"] = ackProps;
reportedProperties["thermostat1"] = component;
await client.UpdateReportedPropertiesAsync(reportedProperties);
}, null);
중첩된 구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"thermostat1" : {
"__t" : "c",
"targetTemperature": 23.2,
}
"$version" : 3
},
"reported": {
"thermostat1" : {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
}
명령
기본 구성 요소는 서비스에서 호출된 명령 이름을 받습니다.
중첩된 구성 요소는 구성 요소 이름과 * 구분 기호가 접두사로 붙은 명령 이름을 받습니다.
await client.SetMethodHandlerAsync("themostat*reboot", (MethodRequest req, object ctx) =>
{
Console.WriteLine("REBOOT");
return Task.FromResult(new MethodResponse(200));
},
null);
요청 및 응답 페이로드
명령은 형식을 사용하여 요청 및 응답 페이로드를 정의합니다. 디바이스는 들어오는 입력 매개 변수를 역직렬화하고 응답을 직렬화해야 합니다.
다음 예제에서는 페이로드에 정의된 복합 형식을 사용하여 명령을 구현하는 방법을 보여줍니다.
{
"@type": "Command",
"name": "start",
"request": {
"name": "startRequest",
"schema": {
"@type": "Object",
"fields": [
{
"name": "startPriority",
"schema": "integer"
},
{
"name": "startMessage",
"schema" : "string"
}
]
}
},
"response": {
"name": "startReponse",
"schema": {
"@type": "Object",
"fields": [
{
"name": "startupTime",
"schema": "integer"
},
{
"name": "startupMessage",
"schema": "string"
}
]
}
}
}
다음 코드 조각은 직렬화 및 역직렬화를 활성화하는 데 사용되는 형식을 포함하여 디바이스가 이 명령 정의를 구현하는 방법을 보여줍니다.
class startRequest
{
public int startPriority { get; set; }
public string startMessage { get; set; }
}
class startResponse
{
public int startupTime { get; set; }
public string startupMessage { get; set; }
}
// ...
await client.SetMethodHandlerAsync("start", (MethodRequest req, object ctx) =>
{
var startRequest = JsonConvert.DeserializeObject<startRequest>(req.DataAsJson);
Console.WriteLine($"Received start command with priority ${startRequest.startPriority} and ${startRequest.startMessage}");
var startResponse = new startResponse
{
startupTime = 123,
startupMessage = "device started with message " + startRequest.startMessage
};
string responsePayload = JsonConvert.SerializeObject(startResponse);
MethodResponse response = new MethodResponse(Encoding.UTF8.GetBytes(responsePayload), 200);
return Task.FromResult(response);
},null);
팁
유선을 통해 전송되는 직렬화된 페이로드에 요청 및 응답 이름이 없습니다.
모델 ID 알림
모델 ID를 알리려면 디바이스가 연결 정보에 해당 ID를 포함해야 합니다.
ClientOptions options = new ClientOptions();
options.setModelId(MODEL_ID);
deviceClient = new DeviceClient(deviceConnectionString, protocol, options);
연결을 초기화하는 데 사용되는 모든 DeviceClient 메서드에서 ClientOptions 오버로드를 사용할 수 있습니다.
팁
모듈 및 IoT Edge의 경우 ModuleClient 대신 DeviceClient를 사용합니다.
팁
디바이스가 모델 ID를 설정할 수 있는 유일한 시간이며 디바이스가 연결된 후에는 업데이트할 수 없습니다.
DPS 페이로드
DPS(Device Provisioning Service)를 사용하는 디바이스에는 다음 JSON 페이로드를 사용하는 프로비저닝 프로세스 중에 사용할 modelId가 포함될 수 있습니다.
{
"modelId" : "dtmi:com:example:Thermostat;1"
}
구성 요소 사용
IoT 플러그 앤 플레이 모델의 구성 요소 이해에 설명된 대로 구성 요소를 사용하여 디바이스를 설명할지 결정해야 합니다. 구성 요소를 사용하는 경우 디바이스는 다음 섹션에 설명된 규칙을 따라야 합니다.
원격
기본 구성 요소에는 원격 분석 메시지에 추가된 특수 속성이 필요하지 않습니다.
중첩된 구성 요소를 사용하는 경우 디바이스는 구성 요소 이름으로 메시지 속성을 설정해야 합니다.
private static void sendTemperatureTelemetry(String componentName) {
double currentTemperature = temperature.get(componentName);
Map<String, Object> payload = singletonMap("temperature", currentTemperature);
Message message = new Message(gson.toJson(payload));
message.setContentEncoding("utf-8");
message.setContentTypeFinal("application/json");
if (componentName != null) {
message.setProperty("$.sub", componentName);
}
deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
}
읽기 전용 속성
기본 구성 요소에서 속성을 보고하는 데 특별한 구문이 필요하지 않습니다.
Property reportedProperty = new Property("maxTempSinceLastReboot", 38.7);
deviceClient.sendReportedProperties(Collections.singleton(reportedProperty));
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"maxTempSinceLastReboot" : 38.7
}
}
중첩된 구성 요소를 사용하는 경우 속성을 구성 요소 이름 내에 생성하며 마커를 포함합니다.
Map<String, Object> componentProperty = new HashMap<String, Object>() {{
put("__t", "c");
put("maxTemperature", 38.7);
}};
Set<Property> reportedProperty = new Property("thermostat1", componentProperty)
deviceClient.sendReportedProperties(reportedProperty);
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1" : {
"__t" : "c",
"maxTemperature" : 38.7
}
}
}
쓰기 가능한 속성
이러한 속성은 디바이스에서 설정하거나 백엔드 애플리케이션에서 업데이트할 수 있습니다. 백엔드 애플리케이션에서 속성을 업데이트하면 클라이언트는 DeviceClient 또는 ModuleClient에서 콜백으로 알림을 받습니다. IoT 플러그 앤 플레이 규칙을 따르려면 디바이스에서 속성이 성공적으로 수신되었음을 서비스에 알려야 합니다.
속성 형식이 Object인 경우 서비스는 개체 필드의 하위 집합만 업데이트하는 경우에도 디바이스에 완전한 개체를 보내야 합니다. 디바이스가 보내는 승인도 완전한 개체여야 합니다.
쓰기 가능한 속성 보고
디바이스에서 쓰기 가능한 속성을 보고하는 경우 규칙에 정의된 ack 값을 포함해야 합니다.
기본 구성 요소에서 쓰기 가능한 속성을 보고하려면 다음을 수행합니다.
@AllArgsConstructor
private static class EmbeddedPropertyUpdate {
@NonNull
@SerializedName("value")
public Object value;
@NonNull
@SerializedName("ac")
public Integer ackCode;
@NonNull
@SerializedName("av")
public Integer ackVersion;
@SerializedName("ad")
public String ackDescription;
}
EmbeddedPropertyUpdate completedUpdate = new EmbeddedPropertyUpdate(23.2, 200, 3, "Successfully updated target temperature");
Property reportedPropertyCompleted = new Property("targetTemperature", completedUpdate);
deviceClient.sendReportedProperties(Collections.singleton(reportedPropertyCompleted));
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "Successfully updated target temperature"
}
}
}
중첩된 구성 요소에서 쓰기 가능한 속성을 보고하려면 트윈에 표식이 있어야 합니다.
Map<String, Object> embeddedProperty = new HashMap<String, Object>() {{
put("value", 23.2);
put("ac", 200);
put("av", 3);
put("ad", "complete");
}};
Map<String, Object> componentProperty = new HashMap<String, Object>() {{
put("__t", "c");
put("targetTemperature", embeddedProperty);
}};
Set<Property> reportedProperty = new Property("thermostat1", componentProperty));
deviceClient.sendReportedProperties(reportedProperty);
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1": {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
}
원하는 속성 업데이트 구독
서비스는 연결된 디바이스에 대한 알림을 트리거하는 원하는 속성을 업데이트할 수 있습니다. 이 알림에는 업데이트를 식별하는 버전 번호를 포함하여 업데이트된 원하는 속성이 포함됩니다. 디바이스는 서비스로 다시 전송된 ack 메시지에 이 버전 번호를 포함해야 합니다.
기본 구성 요소는 단일 속성을 보고 수신된 버전으로 보고된 ack를 만듭니다.
private static class TargetTemperatureUpdateCallback implements TwinPropertyCallBack {
String propertyName = "targetTemperature";
@Override
public void TwinPropertyCallBack(Property property, Object context) {
double targetTemperature = ((Number)property.getValue()).doubleValue();
EmbeddedPropertyUpdate completedUpdate = new EmbeddedPropertyUpdate(temperature, 200, property.getVersion(), "Successfully updated target temperature");
Property reportedPropertyCompleted = new Property(propertyName, completedUpdate);
deviceClient.sendReportedProperties(Collections.singleton(reportedPropertyCompleted));
}
}
// ...
deviceClient.startDeviceTwin(new TwinIotHubEventCallback(), null, new TargetTemperatureUpdateCallback(), null);
Map<Property, Pair<TwinPropertyCallBack, Object>> desiredPropertyUpdateCallback =
Collections.singletonMap(
new Property("targetTemperature", null),
new Pair<>(new TargetTemperatureUpdateCallback(), null));
deviceClient.subscribeToTwinDesiredProperties(desiredPropertyUpdateCallback);
중첩된 구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"targetTemperature": 23.2,
"$version" : 3
},
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "Successfully updated target temperature"
}
}
}
중첩된 구성 요소는 구성 요소 이름으로 래핑된 원하는 속성을 받고 ack에 의해 보고된 속성을 다시 보고해야 합니다.
private static final Map<String, Double> temperature = new HashMap<>();
private static class TargetTemperatureUpdateCallback implements TwinPropertyCallBack {
String propertyName = "targetTemperature";
@Override
public void TwinPropertyCallBack(Property property, Object context) {
String componentName = (String) context;
if (property.getKey().equalsIgnoreCase(componentName)) {
double targetTemperature = (double) ((TwinCollection) property.getValue()).get(propertyName);
Map<String, Object> embeddedProperty = new HashMap<String, Object>() {{
put("value", temperature.get(componentName));
put("ac", 200);
put("av", property.getVersion().longValue());
put("ad", "Successfully updated target temperature.");
}};
Map<String, Object> componentProperty = new HashMap<String, Object>() {{
put("__t", "c");
put(propertyName, embeddedProperty);
}};
Set<Property> completedPropertyPatch = new Property(componentName, componentProperty));
deviceClient.sendReportedProperties(completedPropertyPatch);
} else {
log.debug("Property: Received an unrecognized property update from service.");
}
}
}
// ...
deviceClient.startDeviceTwin(new TwinIotHubEventCallback(), null, new GenericPropertyUpdateCallback(), null);
Map<Property, Pair<TwinPropertyCallBack, Object>> desiredPropertyUpdateCallback = Stream.of(
new AbstractMap.SimpleEntry<Property, Pair<TwinPropertyCallBack, Object>>(
new Property("thermostat1", null),
new Pair<>(new TargetTemperatureUpdateCallback(), "thermostat1")),
new AbstractMap.SimpleEntry<Property, Pair<TwinPropertyCallBack, Object>>(
new Property("thermostat2", null),
new Pair<>(new TargetTemperatureUpdateCallback(), "thermostat2"))
).collect(Collectors.toMap(AbstractMap.SimpleEntry::getKey, AbstractMap.SimpleEntry::getValue));
deviceClient.subscribeToTwinDesiredProperties(desiredPropertyUpdateCallback);
중첩된 구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"thermostat1" : {
"__t" : "c",
"targetTemperature": 23.2,
}
"$version" : 3
},
"reported": {
"thermostat1" : {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
}
명령
기본 구성 요소는 서비스에서 호출된 명령 이름을 받습니다.
중첩된 구성 요소는 구성 요소 이름과 * 구분 기호가 접두사로 붙은 명령 이름을 받습니다.
deviceClient.subscribeToDeviceMethod(new MethodCallback(), null, new MethodIotHubEventCallback(), null);
// ...
private static final Map<String, Double> temperature = new HashMap<>();
private static class MethodCallback implements DeviceMethodCallback {
final String reboot = "reboot";
final String getMaxMinReport1 = "thermostat1*getMaxMinReport";
final String getMaxMinReport2 = "thermostat2*getMaxMinReport";
@Override
public DeviceMethodData call(String methodName, Object methodData, Object context) {
String jsonRequest = new String((byte[]) methodData, StandardCharsets.UTF_8);
switch (methodName) {
case reboot:
int delay = gson.fromJson(jsonRequest, Integer.class);
Thread.sleep(delay * 1000);
temperature.put("thermostat1", 0.0d);
temperature.put("thermostat2", 0.0d);
return new DeviceMethodData(200, null);
// ...
default:
log.debug("Command: command=\"{}\" is not implemented, no action taken.", methodName);
return new DeviceMethodData(404, null);
}
}
}
요청 및 응답 페이로드
명령은 형식을 사용하여 요청 및 응답 페이로드를 정의합니다. 디바이스는 들어오는 입력 매개 변수를 역직렬화하고 응답을 직렬화해야 합니다.
다음 예제에서는 페이로드에 정의된 복합 형식을 사용하여 명령을 구현하는 방법을 보여줍니다.
{
"@type": "Command",
"name": "getMaxMinReport",
"displayName": "Get Max-Min report.",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"request": {
"name": "since",
"displayName": "Since",
"description": "Period to return the max-min report.",
"schema": "dateTime"
},
"response": {
"name" : "tempReport",
"displayName": "Temperature Report",
"schema": {
"@type": "Object",
"fields": [
{
"name": "maxTemp",
"displayName": "Max temperature",
"schema": "double"
},
{
"name": "minTemp",
"displayName": "Min temperature",
"schema": "double"
},
{
"name" : "avgTemp",
"displayName": "Average Temperature",
"schema": "double"
},
{
"name" : "startTime",
"displayName": "Start Time",
"schema": "dateTime"
},
{
"name" : "endTime",
"displayName": "End Time",
"schema": "dateTime"
}
]
}
}
}
다음 코드 조각은 직렬화 및 역직렬화를 활성화하는 데 사용되는 형식을 포함하여 디바이스가 이 명령 정의를 구현하는 방법을 보여줍니다.
deviceClient.subscribeToDeviceMethod(new GetMaxMinReportMethodCallback(), "getMaxMinReport", new MethodIotHubEventCallback(), "getMaxMinReport");
// ...
private static class GetMaxMinReportMethodCallback implements DeviceMethodCallback {
String commandName = "getMaxMinReport";
@Override
public DeviceMethodData call(String methodName, Object methodData, Object context) {
String jsonRequest = new String((byte[]) methodData, StandardCharsets.UTF_8);
Date since = gson.fromJson(jsonRequest, Date.class);
String responsePayload = String.format(
"{\"maxTemp\": %.1f, \"minTemp\": %.1f, \"avgTemp\": %.1f, \"startTime\": \"%s\", \"endTime\": \"%s\"}",
maxTemp,
minTemp,
avgTemp,
since,
endTime);
return new DeviceMethodData(StatusCode.COMPLETED.value, responsePayload);
}
}
팁
유선을 통해 전송되는 직렬화된 페이로드에 요청 및 응답 이름이 없습니다.
모델 ID 알림
모델 ID를 알리려면 디바이스가 연결 정보에 해당 ID를 포함해야 합니다.
const modelIdObject = { modelId: 'dtmi:com:example:Thermostat;1' };
const client = Client.fromConnectionString(deviceConnectionString, Protocol);
await client.setOptions(modelIdObject);
await client.open();
팁
모듈 및 IoT Edge의 경우 ModuleClient 대신 Client를 사용합니다.
팁
디바이스가 모델 ID를 설정할 수 있는 유일한 시간이며 디바이스가 연결된 후에는 업데이트할 수 없습니다.
DPS 페이로드
DPS(Device Provisioning Service)를 사용하는 디바이스에는 다음 JSON 페이로드를 사용하는 프로비저닝 프로세스 중에 사용할 modelId가 포함될 수 있습니다.
{
"modelId" : "dtmi:com:example:Thermostat;1"
}
구성 요소 사용
IoT 플러그 앤 플레이 모델의 구성 요소 이해에 설명된 대로 구성 요소를 사용하여 디바이스를 설명할지 결정해야 합니다. 구성 요소를 사용하는 경우 디바이스는 다음 섹션에 설명된 규칙을 따라야 합니다.
원격
기본 구성 요소에는 원격 분석 메시지에 추가된 특수 속성이 필요하지 않습니다.
중첩된 구성 요소를 사용하는 경우 디바이스는 구성 요소 이름으로 메시지 속성을 설정해야 합니다.
async function sendTelemetry(deviceClient, data, index, componentName) {
const msg = new Message(data);
if (!!(componentName)) {
msg.properties.add(messageSubjectProperty, componentName);
}
msg.contentType = 'application/json';
msg.contentEncoding = 'utf-8';
await deviceClient.sendEvent(msg);
}
읽기 전용 속성
기본 구성 요소에서 속성을 보고하는 데 특별한 구문이 필요하지 않습니다.
const createReportPropPatch = (propertiesToReport) => {
let patch;
patch = { };
patch = propertiesToReport;
return patch;
};
deviceTwin = await client.getTwin();
patchThermostat = createReportPropPatch({
maxTempSinceLastReboot: 38.7
});
deviceTwin.properties.reported.update(patchThermostat, function (err) {
if (err) throw err;
});
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"maxTempSinceLastReboot" : 38.7
}
}
중첩된 구성 요소를 사용하는 경우 속성은 구성 요소 이름 내에 생성되어야 하며 마커를 포함해야 합니다.
helperCreateReportedPropertiesPatch = (propertiesToReport, componentName) => {
let patch;
if (!!(componentName)) {
patch = { };
propertiesToReport.__t = 'c';
patch[componentName] = propertiesToReport;
} else {
patch = { };
patch = propertiesToReport;
}
return patch;
};
deviceTwin = await client.getTwin();
patchThermostat1Info = helperCreateReportedPropertiesPatch({
maxTempSinceLastReboot: 38.7,
}, 'thermostat1');
deviceTwin.properties.reported.update(patchThermostat1Info, function (err) {
if (err) throw err;
});
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1" : {
"__t" : "c",
"maxTempSinceLastReboot" : 38.7
}
}
}
쓰기 가능한 속성
이러한 속성은 디바이스에서 설정하거나 백엔드 애플리케이션에서 업데이트할 수 있습니다. 백엔드 애플리케이션에서 속성을 업데이트하면 클라이언트는 Client 또는 ModuleClient에서 콜백으로 알림을 받습니다. IoT 플러그 앤 플레이 규칙을 따르려면 디바이스에서 속성이 성공적으로 수신되었음을 서비스에 알려야 합니다.
속성 형식이 Object인 경우 서비스는 개체 필드의 하위 집합만 업데이트하는 경우에도 디바이스에 완전한 개체를 보내야 합니다. 디바이스가 보내는 승인도 완전한 개체여야 합니다.
쓰기 가능한 속성 보고
디바이스에서 쓰기 가능한 속성을 보고하는 경우 규칙에 정의된 ack 값을 포함해야 합니다.
기본 구성 요소에서 쓰기 가능한 속성을 보고하려면 다음을 수행합니다.
patch = {
targetTemperature:
{
'value': 23.2,
'ac': 200, // using HTTP status codes
'ad': 'reported default value',
'av': 0 // not read from a desired property
}
};
deviceTwin.properties.reported.update(patch, function (err) {
if (err) throw err;
});
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 0,
"ad": "reported default value"
}
}
}
중첩된 구성 요소에서 쓰기 가능한 속성을 보고하려면 트윈에 표식이 있어야 합니다.
patch = {
thermostat1: {
'__t' : 'c',
targetTemperature: {
'value': 23.2,
'ac': 200, // using HTTP status codes
'ad': 'reported default value',
'av': 0 // not read from a desired property
}
}
};
deviceTwin.properties.reported.update(patch, function (err) {
if (err) throw err;
});
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1": {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 0,
"ad": "complete"
}
}
}
}
원하는 속성 업데이트 구독
서비스는 연결된 디바이스에 대한 알림을 트리거하는 원하는 속성을 업데이트할 수 있습니다. 이 알림에는 업데이트를 식별하는 버전 번호를 포함하여 업데이트된 원하는 속성이 포함됩니다. 디바이스는 서비스로 다시 전송된 ack 메시지에 이 버전 번호를 포함해야 합니다.
기본 구성 요소는 단일 속성을 보고 수신된 버전으로 보고된 ack를 만듭니다.
const propertyUpdateHandler = (deviceTwin, propertyName, reportedValue, desiredValue, version) => {
const patch = createReportPropPatch(
{ [propertyName]:
{
'value': desiredValue,
'ac': 200,
'ad': 'Successfully executed patch for ' + propertyName,
'av': version
}
});
updateComponentReportedProperties(deviceTwin, patch);
};
desiredPropertyPatchHandler = (deviceTwin) => {
deviceTwin.on('properties.desired', (delta) => {
const versionProperty = delta.$version;
Object.entries(delta).forEach(([propertyName, propertyValue]) => {
if (propertyName !== '$version') {
propertyUpdateHandler(deviceTwin, propertyName, null, propertyValue, versionProperty);
}
});
});
};
중첩된 구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"targetTemperature": 23.2,
"$version" : 3
},
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
중첩된 구성 요소는 구성 요소 이름으로 래핑된 원하는 속성을 받고 ack에 의해 보고된 속성을 다시 보고해야 합니다.
const desiredPropertyPatchListener = (deviceTwin, componentNames) => {
deviceTwin.on('properties.desired', (delta) => {
Object.entries(delta).forEach(([key, values]) => {
const version = delta.$version;
if (!!(componentNames) && componentNames.includes(key)) { // then it is a component we are expecting
const componentName = key;
const patchForComponents = { [componentName]: {} };
Object.entries(values).forEach(([propertyName, propertyValue]) => {
if (propertyName !== '__t' && propertyName !== '$version') {
const propertyContent = { value: propertyValue };
propertyContent.ac = 200;
propertyContent.ad = 'Successfully executed patch';
propertyContent.av = version;
patchForComponents[componentName][propertyName] = propertyContent;
}
});
updateComponentReportedProperties(deviceTwin, patchForComponents, componentName);
}
else if (key !== '$version') { // individual property for root
const patchForRoot = { };
const propertyContent = { value: values };
propertyContent.ac = 200;
propertyContent.ad = 'Successfully executed patch';
propertyContent.av = version;
patchForRoot[key] = propertyContent;
updateComponentReportedProperties(deviceTwin, patchForRoot, null);
}
});
});
};
구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"thermostat1" : {
"__t" : "c",
"targetTemperature": 23.2,
}
"$version" : 3
},
"reported": {
"thermostat1" : {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
}
명령
기본 구성 요소는 서비스에서 호출된 명령 이름을 받습니다.
중첩된 구성 요소는 구성 요소 이름과 * 구분 기호가 접두사로 붙은 명령 이름을 받습니다.
const commandHandler = async (request, response) => {
switch (request.methodName) {
// ...
case 'thermostat1*reboot': {
await response.send(200, 'reboot response');
break;
}
default:
await response.send(404, 'unknown method');
break;
}
};
client.onDeviceMethod('thermostat1*reboot', commandHandler);
요청 및 응답 페이로드
명령은 형식을 사용하여 요청 및 응답 페이로드를 정의합니다. 디바이스는 들어오는 입력 매개 변수를 역직렬화하고 응답을 직렬화해야 합니다.
다음 예제에서는 페이로드에 정의된 복합 형식을 사용하여 명령을 구현하는 방법을 보여줍니다.
{
"@type": "Command",
"name": "getMaxMinReport",
"displayName": "Get Max-Min report.",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"request": {
"name": "since",
"displayName": "Since",
"description": "Period to return the max-min report.",
"schema": "dateTime"
},
"response": {
"name" : "tempReport",
"displayName": "Temperature Report",
"schema": {
"@type": "Object",
"fields": [
{
"name": "maxTemp",
"displayName": "Max temperature",
"schema": "double"
},
{
"name": "minTemp",
"displayName": "Min temperature",
"schema": "double"
},
{
"name" : "avgTemp",
"displayName": "Average Temperature",
"schema": "double"
},
{
"name" : "startTime",
"displayName": "Start Time",
"schema": "dateTime"
},
{
"name" : "endTime",
"displayName": "End Time",
"schema": "dateTime"
}
]
}
}
}
다음 코드 조각은 직렬화 및 역직렬화를 활성화하는 데 사용되는 형식을 포함하여 디바이스가 이 명령 정의를 구현하는 방법을 보여줍니다.
class TemperatureSensor {
// ...
getMaxMinReportObject() {
return {
maxTemp: this.maxTemp,
minTemp: this.minTemp,
avgTemp: this.cumulativeTemperature / this.numberOfTemperatureReadings,
endTime: (new Date(Date.now())).toISOString(),
startTime: this.startTime
};
}
}
// ...
const deviceTemperatureSensor = new TemperatureSensor();
const commandHandler = async (request, response) => {
switch (request.methodName) {
case commandMaxMinReport: {
console.log('MaxMinReport ' + request.payload);
await response.send(200, deviceTemperatureSensor.getMaxMinReportObject());
break;
}
default:
await response.send(404, 'unknown method');
break;
}
};
팁
유선을 통해 전송되는 직렬화된 페이로드에 요청 및 응답 이름이 없습니다.
모델 ID 알림
모델 ID를 알리려면 디바이스가 연결 정보에 해당 ID를 포함해야 합니다.
device_client = IoTHubDeviceClient.create_from_symmetric_key(
symmetric_key=symmetric_key,
hostname=registration_result.registration_state.assigned_hub,
device_id=registration_result.registration_state.device_id,
product_info=model_id,
)
팁
모듈 및 IoT Edge의 경우 IoTHubModuleClient 대신 IoTHubDeviceClient를 사용합니다.
팁
디바이스가 모델 ID를 설정할 수 있는 유일한 시간이며 디바이스가 연결된 후에는 업데이트할 수 없습니다.
DPS 페이로드
DPS(Device Provisioning Service)를 사용하는 디바이스에는 다음 JSON 페이로드를 사용하는 프로비저닝 프로세스 중에 사용할 modelId가 포함될 수 있습니다.
{
"modelId" : "dtmi:com:example:Thermostat;1"
}
구성 요소 사용
IoT 플러그 앤 플레이 모델의 구성 요소 이해에 설명된 대로 구성 요소를 사용하여 디바이스를 설명할지 결정해야 합니다. 구성 요소를 사용하는 경우 디바이스는 다음 섹션에 설명된 규칙을 따라야 합니다.
원격
기본 구성 요소에는 원격 분석 메시지에 추가된 특수 속성이 필요하지 않습니다.
중첩된 구성 요소를 사용하는 경우 디바이스는 구성 요소 이름으로 메시지 속성을 설정해야 합니다.
async def send_telemetry_from_temp_controller(device_client, telemetry_msg, component_name=None):
msg = Message(json.dumps(telemetry_msg))
msg.content_encoding = "utf-8"
msg.content_type = "application/json"
if component_name:
msg.custom_properties["$.sub"] = component_name
await device_client.send_message(msg)
읽기 전용 속성
기본 구성 요소에서 속성을 보고하는 데 특별한 구문이 필요하지 않습니다.
await device_client.patch_twin_reported_properties({"maxTempSinceLastReboot": 38.7})
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"maxTempSinceLastReboot" : 38.7
}
}
중첩된 구성 요소를 사용하는 경우 속성은 구성 요소 이름 내에 생성되어야 하며 마커를 포함해야 합니다.
inner_dict = {}
inner_dict["targetTemperature"] = 38.7
inner_dict["__t"] = "c"
prop_dict = {}
prop_dict["thermostat1"] = inner_dict
await device_client.patch_twin_reported_properties(prop_dict)
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1" : {
"__t" : "c",
"maxTempSinceLastReboot" : 38.7
}
}
}
쓰기 가능한 속성
이러한 속성은 디바이스에서 설정하거나 백엔드 애플리케이션에서 업데이트할 수 있습니다. 백엔드 애플리케이션에서 속성을 업데이트하면 클라이언트는 IoTHubDeviceClient 또는 IoTHubModuleClient에서 콜백으로 알림을 받습니다. IoT 플러그 앤 플레이 규칙을 따르려면 디바이스에서 속성이 성공적으로 수신되었음을 서비스에 알려야 합니다.
속성 형식이 Object인 경우 서비스는 개체 필드의 하위 집합만 업데이트하는 경우에도 디바이스에 완전한 개체를 보내야 합니다. 디바이스가 보내는 승인도 완전한 개체여야 합니다.
쓰기 가능한 속성 보고
디바이스에서 쓰기 가능한 속성을 보고하는 경우 규칙에 정의된 ack 값을 포함해야 합니다.
기본 구성 요소에서 쓰기 가능한 속성을 보고하려면 다음을 수행합니다.
prop_dict = {}
prop_dict["targetTemperature"] = {
"ac": 200,
"ad": "reported default value",
"av": 0,
"value": 23.2
}
await device_client.patch_twin_reported_properties(prop_dict)
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 0,
"ad": "reported default value"
}
}
}
중첩된 구성 요소에서 쓰기 가능한 속성을 보고하려면 트윈에 표식이 있어야 합니다.
inner_dict = {}
inner_dict["targetTemperature"] = {
"ac": 200,
"ad": "reported default value",
"av": 0,
"value": 23.2
}
inner_dict["__t"] = "c"
prop_dict = {}
prop_dict["thermostat1"] = inner_dict
await device_client.patch_twin_reported_properties(prop_dict)
디바이스 쌍은 다음과 같은 보고되는 속성으로 업데이트됩니다.
{
"reported": {
"thermostat1": {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 0,
"ad": "complete"
}
}
}
}
원하는 속성 업데이트 구독
서비스는 연결된 디바이스에 대한 알림을 트리거하는 원하는 속성을 업데이트할 수 있습니다. 이 알림에는 업데이트를 식별하는 버전 번호를 포함하여 업데이트된 원하는 속성이 포함됩니다. 디바이스는 서비스로 다시 전송된 ack 메시지에 이 버전 번호를 포함해야 합니다.
기본 구성 요소는 단일 속성을 보고 수신된 버전으로 보고된 ack를 만듭니다.
async def execute_property_listener(device_client):
ignore_keys = ["__t", "$version"]
while True:
patch = await device_client.receive_twin_desired_properties_patch() # blocking call
version = patch["$version"]
prop_dict = {}
for prop_name, prop_value in patch.items():
if prop_name in ignore_keys:
continue
else:
prop_dict[prop_name] = {
"ac": 200,
"ad": "Successfully executed patch",
"av": version,
"value": prop_value,
}
await device_client.patch_twin_reported_properties(prop_dict)
중첩된 구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"targetTemperature": 23.2,
"$version" : 3
},
"reported": {
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
중첩된 구성 요소는 구성 요소 이름으로 래핑된 원하는 속성을 받고 ack에 의해 보고된 속성을 다시 보고해야 합니다.
def create_reported_properties_from_desired(patch):
ignore_keys = ["__t", "$version"]
component_prefix = list(patch.keys())[0]
values = patch[component_prefix]
version = patch["$version"]
inner_dict = {}
for prop_name, prop_value in values.items():
if prop_name in ignore_keys:
continue
else:
inner_dict["ac"] = 200
inner_dict["ad"] = "Successfully executed patch"
inner_dict["av"] = version
inner_dict["value"] = prop_value
values[prop_name] = inner_dict
properties_dict = dict()
if component_prefix:
properties_dict[component_prefix] = values
else:
properties_dict = values
return properties_dict
async def execute_property_listener(device_client):
while True:
patch = await device_client.receive_twin_desired_properties_patch() # blocking call
properties_dict = create_reported_properties_from_desired(patch)
await device_client.patch_twin_reported_properties(properties_dict)
구성 요소에 대한 디바이스 쌍은 다음과 같이 원하는 섹션과 보고된 섹션을 보여줍니다.
{
"desired" : {
"thermostat1" : {
"__t" : "c",
"targetTemperature": 23.2,
}
"$version" : 3
},
"reported": {
"thermostat1" : {
"__t" : "c",
"targetTemperature": {
"value": 23.2,
"ac": 200,
"av": 3,
"ad": "complete"
}
}
}
}
명령
기본 구성 요소는 서비스에서 호출된 명령 이름을 받습니다.
중첩된 구성 요소는 구성 요소 이름과 * 구분 기호가 접두사로 붙은 명령 이름을 받습니다.
command_request = await device_client.receive_method_request("thermostat1*reboot")
요청 및 응답 페이로드
명령은 형식을 사용하여 요청 및 응답 페이로드를 정의합니다. 디바이스는 들어오는 입력 매개 변수를 역직렬화하고 응답을 직렬화해야 합니다.
다음 예제에서는 페이로드에 정의된 복합 형식을 사용하여 명령을 구현하는 방법을 보여줍니다.
{
"@type": "Command",
"name": "getMaxMinReport",
"displayName": "Get Max-Min report.",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"request": {
"name": "since",
"displayName": "Since",
"description": "Period to return the max-min report.",
"schema": "dateTime"
},
"response": {
"name" : "tempReport",
"displayName": "Temperature Report",
"schema": {
"@type": "Object",
"fields": [
{
"name": "maxTemp",
"displayName": "Max temperature",
"schema": "double"
},
{
"name": "minTemp",
"displayName": "Min temperature",
"schema": "double"
},
{
"name" : "avgTemp",
"displayName": "Average Temperature",
"schema": "double"
},
{
"name" : "startTime",
"displayName": "Start Time",
"schema": "dateTime"
},
{
"name" : "endTime",
"displayName": "End Time",
"schema": "dateTime"
}
]
}
}
}
다음 코드 조각은 직렬화 및 역직렬화를 활성화하는 데 사용되는 형식을 포함하여 디바이스가 이 명령 정의를 구현하는 방법을 보여줍니다.
def create_max_min_report_response(values):
response_dict = {
"maxTemp": max_temp,
"minTemp": min_temp,
"avgTemp": sum(avg_temp_list) / moving_window_size,
"startTime": (datetime.now() - timedelta(0, moving_window_size * 8)).isoformat(),
"endTime": datetime.now().isoformat(),
}
# serialize response dictionary into a JSON formatted str
response_payload = json.dumps(response_dict, default=lambda o: o.__dict__, sort_keys=True)
return response_payload
팁
유선을 통해 전송되는 직렬화된 페이로드에 요청 및 응답 이름이 없습니다.
다음 단계
이제 IoT 플러그 앤 플레이 디바이스 개발에 대해 살펴보았습니다. 몇 가지 기타 리소스는 다음과 같습니다: