nanoFramework.Aws.IoTCore.Devices 1.1.128

Prefix Reserved
dotnet add package nanoFramework.Aws.IoTCore.Devices --version 1.1.128                
NuGet\Install-Package nanoFramework.Aws.IoTCore.Devices -Version 1.1.128                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="nanoFramework.Aws.IoTCore.Devices" Version="1.1.128" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add nanoFramework.Aws.IoTCore.Devices --version 1.1.128                
#r "nuget: nanoFramework.Aws.IoTCore.Devices, 1.1.128"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install nanoFramework.Aws.IoTCore.Devices as a Cake Addin
#addin nuget:?package=nanoFramework.Aws.IoTCore.Devices&version=1.1.128

// Install nanoFramework.Aws.IoTCore.Devices as a Cake Tool
#tool nuget:?package=nanoFramework.Aws.IoTCore.Devices&version=1.1.128                

Quality Gate Status Reliability Rating NuGet #yourfirstpr Discord

nanoFramework logo


Welcome to the .NET nanoFramework Aws.IoTCore.Devices repository

Build status

Component Build Status NuGet Package
nanoFramework.Aws.IoTCore.Devices Build Status NuGet

See it in action

TODO! Please help us to add some samples!

Usage

Important: Due to TLS, You must be connected to the internet (which means already having an IP address from your router) and a valid (minimum of today) date and time. Please check the examples that use networking (especially those that include TLS/NTP) to help you ensure it will work.

This AWS IoT SDK is using MQTT. So you need to ensure you have an outbound firewall port open to the TCP port 8883. If you are in an enterprise network, this may be blocked.

If it is, in future, we plan to add WebSocket support.

The the name of the classes and the methods try to get close to the .NET nanoFramework C# Azure IoT SDK. This should allow an easier portability of the code between both cloud provider environments.

Certificate

You have 2 options to provide the right Azure IoT TLS certificate:

  • Pass it in the constructor
  • Store it into the device

The X.509Certificates contain, for your convenience, the default root certificate used to connect to AWS IoT.

Thru the constructor

You will have to embed the certificate into your code, or add it as a resource:

const string AwsRootCA = @"-----BEGIN CERTIFICATE-----
MIIDQTCCAimgAwIBAgITBmyfz5m/jAo54vB4ikPmljZbyjANBgkqhkiG9w0BAQsF
ADA5MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6
b24gUm9vdCBDQSAxMB4XDTE1MDUyNjAwMDAwMFoXDTM4MDExNzAwMDAwMFowOTEL
MAkGA1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEZMBcGA1UEAxMQQW1hem9uIFJv
b3QgQ0EgMTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALJ4gHHKeNXj
ca9HgFB0fW7Y14h29Jlo91ghYPl0hAEvrAIthtOgQ3pOsqTQNroBvo3bSMgHFzZM
9O6II8c+6zf1tRn4SWiw3te5djgdYZ6k/oI2peVKVuRF4fn9tBb6dNqcmzU5L/qw
IFAGbHrQgLKm+a/sRxmPUDgH3KKHOVj4utWp+UhnMJbulHheb4mjUcAwhmahRWa6
VOujw5H5SNz/0egwLX0tdHA114gk957EWW67c4cX8jJGKLhD+rcdqsq08p8kDi1L
93FcXmn/6pUCyziKrlA4b9v7LWIbxcceVOF34GfID5yHI9Y/QCB/IIDEgEw+OyQm
jgSubJrIqg0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMC
AYYwHQYDVR0OBBYEFIQYzIU07LwMlJQuCFmcx7IQTgoIMA0GCSqGSIb3DQEBCwUA
A4IBAQCY8jdaQZChGsV2USggNiMOruYou6r4lK5IpDB/G/wkjUu0yKGX9rbxenDI
U5PMCCjjmCXPI6T53iHTfIUJrU6adTrCC2qJeHZERxhlbI1Bjjt/msv0tadQ1wUs
N+gDS63pYaACbvXy8MWy7Vu33PqUXHeeE6V/Uq2V8viTO96LXFvKWlJbYK8U90vv
o/ufQJVtMVT8QtPHRh8jrdkPSHCa2XV4cdFyQzR1bldZwgJcJmApzyMZFo6IQ6XU
5MsI+yMRQ+hDKXJioaldXgjUkK642M4UwtBV8ob2xJNDd2ZhwLnoQdeXeGADbkpy
rqXRfboQnoZsG4q5WTP468SQvvG5
-----END CERTIFICATE-----
";
MqttConnectionClient awsIoT = new MqttConnectionClient(IotBrokerAddress, ThingId, clientCert, MqttConnectionClient.QoSLevel.AtLeastOnce, awsRootCACert: new X509Certificate(AzureRootCA));

You can place your binary certificate in the resources as well and just get the certificate from it:

X509Certificate awsRootCACert = new X509Certificate(Resources.GetBytes(Resources.BinaryResources.AwsCAcertificate));
MqttConnectionClient awsIoT = new MqttConnectionClient(IotBrokerAddress, ThingId, clientCert, MqttConnectionClient.QoSLevel.AtLeastOnce, awsRootCACert);

Note: when the certificate expires, you will have to fully reflash the device with the new certificates and keys, or build a mechanism into your code to include primary and secondary versions of them.

Storing the certificate into the device

You can store the certificate in the device flash and not in the code, so if you have to change the certificate, you'll just have to clean the current store and upload the new one. Edit the network properties:

edit device network

Navigate to the General tab:

device network certificate

Browse to choose your certificate, it can be in a binary (crt, der) or string form (pem, txt) and select ok. The certificate to connect will be selected automatically during the connection.

Creating an MqttConnectionClient

You can connect to AWS IoT Core using a certificate containing the private certificate and key, or IAM (not currently supported). The following example shows how to create it:

const string ThingId = "nanoDeviceShadow";
const string IotBrokerAddress = "<account>-ats.iot.<region>.amazonaws.com";
//make sure to add a correct pfx certificate
X509Certificate2 clientCert = new X509Certificate2(ClientRsaSha256Crt, ClientRsaKey, "");
MqttConnectionClient awseIoT = new MqttConnectionClient(IotBrokerAddress, ThingId, clientCert, MqttConnectionClient.QoSLevel.AtLeastOnce, awsRootCACert);

Note: please see the previous section to understand how to better pass the certificate for your usage. The example shows the certificate uploaded into the device and not in the code.

Getting and updating Device Shadow

You can request your Shadow simply by calling the GetShadow function.

var shadow = awsIoT.GetShadow(new CancellationTokenSource(20000).Token);
if (shadow == null)
{
    Debug.WriteLine($"Can't get the shadow");
    awsIoT.Close();
    return;
}

Debug.WriteLine($"Shadow ClientToken: {shadow.DeviceId}, #desired: {shadow.status.desired}, #reported: {shadow.status.reported}");

Note: it's important to use a CancellationToken that be cancelled after a certain amount of time. Otherwise, this will be blocking the thread up to the point the shadow will be received.

Shadows have status properties, reported and desired. They are a hashtable and you can get or try to get any element.

You can report your Shadow as simple as this:

TODO: does not work yet!!!

ShadowCollection reported = new ShadowCollection();
reported.Add("firmware", "myNano");
reported.Add("sdk", 0.2);
awsIoT.UpdateReportedProperties(reported);

You also have the option to wait for the shadow update confirmation, in this case use a CancellationToken that can be cancelled. Otherwise the check will be ignored.

Note: the function will return false if the shadow reception confirmation is not checked or if it did not arrive on time.

You can also register for any shadow update:

awsIoT.ShadowUpated += ShadowUpdatedEvent;

void ShadowUpdatedEvent(object sender, ShadowUpdateEventArgs e)
{
    Debug.WriteLine($"Shadow update received:  {e.Shadow}");
}

Sending message

You have to use the SendMessage function to send any kind of message or telemetry to AWS IoT. As with the other function, you have the possibility to ensure delivery using a CancellationToken than can be cancelled. If one that can't be cancelled is used, the delivery insurance will be ignored and the function will return false.

var isReceived = awsIoT.SendMessage($"{{\"Temperature\":42,\"Pressure\":1024}}", new CancellationTokenSource(5000).Token);
Debug.WriteLine($"Message received by IoT Core: {isReceived}");

Note: The message will be send with the same quality of service you created the connection with. You won't get any answer for the quality 0. In this case, you can simplify it to:

awsIoT.SendMessage($"{{\"Temperature\":42,\"Pressure\":1024}}");

Cloud to device messages

You can register an event to receive Cloud to device messages:

TODO: check works!!!

awsIoT.CloudToDeviceMessage += CloudToDeviceMessageEvent;

// The following example shows how to display all keys in debug
void CloudToDeviceMessageEvent(object sender, CloudToDeviceMessageEventArgs e)
{
    Debug.WriteLine($"Message arrived: {e.Message}");
    foreach (string key in e.Properties.Keys)
    {
        Debug.Write($"  Key: {key} = ");
        if (e.Properties[key] == null)
        {
            Debug.WriteLine("null");
        }
        else
        {
            Debug.WriteLine((string)e.Properties[key]);
        }
    }

    // e.Message contains the message itself
    if(e.Message == "stop")
    {
        ShoudIStop = true;
    }
}

Note: the sender is a MqttConnectionClient class, you can then send a message back with a confirmation or any logic you've put in place.

Status update event

A status update event is available:

awsIoT.StatusUpdated += StatusUpdatedEvent;

void StatusUpdatedEvent(object sender, StatusUpdatedEventArgs e)
{
    Debug.WriteLine($"Status changed: {e.Status.State}, {e.Status.State}");
    // You may want to reconnect or use a similar retry mechanism
    ////if (e.Status.State == Status.Disconnected)
    ////{
    ////    mqtt.Open();
    ////}
}

Note that they are status change based, so once the connect or disconnect event arrives, they'll be replaced by other events as soon as something else happened like receiving a shadow.

Future work items for discussion

  • Better documentation about ensuring "persistent" connections (or not) with documentation (including cloud policy doc for support)
  • Add some integration tests, including (scripts to auto provision cloud broker (and/or)) manual setup documents to ensure ease of use.-
  • Partial Greengrass support?!
  • Websocket support?!
  • fleet provisioning support?!

Feedback and documentation

For documentation, providing feedback, issues and finding out how to contribute please refer to the Home repo.

Join our Discord community here.

Credits

The list of contributors to this project can be found at CONTRIBUTORS.

License

The .NET nanoFramework Class Libraries are licensed under the MIT license.

Code of Conduct

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behaviour in our community. For more information see the .NET Foundation Code of Conduct.

.NET Foundation

This project is supported by the .NET Foundation.

Product Compatible and additional computed target framework versions.
.NET Framework net is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.1.128 65 12/23/2024
1.1.124 92 11/4/2024
1.1.121 96 10/11/2024
1.1.120 98 10/3/2024
1.1.119 91 9/26/2024
1.1.116 91 9/9/2024
1.1.113 94 7/30/2024
1.1.110 148 5/20/2024
1.1.108 98 5/13/2024
1.1.106 103 5/10/2024
1.1.104 131 4/30/2024
1.1.102 148 4/9/2024
1.1.100 146 4/3/2024
1.1.97 169 1/29/2024
1.1.95 110 1/26/2024
1.1.93 121 1/24/2024
1.1.91 119 1/23/2024
1.1.87 244 11/10/2023
1.1.85 135 11/8/2023
1.1.83 159 10/10/2023
1.1.81 172 8/28/2023
1.1.79 155 8/28/2023
1.1.77 153 8/28/2023
1.1.74 184 5/29/2023
1.1.65 312 1/14/2023
1.1.62 307 12/28/2022
1.1.60 329 12/27/2022
1.1.53 442 11/24/2022
1.1.48 337 11/15/2022
1.1.46 358 11/4/2022
1.1.43 361 10/28/2022
1.1.41 412 10/28/2022
1.1.39 405 10/27/2022
1.1.37 373 10/26/2022
1.1.34 388 10/16/2022
1.1.29 401 10/4/2022
1.1.27 409 9/30/2022
1.1.25 469 9/23/2022
1.1.23 427 9/20/2022
1.1.21 434 9/16/2022
1.1.18 416 9/9/2022
1.1.14 454 8/5/2022
1.1.12 433 7/26/2022
1.1.10 438 7/19/2022
1.1.8 448 6/14/2022
1.1.6 456 6/14/2022
1.1.4 457 6/10/2022
1.1.1 445 5/30/2022
1.0.0 474 3/29/2022
1.0.0-preview.132 125 3/29/2022
1.0.0-preview.130 127 3/28/2022
1.0.0-preview.128 126 3/28/2022
1.0.0-preview.126 123 3/28/2022
1.0.0-preview.124 120 3/28/2022
1.0.0-preview.120 132 3/17/2022
1.0.0-preview.117 128 3/17/2022
1.0.0-preview.115 128 3/15/2022
1.0.0-preview.113 125 3/15/2022
1.0.0-preview.111 127 3/15/2022
1.0.0-preview.109 124 3/15/2022
1.0.0-preview.108 120 3/15/2022
1.0.0-preview.107 116 3/11/2022
1.0.0-preview.106 132 3/4/2022
1.0.0-preview.105 116 3/1/2022
1.0.0-preview.102 126 2/17/2022
1.0.0-preview.101 116 2/15/2022
1.0.0-preview.100 124 2/8/2022
1.0.0-preview.99 127 2/8/2022
1.0.0-preview.98 138 2/4/2022
1.0.0-preview.97 134 2/4/2022
1.0.0-preview.96 134 2/4/2022
1.0.0-preview.95 141 2/1/2022
1.0.0-preview.94 139 1/28/2022
1.0.0-preview.93 140 1/28/2022
1.0.0-preview.92 130 1/28/2022
1.0.0-preview.91 135 1/28/2022
1.0.0-preview.90 133 1/28/2022
1.0.0-preview.89 141 1/28/2022
1.0.0-preview.88 130 1/25/2022
1.0.0-preview.87 129 1/21/2022
1.0.0-preview.86 137 1/21/2022
1.0.0-preview.85 134 1/21/2022
1.0.0-preview.84 136 1/21/2022
1.0.0-preview.83 137 1/21/2022
1.0.0-preview.82 127 1/21/2022
1.0.0-preview.80 136 1/14/2022
1.0.0-preview.79 138 1/14/2022
1.0.0-preview.76 140 1/6/2022
1.0.0-preview.74 133 1/5/2022
1.0.0-preview.72 137 1/5/2022
1.0.0-preview.71 139 1/4/2022
1.0.0-preview.70 140 1/4/2022
1.0.0-preview.69 139 12/31/2021
1.0.0-preview.68 134 12/31/2021
1.0.0-preview.67 129 12/31/2021
1.0.0-preview.66 140 12/29/2021
1.0.0-preview.65 138 12/29/2021
1.0.0-preview.63 144 12/17/2021
1.0.0-preview.61 153 12/4/2021
1.0.0-preview.59 151 12/4/2021
1.0.0-preview.57 156 12/3/2021
1.0.0-preview.55 159 12/3/2021
1.0.0-preview.53 149 12/3/2021
1.0.0-preview.51 145 12/3/2021
1.0.0-preview.49 145 12/2/2021
1.0.0-preview.47 142 12/2/2021
1.0.0-preview.45 140 12/2/2021
1.0.0-preview.43 144 12/2/2021
1.0.0-preview.41 156 12/1/2021
1.0.0-preview.38 149 11/23/2021
1.0.0-preview.36 143 11/14/2021
1.0.0-preview.34 249 11/13/2021
1.0.0-preview.32 186 11/12/2021
1.0.0-preview.30 167 11/12/2021
1.0.0-preview.28 155 11/10/2021
1.0.0-preview.25 191 10/22/2021
1.0.0-preview.23 146 10/19/2021
1.0.0-preview.20 192 10/18/2021
1.0.0-preview.18 192 10/15/2021
1.0.0-preview.16 200 10/15/2021
1.0.0-preview.14 205 10/15/2021
1.0.0-preview.12 212 10/15/2021
1.0.0-preview.10 213 10/15/2021
1.0.0-preview.8 221 10/15/2021
1.0.0-preview.6 220 10/15/2021
1.0.0-preview.5 236 10/15/2021