If you are reading this article, you already know that there is no native support for UDP Protocol when using Azure IoT Hub. In this article I will explain you how to get your custom UDP endpoint.

UPDATE 26/Jul/2018: I updated the GitHub repository for IoT Edge GA: https://github.com/danigian/iot-edge-udp You should analyze the repo for a more updated example than the one explained in this post

UPDATE 02/Jan/2018: I open sourced a sample module on a GitHub repository: https://github.com/danigian/iot-edge-udp

As a matter of fact, you can read the official documentation that Azure IoT Hub allows devices to use the following protocols (each of them based on TCP) for device-side communications:

  • MQTT (and MQTT over WebSockets)
  • AMQP (and AMQP over WebSockets)
  • HTTPS

Unfortunately, that’s a pity because UDP is fast, lightweight and perfect for low power radio technologies (an example of LPWAN could be NarrowBand IoT)

How to solve

Azure IoT Edge is an Internet of Things service that builds on top of IoT Hub. This service is mainly meant for customers who want to analyze data “at the edge” instead of in the cloud.

Luckily, it is possible also to use Azure IoT Edge as a Gateway. The purpose of gateways in IoT solutions is usually to merge device connectivity with “at the edge” analytics.

Before continuing, if you are new to IoT Edge, I would suggest you take a look at this quickstart, in order to get familiar with the basics of the service.

Now you are ready to start.

Let’s assume that you have sensors and devices that are willing to communicate with the gateway over the 1208/UDP port.

The first step is to develop an IoT Edge Module (from now on “UDPModule”) which will be able to listen over that port.

In order to write the datagram content to the “output1” output of our IoT Edge module, so that it is possible to route that content to other modules, just develop a method, in the “UDPModule”, structured like the following one:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

static public void udpListen(){
	//Assuming to be listening on the 1208/udp port
	UdpClient _udpClient = new UdpClient(1208);
	while(true){
		IPEndPoint RemoteIpEndPoint = new IPEndPoint(IPAddress.Any,0);
		//Be careful here, as the Receive method will block until a datagram arrives from a remote host
		Byte[] receiveBytes = _udpClient.Receive(ref RemoteIpEndPoint);
		string returnData = Encoding.ASCII.GetString(receiveBytes);

		//Writing the UDP content, that we assume to be a valid JSON, to the "output1" of our UDPModule
		ioTHubModuleClient.SendEventAsync("output1", new Message(receiveBytes));
	}
}

After writing the code, build and push the container image to your favorite Docker Registry (you can find mine in the Docker Hub as danigian/udpmodule:debug GA bits available under danigian/1.0.0-ga-arm32v7)

WARNING: you should not use my Docker Image in a production environment!

After that, in order to provision the module, you have to:

  • Go to the Azure portal, navigate to your IoT hub.
  • Go to IoT Edge (preview) and select your IoT Edge device.
  • Select Set Modules.
  • Select Add IoT Edge Module.
  • In the Name field, enter the name you want to assign to your module (for this article: udpModule).
  • In the Image URI field, enter your image URI in your repository (i.e.: danigian/udpmodule:debug)
  • Very important: In order to open ports on your module you have to modify the “Container Create Options”. For example:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
	"ExposedPorts": {
		"1208/udp":{}
	},
	"HostConfig": {
		"PortBindings": {
			"1208/udp": [
				{
					"HostPort": "1208"
				}]
		}
	}
}

  • Leave the other settings unchanged and click Save.
  • Click Next.
  • In the Specify Routes step, copy the JSON below into the text box. In this route, upstream is a special destination that tells Edge Hub to send messages to IoT Hub.
1
2
3
4
5

{
	"routes":{
		"UDPToIoTHub":"FROM /messages/modules/udpModule/outputs/output1 INTO $upstream"
	}
}
  • Click Next.
  • In the Review Template step, click Submit.
  • Return to the IoT Edge device details page and click Refresh.

You should see the new module running and sending your datagrams to IoT Hub!