How to run and configure an IoT Gateway

What is an IoT gateway?

An IoT gateway is the protocol or software that's used to connect Internet of Things servers to the cloud. The IoT Gateway can be run as a standalone application, without any modification. There are different encapsulations of the IoT Gateway already prepared. They are built using the same code, but have different properties and are aimed at different operating systems. In today's tutorial, we will explore how to run and configure the IoT gateway. Since all libraries used are based on .NET Standard, they are portable across platforms and operating systems. The encapsulations are then compiled into .NET Core 2 applications. These are the ones being executed. Since both .NET Standard and .NET Core 2 are portable, the gateway can, therefore, be encapsulated for more operating systems than currently supported. Check out this link for a list of operating systems supported by .NET Core 2.

Available encapsulations such as installers or app package bundles are listed in the following table. For each one is listed the start project that can be used if you build the project and want to start or debug the application from the development environment:

Running the console version

The console version of the IoT Gateway (Waher.IoTGateway.Console) is the simplest encapsulation. It can be run from the command line. It requires some basic configuration to run properly. This configuration can be provided manually (see following sections), or by using the installer. The installer asks the user for some basic information and generates the configuration files necessary to execute the application.

The console version is the simplest encapsulation, with a minimum of operating system dependencies. It's the easiest to port to other environments. It's also simple to run from the development environment. When run, it outputs any events directly to the terminal window. If sniffers are enabled, the corresponding communication is also output to the terminal window.

This provides a simple means to test and debug encrypted communication:

Running the gateway as a Windows service

The IoT Gateway can also be run as a Windows service (Waher.IoTGateway.Svc). This requires the application be executed on a Windows operating system. The application is a .NET Core 2 console application that has command-line switches allowing it to be registered and executed in the background as a Windows service. Since it supports a command-line interface, it can be used to run the gateway from the console as well. The following table lists recognized command-line switches:

Running the gateway as an app

It is possible to run the IoT Gateway as a Universal Windows Platform (UWP) app (Waher.IoTGateway.App). This allows it to be run on Windows phones or embedded devices such as the Raspberry Pi running Windows 10 IoT Core (16299 and later). It can also be used as a template for creating custom apps based on the IoT Gateway:

Configuring the IoT Gateway

All application data files are separated from the executable files. Application data files are files that can be potentially changed by the user. Executable files are files potentially changed by installers. For the Console and Service applications, application data files are stored in the IoT Gateway subfolder to the operating system's Program Data folder. Example: C:ProgramDataIoT Gateway. For the UWP app, a link to the program data folder is provided at the top of the window. The application data folder contains files you might have to configure to get it to work as you want.

Configuring the XMPP interface

All IoT Gateways connect to the XMPP network. This connection is used to provide a secure and interoperable interface to your gateway and its underlying devices. You can also administer the gateway through this XMPP connection.

The XMPP connection is defined in different manners, depending on the encapsulation. The app lets the user configure the connection via a dialog window. The credentials are then persisted in the object database. The Console and Service versions of the IoT Gateway let the user define the connection using an xmpp.config file in the application data folder. The following is an example configuration file:

<?xml version='1.0' encoding='utf-8'?> 
<SimpleXmppConfiguration xmlns='http://waher.se/Schema/SimpleXmppConfiguration.xsd'> 
   <Host>waher.se</Host> 
   <Port>5222</Port> 
   <Account>USERNAME</Account> 
   <Password>PASSWORD</Password> 
   <ThingRegistry>waher.se</ThingRegistry> 
   <Provisioning>waher.se</Provisioning> 
   <Events></Events> 
   <Sniffer>true</Sniffer> 
   <TrustServer>false</TrustServer> 
   <AllowCramMD5>true</AllowCramMD5> 
   <AllowDigestMD5>true</AllowDigestMD5> 
   <AllowPlain>false</AllowPlain> 
   <AllowScramSHA1>true</AllowScramSHA1> 
   <AllowEncryption>true</AllowEncryption> 
   <RequestRosterOnStartup>true</RequestRosterOnStartup> 
</SimpleXmppConfiguration>

The following is a short recapture:

Securing the password

Instead of writing the password in clear text in the configuration file, it is recommended that the password hash is used instead of the authentication mechanism supports hashes. When the installer sets up the gateway, it authenticates the credentials during startup and writes the hash value in the file instead. When the hash value is used, the mechanism used to create the hash must be written as well. In the following example, new-line characters are added for readability:

<Password type="SCRAM-SHA-1"> 
   rAeAYLvAa6QoP8QWyTGRLgKO/J4= 
</Password>

Setting basic properties of the gateway

The basic properties of the IoT Gateway are defined in the Gateway.config file in the program data folder. For example:

<?xml version="1.0" encoding="utf-8" ?> 
<GatewayConfiguration xmlns="http://waher.se/Schema/GatewayConfiguration.xsd"> 
<Domain>example.com</Domain> 
<Certificate configFileName="Certificate.config"/> 
<XmppClient configFileName="xmpp.config"/> 
<DefaultPage>/Index.md</DefaultPage> 
<Database folder="Data" defaultCollectionName="Default" 
   blockSize="8192" blocksInCache="10000" blobBlockSize="8192" 
   timeoutMs="10000" encrypted="true"/> 
<Ports> 
<Port protocol="HTTP">80</Port> 
<Port protocol="HTTP">8080</Port> 
<Port protocol="HTTP">8081</Port> 
<Port protocol="HTTP">8082</Port> 
<Port protocol="HTTPS">443</Port> 
<Port protocol="HTTPS">8088</Port> 
<Port protocol="XMPP.C2S">5222</Port> 
<Port protocol="XMPP.S2S">5269</Port> 
<Port protocol="SOCKS5">1080</Port> 
</Ports> 
<FileFolders> 
<FileFolder webFolder="/Folder1" folderPath="ServerPath1"/> 
<FileFolder webFolder="/Folder2" folderPath="ServerPath2"/> 
<FileFolder webFolder="/Folder3" folderPath="ServerPath3"/> 
</FileFolders> 
</GatewayConfiguration>

Providing a certificate

Different protocols (such as HTTPS) require a certificate to allow callers to validate the domain name claim. Such a certificate can be defined by providing a Certificate.config file in the application data folder and then restarting the gateway. If providing such a file, different from the default file, it will be loaded and processed, and then deleted. The information, together with the certificate, will be moved to the relative safety of the object database. For example:

<?xml version="1.0" encoding="utf-8" ?> 
<CertificateConfiguration xmlns="http://waher.se/Schema/CertificateConfiguration.xsd"> 
<FileName>certificate.pfx</FileName> 
<Password>testexamplecom</Password> 
</CertificateConfiguration> 

This tutorial was taken from Mastering Internet of Things.

Read More

IoT Forensics: Security in an always connected world where things talk

How IoT is going to change tech teams

5 reasons to choose AWS IoT Core for your next IoT project