search

MicrosoftDocs / azure-docs

Open source documentation of Microsoft Azure
https://docs.microsoft.com/azure
Creative Commons Attribution 4.0 International
10.31k stars 21.48k forks source link

Inconsistent or outdated documentation "Ingest IoT Hub telemetry into Azure Digital Twins" #118329

Closed AlexandrStarov closed 10 months ago

AlexandrStarov commented 11 months ago

It’s not entirely clear how exactly you should use telemetry from a device in digital twins

According to the documentation for DTDL models, 'Telemetry' field should be used to display the current value from the IoT edge device. (https://learn.microsoft.com/en-us/azure/digital-twins/concepts-models#properties-and-telemetry)

The "Ingest telemetry from IoT Hub" example shows how to receive telemetry from IoT edge device and forward it to the Digital Twins model. (https://learn.microsoft.com/en-us/azure/digital-twins/how-to-ingest-iot-hub-data#add-a-model-and-twin). This example updates the "Property" type instead of "Telemetry" type.

After studying the official documentation and looking at various examples, I have a few questions:

  1. If I need to show the current state of the device, should I use "Property" or "Telemetry"?
  2. In case "Telemetry", is it correct to use UpdateDigitalTwinAsync method to update telemetry value in the DTDL model?
  3. How to update "Property" value based on "Telemetry" for example one time per minute?

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

Naveenommi-MSFT commented 11 months ago

@AlexandrStarov Thanks for your feedback! We will investigate and update as appropriate.

AshokPeddakotla-MSFT commented 11 months ago

Thanks for the feedback! I have assigned the issue to the content author to evaluate and update as appropriate.

baanders commented 10 months ago

Thank you @AlexandrStarov for raising this issue. I’ve reviewed our docs on this topic and totally agree that the current guidance on this is confusing and should be updated.

To answer your question, you should use Property in your DTDL model to store twin state information. Then, you can update the value of the property with the UpdateDigitalTwinAsync method as you mentioned.

The main way telemetry is used in Azure Digital Twins is totally separate from the model definition: you can use the SendTelemetry API to trigger a Digital twin telemetry message event, which can then be handled by an event handler to take actions on other twins or trigger downstream services. This process can be done without any Telemetry field being defined in the DTDL model, and is more about sending data out from a digital twin than receiving device data in. For receiving device data into Azure Digital Twins and storing it in a twin, you should use DTDL Properties. The steps in the document you linked should help explain how to ingest simulated device data into Azure Digital Twins and store it in a property. For a wider look at the whole flow, you can also review the end-to-end tutorial.

Furthermore, the product team has indicated that there’s actually no unique reason to use the Telemetry field in DTDL models designed for use in Azure Digital Twins. So I’m going to go ahead and update the documentation to recommend using Properties in Azure Digital Twins models and not using the Telemetry field in your models at all. That work is being done in this pull request: https://github.com/MicrosoftDocs/azure-docs-pr/pull/262300

Hopefully removing the use of Telemetry from DTDL models for Azure Digital Twins should eliminate future confusion on this. Git is going to automatically close this issue when that pull request with the fix is merged. However, feel free to continue the conversation here as needed. I hope that this answers your question and appreciate the opportunity to improve our documentation!