Introduction
This paper will show you how to use an Intel® NUC gateway and Microsoft Azure* IoT Edge to connect a sensor to Microsoft Azure* IoT Hub running in the Azure cloud. You'll see how to create a modular sensor application on the gateway that reads real-time sensor data, processes the data locally, and sends the data to Microsoft Azure IoT Hub where it can be stored, visualized and processed in the cloud. Processing data on the gateway allows you to use edge computing to place functionality closer to the sensor, and allows you to integrate sensors that aren't capable of directly connecting to the cloud. We'll use Node.js* and the Microsoft Azure IoT Edge SDK to perform input, processing and output functions in our application.
Setup and Prerequisites
- Intel® NUC gateway running Ubuntu* Server 16.04 LTS operating system.
- Node.js v6.x and NPM installed on the gateway.
- Gateway connected to a LAN network with Internet connectivity.
- RH-USB temperature and humidity sensor.
- A developer workstation or laptop.
- An active Microsoft Azure cloud account.
Connect RH-USB Sensor
The RH-USB sensor is an industrial temperature and humidity sensor with a serial interface that connects via USB. Plug the RH-USB connector into the USB jack on the front of the NUC. After that's done, Ubuntu will create a serial tty device named /dev/ttyUSB0. Confirm that the device was created by logging into the gateway as the Ubuntu user and running the following command and inspecting the output (the dash option is the lowercase letter L):
$ ls -l /dev/ttyUSB*
crw-rw---- 1 root dialout 188, 0 May 10 12:37 /dev/ttyUSB0
Give the ubuntu user read/write access to the sensor's serial device by running the following command on the gateway:
$ sudo usermod -a -G dialout ubuntu
You must log out and log back in as the ubuntu user to pick up the permission change. Use the screen program to verify the sensor is working. screen is a terminal program that allows you to type characters and view responses. Install and run screen on the gateway using the following commands:
$ sudo apt install -y screen
$ screen /dev/ttyUSB0 9600
After screen has started, press Enter and you should see the > character appear. That is the RH-USB command prompt. Type the letters PA and press Enter. You won't see the letters PA but you should see a set of digits like the following.
>50.4,72.8
>
The digits are the humidity (%) and temperature (degrees F) readings from the RH-USB separated by a comma. Exit the screen program by typing Control-A followed by backslash and then typing y to confirm exiting screen.
Set up Local Server for RH-USB Sensor Data
Run these commands on the gateway to download and run the rhusb-server application which provides a local server that exposes RH-USB sensor data to other applications through a REST interface:
$ cd ~
$ sudo apt install -y git
$ git clone https:
$ cd rhusb-server
$ npm install
$ npm start
RH-USB server project on GitHub.
You should see status messages like the following showing the application starting and readings being received from the RH-USB sensor.
> rhusb-server@1.0.0 start /home/ubuntu/rhusb-server
> node rhusb-server.js
Server running at http:
serial.open: Serial port opened
Serial port /dev/ttyUSB0 opened
{"time":"2017-06-13T13:24:25.906Z","temp":"72.9","humid":"57.5","valid":true}
{"time":"2017-06-13T13:24:26.910Z","temp":"72.9","humid":"57.5","valid":true}
{"time":"2017-06-13T13:24:28.141Z","temp":"72.9","humid":"57.5","valid":true}
Leave the application running in a separate terminal session on the Intel® NUC so it can be used in the next steps.
Install Microsoft Azure* IoT Edge Runtime
Run these commands on the Intel gateway to install the Azure IoT Edge runtime:
$ sudo apt install -y libcurl4-openssl-dev
$ sudo npm install -g azure-iot-gateway
Create Node.js* Microsoft Azure* IoT Edge Application
A Microsoft Azure IoT Edge application consists of compute modules that can be written in Java*, C, C# or Node.js. Modules are chained together to form a processing pipeline that implements the overall functionality of an application. The processing pipeline is described by a JSON metadata file that can be modified to add, remove or reconfigure the application.
Use these commands to download and prepare the source code for this application:
$ cd ~
$ git clone https:
$ cd intel-gateway-azure-iot-edge
$ npm install
Microsoft Azure IoT Edge source code on GitHub
The main files in the application are:
- gateway_config_rest.json — JSON metadata file that describes how the processing pipeline is to be configured at runtime. It also contains run-time configuration data such as authentication keys.
- rhusb-rest.js — Node.js module that periodically reads data from the rhusb-rest application on the gateway in order to obtain temperature and humidity sensor readings. Incomplete or erroneous readings are filtered out and valid readings are written to the pipeline so they can be used by other modules.
- rhusb-sim.js — An alternate Node.js module that generates simulated temperature and humidity data for testing when a real sensor is not available.
- printer.js — Node.js module that reads sensor data from the pipeline and prints it to the console for inspection purposes.
- iothub.js — Node.js module that connects to Azure IoT Hub and transmits sensor data from the pipeline to Azure IoT Hub where it can be further processed in the cloud.
- gateway_config_sim.json — An alternate pipeline configuration file that uses the rhusb-sim.js module (simulated data) instead of the rhusb-rest.js module (real data).
Each of the Node.js files implement the standard Azure IoT Edge pipeline callbacks for create(), start(), receive() and destroy().
Create Microsoft Azure* IoT Hub
Before we can send sensor data to Microsoft Azure IoT Hub, we'll need to create an Microsoft Azure IoT Hub in your Microsoft Azure* cloud account. Log into Azure and navigate to the Dashboard, then create an Microsoft Azure IoT Hub by following these steps:
Click New > Internet of Things > IoT Hub and set these parameters:
| Name
| iothub-3982
| Your IoT Hub name must be unique within Azure. Try different names until you find one that's available.
|
| Pricing and scale tier
| F1 - Free
| We'll use the free tier for this application.
|
| Resource group
| MyIOT
| Create a new group.
|
| Subscription
| Pay-As-You-Go
|
|
| Location
| East US
| Pick a location in your geographic region.
|
Checkmark Pin to dashboard and then click Create. IoT Hub will deploy to your Azure account and appear on your Dashboard after a few minutes.
After it's deployed, find the iothubowner Connection string--primary key which is a text string that you'll need later. Click Dashboard > iothub-3982 > Settings > Shared access policies > iothubowner and look for Connection string--primary key under Shared access keys. The string is complex, so copy and paste it for use in the next step.
Create a Device Identity in Azure IoT Hub
Before a device can communicate with Azure IoT Hub it needs to have a device identity in the Azure IoT Hub Device Identity Registry, which is a list of devices authorized to interact with your Azure IoT Hub instance.
Device identities are created and managed through REST APIs provided by Azure IoT Hub. There are different ways to use the REST APIs and we'll use an Azure open source command-line tool called iothub-explorer which is available on GitHub and NPM. iothub-explorer is a Node.js application and you'll need Node.js 6.x or higher installed on your workstation or laptop to use it.
On your workstation use these shell commands to install iothub-explorer:
$ npm install -g iothub-explorer
$ iothub-explorer help
Next we'll create and register a new device named intelnuc using the iothubowner Connection string--primary key we copied earlier from the Azure IoT Hub cloud console. Run this shell command on your workstation using your own iothubowner Connection string--primary key string inside the quotes:
$ iothub-explorer create intelnuc --login "HostName=iothub-3982.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=Be0w9Zew08x9LVAKeiseXsdf/adfe274EODo9Iwek9w=" --connection-string
After the device is created you'll see a message "Created device intelnuc" and a list of parameters for the newly created device. Locate the connectionString parameter which will have a long text string value next to it that starts with HostName=. You'll need to copy and paste this device connectionString value in the next step. The device connection string is also visible in the Azure IoT Hub cloud console.
Add Connection String to the Application Configuration
On the gateway, edit the gateway_config_rest.json file and locate the iothub section. In the args section update the connection_string value by pasting your device connectionString value in place of YOUR_CONNECTION_STRING_HERE. The updated section should look something like this:
{
"name": "iothub",
"loader": {
"name": "node",
"entrypoint": {
"main.path": "iothub.js"
}
},
"args": {
"connection_string": "HostName=iothub-3982.azure-devices.net;DeviceId=intelnuc;SharedAccessKey=KIBi9e389f87ew7hv78ew9+/s9IIOjLKIJIedil9Qda="
}
}
Save the updated file.
Run the Application
Start the application on the gateway by using this command:
$ azure-iot-gateway gateway_config_rest.json
You should see messages printed on the console as the application starts up and then periodic messages containing new sensor data being sent to Azure IoT Hub.
rhusb-rest.create
printer.create
iothub.create
Gateway is running. Press return to quit.
rhusb-rest.start
printer.start
iothub.start
iothub.connect: Connected to Azure IoT Hub
rhusb-rest query sensor: {"time":"2017-06-14T01:31:21.104Z","temp":"72.9","humid":"57.2","source":"rhusb"}
printer.receive: {"time":"2017-06-14T01:31:21.104Z","temp":"72.9","humid":"57.2","source":"rhusb"}
iothub.receive: {"time":"2017-06-14T01:31:21.104Z","temp":"72.9","humid":"57.2","source":"rhusb"}
iothub.receive: Message sent to Azure IoT Hub
On a developer workstation you can monitor messages being received by Azure IoT Hub by running this command with your own iothubowner connection string:
$ iothub-explorer monitor-events intelnuc --login "HostName=iothub-3982.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=Be0w9Zew0909LmAKeiseXsdfBadfe239EODo9iwee9w="
Each new message should look something like this:
==== From: intelnuc ====
{
"time": "2017-06-14T01:31:21.104Z",
"temp": "72.9",
"humid": "57.2",
"source": "rhusb"
}
====================
==== From: intelnuc ====
{
"time": "2017-06-14T01:31:23.103Z",
"temp": "72.9",
"humid": "57.3",
"source": "rhusb"
}
====================
Press Control-C to stop iothub-explorer on the developer workstation.
To stop the gateway application running on the gateway, press the Enter key. You should see messages as each of the modules run their destroy() function. When you are finished running the rhusb-server on the gateway, press Control-C to terminate it.
The simulated sensor module rhusb-sim.js works in a similar manner except that it uses simulated sensor data and doesn't require the rhusb-server application. You can run with the simulator by adding your device connection string to gateway_config_sim.json and then running the command azure-iot-gateway gateway_config_sim.json.
Where to Go From Here
This application provides the basic foundation for a modular solution to read a sensor connected to an Intel® IoT Gateway, process sensor data locally on the gateway, and send the results to the Microsoft Azure cloud. From here you could connect other types of sensors, add more processing modules and algorithms to the gateway application, integrate edge analytics, machine learning or artificial intelligence functions, configure applications to automatically run on system startup, and/or create more complex applications in the Azure cloud that process data and events received from the gateway
