DEV Community: Rido

Developing IoTEdge Modules

Rido — Thu, 21 Dec 2023 00:25:00 +0000

Azure IoT Hub includes support for IoT Edge, a runtime to run custom workloads as Modules.

There has been different tools to help with this task, extensions for Visual Studio, Visual Studio Code and even a CLI can help with the most common developer tasks.

However, most of these tools are in maintenance mode, with no major investments.

An alternative approach to develop IoTEdge modules

A module is just an application, running as a docker container, that communicates with the a system module called $edgeHub via HTTP, AMQP or MQTT protocols. To develop a module we need a local instance of $edgeHub that we can target from the machine we use to develop.

In this post, I'm exploring a different approach to configure your workstation so you can develop and debug modules with your favourite IDE.

Note, this sample is using dotnet, but the same concepts should be applicable in other languages.

How to run $edgeHub locally

$edge hub is available as a docker image in mcr.microsoft.com/azureiotedge-hub:1.4, and we need to perform some pre-liminary tasks before running locally:

Initialize the $edgeHub identity in Azure IoT Hub
Configure $edgeHub module twin
Provide certificates to configure the TLS connection

Provisioning $edgeHub

When you create an IoT Edge device identity in Azuere IoT Hub, it will include the module identities for $edgeAgent and $edgeHub system modules. However, the modules are not initialized and do not include the connection string we will need to configure our local instance of $edgeHub.

In a real environment, this iotedge runtime takes care of initializing the system modules, however it implies to connect, at least one time, the iotedge runtime.

Instead, I'm using the dotnet tool aziotedge-modinit to initialize the $edgeHub module, so we can get the connection string.

.env configuration files

The following az scripts require

The $HUB_ID variable, with the name of the Azure IoT Hub
The $EDGE_ID variable, with the name of the IoTEdge device identity
The az extension is configured to use the subscription with access to the Azure IoT Hub

az account set -s $SUB_ID
$HUB_ID=<hubname>
$EDGE_ID=<edge_device_id>

Initialize the $edgeHub module identity:

source .env
edgeConnStr=$(az iot hub device-identity connection-string show -n $HUB_ID -d $EDGE_ID  -o tsv)
dotnet tool install -g aziotedge-modinit
aziotedge-modinit --moduleId='$edgeHub' --ConnectionStrings:IoTEdge="$edgeConnStr"

Configuring $edgeHub

At startup, $edgeHub requires two properties to be configured in the module twin, however as this is a system module, we cannot update the twin, neither using the portal, or the CLI.

 "$edgeHub": {
    "properties.desired": {
        "schemaVersion": "1.1",
        "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
        },
        "routes": {}
    }
}

The only workaround I've found, is to invoke the SetModules operation, using a default deployment manifest, which includes the expected Twin Properties.

source .env
curl https://raw.githubusercontent.com/ridomin/iotedge-modules-demo/main/deployBase.json -o deployBase.json
az iot edge set-modules -n $HUB_ID -d $EDGE_ID -k deployBase.json

Or you can use the portal and follow the SetModules screens with all default values.

Certificates for local development with dotnet dev-certs

The system modules expose endpoints protected by a TLS connection, to configure the TLS we need to provide an X509 certificate. This certificate can be the same certificate aspnet uses to provide a local TLS connection.

The next script creates a certificate for localhost and exports the public and private keys as .PEM and .KEY files, then we can use those files to configure the docker instance.

dotnet dev-certs https -ep _certs/localhost.pem --format PEM --no-password
chmod +r _certs/*
cp _certs/localhost.pem _certs/ca.pem

Running $edgeHub locally with docker

Now that we have the certs, and the $edgeHub connection string, we can run the docker container with:

source .env
connStr=$(az iot hub module-identity connection-string show -n $HUB_ID -d $EDGE_ID -m '$edgeHub' --query connectionString -o tsv)

docker run -it --rm \
    -e IotHubConnectionString="$connStr" \
    -e EdgeModuleHubServerCertificateFile=/certs/localhost.pem \
    -e EdgeModuleHubServerCAChainCertificateFile=/certs/ca.pem \
    -e EdgeHubDevServerCertificateFile=/certs/localhost.pem \
    -e EdgeHubDevTrustBundleFile=/certs/ca.pem \
    -e EdgeHubDevServerPrivateKeyFile=/certs/localhost.key \
    -v ${pwd}/_certs:/certs \
    -p 8883:8883 \
    mcr.microsoft.com/azureiotedge-hub:1.4

If everything goes as expected, you should see this output.

Create a dotnet Module

Now you can create a dotnet module using the dotnet template, to install the template:

dotnet new install Microsoft.Azure.IoT.Edge.Module

To create a new project based on this template.

MODULE_ID=MyModule
dotnet new aziotedgemodule -o $MODULE_ID

Provision the Module Identity

The SetModules operation will create the module identity, along with the container information to deploy in docker. For local development we just need the module identity:

source ../.env
az iot hub module-identity create -n $HUB_ID -d $EDGE_ID -m $MODULE_ID
modcs=$(az iot hub module-identity connection-string show -n $HUB_ID -d $EDGE_ID -m ModuleA -o tsv)

Run/Debug the custom module

Finally, you can run or debug the module by tweaking the configuration so it will connect to the local $edgeHub instance by appending the ;GatewayHostName=localhost to the module connection string, and using the certificate configured for TLS with the EdgeModuleCACertificateFile variable:

export IotHubConnectionString="$modcs;GatewayHostName=localhost"
export EdgeModuleCACertificateFile="../_certs/ca.pem"
dotnet run

Or you can configure your IDE to set these two environment variables (launch.json for VSCode, or launchSettings.json for VS) before starting a debugging session.

The complete sample is available in https://github.com/ridomin/iotedge-modules-demo (CodeSpaces ready)

The IoT Pattern. A .NET implementation for MQTT

Rido — Mon, 03 Oct 2022 04:00:12 +0000

If there is one thing about IoT that can be considered as a pattern, is the characteristic that define a IoT Solution:

Devices that can be managed remotely

The term devices, is very broad, and can be reduced to the idea of small applications, running on different hardware (from constrained MCUs, to complete Windows or Linux computers, and everything in between) that are able to communicate with and endpoint, typically a cloud service.

These devices are able, not only to request information - like we do everyday through HTTP in our browsers - but also to establish a bi-directional communication. And this is what defines the _ IoT Pattern _.

In this article we are going to explore a .NET implementation of the IoT Pattern for MQTT, using MQTTnet.

{:toc}

The IoT Pattern

The pattern consists on 2 main communication behaviors, usually referred as D2C, for Device to Cloud communications, or C2D for Cloud to Device.

To represent messages set from the device to the cloud, we can define the next interface.

public interface IDeviceToCloud<T>
{
    Task SendMessageAsync(T payload);
}

Messages sent from the cloud to the device usually are followed by another message from the device to acknowledge the message was received. For this case we are going to use a callback with a request and a response using a Func.

public interface ICloudToDevice<T, TResp>
{
    Func<T, Task<TResp>>? OnMessage { get; set; }
}

Telemetry

Telemetry is the most common case, when devices send messages with measurements obtained from sensors, such as temperature. Since these measurement change frequently, the data is considered "volatile", and should be stored somewhere for further analysis. These messages can be as simple as numbers, or following a more complex schema.

public interface ITelemetry<T> : IDeviceToCloud<T> { }

Command

Commands are used to invoke actions on devices, and are one common case of C2D messaging, hence:

public interface ICommand<T, TResp> : ICloudToDevice<T, TResp> { }

Property

Devices can describe some of their characteristics, such as the serial number, or hardware details, but also what can be referred as the device state. Like the variables that define the runtime behavior, suchlike how often to send telemetry messages. There are two types of device properties:

Reported Properties

These properties are reported from the device to the cloud, sometimes also referred as read only properties, and can be defined with:

public interface IReadOnlyProperty<T> : IDeviceToCloud<T> { }

Desired Properties

Some properties can be set from the solution side, C2D, where the device should receive the desired property change, and accept or reject the value. These properties are referred to as desired properties, or writable properties. The acceptance/rejection of a property can be described with ack messages. These ack messages contains additional information about the property, such as the Status, Version or Description, that the device can use to inform to the service if the property was accepted, or not, and related details.

Since the ack messages need to be also reported, the IWritableProperty interface implements D2C and C2D:

public class Ack<T>
{
    public int? Version { get; set; }
    public string? Description { get; set; }
    public int Status { get; set; }
    public T Value { get; set; } = default!;
}

public interface IWritableProperty<T> : ICloudToDevice<T, Ack<T>>, IDeviceToCloud<Ack<T>>
{
    T? Value { get; set; }
    int? Version { get; set; }
}

MQTT

There are multiple protocols available to implement IoT devices, although there is one that is widely used, and sometimes referred as the king in the IoT landscape: MQTT. Compared to the omnipresent HTTP, MQTT has two fundamental benefits: bi-directional communication and power efficiency. These two make the protocol ideal to implement The IoT Pattern.

MQTT Brokers

MQTT is not only a protocol, is also a Pub/Sub messaging system implemented by MQTT Brokers. The most famous is Mosquitto, offered as open source from the Eclipse foundation, but there are many others with different licensing options, from HiveMQ, to VerneMQ, nanoMQ, or HMQ.

MQTT Clients

To interact with the broker we need to:

Establish a connection, using different channels such as TCP, or TCP+TLS, and usually providing authentication credentials such as Username/Password or Client Certificates
Subscribe to topics, using different wildcard patterns such as + or #
Publish messages to topics

The most used client is the mosquitto-client available in almost every Windows/Linux/Mac OS in the form mosquitto_pub and mosquitto_sub CLI commands, and there are multiple other options.

To write device applications we need libraries implementing the protocol, like Paho from the Eclipse foundation, but there are many others for practically every programming platform.

No matter with language you use, the pseudo-code to connect, publish and subscribe will look similar to:

mqtt.connect()
mqtt.subscribe('topicA')
mqtt.OnMessageReceived = (topic, msg) => {
    if (topic == 'topicA') {
        // process msg  
    }
}
mqtt.publish('topicA', 'sampleMessage')

This pattern, although very powerful, makes the client code difficult to write, since the client must process all the incoming messages in a single location, the callback where we subscribe for incoming.

Introducing MQTT Topic Bindings

To implement the interfaces described above using the MQTT protocol we can create topic bindings, these are classes that will implement the details to work with topics: publishing messages and most interestingly to subscribe and make the incoming messages available as .NET callbacks. The messages are serialized for publishing and deserialized when received. These serialization operations are exposed on generic APIs.

To integrate with an existing connection, these binders use Dependency Injection to use an existing connection, represented by the IMqttClient interface available in MQTTnet.

public interface IMqttClient
{
    Task<MqttClientPublishResult> PublishAsync(string topic, byte[] payload);
    Task<MqttClientSubscribeResult> SubscribeAsync(topic);
}

Serializers

Messages are represented as a byte array, with multiple options to use different serializers, to customize the serialization format the binders can be initialized with a IMessageSerializer, such as JSON, Avro, or Protobuf.

public interface IMessageSerializer
{
    byte[] ToBytes<T>(T payload, string name = "");
    T? FromBytes<T>(byte[] payload, string name = "");
}

Wrapped Messages

There are cases where we want the message to be wrapped with the name, eg:

{
    "temperature" : 23.32
}

Hence, the serializers should know that name to provide the actual value.

DeviceToCloud Binder

This D2C binder implements the IDeviceToCloud interface and is responsible to serialize the incoming message into a byte array and publish to the specified topic, there is a constructor that uses the Json serializer and can be configured with a different serializer.

public abstract class DeviceToCloudBinder<T> : IDeviceToCloud<T>
{
    private readonly string _name;
    private readonly IMqttClient _connection;
    private readonly IMessageSerializer _messageSerializer;

    public string TopicPattern = "device/{clientId}/telemetry";
    public bool WrapMessage = false;
    protected bool Retain = false;

    public DeviceToCloudBinder(IMqttClient mqttClient, string name) : this(mqttClient, name, new UTF8JsonSerializer()) { }

    public DeviceToCloudBinder(IMqttClient mqttClient, string name, IMessageSerializer ser)
    {
        _connection = mqttClient;
        _name = name;
        _messageSerializer = ser;
    }

    public async Task SendMessageAsync(T payload, CancellationToken cancellationToken = default)
    {
        string topic = TopicPattern
                            .Replace("{clientId}", _connection.Options.ClientId)
                            .Replace("{name}", _name);
        byte[] payloadBytes;
        if (WrapMessage)
        {
            payloadBytes = _messageSerializer.ToBytes(new Dictionary<string, T> { { _name, payload } });
        }
        else
        {
            payloadBytes = _messageSerializer.ToBytes(payload);
        }
        var pubAck = await _connection.PublishAsync(
            new MqttApplicationMessageBuilder()
                .WithTopic(topic)
                .WithPayload(payloadBytes)
                .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce)
                .WithRetainFlag(Retain)
                .Build(),
            cancellationToken);

        if (pubAck.ReasonCode != MqttClientPublishReasonCode.Success)
        {
            Trace.TraceWarning($"Message not published: {pubAck.ReasonCode}");
        }
    }
}

The abstract class includes two protected members to configure its behavior:

TopicPattern. To configure the topic to publish to.
Retained. If the message should published with the retain flag.
WrapMessages. To create a wrapped version of the message.

CloudToDevice Binder

The C2D binder will listen to all received messages, and expose a delegate to consumers. When a message is received it will filter based on the configured topic pattern and when matched it will deserialize the incoming message and invoke the delegate. Additionally it will serialize and publish the response.

Note: Note that all C2D binders will receive ALL messages, but only those who are sent to the configured topic will be actually processed.

public abstract class CloudToDeviceBinder<T, TResp> : ICloudToDevice<T, TResp>
{
    private readonly string _name;
    private readonly IMqttClient _connection;

    protected bool UnwrapRequest = false;
    protected bool WrapResponse = false;

    protected bool RetainResponse = false;

    public Func<T, Task<TResp>>? OnMessage { get; set; }

    protected Action<TopicParameters>? PreProcessMessage;

    public CloudToDeviceBinder(IMqttClient connection, string name)
        : this(connection, name, new UTF8JsonSerializer()) { }

    public CloudToDeviceBinder(IMqttClient connection, string name, IMessageSerializer serializer)
    {
        _connection = connection;
        _name = name;

        connection.ApplicationMessageReceivedAsync += async m =>
        {
            var topic = m.ApplicationMessage.Topic;
            if (topic.StartsWith(requestTopicPattern!.Replace("/#", string.Empty)))
            {
                if (OnMessage != null)
                {
                    var tp = TopicParser.ParseTopic(topic);
                    PreProcessMessage?.Invoke(tp);

                    T req = serializer.FromBytes<T>(m.ApplicationMessage.Payload, UnwrapRequest ? _name : string.Empty)!;
                    if (req != null)
                    {
                        TResp resp = await OnMessage.Invoke(req);
                        byte[] responseBytes = serializer.ToBytes(resp, WrapResponse ? _name : string.Empty);

                        string? resTopic = responseTopicPattern?
                            .Replace("{rid}", tp.Rid.ToString())
                            .Replace("{version}", tp.Version.ToString());

                        _ = connection.PublishAsync(
                            new MqttApplicationMessageBuilder()
                                .WithTopic(resTopic)
                                .WithPayload(responseBytes)
                                .WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtLeastOnce)
                                .WithRetainFlag(RetainResponse)
                                .Build());
                    }
                    else
                    {
                        Trace.TraceWarning($"Cannot parse incoming message name: {_name} payload: {Encoding.UTF8.GetString(m.ApplicationMessage.Payload)}");
                    }
                }
            }
        };
    }

    private string? requestTopicPattern;
    protected string? RequestTopicPattern
    {
        get => requestTopicPattern;
        set
        {
            requestTopicPattern = value?.Replace("{clientId}", _connection.Options.ClientId).Replace("{name}", _name)!;
            _ = _connection.SubscribeWithReplyAsync(requestTopicPattern);
        }
    }

    private string? responseTopicPattern;
    protected string? ResponseTopicPattern
    {
        get => responseTopicPattern;
        set
        {
            responseTopicPattern = value?.Replace("{clientId}", _connection.Options.ClientId).Replace("{name}", _name)!;
        }
    }
}

With these two binders we can proceed to implement Telemetry, Properties and Commands.

Let's assume we want to use the next MQTT topics:

Pattern	Direction	Topic
Telemetry	->	`device/{clientId}/telemetry`
Command (request)	<-	`device/{clientId}/command/{commandName}`
Command (response)	->	`device/{clientId}/command/{commandName}/res`
ReadOnlyProperty	->	`device/{clientId}/props/{propertyName}`
WritableProperty (request)	<-	`device/{clientId}/props/{propertyName}/set`
WritableProperty (response)	->	`device/{clientId}/props/{propertyName}/ack`

Note: Direction means if the message is published or received from a device point of view: -> means publish and <- means subscribed

Note: The syntax {clientId}, {propertyName} and {commandName} should be replaced with the actual values

Implementing Telemetry, Properties and Commands

With the D2C and C2D binders we can implement the IoT messaging patterns by inheriting from the abstract classes and configure the topics we want to use for each case.

Telemetry

The Telemetry class implements the Telemetry<T> interface publishing messages to the corresponding topic

public class Telemetry<T> : DeviceToCloudBinder<T>, ITelemetry<T>
{
    public Telemetry(IMqttClient mqttClient) : this(mqttClient, string.Empty) { }
    public Telemetry(IMqttClient mqttClient, string name)
        : base(mqttClient, name)
    {
        TopicPattern = "device/{clientId}/telemetry";
        WrapMessage = true;
    }
}

Command

Commands will expose a delegate callback and will send the command response:

public class Command<T, TResp> : CloudToDeviceBinder<T, TResp>, ICommand<T, TResp>
{
    public Command(IMqttClient client, string name)
        : base(client, name)
    {
        RequestTopicPattern = "device/{clientId}/commands/{name}";
        ResponseTopicPattern = "device/{clientId}/commands/{name}/resp";
    }
}

ReadOnlyProperty

ReadOnly properties will use the property name in the topic pattern and do not need to wrap the message:

public class ReadOnlyProperty<T> : DeviceToCloudBinder<T>, IReadOnlyProperty<T>
{
    public ReadOnlyProperty(IMqttClient mqttClient) : this(mqttClient, string.Empty) { }
    public ReadOnlyProperty(IMqttClient mqttClient, string name)
        : base(mqttClient, name)
    {
        TopicPattern = "device/{clientId}/props/{name}";
        WrapMessage = false;
        Retain = true;
    }
}

Although some times must be required to send all the properties in a single message, we could use a generic topic, with wrapped message:

TopicPattern = "device/{clientId}/props";
WrapMessage = true;

WritableProperty

public class WritableProperty<T> : CloudToDeviceBinder<T, Ack<T>>, IWritableProperty<T>
{
    readonly IMqttClient _connection;
    readonly string _name;
    public T? Value { get; set; }
    public int? Version { get; set; } = -1;

    public WritableProperty(IMqttClient c, string name)
        : base(c, name)
    {
        _name = name;
        _connection = c;

        RequestTopicPattern = "device/{clientId}/props/{name}/set/#";
        ResponseTopicPattern = "device/{clientId}/props/{name}/ack";
        RetainResponse = true;
        PreProcessMessage = tp =>
        {
            Version = tp.Version;
        };
    }

    public async Task SendMessageAsync(Ack<T> payload, CancellationToken cancellationToken = default)
    {
        var prop = new ReadOnlyProperty<Ack<T>>(_connection, _name)
        {
            TopicPattern = "device/{clientId}/props/{name}/ack",
            WrapMessage = false
        };
        await prop.SendMessageAsync(payload, cancellationToken);
    }
}

Sample Usage

Now that we have implementations for Telemetry, Properties and Commands, we can define a custom client composed of one or more of these elements:

public class SampleClient
{
    public IReadOnlyProperty<string> Property_sdkInfo { get; set; }
    public IWritableProperty<int> Property_interval { get; set; }
    public ITelemetry<double> Telemetry_temp { get; set; }
    public ICommand<string, string> Command_echo { get; set; }

    public SampleClient(IMqttClient c) 
    {
        Property_sdkInfo = new ReadOnlyProperty<string>(c, "sdkInfo");
        Property_interval = new WritableProperty<int>(c, "interval");
        Telemetry_temp = new Telemetry<double>(c, "temp");
        Command_echo = new Command<string, string>(c, "echo");
    }
}

This client can be used to implement the device application focusing in the application logic without worrying of the underlying details of the pub/sub messaging or serialization formats.

Initialize the SampleClient with an existing mqtt connection:

SampleClient client = new SampleClient(mqttClient);

Update a ReadOnlyProperty

await client.Property_sdkInfo.SendMessageAsync("0.1.0.0", stoppingToken);

Send Telemetry

 await client.Telemetry_temp.SendMessageAsync(23.34);

Implement a Command

client.Command_echo.OnMessage = async req =>
{
    return await Task.FromResult(req + req);
};

Implement a WritableProperty update

client.Property_interval.OnMessage = async p =>
{
    Ack<int> ack = new()
    {
        Version = client.Property_interval.Version,
        Description = "accepted",
        Status = 200,
        Value = p
    };
    return await Task.FromResult(ack);
};

Summary

Following this pattern you can implement MQTT applications by applying SOLID principles. The abstract binders will handle the communication details, the Telemetry, Command, ReadOnlyProperty and WritableProperty implementations can be configured to match the topic structure and serialization formats, compose these with a client and now your application logic can be implemented without taking care of the protocol details.

This pattern is being used in the MQTTnet.Extensions.MultiCloud project, to create MQTT applications that can work with different cloud providers.

Demystifying Azure IoT Hub Device SDKs

Rido — Mon, 02 May 2022 05:06:09 +0000

This post covers how to access main IoTHub features using the MQTT protocol without using the official Device SDKs (as described in the docs), instead it uses a generic MQTT library for dotnet capable of basic MQTT primitives: Connect, Publish and Subscribe to access the Telemetry, Commands and DeviceTwin features.

Choosing an MQTT Library

We are going to use MQTTNet as the foundation for this article, although the same concepts can be applied with any other MQTT client.

Establishing the connection

Azure IoT Hub offers two different authentication method for devices: Shared Security Access (SAS) Tokens and X509 Certificates. Let's start with SAS Tokens.

The MQTT protocol allow clients to connect by specifying a UserName and Password, along with the ClientId. IoTHub requires a specific format for the UserName based on the HubName, DeviceId and the SasToken, and the Password is computed with an HMAC signature adding an expiry string.

The next gist shows how to obtain the UserName and Password from the device connection string based on SAS tokens:

using System.Text;

namespace demistify_iothub
{
    public class SasAuth
    {
        private const string apiversion_2020_09_30 = "2020-09-30";
        public static string GetUserName(string hostName, string deviceId, string modelId = "") =>
            $"{hostName}/{deviceId}/?api-version={apiversion_2020_09_30}&model-id={modelId}";

        private static string Sign(string requestString, string key)
        {
            using (var algorithm = new System.Security.Cryptography.HMACSHA256(Convert.FromBase64String(key)))
            {
                return Convert.ToBase64String(algorithm.ComputeHash(Encoding.UTF8.GetBytes(requestString)));
            }
        }

        public static string CreateSasToken(string resource, string sasKey, int minutes)
        {
            var expiry = DateTimeOffset.UtcNow.AddMinutes(minutes).ToUnixTimeMilliseconds().ToString();
            var sig = System.Net.WebUtility.UrlEncode(Sign($"{resource}\n{expiry}", sasKey));
            return $"SharedAccessSignature sr={resource}&sig={sig}&se={expiry}";
        }

        public static (string username, string password) GenerateHubSasCredentials(string hostName, string deviceId, string sasKey, string modelId, int minutes = 60) =>
            (GetUserName(hostName, deviceId, modelId), CreateSasToken($"{hostName}/devices/{deviceId}", sasKey, minutes));
    }
}

IoTHub requires all MQTT connections to be protected with TLS 1.2, and can be configured using the MQTTNetConnectionOptionsBuilder with the extension method below:

using MQTTnet.Client.Options;
using System.Text;

namespace demistify_iothub
{
    public static class MqttNetExtensions
    {
        public static MqttClientOptionsBuilder WithAzureIoTHubCredentialsSas(this MqttClientOptionsBuilder builder, string hostName, string deviceId, string sasKey, string modelId = "", int sasMinutes = 60)
        {
            (string username, string password) = SasAuth.GenerateHubSasCredentials(hostName, deviceId, sasKey, modelId, sasMinutes);
            builder
                .WithTcpServer(hostName, 8883)
                .WithTls()
                .WithClientId(deviceId)
                .WithCredentials(username, password);
            return builder;
        }
    }
}

Once you have your IoT Hub, and your device , grab the device credentials from the portal or CLI, and replace it in the code below, and once you run it you are connected. See this instructions to create your IoT Hub and register a device.

using MQTTnet;
using MQTTnet.Client;
using MQTTnet.Client.Options;

IMqttClient mqttClient = new MqttFactory().CreateMqttClient();
var connAck = await mqttClient.ConnectAsync(new MqttClientOptionsBuilder()
    .WithAzureIoTHubCredentialsSas(
        hostName: "<your-hub>.azure-devices.net",
        deviceId : "<your-device>",
        sasKey: "MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDA="
    )
    .Build());
System.Console.WriteLine(Azs$"connAck resaon: {connAck.ResultCode} IsConnected: {mqttClient.IsConnected}");

Sending Telemetry

The first feature to explore is device telemetry, telemetry messages can be routed to other Azure services such as Storage, EventHub or EventGrid.

To send a telemetry message we just need to publish a message to a well known MQTT topic:

var pubAck = await mqttClient.PublishAsync(
        $"devices/{mqttClient.Options.ClientId}/messages/events/",
        JsonSerializer.Serialize(new { Environment.WorkingSet }) );

Console.WriteLine($"Telemetry sent with pubAck: {pubAck.ReasonCode}" );

To verify the telemetry has been received by hub use the Azure CLI:

az iot hub monitor-events -n <your-hub>

Implement Commands

Devices connected to IoT Hub can receive command invocations by following the next pattern.

Subscribe to the topic $iothub/methods/POST/#
Process incoming messages and parse the commandName requestIdentifier and commandPayload
Publish the commadn response to topic $iothub/methods/res/{response.Status}/?$rid={rid}

The following code implements this pattern

await mqttClient.SubscribeAsync("$iothub/methods/POST/#");
mqttClient.UseApplicationMessageReceivedHandler(async m =>
{
    var topic = m.ApplicationMessage.Topic;
    if (topic.StartsWith("$iothub/methods/POST/"))
    {
        var segments = topic.Split('/');
        var qs = HttpUtility.ParseQueryString(segments[^1]);
        _ = int.TryParse(qs["$rid"], out int rid);
        var cmdName = segments[3];
        var cmdPayload = Encoding.UTF8.GetString(m.ApplicationMessage.Payload);

        Console.WriteLine($"Executing command {cmdName} with rid {rid} and payload {cmdPayload}");
        await mqttClient.PublishAsync($"$iothub/methods/res/200/?$rid={rid}", cmdPayload);
    }
});

To invoke the command, and see the response from the CLI:

az iot hub invoke-device-method -n yourhub -d yourdevice --method-name myCommand --method-paylaod "Hello"

Properties (aka Device Twins)

Device Twins allows to manage the device state by using the reported and desired properties pattern.

Read DeviceTwin

To read the device twin devices can send a request by publish a message to $iothub/twin/GET/?$rid={rid} and will get the response subscribing to $iothub/twin/res/200.

The code below implements this pattern using the same mqttClient:

await mqttClient.SubscribeAsync("$iothub/twin/res/#");
mqttClient.UseApplicationMessageReceivedHandler(m => {
    var topic = m.ApplicationMessage.Topic;
    if (topic.StartsWith("$iothub/twin/res/200"))
    {
        var segments = topic.Split('/');
        var qs = HttpUtility.ParseQueryString(segments[^1]);
        _ = int.TryParse(qs["$rid"], out int rid);
        var twin = Encoding.UTF8.GetString(m.ApplicationMessage.Payload);
        Console.WriteLine(twin);
    }
});
await mqttClient.PublishAsync($"$iothub/twin/GET/?$rid=1");

Update Device Twin

Device properties can be updated from the device and the values will be stored in the reported section of the twin. To make the update devices must send a message to the topic $iothub/twin/PATCH/properties/reported/?$rid=, as a result of this request devices can subscribe to the topic $iothub/twin/res/204 to get the updated reported version. Here is the flow:

Device subscribes to $iothub/twin/res/204
Device publish a message to $iothub/twin/PATCH/properties/reported/?$rid=
Device process the incoming message and extracts the updated version from the response topic

The code below implements this flow:

await mqttClient.SubscribeAsync("$iothub/twin/res/#");
mqttClient.UseApplicationMessageReceivedHandler(m =>
{
    var topic = m.ApplicationMessage.Topic;
    if (topic.StartsWith("$iothub/twin/res/204"))
    {
        var segments = topic.Split('/');
        var qs = HttpUtility.ParseQueryString(segments[^1]);
        var twinVersion = Convert.ToInt32(qs["$version"]);
        System.Console.WriteLine(twinVersion);
    }
});
await mqttClient.PublishAsync(
    "$iothub/twin/PATCH/properties/reported/?$rid=2",
    JsonSerializer.Serialize(new { myProperty = "myValue" }));

To check the twin value with the CLI:

az iot hub device-twin show -n yourhub -d yourdevice

Handle desired property updates

Every time the desired section of the twin gets updated, IoT Hub makes the update available to connected devices who are subscribed to the topic $iothub/twin/PATCH/properties/desired/#, this flow is similar to the one implemented above for commands:

Device subscribe to $iothub/twin/PATCH/properties/desired/#
When new message is published to this topic the device reads the payload
Optionally the device reports back a reported property to indicate the property was accepted or rejected

await mqttClient.SubscribeAsync("$iothub/twin/PATCH/properties/desired/#");
mqttClient.UseApplicationMessageReceivedHandler(async m =>
{
    var topic = m.ApplicationMessage.Topic;
    if (topic.StartsWith("$iothub/twin/PATCH/properties/desired"))
    {
        string msg = Encoding.UTF8.GetString(m.ApplicationMessage.Payload);
        System.Console.WriteLine(msg);
    }
});

To trigger a device update from the CLI:

az iot hub device-twin update -n yourhub -d yourdevice --desired "{'propName':value}"

Conclusion

You can access main IoTHub features with any MQTT client by connecting with the approprate crendentials and pub/sub to the predefined topics to implement device-to-cloud and cloud-to-device patterns.

Considerations

When using SaS tokens, keep in mind that tere is a default expiry interval - in this sample is 60 minutes, after that period the client will be disconnected. You can use a timer to manually re-connect before the client gets disconnected.

In a future port I will cover how to connect with X509 Certificates that dont have any expiration limt.

The UseApplicationMessageReceivedHandler method, when called multiple times, will remove the previous handlers, in a full exmaple you must parse all incoming messages from the same handler, or... (spoiler alert) use a multicast delegate as will show in a future post.

Enjoy Azure IoT Hub without an official SDK.

The complete code for this sample can be found in this gist

DTDL Parser extensions

Rido — Sat, 09 Apr 2022 06:37:58 +0000

The DTDL dotnet parser provides and object model to inspect DTDL elements: Telemetry, Properties, Commands, Components and Relationships.

All of these are represented as DTEntityInfo elements that must be used with the appropriate DT* types using casting.

To make it easier the navigation through those types, and by using some C# goodness, I've created this DTDL parser C# extensions:

That can be used as

var model = await new ModelParser().ParseAsync(ReadFile("dtmi/samples/aninterface-1.json"));

Console.WriteLine(model.Id);

foreach (var t in model.Telemetries)
{
    Console.WriteLine($" [T] {t.Name} {t.Schema.Id}");
}

foreach (var p in model.Properties)
{
    Console.WriteLine($" [P] {p.Name} {p.Schema.Id}");
}

foreach (var c in model.Commands)
{
    Console.WriteLine($" [C] {c.Name} {c.Request.Id} {c.Response.Id}");
}