Get started with IoT Hub module identity and module twin using the Azure portal and a .NET device

Artikkel
10/01/2024

Module identities and module twins are similar to Azure IoT Hub device identity and device twin, but provide finer granularity. While Azure IoT Hub device identity and device twin enable the back-end application to configure a device and provide visibility on the device's conditions, a module identity and module twin provide these capabilities for individual components of a device. On capable devices with multiple components, such as operating system devices or firmware devices, module identities and module twins allow for isolated configuration and conditions for each component.

Note

The features described in this article are available only in the standard tier of IoT Hub. For more information about the basic and standard/free IoT Hub tiers, see Choose the right IoT Hub tier for your solution.

In this article, you will learn how to:

Create a module identity in the portal.
Use a .NET device SDK to update the module twin from your device.

Note

See Azure IoT SDKs for more information about the SDK tools available to build both device and back-end apps.

Prerequisites

Visual Studio.
An IoT hub in your Azure subscription. If you don't have a hub yet, you can follow the steps in Create an IoT hub.
A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in Register a device.

Module authentication

You can use symmetric keys or X.509 certificates to authenticate module identities. For X.509 certificate authentication, the module's certificate must have its common name (CN) formatted like CN=<deviceid>/<moduleid>. For example:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Create a module identity in the portal

Within one device identity, you can create up to 20 module identities. To add an identity, follow these steps:

From your existing device in the Azure portal, choose Add Module Identity to create your first module identity.
Enter the name myFirstModule. Save your module identity.
Your new module identity appears at the bottom of the screen. Select it to see module identity details.
Save the Connection string (primary key). You use it in the next section to set up your module on the device in a console app.

Update the module twin using .NET device SDK

Now let's communicate to the cloud from your simulated device. Once a module identity is created, a module twin is implicitly created in IoT Hub. In this section, you create a .NET console app on your simulated device that updates the module twin reported properties.

Create a Visual Studio project

To create an app that updates the module twin, reported properties, follow these steps:

In Visual Studio, select Create a new project, then choose Console App (.NET Framework), and select Next.
In Configure your new project, enter UpdateModuleTwinReportedProperties as the Project name. Select Next to continue.
Keep the default .NET framework, then select Create.

Install the latest Azure IoT Hub .NET device SDK

The module identity and module twin features are only available in the IoT Hub pre-release device SDKs. To install it, follow these steps:

In Visual Studio, open Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
Select Browse, and then select Include prerelease. Search for Microsoft.Azure.Devices.Client. Select the latest version and install.

Now you have access to all the module features.

Create UpdateModuleTwinReportedProperties console app

Important

This article includes steps to connect a device using a shared access signature, also called symmetric key authentication. This authentication method is convenient for testing and evaluation, but authenticating a device using X.509 certificates is a more secure approach. To learn more, see Security best practices > Connection security.

To create your app, follow these steps:

Add the following using statements at the top of the Program.cs file:

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

Add the following fields to the Program class. Replace the placeholder value with the module connection string you saved previously.

private const string ModuleConnectionString = "<Your module connection string>";
private static ModuleClient Client = null;

Add the following method OnDesiredPropertyChanged to the Program class:

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, object userContext)
    {
        Console.WriteLine("desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
        Console.WriteLine("Sending current time as reported property");
        TwinCollection reportedProperties = new TwinCollection
        {
            ["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.Now
        };

        await Client.UpdateReportedPropertiesAsync(reportedProperties).ConfigureAwait(false);
    }

Finally, replace the Main method with the following code:

static void Main(string[] args)
{
    Microsoft.Azure.Devices.Client.TransportType transport = Microsoft.Azure.Devices.Client.TransportType.Amqp;

    try
    {
        Client = ModuleClient.CreateFromConnectionString(ModuleConnectionString, transport);
        Client.SetConnectionStatusChangesHandler(ConnectionStatusChangeHandler);
        Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null).Wait();

        Console.WriteLine("Retrieving twin");
        var twinTask = Client.GetTwinAsync();
        twinTask.Wait();
        var twin = twinTask.Result;
        Console.WriteLine(JsonConvert.SerializeObject(twin));

        Console.WriteLine("Sending app start time as reported property");
        TwinCollection reportedProperties = new TwinCollection();
        reportedProperties["DateTimeLastAppLaunch"] = DateTime.Now;

        Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (AggregateException ex)
    {
        Console.WriteLine("Error in sample: {0}", ex);
    }

    Console.WriteLine("Waiting for Events.  Press enter to exit...");
    Console.ReadKey();
    Client.CloseAsync().Wait();
}

private static void ConnectionStatusChangeHandler(ConnectionStatus status, ConnectionStatusChangeReason reason)
{
    Console.WriteLine($"Status {status} changed: {reason}");
}

You can build and run this app by using F5.

Now you know how to retrieve the module twin and update reported properties with AMQP protocol.

Next steps

To continue getting started with IoT Hub and to explore other IoT scenarios, see:

Jagamisviis: