You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/iot-hub/iot-hub-device-streams-overview.md
+31-30Lines changed: 31 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,22 @@
1
1
---
2
2
title: Azure IoT Hub device streams | Microsoft Docs
3
-
description: Overview of Azure IoT Hub device streams, which facilitate secure bi-directional TCP tunnels for a variety of cloud-to-device communication scenarios.
3
+
description: Overview of Azure IoT Hub device streams, which facilitate secure bi-directional TCP tunnels for various cloud-to-device communication scenarios.
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.
15
+
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.
:::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.":::
18
18
19
-
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.
19
+
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.
20
20
21
21
## Benefits
22
22
@@ -44,7 +44,7 @@ The device stream creation process involves a negotiation between the device, se
44
44
45
45
Programmatic creation of a device stream using the SDK involves the following steps, which are also depicted in the figure:
:::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.":::
48
48
49
49
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.
50
50
@@ -56,27 +56,27 @@ Programmatic creation of a device stream using the SDK involves the following st
56
56
57
57
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.
58
58
59
-
In the handshake process above:
59
+
In the previously described handshake process:
60
60
61
-
* 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.
61
+
* 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.
62
62
63
-
* 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.
63
+
* 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.
64
64
65
65
* 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.
66
66
67
67
* The reliability and ordering guarantees of an established stream is on par with TCP.
68
68
69
-
* All connections to IoT Hub and streaming endpoint use TLS and are encrypted.
69
+
* All connections to IoT Hub and its streaming endpoint use TLS and are encrypted.
70
70
71
71
### Termination flow
72
72
73
73
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.
74
74
75
75
## Connectivity requirements
76
76
77
-
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:
77
+
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.
:::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.":::
80
80
81
81
Alternatively, the endpoints information can be retrieved using Azure CLI under the hub's properties section, specifically, `property.hostname` and `property.deviceStreams` keys.
82
82
@@ -95,45 +95,46 @@ The output is a JSON object of all endpoints that your hub's device and service
95
95
```
96
96
97
97
> [!NOTE]
98
-
> 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.
98
+
> Ensure that you install Azure CLI version 2.73.0 or newer. You can download the latest version from the [Install Azure CLI](/cli/azure/install-azure-cli) page.
99
99
>
100
100
101
101
## Allow outbound connectivity to the device streaming endpoints
102
102
103
-
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).
103
+
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).
104
104
105
-
The hostname of device streaming endpoint can be found on the Azure IoT Hub portal under the Overview tab.
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.
107
106
108
-
Alternatively, you can find this information using Azure CLI:
107
+
:::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.":::
108
+
109
+
Alternatively, you can find this information by using the Azure CLI, as shown in the following example:
109
110
110
111
```azurecli-interactive
111
112
az iot hub devicestream show --name <YourIoTHubName>
112
113
```
113
114
114
115
> [!NOTE]
115
-
> 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.
116
+
> Ensure that you install Azure CLI version 2.73.0 or newer. You can download the latest version from the [Install Azure CLI](/cli/azure/install-azure-cli) page.
116
117
>
117
118
118
119
## Troubleshoot via Device Streams resource logs
119
120
120
-
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.
121
+
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.
121
122
122
-
Follow these steps to create a diagnostics setting to send device streams logs for your IoT Hub to Azure Monitor Logs:
123
+
Follow these steps to create a diagnostics setting to send Device Streams resource logs for your IoT hub to Azure Monitor Logs:
123
124
124
-
1. In Azure portal, navigate to your IoT hub. On the left pane, under **Monitoring**, select **Diagnostic settings**. Then select **Add diagnostic setting**.
125
+
1. In Azure portal, navigate to your IoT hub. On the left pane, under **Monitoring**, select **Diagnostic settings**. Then, select **Add diagnostic setting**.
125
126
126
-
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.
127
+
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="Screenshot that shows the Diagnostics setting pane in Azure portal, highlighting settings for Device Streams resource logs.":::
129
130
130
-
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.
131
+
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.
131
132
132
133
As shown here, the identity of the target device and the result of the operation is also available in the logs.
:::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.":::
135
136
136
-
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).
137
+
To learn more about using Azure Monitor with IoT Hub, see [Monitor Azure IoT Hub](monitor-iot-hub.md). For information about all of the resource logs, metrics, and tables available for IoT Hub, see [Azure IoT Hub monitoring data reference](monitor-iot-hub-reference.md).
137
138
138
139
## Regional availability
139
140
@@ -143,11 +144,11 @@ During public preview, IoT Hub device streams are available in the Central US, E
143
144
144
145
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:
145
146
146
-
* The C and C# SDK's support device streams on the device side.
147
+
* The C and C# SDKs support device streams on the device side.
147
148
148
-
* The Node.js and C# SDK support device streams on the service side.
149
+
* The Node.js and C# SDKs support device streams on the service side.
0 commit comments