Rido.IoTHubClient 0.0.1

Rido.IoTHubClient

Minimalistic device client to interact with Azure IoT Hub based on MQTTNet

Features

• Device Auth for Devices and Modules, X509 + SaS with refresh tokens
• V1 support in master (V2 available in the preview branch, enabling Pub/Sub to MQTT Broker)
• DPS Client
• Telemetry, Properties and Commands using reserved topics for v1 and v2
• Extended Connection String support

Connect to IoTHub

Connect With SaS

var client = await HubMqttClient.CreateAsync(hostname, device, sasKey);

Connect with X509

var client = await HubMqttClient.CreateWithClientCertsAsync(hostname, certificate);

Note: See connection settings reference

MQTT Extensions

You can also connect with the MQTTNet client by using the extension methods:

var connack = await mqttClient.ConnectWithSasAsync(hostname, deviceId, sasKey);
var connack = await mqttClient.ConnectWithX509Async(hostname, certificate);

DPS Support

var dpsRes = await DpsClient.ProvisionWithSasAsync("<IdScope>", "<deviceId>", "<deviceKey>");
Console.WriteLine(dpsRes.registrationState.assignedHub));

var dpsRes = await DpsClient.ProvisionWithCertAsync("<IdScope>", "<pathTo.pfx>", "<pfx Pwd>");
Console.WriteLine(dpsRes.registrationState.assignedHub));

Reserved Topics Usage

Send Telemetry

await client.SendTelemetryAsync(new { temperature = 1 });

Read Twin

var twin = await client.GetTwinAsync();

Update Twin (Reported Properties)

var version = await client.UpdateTwinAsync(new { tool = "from Rido.IoTHubClient" }); 
Console.WriteLine("Twin PATCHED version: " + version));

Respond to Twin updates (Desired Properties)

client.OnPropertyReceived += async (s, e) => 
{
    Console.WriteLine($"Processing Desired Property {e.PropertyMessageJson}");
    await Task.Delay(500);
    var puback = await client.UpdateTwinAsync(new { tool = new { ac = 200, av = e.Version, ad = "updated", value = "put value here" } });
};

Respond to Commands

client.OnCommandReceived += async (s, e) =>
{
    Console.WriteLine($"Processing Command {e.CommandName}");
    await Task.Delay(500);
    await client.CommandResponseAsync(e.Rid, e.CommandName, new { myResponse = "ok" }, "200");
};

Connection Settings Reference

This library implements a compatible connection string with Azure IoT SDK Device Client, and adds some new properties:

• HostName Azure IoT Hub hostname (FQDN)
• DeviceId Device Identity
• SharedAccessKey Device Shared Access Key in Base64
• ModelId DTDL Model ID in DTMI format to create PnP Devices
• ModuleId Device Module Identity
• Auth Device Authentication: [SAS, X509]
• SasMinutes SasToken expire time in minutes

Sample Connection String

$"HostName=test.azure-devices.net;DeviceId=myDevive;ModuleId=myModule;SharedAccessKey=<moduleSasKey>;ModelId={modelId}";SasMinutes=120

Tracing

This library uses System.Diagnostics.Tracing

Trace.Listeners[0].Filter = new EventTypeFilter(SourceLevels.Information);
Trace.Listeners.Add(new TextWriterTraceListener(Console.Out));
Trace.Listeners[1].Filter = new EventTypeFilter(SourceLevels.Warning);

Custom Topics Usage

Custom topics require IoTHub V2, available in the preview branch

When connected to a MQTTBroker enabled hub, this library allows to pub/sub to topics defined in the hub topic-space.

Using MQTTNet directly

var connack = await mqttClient.ConnectV2WithSasAsync(hostname, deviceId, sasKey);

With the Client implementing v2 reserved topics

var cs = Environment.GetEnvironmentVariable("cs");
var client = await HubBrokerMqttClient.CreateFromConnectionStringAsync(cs);

client.OnMessageReceived += (s, e) =>
{
    string payload = (e.ApplicationMessage.Topic);
};

await client.SubscribeAsync("vehicles/#");
await client.PublishAsync($"vehicles/{client.ClientId}/GPS/pos",
                            new { lat = 23.32323, lon = 54.45454 });

To create topic spaces, use

az iot hub topic-space create -n {iothub_name} --tsn publisher_ts --tst PublishOnly --template 'vehicles/${principal.deviceid}/GPS/#'
az iot hub topic-space create -n {iothub_name} --tsn subscriber_ts --tst LowFanout --template 'vehicles/#'