Metadata, screenshots, and links updated, minor Acrolinx updates to improve score

Author: DENKEN02MSFT

articles/iot-hub/iot-hub-device-streams-overview.md

@@ -1,22 +1,22 @@
 ---
 title: Azure IoT Hub device streams | Microsoft Docs
-description: Overview of Azure IoT Hub device streams, which facilitate secure bi-directional TCP tunnels for a variety of cloud-to-device communication scenarios.
+description: Overview of Azure IoT Hub device streams, which facilitate secure bi-directional TCP tunnels for various cloud-to-device communication scenarios.
 author: SoniaLopezBravo
 services: iot-hub
 ms.service: azure-iot-hub
-ms.topic: conceptual
-ms.date: 01/15/2019
+ms.topic: concept-article
+ms.date: 05/23/2025
 ms.author: sonialopez
 ms.custom: ['Role: Cloud Development','Role: IoT Device','Role: Technical Support']
 ---
 
 # IoT Hub Device Streams (preview)
 
-Azure IoT Hub *device streams* facilitate the creation of secure bi-directional TCP tunnels for various cloud-to-device communication scenarios. A device stream is mediated by an IoT Hub *streaming endpoint, which acts as a proxy between your device and service endpoints. This setup, depicted in the diagram, is especially useful when devices are behind a network firewall or reside inside of a private network. As such, IoT Hub device streams help address customers' need to reach IoT devices in a firewall-friendly manner and without the need to broadly opening up incoming or outgoing network firewall ports.
+Azure IoT Hub *device streams* facilitate the creation of secure bi-directional TCP tunnels for various cloud-to-device communication scenarios. An IoT Hub *streaming endpoint* mediates device streams, acting as a proxy between your device and service endpoints. This setup, depicted in the following diagram, is especially useful when devices are behind a network firewall or reside inside of a private network. As such, IoT Hub device streams help address customers' need to reach IoT devices in a firewall-friendly manner and without the need to broadly opening up incoming or outgoing network firewall ports.
 
-!["IoT Hub device streams overview"](./media/iot-hub-device-streams-overview/iot-hub-device-streams-overview.png)
+:::image type="content" source="./media/iot-hub-device-streams-overview/iot-hub-device-streams-overview.png" alt-text="Diagram that shows an overview of IoT Hub device streams.":::
 
-Using IoT Hub device streams, devices remain secure and will only need to open up outbound TCP connections to IoT hub's streaming endpoint over port 443. Once a stream is established, the service-side and device-side applications each have programmatic access to a WebSocket client object to send and receive raw bytes to one another. The reliability and ordering guarantees provided by this tunnel is on par with TCP.
+Devices that use IoT Hub device streams can remain secure and only need to open up outbound TCP connections to your IoT hub's streaming endpoint over port 443. Once a stream is established, the service-side and device-side applications each have programmatic access to a WebSocket client object to send and receive raw bytes to one another. The reliability and ordering guarantees provided by this tunnel is on par with TCP.
 
 ## Benefits
 
@@ -44,7 +44,7 @@ The device stream creation process involves a negotiation between the device, se
 
 Programmatic creation of a device stream using the SDK involves the following steps, which are also depicted in the figure:
 
-!["Device stream handshake process"](./media/iot-hub-device-streams-overview/iot-hub-device-streams-handshake.png)
+:::image type="content" source="./media/iot-hub-device-streams-overview/iot-hub-device-streams-handshake.png" alt-text="Diagram that shows the steps of the handshake process for an IoT Hub device stream.":::
 
 1. The device application registers a callback in advance to be notified of when a new device stream is initiated to the device. This step typically takes place when the device boots up and connects to IoT Hub.
 
@@ -56,27 +56,27 @@ Programmatic creation of a device stream using the SDK involves the following st
 
 5. The service is notified of the result of device accepting the stream and proceeds to create its own WebSocket client to the streaming endpoint. Similarly, it receives the streaming endpoint URL and authentication information from IoT Hub.
 
-In the handshake process above:
+In the previously described handshake process:
 
-* The handshake process must complete within 60 seconds (step 2 through 5), otherwise the handshake would fail with a timeout and the service will be notified accordingly.
+* The handshake process must complete within 60 seconds (step 2 through 5), otherwise the handshake fails with a timeout and the service is notified accordingly.
 
-* After the stream creation flow above completes, the streaming endpoint will act as a proxy and will transfer traffic between the service and the device over their respective WebSockets.
+* After the previously described stream creation flow completes, the streaming endpoint acts as a proxy and transfers traffic between the service and the device over their respective WebSockets.
 
 * Device and service both need outbound connectivity to IoT Hub's main endpoint and the streaming endpoint over port 443. The URL of these endpoints is available on *Overview* tab on the IoT Hub's portal.
 
 * The reliability and ordering guarantees of an established stream is on par with TCP.
 
-* All connections to IoT Hub and streaming endpoint use TLS and are encrypted.
+* All connections to IoT Hub and its streaming endpoint use TLS and are encrypted.
 
 ### Termination flow
 
 An established stream terminates when either of the TCP connections to the gateway are disconnected (by the service or device). This action can take place voluntarily by closing the WebSocket on either the device or service programs, or involuntarily if a network connectivity timeout or process failure. Upon termination of either device or service's connection to the streaming endpoint, the other TCP connection is also (forcefully) terminated and the service and device are responsible to re-create the stream, if needed.
 
 ## Connectivity requirements
 
-Both the device and the service sides of a device stream must be capable of establishing TLS-enabled connections to IoT Hub and its streaming endpoint. This situation requires outbound connectivity over port 443 to these endpoints. The hostname associated with these endpoints can be found on the *Overview* tab of IoT Hub, as shown in the figure:
+Both the device and the service sides of a device stream must be capable of establishing TLS-enabled connections to IoT Hub and its streaming endpoint. This situation requires outbound connectivity over port 443 to these endpoints. The hostname associated with the streaming endpoint can be found on the overview pane of your IoT hub in Azure portal, as shown in the following screenshot.
 
-!["Device stream endpoints"](./media/iot-hub-device-streams-overview/device-stream-in-portal.png)
+:::image type="content" source="./media/iot-hub-device-streams-overview/device-stream-in-portal.png" alt-text="Screenshot of the working pane for an IoT hub in Azure portal, highlighting the hostname for device streaming endpoints.":::
 
 Alternatively, the endpoints information can be retrieved using Azure CLI under the hub's properties section, specifically, `property.hostname` and `property.deviceStreams` keys.
 
@@ -95,43 +95,44 @@ The output is a JSON object of all endpoints that your hub's device and service
 ```
 
 > [!NOTE]
-> Ensure you have installed Azure CLI version 2.0.57 or newer. You can download the latest version from the [Install Azure CLI](/cli/azure/install-azure-cli) page.
+> Ensure that you install Azure CLI version 2.0.57 or newer. You can download the latest version from the [Install Azure CLI](/cli/azure/install-azure-cli) page.
 >
 
 ## Allow outbound connectivity to the device streaming endpoints
 
-As mentioned at the beginning of this article, your device creates an outbound connection to IoT Hub streaming endpoint during device streams initiation process. Your firewalls on the device or its network must allow outbound connectivity to the streaming gateway over port 443 (note that communication takes place over a WebSocket connection that is encrypted using TLS).
+As mentioned at the beginning of this article, your device creates an outbound connection to the IoT Hub streaming endpoint during device streams initiation process. Your firewalls on the device or its network must allow outbound connectivity to the streaming gateway over port 443 (note that communication takes place over a WebSocket connection that is encrypted using TLS).
 
-The hostname of device streaming endpoint can be found on the Azure IoT Hub portal under the Overview tab.
-!["Device stream endpoints"](./media/iot-hub-device-streams-overview/device-stream-in-portal.png)
+The hostname associated with the streaming endpoint can be found on the overview pane of your IoT hub in Azure portal, as shown in the following screenshot.
 
-Alternatively, you can find this information using Azure CLI:
+:::image type="content" source="./media/iot-hub-device-streams-overview/device-stream-in-portal.png" alt-text="Screenshot of the working pane for an IoT hub in Azure portal, highlighting the hostname for device streaming endpoints.":::
+
+Alternatively, you can find this information by using the Azure CLI, as shown in the following example:
 
 ```azurecli-interactive
 az iot hub devicestream show --name <YourIoTHubName>
 ```
 
 > [!NOTE]
-> Ensure you have installed Azure CLI version 2.0.57 or newer. You can download the latest version from the [Install Azure CLI](/cli/azure/install-azure-cli) page.
+> Ensure that you install Azure CLI version 2.0.57 or newer. You can download the latest version from the [Install Azure CLI](/cli/azure/install-azure-cli) page.
 >
 
 ## Troubleshoot via Device Streams resource logs
 
-You can set up Azure Monitor to collect the [resource logs for device streams](monitor-iot-hub-reference.md#device-streams-category-preview) emitted by your IoT Hub. This approach can be helpful in troubleshooting scenarios.
+You can set up Azure Monitor to collect the [resource logs for device streams](monitor-iot-hub-reference.md#device-streams-category-preview) emitted by your IoT hub. This approach can be helpful in troubleshooting scenarios.
 
-Follow these steps to create a diagnostics setting to send device streams logs for your IoT Hub to Azure Monitor Logs:
+Follow these steps to create a diagnostics setting to send Device Streams resource logs for your IoT hub to Azure Monitor Logs:
 
-1. In Azure portal, navigate to your IoT hub. On the left pane, under **Monitoring**, select **Diagnostic settings**. Then select **Add diagnostic setting**.
+1. In Azure portal, navigate to your IoT hub. On the left pane, under **Monitoring**, select **Diagnostic settings**. Then, select **Add diagnostic setting**.
 
-2. Provide a name for your diagnostics setting and select **DeviceStreams** from the list of logs. Then select **Send to Log Analytics**. You'll be guided to choose an existing Log Analytics workspace or create a new one.
+2. Provide a name for your diagnostics setting and select **Device Streams (Preview)** from the list of logs. Then select **Send to Log Analytics workspace**. You're guided to choose an existing Log Analytics workspace or create a new one.
 
-    :::image type="content" source="media/iot-hub-device-streams-overview/device-streams-configure-diagnostics.png" alt-text="Enable device streams logs":::
+    :::image type="content" source="./media/iot-hub-device-streams-overview/device-streams-configure-diagnostics.png" alt-text="Screenshot that shows the Diagnostics setting pane in Azure portal, highlighting settings for Device Streams resource logs.":::
 
-3. After you create a diagnostic setting to send your device streams logs to a Log Analytics workspace, you can access the logs by selecting **Logs** under **Monitoring** on the left pane of your IoT hub in Azure portal. Device streams logs appear in the `AzureDiagnostics` table and have `Category=DeviceStreams`. It might take several minutes following an operation for logs to appear in the table.
+3. After you create a diagnostic setting to send your Device Streams resource logs to a Log Analytics workspace, you can access the logs by selecting **Logs** under **Monitoring** on the left pane of your IoT hub in Azure portal. Device Streams resource logs appear in the `AzureDiagnostics` table and have `Category=DeviceStreams`. It might take several minutes following an operation for logs to appear in the table.
 
    As shown here, the identity of the target device and the result of the operation is also available in the logs.
 
-   !["Access device stream logs"](./media/iot-hub-device-streams-overview/device-streams-view-logs.png)
+   :::image type="content" source="./media/iot-hub-device-streams-overview/device-streams-view-logs.png" alt-text="Screenshot that shows the AzureDiagnostic logs for an IoT hub, highlighting the identity, operation, and results for a Device Streams resource log entry.":::
 
 To learn more about using Azure Monitor with IoT Hub, see [Monitor IoT Hub](monitor-iot-hub.md). For information about all of the resource logs, metrics, and tables available for IoT Hub, see [Monitoring Azure IoT Hub data reference](monitor-iot-hub-reference.md).
 
@@ -143,11 +144,11 @@ During public preview, IoT Hub device streams are available in the Central US, E
 
 Two sides of each stream (on the device and service side) use the IoT Hub SDK to establish the tunnel. During public preview, customers can choose from the following SDK languages:
 
-* The C and C# SDK's support device streams on the device side.
+* The C and C# SDKs support device streams on the device side.
 
-* The Node.js and C# SDK support device streams on the service side.
+* The Node.js and C# SDKs support device streams on the service side.
 
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Azure IoT Hub Device Streams Video](/shows/Internet-of-Things-Show/Azure-IoT-Hub-Device-Streams)
+> [Azure IoT Hub Device Streams video](/shows/Internet-of-Things-Show/Azure-IoT-Hub-Device-Streams)