Connect an ESP32 To Azure IoT with .NET nanoFramework

This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Tech Community.

You don’t need a big device to connect to Azure IoT Hub

When you are looking for IoT devices to connect to Azure IoT Hub most are minicomputers or devkits that are cheap but limited in what they can do or just very power hungry. But what about using a Microprocessor I hear you say, well these are great, but you are then normally limited to programming in C which we all know isn’t great.

 

The Azure SDK for Embedded C is designed to allow small embedded (IoT) devices to communicate with Azure services and can be found here but again it’s C you are forced to use, and it’s targeted at larger device as mentioned before due to the memory required.

 

So what options do we have for us .NET developers that is smaller than a Raspberry Pi and allows us to use C#. Well, we have the awesome Wilderness Labs F7 but what about even lower powered off the shelf from Amazon devices like the ESP32-CAM-MBthat are just £10/$13 each or even cheaper if you shop around.

 

This blog post is hopefully going to show you how to take one of these super cheap and easy to purchase devices and with your .NET skills connect to Azure IoT Hub all using C#. For this magic to happen I will be using the .NET nanoFramework which makes it easy to write C# code for a select number of IoT Devices.

 

Let’s dive in…

 

Device being used

The device I am using is an ESP32-CAM and you can get them online just search your favourite online store for ESP32-CAM-MB boards.

 

2021-07-24-22-29-38.png

Connecting the device

When you first connect the device to your PC/Laptop you will hear the Windows Bing-bong but looking in the Device Manager you will notice that it appears listed under the Other Devices section.

 

2021-07-24-22-34-04.png

 

To use the ESP32-CAM-MB you need the CH340 Drivers otherwise it will not connect as a USB device. You can get installation software for the drivers from Sparkfun as this is the quickest and easiest way to install them.

 

After you have the driver installed the device then appears as an Com device in the Device Manager:

 

2021-07-24-22-36-36.png

 

Set-up Visual Studio

First I need to point out that you can use ANY version of Visual Studio to follow along, from the FREE Community Edition all the way up to the Enterprise version. You can grab the FREE Community edition Here

 

We now need to install the Nano Framework VS2019 extention this is a simple installation from either the MarketPlace or using the Extention Manager in VS19 and searching for nanoFrameWork

 

2021-08-10-17-24-15.png

 

Configure the ESP32 Board

Now that the VS19 Extention is installed you need to flash the .NET nanoFramework Firmware onto the ESP32 board as this will include the required nanoFramework Firmware and Bootloaders etc so that you can connect the board to the PC with Visual Studio and target the board for development.

 

The tool need is Open Source here on Github from the nanoFramework team if you want to read up on it.

 

From here you can see that you need to install the CLI tools which is really easy using the dotnet CLI so within your Terminal program like WindowsTerminal run this command.

 

 

dotnet tool install -g nanoff

 

 

Now that nanoff is installed you can connect your board and find it’s Com Port in your Device Manager, right click the windows logo and select Device Manager I find is the quickest way, under the Ports (Com & LPT) you will see your device if you have multiple then unplug and see which one disappears is a good way to work out which port you need. Make a note of the COM number so for me it’s COM6.

 

2021-07-24-22-36-36.png

 

Now you have the Com port you can flash the firmware so back to the Terminal program and run this command, changing the digit after the COM to match your device COM Port

 

 

nanoff --target ESP32_WROOM_32 --serialport COM6 --update --preview

 

 

You should see it whirl away for a minute or two as it erases the flash and then burns the new firmware.

 

2021-07-24-22-44-46.png

 

Create the Project

We are now ready to create our project, so within Visual Studio create a new project on opening and in the search box enter nano and you will see that you can create a Blank Application, give it a name and save location as you normally do in Visual Studio.

 

2021-07-15-14-38-29.png

 

When you have the default blank app showing you now need to install some NuGet packages so that you can use the GPIO of the device and these can be found by typing nanoFramework.Windows.Devices.Gpio into the search box, you may also need to select the ‘Include Pre-release’ box as I did at the time of writing.

 

 

GPIO = General Purpose Input Output

 

 

2021-07-24-22-47-57.png

 

We will also need the following NuGets so may as well install them now but be warned these are currently Preview packages so be sure to tick the ‘Include Pre-release` check box:

 

 

AMQPNetLite.nanoFramework nanoFramework.NetWorkHelper

 

 

Write some code.

I have based this project on the AMQP examples on the nanoFramework Github page but as I don’t like just reporting Temperature and prefer reporting something a little more fun and useful here is my version. I am generating a Latitude and Longitude based off a random bearing and distance from the last waypoint to simulate tracking a device in the real world. This code you can cut and paste into Visual Studio and have a read over but there are a few more steps we need to complete before we can upload the code to the device.

 

 

using Amqp; using nanoFramework.Networking; using System; using System.Diagnostics; using System.Text; using System.Threading; using AmqpTrace = Amqp.Trace; namespace ConnectESP32ToIoTHub { public class Program { // Set-up Wifi Credentials so we can connect to the web. private static string Ssid = "CAS-Wifi"; private static string WifiPassword = "JacobAgius0406!"; // Azure IoTHub settings const string _hubName = "CAS-Learning-IoTHub"; const string _deviceId = "nanoFramework-Device1"; const string _sasToken = "SharedAccessSignature sr=CAS-Learning-IoTHub.azure-devices.net%2Fdevices%2FnanoFramework-Device1&sig=0eGgNE7BqjzWKfeffojGJYaTEQgFV72bTytkUCkU8qQ%3D&se=1631051254"; // Lat/Lon Points static double Latitude; static double Longitude; const double radius = 6378; // Radius of earth in Kilometers at the equator, yes it's a big planet. Fun Fact it's 6356Km pole to pole so the planet is an oblate spheroid or a squashed ball. private static Random _random = new Random(); static bool TraceOn = false; public static void Main() { // Set-up first Point and I have chossen to use the great Royal Observatory, Greenwich, UK where East meets West. Latitude = 51.476852; Longitude = 0.0; Debug.WriteLine("Waiting for network up and IP address..."); bool success = false; CancellationTokenSource cs = new(60000); success = NetworkHelper.ConnectWifiDhcp(Ssid, WifiPassword, setDateTime: true, token: cs.Token); if (!success) { Debug.WriteLine($"Can't get a proper IP address and DateTime, error: {NetworkHelper.ConnectionError.Error}."); if (NetworkHelper.ConnectionError.Exception != null) { Debug.WriteLine($"Exception: {NetworkHelper.ConnectionError.Exception}"); } return; } else { Debug.WriteLine($"YAY! Connected to Wifi - {Ssid}"); } // setup AMQP // set trace level AmqpTrace.TraceLevel = TraceLevel.Frame | TraceLevel.Information; // enable trace AmqpTrace.TraceListener = WriteTrace; Connection.DisableServerCertValidation = false; // launch worker thread new Thread(WorkerThread).Start(); Thread.Sleep(Timeout.Infinite); } private static void WorkerThread() { try { // parse Azure IoT Hub Map settings to AMQP protocol settings string hostName = _hubName + ".azure-devices.net"; string userName = _deviceId + "@sas." + _hubName; string senderAddress = "devices/" + _deviceId + "/messages/events"; string receiverAddress = "devices/" + _deviceId + "/messages/deviceBound"; Connection connection = new Connection(new Address(hostName, 5671, userName, _sasToken)); Session session = new Session(connection); SenderLink sender = new SenderLink(session, "send-link", senderAddress); ReceiverLink receiver = new ReceiverLink(session, "receive-link", receiverAddress); receiver.Start(100, OnMessage); while (true) { string messagePayload = $"{{\"Latitude\":{Latitude},\"Longitude\":{Longitude}}}"; // compose message Message message = new Message(Encoding.UTF8.GetBytes(messagePayload)); message.ApplicationProperties = new Amqp.Framing.ApplicationProperties(); // send message with the new Lat/Lon sender.Send(message, null, null); // data sent Debug.WriteLine($"*** DATA SENT - Lat - {Latitude}, Lon - {Longitude} ***"); // update the location data GetNewDestination(); // wait before sending the next position update Thread.Sleep(5000); } } catch (Exception ex) { Debug.WriteLine($"-- D2C Error - {ex.Message} --"); } } private static void OnMessage(IReceiverLink receiver, Message message) { try { // command received Double.TryParse((string)message.ApplicationProperties["setlat"], out Latitude); Double.TryParse((string)message.ApplicationProperties["setlon"], out Longitude); Debug.WriteLine($"== Received new Location setting: Lat - {Latitude}, Lon - {Longitude} =="); } catch (Exception ex) { Debug.WriteLine($"-- C2D Error - {ex.Message} --"); } } static void WriteTrace(TraceLevel level, string format, params object[] args) { if (TraceOn) { Debug.WriteLine(Fx.Format(format, args)); } } // Starting at the last Lat/Lon move along the bearing and for the distance to reset the Lat/Lon at a new point... public static void GetNewDestination() { // Get a random Bearing and Distance... double distance = _random.Next(10); // Random distance from 0 to 10km... double bearing = _random.Next(360); // Random bearing from 0 to 360 degrees... double lat1 = Latitude * (Math.PI / 180); double lon1 = Longitude * (Math.PI / 180); double brng = bearing * (Math.PI / 180); double lat2 = Math.Asin(Math.Sin(lat1) * Math.Cos(distance / radius) + Math.Cos(lat1) * Math.Sin(distance / radius) * Math.Cos(brng)); double lon2 = lon1 + Math.Atan2(Math.Sin(brng) * Math.Sin(distance / radius) * Math.Cos(lat1), Math.Cos(distance / radius) - Math.Sin(lat1) * Math.Sin(lat2)); Latitude = lat2 * (180 / Math.PI); Longitude = lon2 * (180 / Math.PI); } } }

 

 

Fill in the Blanks.

As you can see at the top of the Class there are some placeholders where you need to fill in with some data, the easy ones are the Wifi credentials these you hopefully should know for your local network and they will allow the ESP32 module to connect to the internet so that it can communicate with the Azure IoT Hub.

 

Next we have some Azure IoT Hub settings that are needed and this is so that the ESP32 knows which Hub and device it is as well as the connection string or SAS Token it should use to find the IoT Hub. So where do we get these from? The Azure IoT Hub name and DeviceID we can get from the Azure IoT Hub on the Azure portal so lets head out to out Azure IoT Hub and add a device, if you want more detail on creating your first Azure IoT Hub and adding a device there is no better place than Docs.Microsoft.com

 

When in theAzure Portaland you have found or created your IoT Hub on the left menu under the Explorer tab click IoT Devices and then the + Add Device.

 

2021-08-17-10-53-07.png

 

On the new pane enter a meaningful name for your device and ensure that Symmetric Keys is selected and when your happy click the Save button at the bottom of the page.

 

2021-08-17-10-57-53.png

 

This means we now have the _hubname which is the name of your IoT Hub and will be at the top of the page as you can see in the first image in this section so for me it’s CAS-Learning-IoTHub.

 

Enter that into the placeholder in the code, next is the device name you just created so you know this already and can enter that for the placeholder of _deviceId but what about that _sasToken that one is a little more tricky.

Creating the SAS Token.

You can read all about SAS Tokens on the Docs website here but how do we go about creating the Token for our device.

 

There are a few ways, as the docs suggest we can use the CLI extension command az iot hub generate-sas-token, or the Azure IoT Tools for Visual Studio Code

Lets try the CLI

In the Azure portal in the top right where your account details are shown you can click to open the Azure CLI:

 

2021-08-17-14-37-17.png

This will open the Azure CLI at the bottom of the browser window and you can do the normal resize things and drag to increase the size or use the icons on the top right of that window.

 

2021-08-17-14-39-20.png

 

Now we can use the az iot hub CLI commands to request a SAS Token for our device and this will look something like this:

 

 

az iot hub generate-sas-token --hub-name CAS-Learning-IoTHub --device-id nanoFramework-Device1 --login 'HostName=CAS-Learning-IoTHub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=<SECRET KEY>'

 

 

As you can see you need to use the Hub Name and the Device ID which you already have from the previous steps but what about that login part? Well this we get from the Azure IoT Hub menu in the portal and click the ‘Shared Access Policies’ then under the list of policies click iothubowner and finally copy the ‘Primary Connection String’ and it’s this you need to use as the login in the CLI, just beware that you have to surround the string in the CLI with SINGLE quote marks for it to be accepted and used.

 

2021-08-17-14-56-16.png

2021-08-17-14-51-17.png

 

Now we have the connection string we can copy this into out place holder in our code, obviously I have blurred the parts that are my keys but you hopefully get the idea here.

What about VSCode

If you have not discovered already there is a fantastic Azure IoT extention for VSCode and it’s this that will be used here.

 

Install the extention and follow the set-up instructions on the marketplace so that you can connect to your Azure Account, personally I use the 2nd option to sign in to my account when doing this on a new machine as it’s easier.

 

Setup Azure IoT Hub through Sign in to Azure

 

Now your connected in your explorer you will see you ‘AZURE IoT HUB’ tab which for me is at the bottom, open this and select your IoT Hub and then Devices.

2021-08-17-15-05-39.png

 

Now right clicking on the device will show a context menu where you can just click the ‘Generate SAS token’

 

2021-08-17-15-07-15.png

 

The VSCode Command Palette will then show asking for the number of HOURS that you wish the token to live for so enter a number.

 

Just beware that this is in hours and not seconds like the CLI so it makes the maths in your head a little easier...

 

2021-08-17-15-08-14.png

 

Once you enter this you will notice in the VSCode output window at the bottom your new SASToken will be displayed (CTRL+ALT+O if the window not displayed).

 

2021-08-17-15-11-58.png

 

Again take this and place it into the placeholder in the code.

Root Certificate

This one got me at first as it’s a very easy thing to miss so I hope me putting it here helps you or even future ME! get this right.

 

We need to ensure that the device is connecting to the web and thus IoT Hub with the correct certificate, but they are currently in the process of switching them over from the Baltimore CyberTrust to DigiCert Global G2 now rather than me try to explain this here is a blog post all about it

 

So at the time of writing this post Azure IoT will only use the Baltimore CyberTrust so lets use that, the process is the same for both anyway. First we need to download the Certificate and there is a page in the Docs that has the links.

 

2021-08-17-15-32-28.png

 

Once downloaded we need to upload this file to the ESP32 module and this is where the awesome nanoFramework team have us covered. Connect your device to your PC/Laptop again and in Visual Studio open the nanoFramework Device Explorer

 

2021-08-17-15-41-46.png

 

In here we should see our device showing up, if not click the magnifying glass to scan and be sure that the cable you are using is a data cable and not a charging only cable (I throw charging only out now I have wasted too many hours of my life being caught by them…). Once your device is shown click the ‘Edit Network Configuration’ icon as shown boxed in the screen grab.

 

2021-08-17-15-45-41.png

 

This opens a dialog box and clicking the last tab ‘General’ we can see the ‘Root CA’ where we can browse for the Cert we downloaded and have it uploaded to the ESP32 device.

 

Note:

There is no feedback sadly that the certificate is selected to be uploaded so you will have to trust in yourself that you did it right, or like me do it twice to be sure.

 

2021-08-17-15-49-24.png

 

Upload our code

Now we have all the placeholders filled in and the Root cert prepared we are ready to upload and test, now as a .NET developer what is your muscle memory for running code…. Yep click F5… How awesome is that.

 

The first time you do this it takes a minute or two but subsequent builds are much faster.

 

Don’t forget you have the full power of the Visual Studio debugger so feel free to add a breakpoint or two and step through the code to watch the magic.

 

We now have the code running on out little ESP device and we can step through and check the variables etc but how can we see the data arriving at the IoT Hub? Well that can be done very easily again using either the VSCode extention or the Azure CLi.

Monitor using the CLI

Using the same method as shown above open the Azure CLI and use the Azure CLI Command

 

 

az iot hub monitor-events --output table --hub-name {YourIoTHubName} --login 'HostName=CAS-Learning-IoTHub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=<SECRET KEY>'

 

 

You will then see the data arriving and displayed inside the CLI, the cool advantage of using the CLI commands is that once you get used to them you can use the Mobile App on your Android/IoS device which is a Xamarin App by the way to query your Azure IoT Hub and devices.

 

2021-09-07-18-06-20.png

 

Monitor using VSCode

This is by far the easier way and you right click on the device like you did to generate the SAS Token but now you select the Start Monitoring Built-In Event Endpoint from the context menu.

 

2021-09-07-17-40-02.png

 

You should now see in the Output Window at the bottom the data will start to arrive.

 

2021-09-07-17-41-42.png

 

Consuming Messages

If like me you have an S1 Standard tier IoT Hub then you have a daily limit of 400,000 message which sounds a lot but now lets think about the number of messages this actually gives. Our Device is sending a message every 5 seconds so given the 24 hrs in the day that’s:

 

24 * 60 * 60 = 86,400 seconds per day

Divide by 5 gives - 17,280 messages per day.

But with a limit of 400,000 per day that is only 23 devices before they are all used up?

 

Therefore it’s always a good idea when planning your system to think about the number of devices and also the number of messages each will send. Do you really need an update every 5 seconds for example or will every 30 seconds do? That would change this from 23 devices to 138 devices as an example.

 

Of course if you do need more you can step up to S2 giving 6 million or and S3 giving 300 million but it’s a higher cost.

 

The other alternative is to add more S1 units and get multiples of the 400,000. It’s always worth doing the maths and picking the correct tier rather than having your boss ask why the Azure bill just jumped, you can looking at the pricing more Here

 

You can check you message usage on the Overview page of the IoT Hub and look at the usage graphs as well.

 

2021-09-07-17-56-05.png

 

Conclusion

So that’s it’s congratulations you now have a cheap £10/$13 ESP32 IoT device connecting over WiFi to Azure IoT Hub and sending messages, all using C# and .NET and I hope you agree it opens the IoT space to .NET developers which is awesome.

 

Connect a sensor or two to the Board and there are millions of sensors to choose from out there even some Temp and Humidity sensors if you really have to, and you have an IoT Solution for your business or your Home Automation and much cheaper and easier than other methods.

 

Those of you that didn’t just Cut&Paste the code from above like you do over at Stack Overflow will have noticed I added an OnMessage() method and this I will use in the next post I write where I will show that you can also use nanoFramework and IoT Hub to send Cloud-2-Device messages. These are messages that are sent from the Azure Cloud down to the device to change setting or configure a value, in this case I will be editing the Lat/Lon among other things as well as plotting the points on a Bing Map using PowerBI and Stream Analytics if you can’t wait you can take a quick peak at the Microsoft Docs for that part.

 

It just leaves me to say thanks to the amazing team behind nanoFramework and also to the .NET Foundation for supporting and helping the project grow.

 

Lastly if you have any projects that need support and help from a Freelance .NET IoT and Mobile developer or just want to chat, geek out or comment on this blog post you can find me over at Twitter @CliffordAgius DM’s are open.

 

Happy Coding!

Leave a Reply

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.