Merge pull request #274277 from kgremban/may3-hubfreshness

JamesJBarnett · web-flow · commit 1b527fe2d26c · 2024-05-06T10:48:21.000-07:00
IoT Hub freshness
diff --git a/articles/iot-hub/iot-hub-devguide-device-twins.md b/articles/iot-hub/iot-hub-devguide-device-twins.md
@@ -129,7 +129,7 @@ In the previous example, the `telemetryConfig` device twin desired and reported
    },
    ```
 
-2. The device app is notified of the change immediately if the device is connected. If it's not connected, the device app follows the [device reconnection flow](#device-reconnection-flow) when it connects. The device app then reports the updated configuration (or an error condition using the `status` property). Here is the portion of the reported properties:
+2. The device app is notified of the change immediately if the device is connected. If it's not connected, the device app follows the [device reconnection flow](#device-reconnection-flow) when it connects. The device app then reports the updated configuration (or an error condition using the `status` property). Here's the portion of the reported properties:
 
    ```json
    "reported": {
@@ -141,7 +141,7 @@ In the previous example, the `telemetryConfig` device twin desired and reported
    }
    ```
 
-3. The solution back end can track the results of the configuration operation across many devices by [querying](iot-hub-devguide-query-language.md) device twins.
+3. The solution back end tracks the results of the configuration operation across many devices by [querying](iot-hub-devguide-query-language.md) device twins.
 
 > [!NOTE]
 > The preceding snippets are examples, optimized for readability, of one way to encode a device configuration and its status. IoT Hub does not impose a specific schema for the device twin desired and reported properties in the device twins.
@@ -323,9 +323,9 @@ This information is kept at every level (not just the leaves of the JSON structu
 
 ## Optimistic concurrency
 
-Tags, desired properties, and reported properties all support optimistic concurrency. If you need to guarantee order of twin property updates, consider implementing synchronization at the application level by waiting for reported properties callback before sending the next update. 
+Tags, desired properties, and reported properties all support optimistic concurrency. If you need to guarantee order of twin property updates, consider implementing synchronization at the application level by waiting for reported properties callback before sending the next update.
 
-Device twins have an ETag (`etag` property), as per [RFC7232](https://tools.ietf.org/html/rfc7232), that represents the twin's JSON representation. You can use the `etag` property in conditional update operations from the solution back end to ensure consistency. This is the only option for ensuring consistency in operations that involve the `tags` container.
+Device twins have an ETag property `etag`, as per [RFC7232](https://tools.ietf.org/html/rfc7232), that represents the twin's JSON representation. You can use the `etag` property in conditional update operations from the solution back end to ensure consistency. This property is the only option for ensuring consistency in operations that involve the `tags` container.
 
 Device twin desired and reported properties also have a `$version` value that is guaranteed to be incremental. Similarly to an ETag, the version can be used by the updating party to enforce consistency of updates. For example, a device app for a reported property or the solution back end for a desired property.
 
@@ -343,14 +343,7 @@ The device app can ignore all notifications with `$version` less or equal than t
 
 ## Next steps
 
-Now you have learned about device twins, you may be interested in the following IoT Hub developer guide topics:
+To try out some of the concepts described in this article, see the following IoT Hub articles:
 
-* [Understand and use module twins in IoT Hub](iot-hub-devguide-module-twins.md)
-* [Invoke a direct method on a device](iot-hub-devguide-direct-methods.md)
-* [Schedule jobs on multiple devices](iot-hub-devguide-jobs.md)
-
-To try out some of the concepts described in this article, see the following IoT Hub tutorials:
-
-* [How to use the device twin](device-twins-node.md)
-* [How to use device twin properties](tutorial-device-twins.md)
-* [Device management with the Azure IoT Hub extension for VS Code](iot-hub-device-management-iot-toolkit.md)
+* [Tutorial: Configure your devices with device twin properties](tutorial-device-twins.md)
+* [How to use device twins](device-twins-dotnet.md)
diff --git a/articles/iot-hub/iot-hub-devguide-direct-methods.md b/articles/iot-hub/iot-hub-devguide-direct-methods.md
@@ -6,33 +6,31 @@ author: kgremban
 ms.author: kgremban
 ms.service: iot-hub
 ms.topic: concept-article
-ms.date: 07/15/2022
+ms.date: 05/03/2024
 ms.custom: [amqp, mqtt,'Role: Cloud Development', 'Role: IoT Device']
 ---
 
 # Understand and invoke direct methods from IoT Hub
 
-IoT Hub gives you the ability to invoke direct methods on devices from the cloud. Direct methods represent a request-reply interaction with a device similar to an HTTP call in that they succeed or fail immediately (after a user-specified timeout). This approach is useful for scenarios where the course of immediate action is different depending on whether the device was able to respond.
+IoT Hub *direct methods* enable you to remotely invoke calls on devices from the cloud. Direct methods follow a request-response pattern and are meant for communications that require immediate confirmation of their result. For example, interactive control of a device, such as turning on a fan. This functionality is useful for scenarios where the course of immediate action is different depending on whether the device was able to respond.
 
 [!INCLUDE [iot-hub-basic](../../includes/iot-hub-basic-whole.md)]
 
-Each device method targets a single device. [Schedule jobs on multiple devices](iot-hub-devguide-jobs.md) shows how to provide a way to invoke direct methods on multiple devices, and schedule method invocation for disconnected devices.
+Each device method targets a single device. If you want to invoke direct methods on multiple devices, or schedule methods for disconnected devices, see [Schedule jobs on multiple devices](iot-hub-devguide-jobs.md).
 
 Anyone with **service connect** permissions on IoT Hub may invoke a method on a device.
 
-Direct methods follow a request-response pattern and are meant for communications that require immediate confirmation of their result. For example, interactive control of the device, such as turning on a fan.
-
-Refer to [Cloud-to-device communication guidance](iot-hub-devguide-c2d-guidance.md) if in doubt between using desired properties, direct methods, or cloud-to-device messages.
+Refer to the [Cloud-to-device communication guidance](iot-hub-devguide-c2d-guidance.md) if in doubt between using desired properties, direct methods, or cloud-to-device messages.
 
 ## Method lifecycle
 
 Direct methods are implemented on the device and may require zero or more inputs in the method payload to correctly instantiate. You invoke a direct method through a service-facing URI (`{iot hub}/twins/{device id}/methods/`). A device receives direct methods through a device-specific MQTT topic (`$iothub/methods/POST/{method name}/`) or through AMQP links (the `IoThub-methodname` and `IoThub-status` application properties).
 
 > [!NOTE]
-> When you invoke a direct method on a device, property names and values can only contain US-ASCII printable alphanumeric, except any in the following set: ``{'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}``
+> When you invoke a direct method on a device, property names and values can only contain US-ASCII printable alphanumeric, except any in the following set: `$ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT`
 >
 
-Direct methods are synchronous and either succeed or fail after the timeout period (default: 30 seconds, settable between 5 and 300 seconds). Direct methods are useful in interactive scenarios where you want a device to act if and only if the device is online and receiving commands. For example, turning on a light from a phone. In these scenarios, you want to see an immediate success or failure so the cloud service can act on the result as soon as possible. The device may return some message body as a result of the method, but it isn't required for the method to do so. There is no guarantee on ordering or any concurrency semantics on method calls.
+Direct methods are synchronous and either succeed or fail after the timeout period (default 30 seconds; settable between 5 and 300 seconds). Direct methods are useful in interactive scenarios where you want a device to act if and only if the device is online and receiving commands. For example, turning on a light from a phone. In these scenarios, you want to see an immediate success or failure so the cloud service can act on the result as soon as possible. The device may return some message body as a result of the method, but it isn't required. There is no guarantee on ordering or any concurrency semantics on method calls.
 
 Direct methods are HTTPS-only from the cloud side and MQTT, AMQP, MQTT over WebSockets, or AMQP over WebSockets from the device side.
 
@@ -76,7 +74,7 @@ The value provided as `connectTimeoutInSeconds` in the request is the amount of
 
 #### Example
 
-This example will allow you to securely initiate a request to invoke a direct method on an IoT device registered to an Azure IoT hub.
+This example initiates a request to invoke a direct method on an IoT device registered to an Azure IoT hub.
 
 To begin, use the [Microsoft Azure IoT extension for Azure CLI](https://github.com/Azure/azure-iot-cli-extension) to create a SharedAccessSignature.
 
@@ -101,10 +99,10 @@ curl -X POST \
 }'
 ```
 
-Execute the modified command to invoke the specified direct method. Successful requests will return an HTTP 200 status code.
+Execute the modified command to invoke the specified direct method. Successful requests return an HTTP 200 status code.
 
 > [!NOTE]
-> The example above demonstrates invoking a direct method on a device.  If you want to invoke a direct method in an IoT Edge Module, you would need to modify the url request as shown below:
+> The example above demonstrates invoking a direct method on a device. If you want to invoke a direct method in an IoT Edge Module, modify the url request to include `/modules/<moduleName>` as shown below:
 >
 > ```bash
 > https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12
@@ -199,27 +197,11 @@ The method's response is returned on the sending link and is structured as follo
 
 * The AMQP message body containing the method response as JSON.
 
-## Additional reference material
-
-Other reference topics in the IoT Hub developer guide include:
-
-* [IoT Hub endpoints](iot-hub-devguide-endpoints.md) describes the various endpoints that each IoT hub exposes for run-time and management operations.
-
-* [Throttling and quotas](iot-hub-devguide-quotas-throttling.md) describes the quotas that apply and the throttling behavior to expect when you use IoT Hub.
-
-* [Azure IoT device and service SDKs](iot-hub-devguide-sdks.md) lists the various language SDKs you can use when you develop both device and service apps that interact with IoT Hub.
-
-* [IoT Hub query language for device twins, jobs, and message routing](iot-hub-devguide-query-language.md) describes the IoT Hub query language you can use to retrieve information from IoT Hub about your device twins and jobs.
-
-* [IoT Hub MQTT support](../iot/iot-mqtt-connect-to-iot-hub.md) provides more information about IoT Hub support for the MQTT protocol.
-
 ## Next steps
 
 Now you have learned how to use direct methods, you may be interested in the following IoT Hub developer guide article:
 
 * [Schedule jobs on multiple devices](iot-hub-devguide-jobs.md)
+* [Azure IoT device and service SDKs](iot-hub-devguide-sdks.md) lists the various language SDKs you can use when you develop both device and service apps that interact with IoT Hub.
+* [IoT Hub query language for device twins, jobs, and message routing](iot-hub-devguide-query-language.md) describes the IoT Hub query language you can use to retrieve information from IoT Hub about your device twins and jobs.
 
-If you would like to try out some of the concepts described in this article, you may be interested in the following IoT Hub tutorial:
-
-* [Quickstart: Control a device connected to an IoT hub](quickstart-control-device.md)
-* [Device management with the Azure IoT Hub extension for VS Code](iot-hub-device-management-iot-toolkit.md)
diff --git a/articles/iot-hub/iot-hub-devguide-sdks.md b/articles/iot-hub/iot-hub-devguide-sdks.md
@@ -6,24 +6,26 @@ author: kgremban
 ms.author: kgremban
 ms.service: iot-hub
 ms.topic: concept-article
-ms.date: 11/18/2022
+ms.date: 05/03/2024
 ms.custom: [mqtt, 'Role: IoT Device', 'Role: Cloud Development']
 ---
 
 # Azure IoT Hub SDKs
 
-There are three categories of software development kits (SDKs) for working with IoT Hub:
+IoT Hub provides three categories of software development kits (SDKs) to help you build device and back-end applications:
 
-* [**IoT Hub device SDKs**](#azure-iot-hub-device-sdks) enable you to build apps that run on your IoT devices using the device client or module client. These apps send telemetry to your IoT hub, and optionally receive messages, jobs, methods, or twin updates from your IoT hub. You can use these SDKs to build device apps that use [Azure IoT Plug and Play](../iot/overview-iot-plug-and-play.md) conventions and models to advertise their capabilities to IoT Plug and Play-enabled applications. You can also use the module client to author [modules](../iot-edge/iot-edge-modules.md) for [Azure IoT Edge runtime](../iot-edge/about-iot-edge.md).
+* [**IoT Hub device SDKs**](#azure-iot-hub-device-sdks) enable you to build applications that run on your IoT devices using the device client or module client. These apps send telemetry to your IoT hub, and optionally receive messages, jobs, methods, or twin updates from your IoT hub. You can use these SDKs to build device apps that use [Azure IoT Plug and Play](../iot/overview-iot-plug-and-play.md) conventions and models to advertise their capabilities to IoT Plug and Play-enabled applications. You can also use the module client to author modules for [Azure IoT Edge](../iot-edge/about-iot-edge.md).
 
 * [**IoT Hub service SDKs**](#azure-iot-hub-service-sdks) enable you to build backend applications to manage your IoT hub, and optionally send messages, schedule jobs, invoke direct methods, or send desired property updates to your IoT devices or modules.
 
 * [**IoT Hub management SDKs**](#azure-iot-hub-management-sdks) help you build backend applications that manage the IoT hubs in your Azure subscription.
 
-Microsoft also provides a set of SDKs for provisioning devices through and building backend services for the [Device Provisioning Service](../iot-dps/about-iot-dps.md). To learn more, see [Microsoft SDKs for IoT Hub Device Provisioning Service](../iot-dps/libraries-sdks.md).
+Microsoft also provides a set of SDKs for provisioning devices through and building backend services for the Device Provisioning Service. To learn more, see [Microsoft SDKs for IoT Hub Device Provisioning Service](../iot-dps/libraries-sdks.md).
 
 Learn about the [benefits of developing using Azure IoT SDKs](https://azure.microsoft.com/blog/benefits-of-using-the-azure-iot-sdks-in-your-azure-iot-solution/).
 
+[!INCLUDE [iot-hub-basic](../../includes/iot-hub-basic-partial.md)]
+
 ## Azure IoT Hub device SDKs
 
 [!INCLUDE [iot-hub-sdks-device](../../includes/iot-hub-sdks-device.md)]
@@ -34,8 +36,6 @@ Learn more about the IoT Hub device SDKs in the [IoT device development document
 
 [!INCLUDE [iot-hub-sdks-embedded](../../includes/iot-hub-sdks-embedded.md)]
 
-Learn more about the IoT Hub embedded device SDKs in the [IoT device development documentation](../iot/iot-sdks.md).
-
 ## Azure IoT Hub service SDKs
 
 [!INCLUDE [iot-hub-sdks-service](../../includes/iot-hub-sdks-service.md)]
@@ -44,15 +44,13 @@ Learn more about the IoT Hub embedded device SDKs in the [IoT device development
 
 [!INCLUDE [iot-hub-sdks-management](../../includes/iot-hub-sdks-management.md)]
 
-[!INCLUDE [iot-hub-basic](../../includes/iot-hub-basic-partial.md)]
-
 ## SDKs for related Azure IoT services
 
 Azure IoT SDKs are also available for the following services:
 
-* [Microsoft SDKs for IoT Hub Device Provisioning Service](../iot-dps/libraries-sdks.md): To help you provision devices through and build backend services for the Device Provisioning Service.
+* [SDKs for IoT Hub Device Provisioning Service](../iot-dps/libraries-sdks.md): To help you provision devices through and build backend services for the Device Provisioning Service.
 
-* [Device Update for IoT Hub SDKs](../iot-hub-device-update/understand-device-update.md): To help you deploy over-the-air (OTA) updates for IoT devices.
+* [SDKs for Device Update for IoT Hub](../iot-hub-device-update/understand-device-update.md): To help you deploy over-the-air (OTA) updates for IoT devices.
 
 ## Next steps
 
