9 min read

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:

Platform Executable project
Windows console Waher.IoTGateway.Console
Windows service Waher.IoTGateway.Svc
Universal Windows Platform app Waher.IoTGateway.App
The IoT Gateway encapsulations can be downloaded from the GitHub project page:
All gateways use the library Waher.IoTGateway, which defines the executing environment of the gateway and interacts with all pluggable modules and services. They also use the Waher.IoTGateway.Resources library, which contains resource files common among all encapsulations. The Waher.IoTGateway library is also available as a NuGet:

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:

IoT Gateway console application

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:

Switch Description
-? Shows help information.
-console Runs the service as a console application.
-install Installs the application as a Window Service in the underlying operating system.
-displayname Name Sets a custom display name for the Windows service. The default name if omitted is IoT Gateway Service.
-description Desc Sets a custom textual description for the Windows service. The default description if omitted is Windows Service hosting the Waher IoT Gateway.
-immediate If the service should be started immediately.
-localsystem Installed service will run using the Local System account.
-localservice Installed service will run using the Local Service account (default).
-networkservice Installed service will run using the Network Service account.
-start Mode Sets the default starting mode of the Windows service. The default is Disabled. Available options are StartOnBoot, StartOnSystemStart, AutoStart, StartOnDemand and Disabled
-uninstall Uninstalls the application as a Windows service from the operating system.


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:

IoT Gateway UWP App

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'> 

The following is a short recapture:

Element Type Description
Host String Host name of the XMPP broker to use.
Port 1-65535 Port number to connect to.
Account String Name of XMPP account.
Password String Password to use (or password hash).
ThingRegistry String Thing registry to use, or empty if not.
Provisioning String Provisioning server to use, or empty if not.
Events String Event long to use, or empty if not.
Sniffer Boolean If network communication is to be sniffed or not.
TrustServer Boolean If the XMPP broker is to be trusted.
AllowCramMD5 Boolean If the CRAM-MD5 authentication mechanism is allowed.
AllowDigestMD5 Boolean If the DIGEST-MD5 authentication mechanism is allowed.
AllowPlain Boolean If the PLAIN authentication mechanism is allowed.
AllowScramSHA1 Boolean If the SCRAM-SHA-1 authentication mechanism is allowed.
AllowEncryption Boolean If encryption is allowed.
RequestRosterOnStartup Boolean If the roster is required, it should be requested on start up.

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"> 

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"> 
<Certificate configFileName="Certificate.config"/> 
<XmppClient configFileName="xmpp.config"/> 
<Database folder="Data" defaultCollectionName="Default" 
   blockSize="8192" blocksInCache="10000" blobBlockSize="8192" 
   timeoutMs="10000" encrypted="true"/> 
<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> 
<FileFolder webFolder="/Folder1" folderPath="ServerPath1"/> 
<FileFolder webFolder="/Folder2" folderPath="ServerPath2"/> 
<FileFolder webFolder="/Folder3" folderPath="ServerPath3"/> 
Element Type Description
Domain String The name of the domain, if any, pointing to the machine running the IoT Gateway.
Certificate String The configuration file name specifying details about the certificate to use.
XmppClient String The configuration file name specifying details about the XMPP connection.
DefaultPage String Relative URL to the page shown if no web page is specified when browsing the IoT Gateway.
Database String How the local object database is configured. Typically, these settings do not need to be changed. All you need to know is that you can persist and search for your objects using the static Database defined in Waher.Persistence.
Ports Port Which port numbers to use for different protocols supported by the IoT Gateway.
FileFolders FileFolder Contains definitions of virtual web folders.

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"> 
Element Type Description
FileName String Name of certificate file to import.
Password String Password needed to access private part of certificate.


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



Please enter your comment!
Please enter your name here