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 |
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:
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:
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:
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"> 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>
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"> <FileName>certificate.pfx</FileName> <Password>testexamplecom</Password> </CertificateConfiguration>
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