Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
In this quickstart, you prepare cloud resources, configure a delivery path, connect a device through the unified SDK, and verify telemetry at a downstream destination. The device examples use an existing X.509 certificate for DPS onboarding and the subsequent hub connection. Use the linked guides for each stage of the journey.
Important
Azure IoT Hub with the MQTT v5 connection profile is in preview. Review the capability matrix before starting.
Sample scripts and code
The Azure IoT Hub MQTT v5 and ADR preview samples repository provides PowerShell setup scripts, C and .NET device code, and a verifier that checks message receipt at standalone Azure Event Hubs destinations. The standard scenario also checks direct methods and desired-to-reported twin property updates. Follow the repository's instructions to run the samples on Windows.
Unlike the existing-certificate walkthrough in this article, the samples use a symmetric key for DPS onboarding and request an operational certificate with a certificate signing request (CSR). The device then connects to IoT Hub with X.509. The samples create their own environment. Don't run their setup script against an environment created by this walkthrough.
Note
The samples passed local builds and offline checks. Live Azure scenarios and clean-machine setup still require validation. Confirm access to the required preview CLI extension before starting. The samples create billable resources. Review their requirements and cleanup instructions.
Prerequisites
- An Azure subscription.
- Permission to create and link Azure IoT Hub, Azure Device Registry (ADR) namespaces, and Device Provisioning Service (DPS) instances.
- Permission to configure required identities, role assignments, and routing.
- A supported downstream destination and a way to read received messages.
- A development environment for the unified .NET or C SDK.
- An existing X.509 device certificate and its matching private key.
Use a disposable evaluation environment where possible. Record the resources you create so that cleanup doesn't remove shared infrastructure.
1. Configure an MQTT v5 hub
Follow Configure an IoT hub with the MQTT v5 connection profile to create the hub and configure:
- An IoT hub with the MQTT v5 connection profile selected at creation.
- Its Azure Device Registry namespace association and required permissions.
- DPS, linked through the ADR namespace to the intended hub.
- An enabled X.509 enrollment for the test device.
Use the hub configuration guide for the supported portal, CLI, and ARM steps and their prerequisites. Record the DPS ID scope for the device application. For onboarding options and credential configuration, see Connect a device using MQTT v5.
Checkpoint: The resource associations and enrollment are ready for the device.
2. Configure topics, routes, and destinations
Complete this stage before running the device application:
- If the application uses custom topics, configure its allowed topics by using Configure custom topic groups.
- Create a routing endpoint for a supported downstream destination and grant IoT Hub the required access.
- Create and enable a route for incoming device telemetry with query
true. - Prepare the destination reader.
- Enable the diagnostic collection needed for the test.
See Shared routing requirements. For destination-specific requirements, see Custom endpoints for message routing. Set up diagnostics with Collect and route monitoring data.
A custom topic group doesn't create a route, and a route doesn't grant topic publishing permission.
The all-messages route is explicit customer configuration, not an automatic default. Fallback is disabled for preview. There's no customer-accessible built-in telemetry destination to use instead of configuring your own route.
Checkpoint: The route is enabled, references the intended endpoint, and the destination reader is ready.
3. Configure the device and publish
Follow Connect a device using MQTT v5:
- Choose .NET or C and use the version specified by the example.
- Configure the DPS ID scope and X.509 credentials.
- Let the SDK provision the device and establish the hub connection.
- Check that DPS assigned the intended hub with the MQTT v5 connection profile.
- Send the example's JSON telemetry and record the publish outcome.
MQTT v5 is fixed by the profile. Configure TLS and certificate trust according to the device platform; don't disable certificate validation. See IoT Hub endpoints and X.509 device authentication.
The initial examples send messages by using the SDK's telemetry API, which publishes to an IoT Hub-defined telemetry topic. To publish to your own MQTT topics, configure a custom topic group and use the SDK's custom publishing API with an allowed topic. Both approaches use the same SDK-managed connection.
Checkpoint: The device reports provisioning, connection, and publish results.
4. Verify delivery and monitor
- Read the configured destination during the test interval.
- Find the current message by using its test identifier, or the C sample's test device and payload.
- Compare the received payload and metadata with the sent data.
- Inspect available IoT Hub metrics and resource logs during the same interval.
A publish acknowledgment or an ingress metric doesn't prove that you can read the message downstream. If the message doesn't arrive, check the route, query, destination access, and consumer configuration in that order.
Follow Monitor a test run for shared monitoring checkpoints and Troubleshoot provisioning and delivery for MQTT v5-specific failures.
Checkpoint: The test message is available to the destination reader and you know where to look when the pipeline fails.
Clean up resources
Stop the test device application. Remove test credentials from the development environment when you no longer need them.
Delete only resources that you created for this evaluation. Before deleting a resource group, check whether the ADR namespace, DPS instance, destination, or monitoring workspace is shared. Review related role assignments and diagnostic settings.
Next steps
- Add custom-topic publishing and selective routes.
- Review the shared SDK lifecycle and capabilities.
- Set up operational alerts with Monitor Azure IoT Hub.
- Use the destination service's documentation to build analytics or dashboards.