教學課程：建立用戶端應用程式並將其連線至您的 Azure IoT Central 應用程式
重要
本文包含使用共用存取簽章 (也稱為對稱金鑰驗證) 連線裝置的步驟。 此驗證方法方便進行測試和評估，但使用 X.509 憑證來驗證裝置是更安全的方法。 若要深入了解，請參閱安全性最佳做法>連線安全性。
本教學課程說明如何將用戶端應用程式與您的 Azure IoT Central 應用程式連線。 應用程式會模擬溫度控制器裝置的行為。 應用程式在連線至 IoT Central 時，將會傳送溫度控制器裝置型號的型號識別碼。 IoT Central 會使用型號識別碼來擷取裝置型號，並為您建立裝置範本。 您可將檢視新增至裝置範本，讓操作員能與裝置互動。
在本教學課程中，您會了解如何：
- 建立和執行裝置程式碼，並查看其是否與您的 IoT Central 應用程式連線。
- 檢視裝置所傳送的模擬遙測。
- 將自訂檢視新增至裝置範本。
- 發佈裝置範本。
- 使用檢視管理裝置屬性。
- 呼叫命令以控制裝置。
必要條件
若要完成本教學課程中的步驟，您需要：
啟用中的 Azure 訂用帳戶。 如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
從自訂應用程式範本建立的 IoT Central 應用程式。 若要深入了解，請參閱建立 IoT Central 應用程式和關於您的應用程式。
您可以在 Linux 或 Windows 上執行本教學課程。 本教學課程中的殼層命令會遵循路徑分隔符號 '/' 的 Linux 慣例，如果您在 Windows 上遵循，請務必針對 '\' 交換這些分隔符號。
必要條件會因作業系統而有所不同：
Linux
本教學課程假設您使用 Ubuntu Linux。 本教學課程中的步驟已使用 Ubuntu 18.04 進行測試。
若要在 Linux 上完成本教學課程，您必須在本機 Linux 環境上安裝下列軟體：
使用 apt-get 命令，安裝 GCC、Git、cmake 和所有必要的相依性：
sudo apt-get update
sudo apt-get install -y git cmake build-essential curl libcurl4-openssl-dev libssl-dev uuid-dev
確認 cmake 的版本大於 2.8.12，且 GCC 的版本大於 4.4.7。
cmake --version
gcc --version
Windows
若要在 Windows 上完成此教學課程，請在您的本機 Windows 環境上安裝下列軟體：
- Visual Studio (Community、Professional 或 Enterprise) - 在安裝 Visual Studio 時，請確實包含使用 C++ 的桌面開發工作負載。
- Git。
- CMake。
下載程式碼
在此教學課程中，您會準備可用來複製及建置 Azure IoT 中樞裝置 C SDK 的開發環境。
在您選擇的目錄中開啟命令提示字元。 執行下列命令，將 Azure IoT C SDK 和程式庫 GitHub 存放庫複製到下列位置：
git clone https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
預期此作業需要幾分鐘的時間才能完成。
檢閱程式碼
在您先前下載的 Microsoft Azure IoT SDK for C 複本中，在文字編輯器中開啟 azure-iot-sdk-c/iothub_client/samples/pnp/pnp_temperature_controller/pnp_temperature_controller.c 和 azure-iot-sdk-c/iothub_client/samples/pnp/pnp_temperature_controller/pnp_thermostat_component.c 檔案。
此範例會實作多重元件溫度控制器數位對應項定義語言模型。
執行範例以連線到 IoT Central 時，該檔案會使用裝置佈建服務 (DPS) 來註冊裝置並產生連接字串。 此範例會從命令列環境中，取出所需的 DPS 連線資訊。
在 pnp_temperature_controller.c 中，main 函式會先呼叫 CreateDeviceClientAndAllocateComponents：
- 設定
dtmi:com:example:Thermostat;1模型識別碼。 IoT Central 會使用型號識別碼來識別或產生此裝置的裝置範本。 若要深入了解，請參閱將裝置指派給裝置範本。 - 使用 DPS 來佈建和註冊裝置。
- 建立裝置用戶端控制代碼，並連線到您的 IoT Central 應用程式。
- 在溫度控制器元件中建立命令的處理常式。
- 在溫度控制器元件中建立屬性更新的處理常式。
- 建立兩個控溫器元件。
main 函式接下來會：
- 報告所有元件的某些初始屬性值。
- 啟動迴圈以從所有元件傳送遙測。
然後 main 函式會啟動執行緒，以定期傳送遙測資料。
int main(void)
{
IOTHUB_DEVICE_CLIENT_LL_HANDLE deviceClient = NULL;
g_pnpDeviceConfiguration.modelId = g_temperatureControllerModelId;
g_pnpDeviceConfiguration.enableTracing = g_hubClientTraceEnabled;
// First determine the IoT Hub / credentials / device to use.
if (GetConnectionSettingsFromEnvironment(&g_pnpDeviceConfiguration) == false)
{
LogError("Cannot read required environment variable(s)");
}
// Creates the thermostat subcomponents defined by this model. Since everything
// is simulated, this setup stage just creates simulated objects in memory.
else if (AllocateThermostatComponents() == false)
{
LogError("Failure allocating thermostat components");
}
// Create a handle to device client handle. Note that this call may block
// for extended periods of time when using DPS.
else if ((deviceClient = CreateAndConfigureDeviceClientHandleForPnP()) == NULL)
{
LogError("Failure creating Iot Hub device client");
PnP_ThermostatComponent_Destroy(g_thermostatHandle1);
PnP_ThermostatComponent_Destroy(g_thermostatHandle2);
}
else
{
LogInfo("Successfully created device client. Hit Control-C to exit program\n");
int numberOfIterations = 0;
// During startup, send what DTDLv2 calls "read-only properties" to indicate initial device state.
PnP_TempControlComponent_ReportSerialNumber_Property(deviceClient);
PnP_DeviceInfoComponent_Report_All_Properties(g_deviceInfoComponentName, deviceClient);
PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(g_thermostatHandle1, deviceClient);
PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(g_thermostatHandle2, deviceClient);
while (true)
{
// Wake up periodically to poll. Even if we do not plan on sending telemetry, we still need to poll periodically in order to process
// incoming requests from the server and to do connection keep alives.
if ((numberOfIterations % g_sendTelemetryPollInterval) == 0)
{
PnP_TempControlComponent_SendWorkingSet(deviceClient);
PnP_ThermostatComponent_SendCurrentTemperature(g_thermostatHandle1, deviceClient);
PnP_ThermostatComponent_SendCurrentTemperature(g_thermostatHandle2, deviceClient);
}
IoTHubDeviceClient_LL_DoWork(deviceClient);
ThreadAPI_Sleep(g_sleepBetweenPollsMs);
numberOfIterations++;
}
// The remainder of the code is used for cleaning up our allocated resources. It won't be executed in this
// sample (because the loop above is infinite and is only broken out of by Control-C of the program), but
// it is included for reference.
// Free the memory allocated to track simulated thermostat.
PnP_ThermostatComponent_Destroy(g_thermostatHandle1);
PnP_ThermostatComponent_Destroy(g_thermostatHandle2);
// Clean up the IoT Hub SDK handle.
IoTHubDeviceClient_LL_Destroy(deviceClient);
// Free all IoT Hub subsystem.
IoTHub_Deinit();
}
return 0;
}
在 pnp_thermostat_component.c 中，PnP_ThermostatComponent_SendCurrentTemperature 函式會顯示裝置如何將溫度遙測資料從元件傳送至 IoT Central：
void PnP_ThermostatComponent_SendCurrentTemperature(PNP_THERMOSTAT_COMPONENT_HANDLE pnpThermostatComponentHandle, IOTHUB_DEVICE_CLIENT_LL_HANDLE deviceClient)
{
PNP_THERMOSTAT_COMPONENT* pnpThermostatComponent = (PNP_THERMOSTAT_COMPONENT*)pnpThermostatComponentHandle;
IOTHUB_MESSAGE_HANDLE messageHandle = NULL;
IOTHUB_MESSAGE_RESULT messageResult;
IOTHUB_CLIENT_RESULT iothubClientResult;
char temperatureStringBuffer[CURRENT_TEMPERATURE_BUFFER_SIZE];
// Create the telemetry message body to send.
if (snprintf(temperatureStringBuffer, sizeof(temperatureStringBuffer), g_temperatureTelemetryBodyFormat, pnpThermostatComponent->currentTemperature) < 0)
{
LogError("snprintf of current temperature telemetry failed");
}
// Create the message handle and specify its metadata.
else if ((messageHandle = IoTHubMessage_CreateFromString(temperatureStringBuffer)) == NULL)
{
LogError("IoTHubMessage_PnP_CreateFromString failed");
}
else if ((messageResult = IoTHubMessage_SetContentTypeSystemProperty(messageHandle, g_jsonContentType)) != IOTHUB_MESSAGE_OK)
{
LogError("IoTHubMessage_SetContentTypeSystemProperty failed, error=%d", messageResult);
}
else if ((messageResult = IoTHubMessage_SetContentEncodingSystemProperty(messageHandle, g_utf8EncodingType)) != IOTHUB_MESSAGE_OK)
{
LogError("IoTHubMessage_SetContentEncodingSystemProperty failed, error=%d", messageResult);
}
else if ((messageResult = IoTHubMessage_SetComponentName(messageHandle, pnpThermostatComponent->componentName)) != IOTHUB_MESSAGE_OK)
{
LogError("IoTHubMessage_SetContentEncodingSystemProperty failed, error=%d", messageResult);
}
// Send the telemetry message.
else if ((iothubClientResult = IoTHubDeviceClient_LL_SendTelemetryAsync(deviceClient, messageHandle, NULL, NULL)) != IOTHUB_CLIENT_OK)
{
LogError("Unable to send telemetry message, error=%d", iothubClientResult);
}
IoTHubMessage_Destroy(messageHandle);
}
在 pnp_thermostat_component.c 中，PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property 函式會將 maxTempSinceLastReboot 屬性更新從元件傳送至 IoT Central：
void PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(PNP_THERMOSTAT_COMPONENT_HANDLE pnpThermostatComponentHandle, IOTHUB_DEVICE_CLIENT_LL_HANDLE deviceClient)
{
PNP_THERMOSTAT_COMPONENT* pnpThermostatComponent = (PNP_THERMOSTAT_COMPONENT*)pnpThermostatComponentHandle;
char maximumTemperatureAsString[MAX_TEMPERATURE_SINCE_REBOOT_BUFFER_SIZE];
IOTHUB_CLIENT_RESULT iothubClientResult;
if (snprintf(maximumTemperatureAsString, sizeof(maximumTemperatureAsString), g_maxTempSinceLastRebootPropertyFormat, pnpThermostatComponent->maxTemperature) < 0)
{
LogError("Unable to create max temp since last reboot string for reporting result");
}
else
{
IOTHUB_CLIENT_PROPERTY_REPORTED maxTempProperty;
maxTempProperty.structVersion = IOTHUB_CLIENT_PROPERTY_REPORTED_STRUCT_VERSION_1;
maxTempProperty.name = g_maxTempSinceLastRebootPropertyName;
maxTempProperty.value = maximumTemperatureAsString;
unsigned char* propertySerialized = NULL;
size_t propertySerializedLength;
// The first step of reporting properties is to serialize IOTHUB_CLIENT_PROPERTY_WRITABLE_RESPONSE into JSON for sending.
if ((iothubClientResult = IoTHubClient_Properties_Serializer_CreateReported(&maxTempProperty, 1, pnpThermostatComponent->componentName, &propertySerialized, &propertySerializedLength)) != IOTHUB_CLIENT_OK)
{
LogError("Unable to serialize reported state, error=%d", iothubClientResult);
}
// The output of IoTHubClient_Properties_Serializer_CreateReported is sent to IoTHubDeviceClient_LL_SendPropertiesAsync to perform network I/O.
else if ((iothubClientResult = IoTHubDeviceClient_LL_SendPropertiesAsync(deviceClient, propertySerialized, propertySerializedLength, NULL, NULL)) != IOTHUB_CLIENT_OK)
{
LogError("Unable to send reported state, error=%d", iothubClientResult);
}
else
{
LogInfo("Sending %s property to IoTHub for component %s", g_maxTempSinceLastRebootPropertyName, pnpThermostatComponent->componentName);
}
IoTHubClient_Properties_Serializer_Destroy(propertySerialized);
}
}
在 pnp_thermostat_component.c 中，PnP_ThermostatComponent_ProcessPropertyUpdate 函式會處理來自 IoT Central 的可寫入屬性更新：
void PnP_ThermostatComponent_ProcessPropertyUpdate(PNP_THERMOSTAT_COMPONENT_HANDLE pnpThermostatComponentHandle, IOTHUB_DEVICE_CLIENT_LL_HANDLE deviceClient, const char* propertyName, const char* propertyValue, int version)
{
PNP_THERMOSTAT_COMPONENT* pnpThermostatComponent = (PNP_THERMOSTAT_COMPONENT*)pnpThermostatComponentHandle;
if (strcmp(propertyName, g_targetTemperaturePropertyName) != 0)
{
LogError("Property %s was requested to be changed but is not part of the thermostat interface definition", propertyName);
}
else
{
char* next;
double targetTemperature = strtod(propertyValue, &next);
if ((propertyValue == next) || (targetTemperature == HUGE_VAL) || (targetTemperature == (-1*HUGE_VAL)))
{
LogError("Property %s is not a valid number", propertyValue);
SendTargetTemperatureResponse(pnpThermostatComponent, deviceClient, propertyValue, PNP_STATUS_BAD_FORMAT, version, g_temperaturePropertyResponseDescriptionNotInt);
}
else
{
LogInfo("Received targetTemperature %f for component %s", targetTemperature, pnpThermostatComponent->componentName);
bool maxTempUpdated = false;
UpdateTemperatureAndStatistics(pnpThermostatComponent, targetTemperature, &maxTempUpdated);
// The device needs to let the service know that it has received the targetTemperature desired property.
SendTargetTemperatureResponse(pnpThermostatComponent, deviceClient, propertyValue, PNP_STATUS_SUCCESS, version, NULL);
if (maxTempUpdated)
{
// If the maximum temperature has been updated, we also report this as a property.
PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(pnpThermostatComponent, deviceClient);
}
}
}
}
在 pnp_thermostat_component.c 中，PnP_ThermostatComponent_ProcessCommand 函式會處理從 IoT Central 呼叫的命令：
void PnP_ThermostatComponent_ProcessCommand(PNP_THERMOSTAT_COMPONENT_HANDLE pnpThermostatComponentHandle, const char *pnpCommandName, JSON_Value* commandJsonValue, IOTHUB_CLIENT_COMMAND_RESPONSE* commandResponse)
{
PNP_THERMOSTAT_COMPONENT* pnpThermostatComponent = (PNP_THERMOSTAT_COMPONENT*)pnpThermostatComponentHandle;
const char* sinceStr;
if (strcmp(pnpCommandName, g_getMaxMinReportCommandName) != 0)
{
LogError("Command %s is not supported on thermostat component", pnpCommandName);
commandResponse->statusCode = PNP_STATUS_NOT_FOUND;
}
// See caveats section in ../readme.md; we don't actually respect this sinceStr to keep the sample simple,
// but want to demonstrate how to parse out in any case.
else if ((sinceStr = json_value_get_string(commandJsonValue)) == NULL)
{
LogError("Cannot retrieve JSON string for command");
commandResponse->statusCode = PNP_STATUS_BAD_FORMAT;
}
else if (BuildMaxMinCommandResponse(pnpThermostatComponent, commandResponse) == false)
{
LogError("Unable to build response for component %s", pnpThermostatComponent->componentName);
commandResponse->statusCode = PNP_STATUS_INTERNAL_ERROR;
}
else
{
LogInfo("Returning success from command request for component %s", pnpThermostatComponent->componentName);
commandResponse->statusCode = PNP_STATUS_SUCCESS;
}
}
建置程式碼
您可以使用裝置 SDK 建置包含的範例程式碼：
在裝置 SDK 根資料夾中建立 cmake 子目錄，並瀏覽至該資料夾：
cd azure-iot-sdk-c mkdir cmake cd cmake執行下列命令，以建置 SDK 和範例：
cmake -Duse_prov_client=ON -Dhsm_type_symm_key=ON -Drun_e2e_tests=OFF .. cmake --build .
取得連線資訊
稍後在本教學課程中執行範例裝置應用程式時，您需要下列組態值：
- 識別碼範圍：在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組]。 記下識別碼範圍值。
- 群組主索引鍵：在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組] > [SAS-IoT-Devices]。 記下共用存取簽章主要金鑰值。
使用 Azure Cloud Shell 從您擷取的群組主索引鍵產生裝置金鑰：
az extension add --name azure-iot
az iot central device compute-device-key --device-id sample-device-01 --pk <the group primary key value>
記下產生的裝置金鑰，您稍後將在本教學課程中使用此值。
注意
若要執行此範例，您不需要事先在 IoT Central 應用程式中註冊裝置。 此範例會使用 IoT Central 功能，在第一次連線時自動註冊裝置。
執行程式碼
若要執行範例應用程式，請開啟命令列環境，然後瀏覽至 azure-iot-sdk-c\cmake 資料夾。
設定環境變數來設定範例。 下列程式碼片段顯示如何在 Windows 命令提示字元中設定環境變數。 如果您使用 bash shell，請以 export 命令取代 set 命令：
set IOTHUB_DEVICE_SECURITY_TYPE=DPS
set IOTHUB_DEVICE_DPS_ID_SCOPE=<The ID scope you made a note of previously>
set IOTHUB_DEVICE_DPS_DEVICE_ID=sample-device-01
set IOTHUB_DEVICE_DPS_DEVICE_KEY=<The generated device key you made a note of previously>
set IOTHUB_DEVICE_DPS_ENDPOINT=global.azure-devices-provisioning.net
若要執行範例：
# Bash
cd iothub_client/samples/pnp/pnp_temperature_controller/
./pnp_temperature_controller
REM Windows
cd iothub_client\samples\pnp\pnp_temperature_controller\Debug
.\pnp_temperature_controller.exe
下列輸出顯示裝置註冊和連線到 IoT Central。 範本開始傳送遙測：
Info: Initiating DPS client to retrieve IoT Hub connection information
-> 09:43:27 CONNECT | VER: 4 | KEEPALIVE: 0 | FLAGS: 194 | USERNAME: 0ne0026656D/registrations/sample-device-01/api-version=2019-03-31&ClientVersion=1.6.0 | PWD: XXXX | CLEAN: 1
<- 09:43:28 CONNACK | SESSION_PRESENT: false | RETURN_CODE: 0x0
-> 09:43:29 SUBSCRIBE | PACKET_ID: 1 | TOPIC_NAME: $dps/registrations/res/# | QOS: 1
<- 09:43:30 SUBACK | PACKET_ID: 1 | RETURN_CODE: 1
-> 09:43:30 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_MOST_ONCE | TOPIC_NAME: $dps/registrations/PUT/iotdps-register/?$rid=1 | PAYLOAD_LEN: 102
<- 09:43:31 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_LEAST_ONCE | TOPIC_NAME: $dps/registrations/res/202/?$rid=1&retry-after=3 | PACKET_ID: 2 | PAYLOAD_LEN: 94
-> 09:43:31 PUBACK | PACKET_ID: 2
-> 09:43:33 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_MOST_ONCE | TOPIC_NAME: $dps/registrations/GET/iotdps-get-operationstatus/?$rid=2&operationId=4.2f792ade0a5c3e68.baf0e879-d88a-4153-afef-71aff51fd847 | PAYLOAD_LEN: 102
<- 09:43:34 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_LEAST_ONCE | TOPIC_NAME: $dps/registrations/res/202/?$rid=2&retry-after=3 | PACKET_ID: 2 | PAYLOAD_LEN: 173
-> 09:43:34 PUBACK | PACKET_ID: 2
-> 09:43:36 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_MOST_ONCE | TOPIC_NAME: $dps/registrations/GET/iotdps-get-operationstatus/?$rid=3&operationId=4.2f792ade0a5c3e68.baf0e879-d88a-4153-afef-71aff51fd847 | PAYLOAD_LEN: 102
<- 09:43:37 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_LEAST_ONCE | TOPIC_NAME: $dps/registrations/res/200/?$rid=3 | PACKET_ID: 2 | PAYLOAD_LEN: 478
-> 09:43:37 PUBACK | PACKET_ID: 2
Info: Provisioning callback indicates success. iothubUri=iotc-60a....azure-devices.net, deviceId=sample-device-01
-> 09:43:37 DISCONNECT
Info: DPS successfully registered. Continuing on to creation of IoTHub device client handle.
Info: Successfully created device client. Hit Control-C to exit program
Info: Sending serialNumber property to IoTHub
Info: Sending device information property to IoTHub. propertyName=swVersion, propertyValue="1.0.0.0"
Info: Sending device information property to IoTHub. propertyName=manufacturer, propertyValue="Sample-Manufacturer"
Info: Sending device information property to IoTHub. propertyName=model, propertyValue="sample-Model-123"
Info: Sending device information property to IoTHub. propertyName=osName, propertyValue="sample-OperatingSystem-name"
Info: Sending device information property to IoTHub. propertyName=processorArchitecture, propertyValue="Contoso-Arch-64bit"
Info: Sending device information property to IoTHub. propertyName=processorManufacturer, propertyValue="Processor Manufacturer(TM)"
Info: Sending device information property to IoTHub. propertyName=totalStorage, propertyValue=10000
Info: Sending device information property to IoTHub. propertyName=totalMemory, propertyValue=200
Info: Sending maximumTemperatureSinceLastReboot property to IoTHub for component=thermostat1
Info: Sending maximumTemperatureSinceLastReboot property to IoTHub for component=thermostat2
-> 09:43:44 CONNECT | VER: 4 | KEEPALIVE: 240 | FLAGS: 192 | USERNAME: iotc-60a576a2-eec7-48e2-9306-9e7089a79995.azure-devices.net/sample-device-01/?api-version=2020-09-30&DeviceClientType=iothubclient%2f1.6.0%20(native%3b%20Linux%3b%20x86_64)&model-id=dtmi%3acom%3aexample%3aTemperatureController%3b1 | PWD: XXXX | CLEAN: 0
<- 09:43:44 CONNACK | SESSION_PRESENT: false | RETURN_CODE: 0x0
-> 09:43:44 SUBSCRIBE | PACKET_ID: 2 | TOPIC_NAME: $iothub/twin/res/# | QOS: 0 | TOPIC_NAME: $iothub/methods/POST/# | QOS: 0
-> 09:43:44 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_LEAST_ONCE | TOPIC_NAME: devices/sample-device-01/messages/events/ | PACKET_ID: 3 | PAYLOAD_LEN: 19
-> 09:43:44 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_LEAST_ONCE | TOPIC_NAME: devices/sample-device-01/messages/events/%24.sub=thermostat1 | PACKET_ID: 4 | PAYLOAD_LEN: 21
-> 09:43:44 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_LEAST_ONCE | TOPIC_NAME: devices/sample-device-01/messages/events/%24.sub=thermostat2 | PACKET_ID: 5 | PAYLOAD_LEN: 21
身為 Azure IoT Central 應用程式的操作者，您可以：
在 [概觀] 頁面上檢視兩個控溫器元件所傳送的遙測：
在 [關於] 頁面上，檢視裝置屬性。 此頁面會顯示裝置資訊元件和兩個控溫器元件的屬性：
自訂裝置範本
身為解決方案開發人員，您可以自訂在溫度控制器裝置連線時自動建立的 IoT Central 裝置範本。
若要新增雲端屬性來儲存與裝置相關聯的客戶名稱：
在 IoT Central 應用程式中，瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
在 [溫度控制器] 模型中，選取 [+新增功能]。
輸入 [客戶名稱] 作為 [顯示名稱]、選取 [雲端屬性] 作為功能類型、展開項目，然後選擇 [字串] 作為 [結構描述]。 然後選取儲存。
若要自訂 Get Max-Min report 命令在 IoT Central 應用程式中顯示的方式：
瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
針對 getMaxMinReport (thermostat1)，請將 Get Max-Min report. 取代為 Get thermostat1 status report。
針對 getMaxMinReport (thermostat2)，請將 Get Max-Min report. 取代為 Get thermostat2 status report。
選取 [儲存]。
若要自訂 [目標溫度] 可寫入屬性在 IoT Central 應用程式中顯示的方式：
瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
針對 targetTemperature (thermostat1)，將 [目標溫度] 取代為 [目標溫度 (1)]。
針對 targetTemperature (thermostat2)，將 [目標溫度] 取代為 [目標溫度 (2)]。
選取 [儲存]。
溫度控制器模型中的控溫器模型包含目標溫度可寫入屬性，裝置範本包含客戶名稱雲端屬性。 若要建立操作員可以編輯這些屬性的檢視：
選取 [檢視]，再選取 [編輯裝置和雲端資料] 圖格。
輸入「屬性」作為表單名稱。
選取 [目標溫度 (1)]、[目標溫度 (2)]，以及 [客戶名稱] 屬性。 然後選取 [新增區段]。
儲存您的變更。
發佈裝置範本
您必須先發佈裝置範本，操作員才能看到並使用您的自訂項目。
從控溫器裝置範本中，選取 [發佈]。 在 [將此裝置範本發佈至應用程式] 面板上，選取 [發佈]。
操作員現在可以使用 [屬性] 檢視來更新屬性值，並在裝置命令頁面上呼叫稱為 Get thermostat1 status report 和 Get thermostat2 status report 的命令：
在 [屬性] 頁面上更新可寫入的屬性值：
呼叫 [命令] 頁面中的命令。 如果您執行狀態報告命令，請在執行該命令之前，先選取 [自從] 參數的日期和時間：
您可看到裝置如何回應命令和屬性更新：
<- 09:49:03 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_MOST_ONCE | TOPIC_NAME: $iothub/methods/POST/thermostat1*getMaxMinReport/?$rid=1 | PAYLOAD_LEN: 26
Info: Received PnP command for component=thermostat1, command=getMaxMinReport
Info: Returning success from command request for component=thermostat1
-> 09:49:03 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_MOST_ONCE | TOPIC_NAME: $iothub/methods/res/200/?$rid=1 | PAYLOAD_LEN: 117
...
<- 09:50:04 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_MOST_ONCE | TOPIC_NAME: $iothub/twin/PATCH/properties/desired/?$version=2 | PAYLOAD_LEN: 63
Info: Received targetTemperature=67.000000 for component=thermostat2
Info: Sending acknowledgement of property to IoTHub for component=thermostat2
必要條件
若要完成本文中的步驟，您需要下列資源︰
啟用中的 Azure 訂用帳戶。 如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
從自訂應用程式範本建立的 IoT Central 應用程式。 若要深入了解，請參閱建立 IoT Central 應用程式和關於您的應用程式。
Visual Studio (Community、Professional 或 Enterprise) 版本的開發電腦。
Microsoft Azure IoT SDK for C# (.NET) GitHub 存放庫的本機複本，其中包含範例程式碼。 使用此連結來下載存放庫的複本：下載 ZIP。 接著將檔案解壓縮到本機電腦上的適當位置。
檢閱程式碼
在您先前所下載 Microsoft Azure IoT SDK for C# 存放庫的複本中，在 Visual Studio 中開啟 azure-iot-sdk-csharp-main\azureiot.sln 方案檔。 在 [方案總管] 中 ，展開 [PnpDeviceSamples > TemperatureController] 資料夾，然後開啟 Program.cs 和 TemperatureControllerSample.cs 檔案，以檢視此範例的程式碼。
此範例會實作多重元件溫度控制器數位對應項定義語言模型。
執行範例以連線到 IoT Central 時，該檔案會使用裝置佈建服務 (DPS) 來註冊裝置並產生連接字串。 此範例會從環境中取出所需的 DPS 連線資訊。
在 Program.cs 中，Main 方法會呼叫 SetupDeviceClientAsync 來執行下列動作：
- 在透過 DPS 佈建裝置時，使用模型識別碼
dtmi:com:example:TemperatureController;2。 IoT Central 會使用型號識別碼來識別或產生此裝置的裝置範本。 若要深入了解，請參閱將裝置指派給裝置範本。 - 建立 DeviceClient 執行個體以連線到 IoT Central。
private static async Task<DeviceClient> SetupDeviceClientAsync(Parameters parameters, CancellationToken cancellationToken)
{
DeviceClient deviceClient;
switch (parameters.DeviceSecurityType.ToLowerInvariant())
{
case "dps":
DeviceRegistrationResult dpsRegistrationResult = await ProvisionDeviceAsync(parameters, cancellationToken);
var authMethod = new DeviceAuthenticationWithRegistrySymmetricKey(dpsRegistrationResult.DeviceId, parameters.DeviceSymmetricKey);
deviceClient = InitializeDeviceClient(dpsRegistrationResult.AssignedHub, authMethod);
break;
case "connectionstring":
// ...
default:
// ...
}
return deviceClient;
}
Main 方法接著會建立 TemperatureControllerSample 執行個體，並呼叫 PerformOperationsAsync 方法來處理與 IoT Central 的互動。
在 TemperatureControllerSample.cs 中，PerformOperationsAsync 方法會：
- 在預設元件上設定 reboot 命令的處理常式。
- 設定兩個控溫器元件上 getMaxMinReport 命令的處理常式。
- 設定處理常式，以接收兩個控溫器元件上的目標溫度屬性更新。
- 傳送初始裝置資訊屬性更新。
- 定期從兩個控溫器元件傳送溫度遙測。
- 定期從預設元件傳送工作集遙測資料。
- 每當兩個控溫器元件中達到新的最高溫度時，傳送自上次重新啟動以來的最高溫度。
public async Task PerformOperationsAsync(CancellationToken cancellationToken)
{
await _deviceClient.SetMethodHandlerAsync("reboot", HandleRebootCommandAsync, _deviceClient, cancellationToken);
// For a component-level command, the command name is in the format "<component-name>*<command-name>".
await _deviceClient.SetMethodHandlerAsync("thermostat1*getMaxMinReport", HandleMaxMinReportCommand, Thermostat1, cancellationToken);
await _deviceClient.SetMethodHandlerAsync("thermostat2*getMaxMinReport", HandleMaxMinReportCommand, Thermostat2, cancellationToken);
await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(SetDesiredPropertyUpdateCallback, null, cancellationToken);
_desiredPropertyUpdateCallbacks.Add(Thermostat1, TargetTemperatureUpdateCallbackAsync);
_desiredPropertyUpdateCallbacks.Add(Thermostat2, TargetTemperatureUpdateCallbackAsync);
await UpdateDeviceInformationAsync(cancellationToken);
await SendDeviceSerialNumberAsync(cancellationToken);
bool temperatureReset = true;
_maxTemp[Thermostat1] = 0d;
_maxTemp[Thermostat2] = 0d;
while (!cancellationToken.IsCancellationRequested)
{
if (temperatureReset)
{
// Generate a random value between 5.0°C and 45.0°C for the current temperature reading for each "Thermostat" component.
_temperature[Thermostat1] = Math.Round(s_random.NextDouble() * 40.0 + 5.0, 1);
_temperature[Thermostat2] = Math.Round(s_random.NextDouble() * 40.0 + 5.0, 1);
}
await SendTemperatureAsync(Thermostat1, cancellationToken);
await SendTemperatureAsync(Thermostat2, cancellationToken);
await SendDeviceMemoryAsync(cancellationToken);
temperatureReset = _temperature[Thermostat1] == 0 && _temperature[Thermostat2] == 0;
await Task.Delay(5 * 1000);
}
}
SendTemperatureAsync 方法會顯示裝置如何將溫度遙測資料從元件傳送至 IoT Central。 SendTemperatureTelemetryAsync 方法會使用 PnpConvention 類別來建置訊息：
private async Task SendTemperatureAsync(string componentName, CancellationToken cancellationToken)
{
await SendTemperatureTelemetryAsync(componentName, cancellationToken);
double maxTemp = _temperatureReadingsDateTimeOffset[componentName].Values.Max<double>();
if (maxTemp > _maxTemp[componentName])
{
_maxTemp[componentName] = maxTemp;
await UpdateMaxTemperatureSinceLastRebootAsync(componentName, cancellationToken);
}
}
private async Task SendTemperatureTelemetryAsync(string componentName, CancellationToken cancellationToken)
{
const string telemetryName = "temperature";
double currentTemperature = _temperature[componentName];
using Message msg = PnpConvention.CreateMessage(telemetryName, currentTemperature, componentName);
await _deviceClient.SendEventAsync(msg, cancellationToken);
if (_temperatureReadingsDateTimeOffset.ContainsKey(componentName))
{
_temperatureReadingsDateTimeOffset[componentName].TryAdd(DateTimeOffset.UtcNow, currentTemperature);
}
else
{
_temperatureReadingsDateTimeOffset.TryAdd(
componentName,
new Dictionary<DateTimeOffset, double>
{
{ DateTimeOffset.UtcNow, currentTemperature },
});
}
}
UpdateMaxTemperatureSinceLastRebootAsync 方法會將 maxTempSinceLastReboot 屬性更新傳送至 IoT Central。 這個方法會使用 PnpConvention 類別來建立修補程式：
private async Task UpdateMaxTemperatureSinceLastRebootAsync(string componentName, CancellationToken cancellationToken)
{
const string propertyName = "maxTempSinceLastReboot";
double maxTemp = _maxTemp[componentName];
TwinCollection reportedProperties = PnpConvention.CreateComponentPropertyPatch(componentName, propertyName, maxTemp);
await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties, cancellationToken);
}
TargetTemperatureUpdateCallbackAsync 方法會處理來自 IoT Central 的可寫入目標溫度屬性更新。 這個方法會使用 PnpConvention 類別來讀取屬性更新訊息，並建構回應：
private async Task TargetTemperatureUpdateCallbackAsync(TwinCollection desiredProperties, object userContext)
{
const string propertyName = "targetTemperature";
string componentName = (string)userContext;
bool targetTempUpdateReceived = PnpConvention.TryGetPropertyFromTwin(
desiredProperties,
propertyName,
out double targetTemperature,
componentName);
if (!targetTempUpdateReceived)
{
return;
}
TwinCollection pendingReportedProperty = PnpConvention.CreateComponentWritablePropertyResponse(
componentName,
propertyName,
targetTemperature,
(int)StatusCode.InProgress,
desiredProperties.Version);
await _deviceClient.UpdateReportedPropertiesAsync(pendingReportedProperty);
// Update Temperature in 2 steps
double step = (targetTemperature - _temperature[componentName]) / 2d;
for (int i = 1; i <= 2; i++)
{
_temperature[componentName] = Math.Round(_temperature[componentName] + step, 1);
await Task.Delay(6 * 1000);
}
TwinCollection completedReportedProperty = PnpConvention.CreateComponentWritablePropertyResponse(
componentName,
propertyName,
_temperature[componentName],
(int)StatusCode.Completed,
desiredProperties.Version,
"Successfully updated target temperature");
await _deviceClient.UpdateReportedPropertiesAsync(completedReportedProperty);
}
HandleMaxMinReportCommand 方法會處理從 IoT Central 呼叫之元件的命令：
private Task<MethodResponse> HandleMaxMinReportCommand(MethodRequest request, object userContext)
{
try
{
string componentName = (string)userContext;
DateTime sinceInUtc = JsonConvert.DeserializeObject<DateTime>(request.DataAsJson);
var sinceInDateTimeOffset = new DateTimeOffset(sinceInUtc);
if (_temperatureReadingsDateTimeOffset.ContainsKey(componentName))
{
Dictionary<DateTimeOffset, double> allReadings = _temperatureReadingsDateTimeOffset[componentName];
Dictionary<DateTimeOffset, double> filteredReadings = allReadings.Where(i => i.Key > sinceInDateTimeOffset)
.ToDictionary(i => i.Key, i => i.Value);
if (filteredReadings != null && filteredReadings.Any())
{
var report = new
{
maxTemp = filteredReadings.Values.Max<double>(),
minTemp = filteredReadings.Values.Min<double>(),
avgTemp = filteredReadings.Values.Average(),
startTime = filteredReadings.Keys.Min(),
endTime = filteredReadings.Keys.Max(),
};
byte[] responsePayload = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(report));
return Task.FromResult(new MethodResponse(responsePayload, (int)StatusCode.Completed));
}
return Task.FromResult(new MethodResponse((int)StatusCode.NotFound));
}
return Task.FromResult(new MethodResponse((int)StatusCode.NotFound));
}
catch (JsonReaderException ex)
{
// ...
}
}
取得連線資訊
稍後在本教學課程中執行範例裝置應用程式時，您需要下列組態值：
- 識別碼範圍：在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組]。 記下識別碼範圍值。
- 群組主索引鍵：在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組] > [SAS-IoT-Devices]。 記下共用存取簽章主要金鑰值。
使用 Azure Cloud Shell 從您擷取的群組主索引鍵產生裝置金鑰：
az extension add --name azure-iot
az iot central device compute-device-key --device-id sample-device-01 --pk <the group primary key value>
記下產生的裝置金鑰，您稍後將在本教學課程中使用此值。
注意
若要執行此範例，您不需要事先在 IoT Central 應用程式中註冊裝置。 此範例會使用 IoT Central 功能，在第一次連線時自動註冊裝置。
執行程式碼
注意
在執行程式碼之前，請先將 TemperatureController 設定為啟始專案。
若要在 Visual Studio 中執行範例應用程式：
在 [方案總管] 中，選取 [PnpDeviceSamples > TemperatureController] 專案檔。
瀏覽至 [專案] > [TemperatureController 屬性] > [偵錯]。 然後將下列環境變數新增至專案：
名稱 值 IOTHUB_DEVICE_SECURITY_TYPE DPS IOTHUB_DEVICE_DPS_ENDPOINT global.azure-devices-provisioning.net IOTHUB_DEVICE_DPS_ID_SCOPE 您先前記下的識別碼範圍值。 IOTHUB_DEVICE_DPS_DEVICE_ID sample-device-01 IOTHUB_DEVICE_DPS_DEVICE_KEY 您先前所記下的已產生裝置金鑰值。
您現在可以在 Visual Studio 中執行和偵錯範例。
下列輸出顯示裝置註冊和連線到 IoT Central。 範本開始傳送遙測：
[03/31/2021 14:43:17]info: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Press Control+C to quit the sample.
[03/31/2021 14:43:17]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Set up the device client.
[03/31/2021 14:43:18]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Initializing via DPS
[03/31/2021 14:43:27]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Set handler for 'reboot' command.
[03/31/2021 14:43:27]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Connection status change registered - status=Connected, reason=Connection_Ok.
[03/31/2021 14:43:28]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Set handler for "getMaxMinReport" command.
[03/31/2021 14:43:28]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Set handler to receive 'targetTemperature' updates.
[03/31/2021 14:43:28]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Property: Update - component = 'deviceInformation', properties update is complete.
[03/31/2021 14:43:28]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Property: Update - { "serialNumber": "SR-123456" } is complete.
[03/31/2021 14:43:29]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Telemetry: Sent - component="thermostat1", { "temperature": 34.2 } in °C.
[03/31/2021 14:43:29]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Property: Update - component="thermostat1", { "maxTempSinceLastReboot": 34.2 } in °C is complete.
[03/31/2021 14:43:29]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Telemetry: Sent - component="thermostat2", { "temperature": 25.1 } in °C.
[03/31/2021 14:43:29]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Property: Update - component="thermostat2", { "maxTempSinceLastReboot": 25.1 } in °C is complete.
[03/31/2021 14:43:29]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Telemetry: Sent - {"workingSet":31412} in KB.
身為 Azure IoT Central 應用程式的操作者，您可以：
在 [概觀] 頁面上檢視兩個控溫器元件所傳送的遙測：
在 [關於] 頁面上，檢視裝置屬性。 此頁面會顯示裝置資訊元件和兩個控溫器元件的屬性：
自訂裝置範本
身為解決方案開發人員，您可以自訂在溫度控制器裝置連線時自動建立的 IoT Central 裝置範本。
若要新增雲端屬性來儲存與裝置相關聯的客戶名稱：
在 IoT Central 應用程式中，瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
在 [溫度控制器] 模型中，選取 [+新增功能]。
輸入 [客戶名稱] 作為 [顯示名稱]、選取 [雲端屬性] 作為功能類型、展開項目，然後選擇 [字串] 作為 [結構描述]。 然後選取儲存。
若要自訂 Get Max-Min report 命令在 IoT Central 應用程式中顯示的方式：
瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
針對 getMaxMinReport (thermostat1)，請將 Get Max-Min report. 取代為 Get thermostat1 status report。
針對 getMaxMinReport (thermostat2)，請將 Get Max-Min report. 取代為 Get thermostat2 status report。
選取 [儲存]。
若要自訂 [目標溫度] 可寫入屬性在 IoT Central 應用程式中顯示的方式：
瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
針對 targetTemperature (thermostat1)，將 [目標溫度] 取代為 [目標溫度 (1)]。
針對 targetTemperature (thermostat2)，將 [目標溫度] 取代為 [目標溫度 (2)]。
選取 [儲存]。
溫度控制器模型中的控溫器模型包含目標溫度可寫入屬性，裝置範本包含客戶名稱雲端屬性。 若要建立操作員可以編輯這些屬性的檢視：
選取 [檢視]，再選取 [編輯裝置和雲端資料] 圖格。
輸入「屬性」作為表單名稱。
選取 [目標溫度 (1)]、[目標溫度 (2)]，以及 [客戶名稱] 屬性。 然後選取 [新增區段]。
儲存您的變更。
發佈裝置範本
您必須先發佈裝置範本，操作員才能看到並使用您的自訂項目。
從控溫器裝置範本中，選取 [發佈]。 在 [將此裝置範本發佈至應用程式] 面板上，選取 [發佈]。
操作員現在可以使用 [屬性] 檢視來更新屬性值，並在裝置命令頁面上呼叫稱為 Get thermostat1 status report 和 Get thermostat2 status report 的命令：
在 [屬性] 頁面上更新可寫入的屬性值：
呼叫 [命令] 頁面中的命令。 如果您執行狀態報告命令，請在執行該命令之前，先選取 [自從] 參數的日期和時間：
您可看到裝置如何回應命令和屬性更新：
[03/31/2021 14:47:00]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Command: Received - component="thermostat2", generating max, min and avg temperature report since 31/03/2021 06:00:00.
[03/31/2021 14:47:00]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Command: component="thermostat2", MaxMinReport since 31/03/2021 06:00:00: maxTemp=36.4, minTemp=36.4, avgTemp=36.4, startTime=31/03/2021 14:46:33, endTime=31/03/2021 14:46:55
...
[03/31/2021 14:46:36]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Property: Received - component="thermostat1", { "targetTemperature": 67°C }.
[03/31/2021 14:46:36]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Property: Update - component="thermostat1", {"targetTemperature": 67 } in °C is InProgress.
[03/31/2021 14:46:49]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Property: Update - component="thermostat1", {"targetTemperature": 67 } in °C is Completed
[03/31/2021 14:46:49]dbug: Microsoft.Azure.Devices.Client.Samples.TemperatureControllerSample[0]
Telemetry: Sent - component="thermostat1", { "temperature": 67 } in °C.
必要條件
若要完成本文中的步驟，您需要下列資源︰
啟用中的 Azure 訂用帳戶。 如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
從自訂應用程式範本建立的 IoT Central 應用程式。 若要深入了解，請參閱建立 IoT Central 應用程式和關於您的應用程式。
Java SE 開發套件 8 或更新版本的開發電腦。 如需詳細資訊，請參閱安裝 JDK。
Microsoft Azure IoT SDK for JAVA GitHub 存放庫的本機複本，其中包含範例程式碼。 使用此連結來下載存放庫的複本：下載 ZIP。 接著將檔案解壓縮到本機電腦上的適當位置。
檢閱程式碼
在您先前下載的 Microsoft Azure IoT SDK for JAVA 複本中，以文字編輯器開啟 azure-iot-sdk-java/iothub/device/iot-device-samples/pnp-device-sample/temperature-controller-device-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/device/TemperatureController.java 檔案。
此範例會實作多重元件溫度控制器數位對應項定義語言模型。
執行範例以連線到 IoT Central 時，該檔案會使用裝置佈建服務 (DPS) 來註冊裝置並產生連接字串。 此範例會從命令列環境中，取出所需的 DPS 連線資訊。
main 方法：
- 呼叫
initializeAndProvisionDevice來設定dtmi:com:example:TemperatureController;2模型識別碼、使用 DPS 來佈建和註冊裝置、建立 DeviceClient 執行個體，以及連線到您的 IoT Central 應用程式。 IoT Central 會使用型號識別碼來識別或產生此裝置的裝置範本。 若要深入了解，請參閱將裝置指派給裝置範本。 - 建立
getMaxMinReport和reboot命令的命令處理常式。 - 建立可寫入
targetTemperature屬性的屬性更新處理常式。 - 傳送 [裝置資訊] 介面和 [裝置記憶體] 和 [序號] 屬性中屬性的初始值。
- 啟動執行緒以從兩個控溫器傳送溫度遙測，並每隔五秒更新
maxTempSinceLastReboot屬性。
public static void main(String[] args) throws Exception {
// ...
switch (deviceSecurityType.toLowerCase())
{
case "dps":
{
if (validateArgsForDpsFlow())
{
initializeAndProvisionDevice();
break;
}
throw new IllegalArgumentException("Required environment variables are not set for DPS flow, please recheck your environment.");
}
case "connectionstring":
{
// ...
}
default:
{
// ...
}
}
deviceClient.subscribeToMethods(new MethodCallback(), null);
deviceClient.subscribeToDesiredPropertiesAsync(
{
(twin, context) ->
TwinCollection desiredProperties = twin.getDesiredProperties();
for (String desiredPropertyKey : desiredProperties.keySet())
{
TargetTemperatureUpdateCallback.onPropertyChanged(new Property(desiredPropertyKey, desiredProperties.get(desiredPropertyKey)), null);
}
},
null,
(exception, context) ->
{
if (exception == null)
{
log.info("Successfully subscribed to desired properties. Getting initial state");
deviceClient.getTwinAsync(
(twin, getTwinException, getTwinContext) ->
{
log.info("Initial twin state received");
log.info(twin.toString());
},
null);
}
else
{
log.info("Failed to subscribe to desired properties. Error code {}", exception.getStatusCode());
System.exit(-1);
}
},
null);
updateDeviceInformation();
sendDeviceMemory();
sendDeviceSerialNumber();
final AtomicBoolean temperatureReset = new AtomicBoolean(true);
maxTemperature.put(THERMOSTAT_1, 0.0d);
maxTemperature.put(THERMOSTAT_2, 0.0d);
new Thread(new Runnable() {
@SneakyThrows({InterruptedException.class, IOException.class})
@Override
public void run() {
while (true) {
if (temperatureReset.get()) {
// Generate a random value between 5.0°C and 45.0°C for the current temperature reading for each "Thermostat" component.
temperature.put(THERMOSTAT_1, BigDecimal.valueOf(random.nextDouble() * 40 + 5).setScale(1, RoundingMode.HALF_UP).doubleValue());
temperature.put(THERMOSTAT_2, BigDecimal.valueOf(random.nextDouble() * 40 + 5).setScale(1, RoundingMode.HALF_UP).doubleValue());
}
sendTemperatureReading(THERMOSTAT_1);
sendTemperatureReading(THERMOSTAT_2);
temperatureReset.set(temperature.get(THERMOSTAT_1) == 0 && temperature.get(THERMOSTAT_2) == 0);
Thread.sleep(5 * 1000);
}
}
}).start();
}
initializeAndProvisionDevice 方法會顯示裝置如何使用 DPS 來註冊及連線到 IoT Central。 承載包含模型識別碼，IoT Central 會用來將裝置指派給裝置範本：
private static void initializeAndProvisionDevice() throws Exception {
SecurityProviderSymmetricKey securityClientSymmetricKey = new SecurityProviderSymmetricKey(deviceSymmetricKey.getBytes(), registrationId);
ProvisioningDeviceClient provisioningDeviceClient;
ProvisioningStatus provisioningStatus = new ProvisioningStatus();
provisioningDeviceClient = ProvisioningDeviceClient.create(globalEndpoint, scopeId, provisioningProtocol, securityClientSymmetricKey);
AdditionalData additionalData = new AdditionalData();
additionalData.setProvisioningPayload(com.microsoft.azure.sdk.iot.provisioning.device.plugandplay.PnpHelper.createDpsPayload(MODEL_ID));
ProvisioningDeviceClientRegistrationResult registrationResult = provisioningDeviceClient.registerDeviceSync(additionalData);
ClientOptions options = ClientOptions.builder().modelId(MODEL_ID).build();
if (registrationResult.getProvisioningDeviceClientStatus() == ProvisioningDeviceClientStatus.PROVISIONING_DEVICE_STATUS_ASSIGNED) {
System.out.println("IotHUb Uri : " + registrationResult.getIothubUri());
System.out.println("Device ID : " + registrationResult.getDeviceId());
String iotHubUri = registrationResult.getIothubUri();
String deviceId = registrationResult.getDeviceId();
log.debug("Opening the device client.");
deviceClient = new DeviceClient(iotHubUri, deviceId, securityClientSymmetricKey, IotHubClientProtocol.MQTT, options);
deviceClient.open(true);
}
}
sendTemperatureTelemetry 方法會顯示裝置如何將溫度遙測資料從元件傳送至 IoT Central。 這個方法會使用 PnpConvention 類別來建立訊息：
private static void sendTemperatureTelemetry(String componentName) {
String telemetryName = "temperature";
double currentTemperature = temperature.get(componentName);
Message message = PnpConvention.createIotHubMessageUtf8(telemetryName, currentTemperature, componentName);
deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
// Add the current temperature entry to the list of temperature readings.
Map<Date, Double> currentReadings;
if (temperatureReadings.containsKey(componentName)) {
currentReadings = temperatureReadings.get(componentName);
} else {
currentReadings = new HashMap<>();
}
currentReadings.put(new Date(), currentTemperature);
temperatureReadings.put(componentName, currentReadings);
}
updateMaxTemperatureSinceLastReboot 方法會將 maxTempSinceLastReboot 屬性更新從元件傳送至 IoT Central。 這個方法會使用 PnpConvention 類別來建立修補程式：
private static void updateMaxTemperatureSinceLastReboot(String componentName) throws IOException {
String propertyName = "maxTempSinceLastReboot";
double maxTemp = maxTemperature.get(componentName);
TwinCollection reportedProperty = PnpConvention.createComponentPropertyPatch(propertyName, maxTemp, componentName);
deviceClient.updateReportedPropertiesAsync(reportedProperty, sendReportedPropertiesResponseCallback, null);
log.debug("Property: Update - {\"{}\": {}°C} is {}.", propertyName, maxTemp, StatusCode.COMPLETED);
}
TargetTemperatureUpdateCallback 類別包含 onPropertyChanged 方法，可處理來自 IoT Central 元件的可寫入屬性更新。 這個方法會使用 PnpConvention 類別來建立回應：
private static class TargetTemperatureUpdateCallback
{
final static String propertyName = "targetTemperature";
@SneakyThrows(InterruptedException.class)
public static void onPropertyChanged(Property property, Object context) {
String componentName = (String) context;
if (property.getKey().equalsIgnoreCase(componentName)) {
double targetTemperature = (double) ((TwinCollection) property.getValue()).get(propertyName);
log.debug("Property: Received - component=\"{}\", {\"{}\": {}°C}.", componentName, propertyName, targetTemperature);
TwinCollection pendingPropertyPatch = PnpConvention.createComponentWritablePropertyResponse(
propertyName,
targetTemperature,
componentName,
StatusCode.IN_PROGRESS.value,
property.getVersion().longValue(),
null);
deviceClient.updateReportedPropertiesAsync(pendingPropertyPatch, sendReportedPropertiesResponseCallback, null);
log.debug("Property: Update - component=\"{}\", {\"{}\": {}°C} is {}", componentName, propertyName, targetTemperature, StatusCode.IN_PROGRESS);
// Update temperature in 2 steps
double step = (targetTemperature - temperature.get(componentName)) / 2;
for (int i = 1; i <=2; i++) {
temperature.put(componentName, BigDecimal.valueOf(temperature.get(componentName) + step).setScale(1, RoundingMode.HALF_UP).doubleValue());
Thread.sleep(5 * 1000);
}
TwinCollection completedPropertyPatch = PnpConvention.createComponentWritablePropertyResponse(
propertyName,
temperature.get(componentName),
componentName,
StatusCode.COMPLETED.value,
property.getVersion().longValue(),
"Successfully updated target temperature.");
deviceClient.updateReportedPropertiesAsync(completedPropertyPatch, sendReportedPropertiesResponseCallback, null);
log.debug("Property: Update - {\"{}\": {}°C} is {}", propertyName, temperature.get(componentName), StatusCode.COMPLETED);
} else {
log.debug("Property: Received an unrecognized property update from service.");
}
}
}
MethodCallback 類別包含 onMethodInvoked 方法，可處理從 IoT Central 呼叫的元件命令：
private static class MethodCallback implements com.microsoft.azure.sdk.iot.device.twin.MethodCallback
{
final String reboot = "reboot";
final String getMaxMinReport1 = "thermostat1*getMaxMinReport";
final String getMaxMinReport2 = "thermostat2*getMaxMinReport";
@SneakyThrows(InterruptedException.class)
@Override
public DirectMethodResponse onMethodInvoked(String methodName, DirectMethodPayload methodData, Object context) {
String jsonRequest = methodData.getPayload(String.class);
switch (methodName) {
case reboot:
int delay = getCommandRequestValue(jsonRequest, Integer.class);
log.debug("Command: Received - Rebooting thermostat (resetting temperature reading to 0°C after {} seconds).", delay);
Thread.sleep(delay * 1000L);
temperature.put(THERMOSTAT_1, 0.0d);
temperature.put(THERMOSTAT_2, 0.0d);
maxTemperature.put(THERMOSTAT_1, 0.0d);
maxTemperature.put(THERMOSTAT_2, 0.0d);
temperatureReadings.clear();
return new DirectMethodResponse(StatusCode.COMPLETED.value, null);
case getMaxMinReport1:
case getMaxMinReport2:
String[] words = methodName.split("\\*");
String componentName = words[0];
if (temperatureReadings.containsKey(componentName)) {
Date since = getCommandRequestValue(jsonRequest, Date.class);
log.debug("Command: Received - component=\"{}\", generating min, max, avg temperature report since {}", componentName, since);
Map<Date, Double> allReadings = temperatureReadings.get(componentName);
Map<Date, Double> filteredReadings = allReadings.entrySet().stream()
.filter(map -> map.getKey().after(since))
.collect(Collectors.toMap(Entry::getKey, Entry::getValue));
if (!filteredReadings.isEmpty()) {
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
double maxTemp = Collections.max(filteredReadings.values());
double minTemp = Collections.min(filteredReadings.values());
double avgTemp = filteredReadings.values().stream().mapToDouble(Double::doubleValue).average().orElse(Double.NaN);
String startTime = sdf.format(Collections.min(filteredReadings.keySet()));
String endTime = sdf.format(Collections.max(filteredReadings.keySet()));
String responsePayload = String.format(
"{\"maxTemp\": %.1f, \"minTemp\": %.1f, \"avgTemp\": %.1f, \"startTime\": \"%s\", \"endTime\": \"%s\"}",
maxTemp,
minTemp,
avgTemp,
startTime,
endTime);
log.debug("Command: MaxMinReport since {}: \"maxTemp\": {}°C, \"minTemp\": {}°C, \"avgTemp\": {}°C, \"startTime\": {}, \"endTime\": {}",
since,
maxTemp,
minTemp,
avgTemp,
startTime,
endTime);
return new DirectMethodResponse(StatusCode.COMPLETED.value, responsePayload);
}
log.debug("Command: component=\"{}\", no relevant readings found since {}, cannot generate any report.", componentName, since);
return new DirectMethodResponse(StatusCode.NOT_FOUND.value, null);
}
log.debug("Command: component=\"{}\", no temperature readings sent yet, cannot generate any report.", componentName);
return new DirectMethodResponse(StatusCode.NOT_FOUND.value, null);
default:
log.debug("Command: command=\"{}\" is not implemented, no action taken.", methodName);
return new DirectMethodResponse(StatusCode.NOT_FOUND.value, null);
}
}
}
取得連線資訊
稍後在本教學課程中執行範例裝置應用程式時，您需要下列組態值：
- 識別碼範圍：在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組]。 記下識別碼範圍值。
- 群組主索引鍵：在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組] > [SAS-IoT-Devices]。 記下共用存取簽章主要金鑰值。
使用 Azure Cloud Shell 從您擷取的群組主索引鍵產生裝置金鑰：
az extension add --name azure-iot
az iot central device compute-device-key --device-id sample-device-01 --pk <the group primary key value>
記下產生的裝置金鑰，您稍後將在本教學課程中使用此值。
注意
若要執行此範例，您不需要事先在 IoT Central 應用程式中註冊裝置。 此範例會使用 IoT Central 功能，在第一次連線時自動註冊裝置。
在 Windows 上，瀏覽至您下載 Azure IoT SDK for Java 存放庫的根資料夾。
執行下列命令以建置範例應用程式：
mvn install -T 2C -DskipTests
執行程式碼
若要執行範例應用程式，請開啟命令列環境，並瀏覽至資料夾 azure-iot-sdk-java/iothub/device/iot-device-samples/pnp-device-sample/temperature-controller-device-sample，其中包含 src 資料夾與 TemperatureController.java 範例檔案。
設定環境變數來設定範例。 下列程式碼片段顯示如何在 Windows 命令提示字元中設定環境變數。 如果您使用 bash shell，請以 export 命令取代 set 命令：
set IOTHUB_DEVICE_SECURITY_TYPE=DPS
set IOTHUB_DEVICE_DPS_ID_SCOPE=<The ID scope you made a note of previously>
set IOTHUB_DEVICE_DPS_DEVICE_ID=sample-device-01
set IOTHUB_DEVICE_DPS_DEVICE_KEY=<The generated device key you made a note of previously>
set IOTHUB_DEVICE_DPS_ENDPOINT=global.azure-devices-provisioning.net
執行範例：
mvn exec:java -Dexec.mainClass="samples.com.microsoft.azure.sdk.iot.device.TemperatureController"
下列輸出顯示裝置註冊和連線到 IoT Central。 範本開始傳送遙測：
2021-03-30 15:33:25.138 DEBUG TemperatureController:123 - Initialize the device client.
Waiting for Provisioning Service to register
Waiting for Provisioning Service to register
IotHUb Uri : iotc-60a.....azure-devices.net
Device ID : sample-device-01
2021-03-30 15:33:38.294 DEBUG TemperatureController:247 - Opening the device client.
2021-03-30 15:33:38.307 INFO ExponentialBackoffWithJitter:98 - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2021-03-30 15:33:38.321 INFO ExponentialBackoffWithJitter:98 - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2021-03-30 15:33:38.427 DEBUG MqttIotHubConnection:274 - Opening MQTT connection...
2021-03-30 15:33:38.427 DEBUG Mqtt:123 - Sending MQTT CONNECT packet...
2021-03-30 15:33:44.628 DEBUG Mqtt:126 - Sent MQTT CONNECT packet was acknowledged
2021-03-30 15:33:44.630 DEBUG Mqtt:256 - Sending MQTT SUBSCRIBE packet for topic devices/sample-device-01/messages/devicebound/#
2021-03-30 15:33:44.731 DEBUG Mqtt:261 - Sent MQTT SUBSCRIBE packet for topic devices/sample-device-01/messages/devicebound/# was acknowledged
2021-03-30 15:33:44.733 DEBUG MqttIotHubConnection:279 - MQTT connection opened successfully
2021-03-30 15:33:44.733 DEBUG IotHubTransport:302 - The connection to the IoT Hub has been established
2021-03-30 15:33:44.734 INFO IotHubTransport:1429 - Updating transport status to new status CONNECTED with reason CONNECTION_OK
2021-03-30 15:33:44.735 DEBUG IotHubTransport:1439 - Invoking connection status callbacks with new status details
2021-03-30 15:33:44.739 DEBUG IotHubTransport:394 - Client connection opened successfully
2021-03-30 15:33:44.740 INFO DeviceClient:438 - Device client opened successfully
2021-03-30 15:33:44.740 DEBUG TemperatureController:152 - Set handler for "reboot" command.
2021-03-30 15:33:44.742 DEBUG TemperatureController:153 - Set handler for "getMaxMinReport" command.
2021-03-30 15:33:44.774 INFO IotHubTransport:489 - Message was queued to be sent later ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [bbbb1111-cc22-3333-44dd-555555eeeeee] Device Operation Type [DEVICE_OPERATION_METHOD_SUBSCRIBE_REQUEST] )
2021-03-30 15:33:44.774 DEBUG TemperatureController:156 - Set handler to receive "targetTemperature" updates.
2021-03-30 15:33:44.775 INFO IotHubTransport:1344 - Sending message ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [bbbb1111-cc22-3333-44dd-555555eeeeee] Device Operation Type [DEVICE_OPERATION_METHOD_SUBSCRIBE_REQUEST] )
2021-03-30 15:33:44.779 DEBUG Mqtt:256 - Sending MQTT SUBSCRIBE packet for topic $iothub/methods/POST/#
2021-03-30 15:33:44.793 INFO IotHubTransport:489 - Message was queued to be sent later ( Message details: Correlation Id [cccc2222-dd33-4444-55ee-666666ffffff] Message Id [dddd3333-ee44-5555-66ff-777777aaaaaa] Device Operation Type [DEVICE_OPERATION_TWIN_SUBSCRIBE_DESIRED_PROPERTIES_REQUEST] )
2021-03-30 15:33:44.794 INFO IotHubTransport:489 - Message was queued to be sent later ( Message details: Correlation Id [eeee4444-ff55-6666-77aa-888888bbbbbb] Message Id [ffff5555-aa66-7777-88bb-999999cccccc] Request Id [0] Device Operation Type [DEVICE_OPERATION_TWIN_GET_REQUEST] )
2021-03-30 15:33:44.819 INFO IotHubTransport:489 - Message was queued to be sent later ( Message details: Correlation Id [aaaa6666-bb77-8888-99cc-000000dddddd] Message Id [aaaa0000-bb11-2222-33cc-444444dddddd] Device Operation Type [DEVICE_OPERATION_TWIN_SUBSCRIBE_DESIRED_PROPERTIES_REQUEST] )
2021-03-30 15:33:44.881 DEBUG Mqtt:261 - Sent MQTT SUBSCRIBE packet for topic $iothub/methods/POST/# was acknowledged
2021-03-30 15:33:44.882 INFO IotHubTransport:1344 - Sending message ( Message details: Correlation Id [cccc2222-dd33-4444-55ee-666666ffffff] Message Id [dddd3333-ee44-5555-66ff-777777aaaaaa] Device Operation Type [DEVICE_OPERATION_TWIN_SUBSCRIBE_DESIRED_PROPERTIES_REQUEST] )
2021-03-30 15:33:44.882 DEBUG Mqtt:256 - Sending MQTT SUBSCRIBE packet for topic $iothub/twin/res/#
2021-03-30 15:33:44.893 INFO IotHubTransport:489 - Message was queued to be sent later ( Message details: Correlation Id [bbbb1111-cc22-3333-44dd-555555eeeeee] Message Id [cccc2222-dd33-4444-55ee-666666ffffff] Request Id [1] Device Operation Type [DEVICE_OPERATION_TWIN_UPDATE_REPORTED_PROPERTIES_REQUEST] )
2021-03-30 15:33:44.904 DEBUG TemperatureController:423 - Property: Update - component = "deviceInformation" is COMPLETED.
2021-03-30 15:33:44.915 INFO IotHubTransport:489 - Message was queued to be sent later ( Message details: Correlation Id [dddd3333-ee44-5555-66ff-777777aaaaaa] Message Id [eeee4444-ff55-6666-77aa-888888bbbbbb] )
2021-03-30 15:33:44.915 DEBUG TemperatureController:434 - Telemetry: Sent - {"workingSet": 1024.0KiB }
2021-03-30 15:33:44.915 INFO IotHubTransport:489 - Message was queued to be sent later ( Message details: Correlation Id [ffff5555-aa66-7777-88bb-999999cccccc] Message Id [aaaa6666-bb77-8888-99cc-000000dddddd] Request Id [2] Device Operation Type [DEVICE_OPERATION_TWIN_UPDATE_REPORTED_PROPERTIES_REQUEST] )
2021-03-30 15:33:44.916 DEBUG TemperatureController:442 - Property: Update - {"serialNumber": SR-123456} is COMPLETED
2021-03-30 15:33:44.927 INFO IotHubTransport:489 - Message was queued to be sent later ( Message details: Correlation Id [aaaa0000-bb11-2222-33cc-444444dddddd] Message Id [bbbb1111-cc22-3333-44dd-555555eeeeee] )
2021-03-30 15:33:44.927 DEBUG TemperatureController:461 - Telemetry: Sent - {"temperature": 5.8°C} with message Id bbbb1111-cc22-3333-44dd-555555eeeeee.
身為 Azure IoT Central 應用程式的操作者，您可以：
在 [概觀] 頁面上檢視兩個控溫器元件所傳送的遙測：
在 [關於] 頁面上，檢視裝置屬性。 此頁面會顯示裝置資訊元件和兩個控溫器元件的屬性：
自訂裝置範本
身為解決方案開發人員，您可以自訂在溫度控制器裝置連線時自動建立的 IoT Central 裝置範本。
若要新增雲端屬性來儲存與裝置相關聯的客戶名稱：
在 IoT Central 應用程式中，瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
在 [溫度控制器] 模型中，選取 [+新增功能]。
輸入 [客戶名稱] 作為 [顯示名稱]、選取 [雲端屬性] 作為功能類型、展開項目，然後選擇 [字串] 作為 [結構描述]。 然後選取儲存。
若要自訂 Get Max-Min report 命令在 IoT Central 應用程式中顯示的方式：
瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
針對 getMaxMinReport (thermostat1)，請將 Get Max-Min report. 取代為 Get thermostat1 status report。
針對 getMaxMinReport (thermostat2)，請將 Get Max-Min report. 取代為 Get thermostat2 status report。
選取 [儲存]。
若要自訂 [目標溫度] 可寫入屬性在 IoT Central 應用程式中顯示的方式：
瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
針對 targetTemperature (thermostat1)，將 [目標溫度] 取代為 [目標溫度 (1)]。
針對 targetTemperature (thermostat2)，將 [目標溫度] 取代為 [目標溫度 (2)]。
選取 [儲存]。
溫度控制器模型中的控溫器模型包含目標溫度可寫入屬性，裝置範本包含客戶名稱雲端屬性。 若要建立操作員可以編輯這些屬性的檢視：
選取 [檢視]，再選取 [編輯裝置和雲端資料] 圖格。
輸入「屬性」作為表單名稱。
選取 [目標溫度 (1)]、[目標溫度 (2)]，以及 [客戶名稱] 屬性。 然後選取 [新增區段]。
儲存您的變更。
發佈裝置範本
您必須先發佈裝置範本，操作員才能看到並使用您的自訂項目。
從控溫器裝置範本中，選取 [發佈]。 在 [將此裝置範本發佈至應用程式] 面板上，選取 [發佈]。
操作員現在可以使用 [屬性] 檢視來更新屬性值，並在裝置命令頁面上呼叫稱為 Get thermostat1 status report 和 Get thermostat2 status report 的命令：
在 [屬性] 頁面上更新可寫入的屬性值：
呼叫 [命令] 頁面中的命令。 如果您執行狀態報告命令，請在執行該命令之前，先選取 [自從] 參數的日期和時間：
您可看到裝置如何回應命令和屬性更新：
2021-03-30 15:43:57.133 DEBUG TemperatureController:309 - Command: Received - component="thermostat1", generating min, max, avg temperature report since Tue Mar 30 06:00:00 BST 2021
2021-03-30 15:43:57.153 DEBUG TemperatureController:332 - Command: MaxMinReport since Tue Mar 30 06:00:00 BST 2021: "maxTemp": 35.6°C, "minTemp": 35.6°C, "avgTemp": 35.6°C, "startTime": 2021-03-30T15:43:41Z, "endTime": 2021-03-30T15:43:56Z
2021-03-30 15:43:57.394 DEBUG TemperatureController:502 - Command - Response from IoT Hub: command name=null, status=OK_EMPTY
...
2021-03-30 15:48:47.808 DEBUG TemperatureController:372 - Property: Received - component="thermostat2", {"targetTemperature": 67.0°C}.
2021-03-30 15:48:47.837 DEBUG TemperatureController:382 - Property: Update - component="thermostat2", {"targetTemperature": 67.0°C} is IN_PROGRESS
必要條件
若要完成本文中的步驟，您需要下列資源︰
啟用中的 Azure 訂用帳戶。 如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
從自訂應用程式範本建立的 IoT Central 應用程式。 若要深入了解，請參閱建立 IoT Central 應用程式和關於您的應用程式。
已安裝 Node.js 版本 6 或更新版本的開發電腦。 您可以在命令列執行
node --version來檢查版本。 本教學課程中的指示假設您是在 Windows 命令提示字元中執行 node 命令。 不過，您可以在許多其他作業系統上使用 Node.js。Microsoft Azure IoT SDK for Node.js GitHub 存放庫的本機複本，其中包含範例程式碼。 使用此連結來下載存放庫的複本：下載 ZIP。 接著將檔案解壓縮到本機電腦上的適當位置。
檢閱程式碼
在您先前下載的 Microsoft Azure IoT SDK for Node.js 複本中，以文字編輯器開啟 azure-iot-sdk-node/device/samples/javascript/pnp_temperature_controller.js 檔案。
此範例會實作多重元件溫度控制器數位對應項定義語言模型。
執行範例以連線到 IoT Central 時，該檔案會使用裝置佈建服務 (DPS) 來註冊裝置並產生連接字串。 此範例會從命令列環境中，取出所需的 DPS 連線資訊。
main 方法：
- 建立
client物件，並在開啟連線之前設定dtmi:com:example:TemperatureController;2模型識別碼。 IoT Central 會使用型號識別碼來識別或產生此裝置的裝置範本。 若要深入了解，請參閱將裝置指派給裝置範本。 - 建立三個命令的命令處理常式。
- 啟動每個控溫器元件的迴圈，每 5 秒傳送溫度遙測。
- 啟動預設元件的迴圈，每 6 秒傳送工作集大小遙測。
- 針對每個控溫器元件傳送
maxTempSinceLastReboot屬性。 - 傳送裝置資訊屬性。
- 建立三個元件的可寫入屬性處理常式。
async function main() {
// ...
// fromConnectionString must specify a transport, coming from any transport package.
const client = Client.fromConnectionString(deviceConnectionString, Protocol);
console.log('Connecting using connection string: ' + deviceConnectionString);
let resultTwin;
try {
// Add the modelId here
await client.setOptions(modelIdObject);
await client.open();
console.log('Enabling the commands on the client');
client.onDeviceMethod(commandNameGetMaxMinReport1, commandHandler);
client.onDeviceMethod(commandNameGetMaxMinReport2, commandHandler);
client.onDeviceMethod(commandNameReboot, commandHandler);
// Send Telemetry after some interval
let index1 = 0;
let index2 = 0;
let index3 = 0;
intervalToken1 = setInterval(() => {
const data = JSON.stringify(thermostat1.updateSensor().getCurrentTemperatureObject());
sendTelemetry(client, data, index1, thermostat1ComponentName).catch((err) => console.log('error ', err.toString()));
index1 += 1;
}, 5000);
intervalToken2 = setInterval(() => {
const data = JSON.stringify(thermostat2.updateSensor().getCurrentTemperatureObject());
sendTelemetry(client, data, index2, thermostat2ComponentName).catch((err) => console.log('error ', err.toString()));
index2 += 1;
}, 5500);
intervalToken3 = setInterval(() => {
const data = JSON.stringify({ workingset: 1 + (Math.random() * 90) });
sendTelemetry(client, data, index3, null).catch((err) => console.log('error ', err.toString()));
index3 += 1;
}, 6000);
// attach a standard input exit listener
exitListener(client);
try {
resultTwin = await client.getTwin();
// Only report readable properties
const patchRoot = helperCreateReportedPropertiesPatch({ serialNumber: serialNumber }, null);
const patchThermostat1Info = helperCreateReportedPropertiesPatch({
maxTempSinceLastReboot: thermostat1.getMaxTemperatureValue(),
}, thermostat1ComponentName);
const patchThermostat2Info = helperCreateReportedPropertiesPatch({
maxTempSinceLastReboot: thermostat2.getMaxTemperatureValue(),
}, thermostat2ComponentName);
const patchDeviceInfo = helperCreateReportedPropertiesPatch({
manufacturer: 'Contoso Device Corporation',
model: 'Contoso 47-turbo',
swVersion: '10.89',
osName: 'Contoso_OS',
processorArchitecture: 'Contoso_x86',
processorManufacturer: 'Contoso Industries',
totalStorage: 65000,
totalMemory: 640,
}, deviceInfoComponentName);
// the below things can only happen once the twin is there
updateComponentReportedProperties(resultTwin, patchRoot, null);
updateComponentReportedProperties(resultTwin, patchThermostat1Info, thermostat1ComponentName);
updateComponentReportedProperties(resultTwin, patchThermostat2Info, thermostat2ComponentName);
updateComponentReportedProperties(resultTwin, patchDeviceInfo, deviceInfoComponentName);
desiredPropertyPatchListener(resultTwin, [thermostat1ComponentName, thermostat2ComponentName, deviceInfoComponentName]);
} catch (err) {
console.error('could not retrieve twin or report twin properties\n' + err.toString());
}
} catch (err) {
console.error('could not connect Plug and Play client or could not attach interval function for telemetry\n' + err.toString());
}
}
provisionDevice 函式會顯示裝置如何使用 DPS 來註冊及連線到 IoT Central。 承載包含模型識別碼，IoT Central 會用來將裝置指派給裝置範本：
async function provisionDevice(payload) {
var provSecurityClient = new SymmetricKeySecurityClient(registrationId, symmetricKey);
var provisioningClient = ProvisioningDeviceClient.create(provisioningHost, idScope, new ProvProtocol(), provSecurityClient);
if (payload) {
provisioningClient.setProvisioningPayload(payload);
}
try {
let result = await provisioningClient.register();
deviceConnectionString = 'HostName=' + result.assignedHub + ';DeviceId=' + result.deviceId + ';SharedAccessKey=' + symmetricKey;
console.log('registration succeeded');
console.log('assigned hub=' + result.assignedHub);
console.log('deviceId=' + result.deviceId);
console.log('payload=' + JSON.stringify(result.payload));
} catch (err) {
console.error("error registering device: " + err.toString());
}
}
sendTelemetry 函式會顯示裝置如何將溫度遙測資料傳送至 IoT Central。 針對來自元件的遙測，它會新增名為 $.sub 且具有元件名稱的屬性：
async function sendTelemetry(deviceClient, data, index, componentName) {
if componentName) {
console.log('Sending telemetry message %d from component: %s ', index, componentName);
} else {
console.log('Sending telemetry message %d from root interface', index);
}
const msg = new Message(data);
if (componentName) {
msg.properties.add(messageSubjectProperty, componentName);
}
msg.contentType = 'application/json';
msg.contentEncoding = 'utf-8';
await deviceClient.sendEvent(msg);
}
main 方法會使用稱為 helperCreateReportedPropertiesPatch 的協助程式方法來建立屬性更新訊息。 此方法會採用選擇性參數來指定傳送屬性的元件：
const helperCreateReportedPropertiesPatch = (propertiesToReport, componentName) => {
let patch;
if (!!(componentName)) {
patch = { };
propertiesToReport.__t = 'c';
patch[componentName] = propertiesToReport;
} else {
patch = { };
patch = propertiesToReport;
}
if (!!(componentName)) {
console.log('The following properties will be updated for component: ' + componentName);
} else {
console.log('The following properties will be updated for root interface.');
}
console.log(patch);
return patch;
};
main 方法會使用下列方法來處理來自 IoT Central 可寫入屬性的更新。 請注意如何使用版本和狀態碼來建置回應：
const desiredPropertyPatchListener = (deviceTwin, componentNames) => {
deviceTwin.on('properties.desired', (delta) => {
console.log('Received an update for device with value: ' + JSON.stringify(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') {
console.log('Will update property: ' + propertyName + ' to value: ' + propertyValue + ' of component: ' + componentName);
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 = { };
console.log('Will update property: ' + key + ' to value: ' + values + ' for root');
const propertyContent = { value: values };
propertyContent.ac = 200;
propertyContent.ad = 'Successfully executed patch';
propertyContent.av = version;
patchForRoot[key] = propertyContent;
updateComponentReportedProperties(deviceTwin, patchForRoot, null);
}
});
});
};
main 方法會使用下列方法來處理來自 IoT Central 的命令：
const commandHandler = async (request, response) => {
helperLogCommandRequest(request);
switch (request.methodName) {
case commandNameGetMaxMinReport1: {
await sendCommandResponse(request, response, 200, thermostat1.getMaxMinReportObject());
break;
}
case commandNameGetMaxMinReport2: {
await sendCommandResponse(request, response, 200, thermostat2.getMaxMinReportObject());
break;
}
case commandNameReboot: {
await sendCommandResponse(request, response, 200, 'reboot response');
break;
}
default:
await sendCommandResponse(request, response, 404, 'unknown method');
break;
}
};
const sendCommandResponse = async (request, response, status, payload) => {
try {
await response.send(status, payload);
console.log('Response to method: ' + request.methodName + ' sent successfully.' );
} catch (err) {
console.error('An error occurred when sending a method response:\n' + err.toString());
}
};
取得連線資訊
稍後在本教學課程中執行範例裝置應用程式時，您需要下列組態值：
- 識別碼範圍：在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組]。 記下識別碼範圍值。
- 群組主索引鍵：在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組] > [SAS-IoT-Devices]。 記下共用存取簽章主要金鑰值。
使用 Azure Cloud Shell 從您擷取的群組主索引鍵產生裝置金鑰：
az extension add --name azure-iot
az iot central device compute-device-key --device-id sample-device-01 --pk <the group primary key value>
記下產生的裝置金鑰，您稍後將在本教學課程中使用此值。
注意
若要執行此範例，您不需要事先在 IoT Central 應用程式中註冊裝置。 此範例會使用 IoT Central 功能，在第一次連線時自動註冊裝置。
執行程式碼
若要執行範例應用程式，請開啟命令列環境，然後瀏覽至資料夾 azure-iot-sdk-node/device/samples/javascript，其中包含 pnp_temperature_controller.js 範例檔案。
設定環境變數來設定範例。 下列程式碼片段顯示如何在 Windows 命令提示字元中設定環境變數。 如果您使用 bash shell，請以 export 命令取代 set 命令：
set IOTHUB_DEVICE_SECURITY_TYPE=DPS
set IOTHUB_DEVICE_DPS_ID_SCOPE=<The ID scope you made a note of previously>
set IOTHUB_DEVICE_DPS_DEVICE_ID=sample-device-01
set IOTHUB_DEVICE_DPS_DEVICE_KEY=<The generated device key you made a note of previously>
set IOTHUB_DEVICE_DPS_ENDPOINT=global.azure-devices-provisioning.net
安裝必要的套件：
npm install
執行範例：
node pnp_temperature_controller.js
下列輸出顯示裝置註冊和連線到 IoT Central。 然後範例會先從兩個控溫器元件傳送 maxTempSinceLastReboot 屬性，再開始傳送遙測：
registration succeeded
assigned hub=iotc-....azure-devices.net
deviceId=sample-device-01
payload=undefined
Connecting using connection string: HostName=iotc-....azure-devices.net;DeviceId=sample-device-01;SharedAccessKey=qdv...IpAo=
Enabling the commands on the client
Please enter q or Q to exit sample.
The following properties will be updated for root interface.
{ serialNumber: 'alwinexlepaho8329' }
The following properties will be updated for component: thermostat1
{ thermostat1: { maxTempSinceLastReboot: 1.5902294191855972, __t: 'c' } }
The following properties will be updated for component: thermostat2
{ thermostat2: { maxTempSinceLastReboot: 16.181771928614545, __t: 'c' } }
The following properties will be updated for component: deviceInformation
{ deviceInformation:
{ manufacturer: 'Contoso Device Corporation',
model: 'Contoso 47-turbo',
swVersion: '10.89',
osName: 'Contoso_OS',
processorArchitecture: 'Contoso_x86',
processorManufacturer: 'Contoso Industries',
totalStorage: 65000,
totalMemory: 640,
__t: 'c' } }
executed sample
Received an update for device with value: {"$version":1}
Properties have been reported for component: thermostat1
Properties have been reported for component: thermostat2
Properties have been reported for component: deviceInformation
Properties have been reported for root interface.
Sending telemetry message 0 from component: thermostat1
Sending telemetry message 0 from component: thermostat2
Sending telemetry message 0 from root interface
身為 Azure IoT Central 應用程式的操作者，您可以：
在 [概觀] 頁面上檢視兩個控溫器元件所傳送的遙測：
在 [關於] 頁面上，檢視裝置屬性。 此頁面會顯示裝置資訊元件和兩個控溫器元件的屬性：
自訂裝置範本
身為解決方案開發人員，您可以自訂在溫度控制器裝置連線時自動建立的 IoT Central 裝置範本。
若要新增雲端屬性來儲存與裝置相關聯的客戶名稱：
在 IoT Central 應用程式中，瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
在 [溫度控制器] 模型中，選取 [+新增功能]。
輸入 [客戶名稱] 作為 [顯示名稱]、選取 [雲端屬性] 作為功能類型、展開項目，然後選擇 [字串] 作為 [結構描述]。 然後選取儲存。
若要自訂 Get Max-Min report 命令在 IoT Central 應用程式中顯示的方式：
瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
針對 getMaxMinReport (thermostat1)，請將 Get Max-Min report. 取代為 Get thermostat1 status report。
針對 getMaxMinReport (thermostat2)，請將 Get Max-Min report. 取代為 Get thermostat2 status report。
選取 [儲存]。
若要自訂 [目標溫度] 可寫入屬性在 IoT Central 應用程式中顯示的方式：
瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
針對 targetTemperature (thermostat1)，將 [目標溫度] 取代為 [目標溫度 (1)]。
針對 targetTemperature (thermostat2)，將 [目標溫度] 取代為 [目標溫度 (2)]。
選取 [儲存]。
溫度控制器模型中的控溫器模型包含目標溫度可寫入屬性，裝置範本包含客戶名稱雲端屬性。 若要建立操作員可以編輯這些屬性的檢視：
選取 [檢視]，再選取 [編輯裝置和雲端資料] 圖格。
輸入「屬性」作為表單名稱。
選取 [目標溫度 (1)]、[目標溫度 (2)]，以及 [客戶名稱] 屬性。 然後選取 [新增區段]。
儲存您的變更。
發佈裝置範本
您必須先發佈裝置範本，操作員才能看到並使用您的自訂項目。
從控溫器裝置範本中，選取 [發佈]。 在 [將此裝置範本發佈至應用程式] 面板上，選取 [發佈]。
操作員現在可以使用 [屬性] 檢視來更新屬性值，並在裝置命令頁面上呼叫稱為 Get thermostat1 status report 和 Get thermostat2 status report 的命令：
在 [屬性] 頁面上更新可寫入的屬性值：
呼叫 [命令] 頁面中的命令。 如果您執行狀態報告命令，請在執行該命令之前，先選取 [自從] 參數的日期和時間：
您可看到裝置如何回應命令和屬性更新。 getMaxMinReport 命令位於 thermostat2 元件中，而 reboot 命令位於預設元件中。 已為 thermostat2 元件設定 targetTemperature 可寫入屬性：
Received command request for command name: thermostat2*getMaxMinReport
The command request payload is:
2021-03-26T06:00:00.000Z
Response to method: thermostat2*getMaxMinReport sent successfully.
...
Received command request for command name: reboot
The command request payload is:
10
Response to method: reboot sent successfully.
...
Received an update for device with value: {"thermostat2":{"targetTemperature":76,"__t":"c"},"$version":2}
Will update property: targetTemperature to value: 76 of component: thermostat2
Properties have been reported for component: thermostat2
必要條件
若要完成本文中的步驟，您需要下列資源︰
啟用中的 Azure 訂用帳戶。 如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
從自訂應用程式範本建立的 IoT Central 應用程式。 若要深入了解，請參閱建立 IoT Central 應用程式和關於您的應用程式。
已安裝 Python 的開發電腦。 如需目前的 Python 版本需求，請查看 Azure IoT Python SDK。 您可以在命令列執行
python --version來檢查版本。 Python 適用於多種作業系統。 本教學課程中的指示假設您是在 Windows 命令提示字元中執行 python 命令。Microsoft Azure IoT SDK for Python GitHub 存放庫的本機複本，其中包含範例程式碼。 使用此連結來下載存放庫的複本：下載 ZIP。 接著將檔案解壓縮到本機電腦上的適當位置。
檢閱程式碼
在您先前下載的 Microsoft Azure IoT SDK for Python 複本中，以文字編輯器開啟 azure-iot-sdk-python/samples/pnp/temp_controller_with_thermostats.py 檔案。
此範例會實作多重元件溫度控制器數位對應項定義語言模型。
執行範例以連線到 IoT Central 時，該檔案會使用裝置佈建服務 (DPS) 來註冊裝置並產生連接字串。 此範例會從命令列環境中，取出所需的 DPS 連線資訊。
main 函式：
- 使用 DPS 來佈建裝置。 佈建資訊包括模型識別碼。 IoT Central 會使用型號識別碼來識別或產生此裝置的裝置範本。 若要深入了解，請參閱將裝置指派給裝置範本。
- 建立
Device_client物件，並在開啟連線之前設定dtmi:com:example:TemperatureController;2模型識別碼。 - 將初始屬性值傳送至 IoT Central。 它會使用
pnp_helper來建立修補程式。 - 建立
getMaxMinReport和reboot命令的接聽程式。 每個控溫器元件都有自己的getMaxMinReport命令。 - 建立屬性接聽程式，以接聽可寫入的屬性更新。
- 啟動迴圈，從兩個控溫器元件傳送溫度遙測，以及每 8 秒從預設元件的工作集遙測。
async def main():
switch = os.getenv("IOTHUB_DEVICE_SECURITY_TYPE")
if switch == "DPS":
provisioning_host = (
os.getenv("IOTHUB_DEVICE_DPS_ENDPOINT")
if os.getenv("IOTHUB_DEVICE_DPS_ENDPOINT")
else "global.azure-devices-provisioning.net"
)
id_scope = os.getenv("IOTHUB_DEVICE_DPS_ID_SCOPE")
registration_id = os.getenv("IOTHUB_DEVICE_DPS_DEVICE_ID")
symmetric_key = os.getenv("IOTHUB_DEVICE_DPS_DEVICE_KEY")
registration_result = await provision_device(
provisioning_host, id_scope, registration_id, symmetric_key, model_id
)
if registration_result.status == "assigned":
print("Device was assigned")
print(registration_result.registration_state.assigned_hub)
print(registration_result.registration_state.device_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,
)
else:
raise RuntimeError(
"Could not provision device. Aborting Plug and Play device connection."
)
elif switch == "connectionString":
# ...
# Connect the client.
await device_client.connect()
################################################
# Update readable properties from various components
properties_root = pnp_helper.create_reported_properties(serialNumber=serial_number)
properties_thermostat1 = pnp_helper.create_reported_properties(
thermostat_1_component_name, maxTempSinceLastReboot=98.34
)
properties_thermostat2 = pnp_helper.create_reported_properties(
thermostat_2_component_name, maxTempSinceLastReboot=48.92
)
properties_device_info = pnp_helper.create_reported_properties(
device_information_component_name,
swVersion="5.5",
manufacturer="Contoso Device Corporation",
model="Contoso 4762B-turbo",
osName="Mac Os",
processorArchitecture="x86-64",
processorManufacturer="Intel",
totalStorage=1024,
totalMemory=32,
)
property_updates = asyncio.gather(
device_client.patch_twin_reported_properties(properties_root),
device_client.patch_twin_reported_properties(properties_thermostat1),
device_client.patch_twin_reported_properties(properties_thermostat2),
device_client.patch_twin_reported_properties(properties_device_info),
)
################################################
# Get all the listeners running
print("Listening for command requests and property updates")
global THERMOSTAT_1
global THERMOSTAT_2
THERMOSTAT_1 = Thermostat(thermostat_1_component_name, 10)
THERMOSTAT_2 = Thermostat(thermostat_2_component_name, 10)
listeners = asyncio.gather(
execute_command_listener(
device_client, method_name="reboot", user_command_handler=reboot_handler
),
execute_command_listener(
device_client,
thermostat_1_component_name,
method_name="getMaxMinReport",
user_command_handler=max_min_handler,
create_user_response_handler=create_max_min_report_response,
),
execute_command_listener(
device_client,
thermostat_2_component_name,
method_name="getMaxMinReport",
user_command_handler=max_min_handler,
create_user_response_handler=create_max_min_report_response,
),
execute_property_listener(device_client),
)
################################################
# Function to send telemetry every 8 seconds
async def send_telemetry():
print("Sending telemetry from various components")
while True:
curr_temp_ext = random.randrange(10, 50)
THERMOSTAT_1.record(curr_temp_ext)
temperature_msg1 = {"temperature": curr_temp_ext}
await send_telemetry_from_temp_controller(
device_client, temperature_msg1, thermostat_1_component_name
)
curr_temp_int = random.randrange(10, 50) # Current temperature in Celsius
THERMOSTAT_2.record(curr_temp_int)
temperature_msg2 = {"temperature": curr_temp_int}
await send_telemetry_from_temp_controller(
device_client, temperature_msg2, thermostat_2_component_name
)
workingset_msg3 = {"workingSet": random.randrange(1, 100)}
await send_telemetry_from_temp_controller(device_client, workingset_msg3)
send_telemetry_task = asyncio.ensure_future(send_telemetry())
# ...
provision_device 函式會使用 DPS 來佈建裝置，並向 IoT Central 註冊。 函式包含裝置型號識別碼，IoT Central 會用來在佈建承載中將裝置指派給裝置範本：
async def provision_device(provisioning_host, id_scope, registration_id, symmetric_key, model_id):
provisioning_device_client = ProvisioningDeviceClient.create_from_symmetric_key(
provisioning_host=provisioning_host,
registration_id=registration_id,
id_scope=id_scope,
symmetric_key=symmetric_key,
)
provisioning_device_client.provisioning_payload = {"modelId": model_id}
return await provisioning_device_client.register()
execute_command_listener 函式會處理命令要求，當裝置收到控溫器元件的 getMaxMinReport 命令時執行 max_min_handler 函式，並在裝置收到 reboot 命令時執行 reboot_handler 函式。 它會使用 pnp_helper 模組來建置回應：
async def execute_command_listener(
device_client,
component_name=None,
method_name=None,
user_command_handler=None,
create_user_response_handler=None,
):
while True:
if component_name and method_name:
command_name = component_name + "*" + method_name
elif method_name:
command_name = method_name
else:
command_name = None
command_request = await device_client.receive_method_request(command_name)
print("Command request received with payload")
values = command_request.payload
print(values)
if user_command_handler:
await user_command_handler(values)
else:
print("No handler provided to execute")
(response_status, response_payload) = pnp_helper.create_response_payload_with_status(
command_request, method_name, create_user_response=create_user_response_handler
)
command_response = MethodResponse.create_from_method_request(
command_request, response_status, response_payload
)
try:
await device_client.send_method_response(command_response)
except Exception:
print("responding to the {command} command failed".format(command=method_name))
async def execute_property_listener 會處理可寫入的屬性更新，例如控溫器元件的 targetTemperature，並產生 JSON 回應。 它會使用 pnp_helper 模組來建置回應：
async def execute_property_listener(device_client):
while True:
patch = await device_client.receive_twin_desired_properties_patch() # blocking call
print(patch)
properties_dict = pnp_helper.create_reported_properties_from_desired(patch)
await device_client.patch_twin_reported_properties(properties_dict)
send_telemetry_from_temp_controller 函式會將遙測訊息從控溫器元件傳送至 IoT Central。 它會使用 pnp_helper 模組來建置訊息：
async def send_telemetry_from_temp_controller(device_client, telemetry_msg, component_name=None):
msg = pnp_helper.create_telemetry(telemetry_msg, component_name)
await device_client.send_message(msg)
print("Sent message")
print(msg)
await asyncio.sleep(5)
取得連線資訊
稍後在本教學課程中執行範例裝置應用程式時，您需要下列組態值：
- 識別碼範圍：在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組]。 記下識別碼範圍值。
- 群組主索引鍵：在您的 IoT Central 應用程式中，瀏覽至 [權限] > [裝置連線群組] > [SAS-IoT-Devices]。 記下共用存取簽章主要金鑰值。
使用 Azure Cloud Shell 從您擷取的群組主索引鍵產生裝置金鑰：
az extension add --name azure-iot
az iot central device compute-device-key --device-id sample-device-01 --pk <the group primary key value>
記下產生的裝置金鑰，您稍後將在本教學課程中使用此值。
注意
若要執行此範例，您不需要事先在 IoT Central 應用程式中註冊裝置。 此範例會使用 IoT Central 功能，在第一次連線時自動註冊裝置。
執行程式碼
若要執行範例應用程式，請開啟命令列環境，然後瀏覽至資料夾 azure-iot-sdk-python-2/samples/pnp，其中包含 temp_controller_with_thermostats.py 範例檔案。
設定環境變數來設定範例。 下列程式碼片段顯示如何在 Windows 命令提示字元中設定環境變數。 如果您使用 bash shell，請以 export 命令取代 set 命令：
set IOTHUB_DEVICE_SECURITY_TYPE=DPS
set IOTHUB_DEVICE_DPS_ID_SCOPE=<The ID scope you made a note of previously>
set IOTHUB_DEVICE_DPS_DEVICE_ID=sample-device-01
set IOTHUB_DEVICE_DPS_DEVICE_KEY=<The generated device key you made a note of previously>
set IOTHUB_DEVICE_DPS_ENDPOINT=global.azure-devices-provisioning.net
安裝必要的套件：
pip install azure-iot-device
執行範例：
python temp_controller_with_thermostats.py
下列輸出顯示裝置註冊和連線到 IoT Central。 範例會先從兩個控溫器元件傳送 maxTempSinceLastReboot 屬性，再開始傳送遙測：
Device was assigned
iotc-60a.....azure-devices.net
sample-device-01
Updating pnp properties for root interface
{'serialNumber': 'alohomora'}
Updating pnp properties for thermostat1
{'thermostat1': {'maxTempSinceLastReboot': 98.34, '__t': 'c'}}
Updating pnp properties for thermostat2
{'thermostat2': {'maxTempSinceLastReboot': 48.92, '__t': 'c'}}
Updating pnp properties for deviceInformation
{'deviceInformation': {'swVersion': '5.5', 'manufacturer': 'Contoso Device Corporation', 'model': 'Contoso 4762B-turbo', 'osName': 'Mac Os', 'processorArchitecture': 'x86-64', 'processorManufacturer': 'Intel', 'totalStorage': 1024, 'totalMemory': 32, '__t': 'c'}}
Listening for command requests and property updates
Press Q to quit
Sending telemetry from various components
Sent message
{"temperature": 27}
Sent message
{"temperature": 17}
Sent message
{"workingSet": 13}
身為 Azure IoT Central 應用程式的操作者，您可以：
在 [概觀] 頁面上檢視兩個控溫器元件所傳送的遙測：
在 [關於] 頁面上，檢視裝置屬性。 此頁面會顯示裝置資訊元件和兩個控溫器元件的屬性：
自訂裝置範本
身為解決方案開發人員，您可以自訂在溫度控制器裝置連線時自動建立的 IoT Central 裝置範本。
若要新增雲端屬性來儲存與裝置相關聯的客戶名稱：
在 IoT Central 應用程式中，瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
在 [溫度控制器] 模型中，選取 [+新增功能]。
輸入 [客戶名稱] 作為 [顯示名稱]、選取 [雲端屬性] 作為功能類型、展開項目，然後選擇 [字串] 作為 [結構描述]。 然後選取儲存。
若要自訂 Get Max-Min report 命令在 IoT Central 應用程式中顯示的方式：
瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
針對 getMaxMinReport (thermostat1)，請將 Get Max-Min report. 取代為 Get thermostat1 status report。
針對 getMaxMinReport (thermostat2)，請將 Get Max-Min report. 取代為 Get thermostat2 status report。
選取 [儲存]。
若要自訂 [目標溫度] 可寫入屬性在 IoT Central 應用程式中顯示的方式：
瀏覽至 [裝置範本] 頁面上的 [溫度控制器]。
針對 targetTemperature (thermostat1)，將 [目標溫度] 取代為 [目標溫度 (1)]。
針對 targetTemperature (thermostat2)，將 [目標溫度] 取代為 [目標溫度 (2)]。
選取 [儲存]。
溫度控制器模型中的控溫器模型包含目標溫度可寫入屬性，裝置範本包含客戶名稱雲端屬性。 若要建立操作員可以編輯這些屬性的檢視：
選取 [檢視]，再選取 [編輯裝置和雲端資料] 圖格。
輸入「屬性」作為表單名稱。
選取 [目標溫度 (1)]、[目標溫度 (2)]，以及 [客戶名稱] 屬性。 然後選取 [新增區段]。
儲存您的變更。
發佈裝置範本
您必須先發佈裝置範本，操作員才能看到並使用您的自訂項目。
從控溫器裝置範本中，選取 [發佈]。 在 [將此裝置範本發佈至應用程式] 面板上，選取 [發佈]。
操作員現在可以使用 [屬性] 檢視來更新屬性值，並在裝置命令頁面上呼叫稱為 Get thermostat1 status report 和 Get thermostat2 status report 的命令：
在 [屬性] 頁面上更新可寫入的屬性值：
呼叫 [命令] 頁面中的命令。 如果您執行狀態報告命令，請在執行該命令之前，先選取 [自從] 參數的日期和時間：
您可看到裝置如何回應命令和屬性更新：
{'thermostat1': {'targetTemperature': 67, '__t': 'c'}, '$version': 2}
the data in the desired properties patch was: {'thermostat1': {'targetTemperature': 67, '__t': 'c'}, '$version': 2}
Values received are :-
{'targetTemperature': 67, '__t': 'c'}
Sent message
...
Command request received with payload
2021-03-31T05:00:00.000Z
Will return the max, min and average temperature from the specified time 2021-03-31T05:00:00.000Z to the current time
Done generating
{"avgTemp": 4.0, "endTime": "2021-03-31T12:29:48.322427", "maxTemp": 18, "minTemp": null, "startTime": "2021-03-31T12:28:28.322381"}
檢視未經處理資料
您可以使用 [未經處理資料] 檢視，來檢查裝置傳送到 IoT Central 的未經處理資料：
在此檢視中，您可以選取要顯示的資料行，並設定要檢視的時間範圍。 [未模型化的資料] 資料行會顯示裝置內不符合裝置範本中任何屬性或遙測定義的裝置資料。
清除資源
如果您不打算完成任何進一步的 IoT Central 快速入門或教學課程，則可以刪除您的 IoT Central 應用程式：
- 在您的 IoT Central 應用程式中，瀏覽至 [應用程式] > [管理]。
- 選取 [刪除]，然後確認您的動作。
下一步
如果您想要繼續進行這套 IoT Central 教學課程並深入了解如何建置 IoT Central 解決方案，請參閱：