FLEDGE IIoT Quick Start – Get up and running in less than an hour

So you want to be an IIoT Geek. Jumping into this emerging field can be a little intimidating, especially if you don't have a background in Linux. In this demonstration, we will use Docker to quickly stand up a FLEDGE IIoT Framework node along with the FLEDGE GUI to configure it and have a Kafka instance to publish the data to. It will give you a feel for how FLEDGE works and introduce you to some of the tools involved. This is the easiest way to take the plunge and you should be able to get this running in less than an hour, probably more like 15-30 minutes.

Requirements

There are a few things that you will need to install to get going. I'm giving you the broad strokes here and not step-by-step instructions.

Windows Subsystem for Linux (WSL)

The first step will be to make sure that you have the Windows Subsystem for Linux (WSL) feature enabled on your workstation. This subsystem allows you to run Linux directly on your workstation. If you haven't used WSL before, I highly recommend installing it as the easiest way to starting getting Linux experience. First, you need to enable the Windows Feature.

WSL acts as the host for Docker on Windows, which we will install soon.

 

Ubuntu 20.04 LTS from the Windows Store

Once the WSL Feature is installed, you will need to install an actual Linux distribution on your workstation. The WSL feature installs the OS components to support WSL, but this step actually installs Linux on your system. You can install more than one distribution on your system. Ubuntu 20.04 LTS, a common Linux distribution, is the one that I use. Once you install it from the store, just click "Launch" and it will fire up a command prompt and finish the installation.

DockerNow you are ready to download and install Docker on your workstation. Docker hosts our FLEDGE and Kafka components. Docker allows us to build containers hosting our components. The container configuration is specified in a Dockerfile containing the list of commands needed to build the container. I am providing you with the source for these Dockerfiles to get you started.

https://www.docker.com/products/docker-desktop

Git (optional)

Git is a source code repository commonly used in the Linux world, well, really the entire software development world at this point. My Dockerfiles are hosted on github, and you should have git to download the source. If you would prefer, you can also skip this step and just download everything as a zip file, but if you have not used git before, I highly recommend that you at least become familiar with it. Every geek should know git.

https://gitforwindows.org/

Visual Studio (optional)

Visual Studio Code (VS Code) is a lightweight, open-source, software development environment. The generic framework is supplemented with a wide array of plugins to support various programming languages and development tools. You don't have to install this, but it will make this demo a little bit easier and, every geek should have VS Code installed on their workstation.

https://code.visualstudio.com/

Once you have VS Code installed, I recommend adding the Docker plugin.

https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker

 

FLEDGE Containers and Dockerfile Sources

Now that you have all of the prerequisites configured, let's jump into the good stuff. I've put together some Docker images for you to play with and published them to Docker Hub. Now that you have Docker installed on your computer, you can just pull these images from Docker Hub and be ready to go. Since any geek worth their salt shows their work, I have also published the source Dockerfiles needed to build the images so that you can learn from them or if you are more experienced, offer criticism on how I can improve them.

The first Docker source is the main FLEDGE node container. The Dockerfile in this repository installs FLEDGE from the deployment package available from Dianomic.

https://github.com/RobRaesemann/FLEDGE-IOT-Docker

This repository also contains the docker-compose.yml file that will start up FLEDGE, FLEDGE GUI, and Kafka, all ready to go for you.

The FLEDGE GUI is a website for configuring your FLEDGE nodes. Here is the repository containing the source for it. The gui is an Angular application and this Docker image serves it from the popular NGINX web host.

https://github.com/RobRaesemann/fledge-gui-from-pkg-docker

Docker Hub Images

I have already created Docker images using the sources provided on Github. You will not need to build the images yourself, you should just be able to download them from Docker hub. Here are links to the images, but you don't need to download them manually. We will use docker-compose to do all of that for us. I am just providing links to that you can see where the images are coming from.

https://hub.docker.com/r/robraesemann/fledge

https://hub.docker.com/r/robraesemann/fledge-gui

Download the source containing the docker-compose.yml file

The docker-compose.yml file contained in the source repository for FLEDGE-IOT-Docker will do all of the heavy lifting for us. You will need this file to start everything up. Docker-compose will then download the Docker images from Docker Hub and start everything up properly configured for us.

Start in a directory where you would like to store the source code and execute this command to clone the git repository to your local hard drive.

git clone https://github.com/RobRaesemann/FLEDGE-IOT-Docker.git

This will create a subfolder called FLEDGE-IOT-Docker that will contain all of the files.

If you didn't install git, you can also download the code in a zip file and then decompress it.

 

Creating and running the containers using docker-compose

If you have visited the Docker Hub pages hosting my images then you have seen the documentation showing how you can run each individual container manually from the command line. To make this demonstration easier, I have created a docker-compose file. Docker-compose allows us to start multiple containers with all of the configurations necessary with one simple command. It avoids the complexity of starting each individual container manually with all of the command line options necessary.

If you installed VS Code on your system you should just be able to right-click on the FLEDGE-IOT-Docker folder in Explorer and select the menu option to open the directory in VS Code. From there you can right-click on the docker-compose.yml file and select "Compose Up".

This will invoke the command to start the containers as configured in the file. You should see results something like below. I have already pulled the images from Docker hub so your results will probably show progress in downloading the images and then starting the containers.

If you didn't install VS Code, you can simply go into the FLEDGE-IOT-Docker folder and issue the command

docker-compose up

Make sure everything is running

Go to a command prompt and issue the command

docker ps

You should see results similar to below. It is pretty busy, but we can see that we have containers called fledge, fledge_gui, zookeeper, and broker running. Zookeeper and broker are our Kafka instance, fledge is our fledge node, and fledge gui is an NGINX instance serving up our web GUI for configuring the FLEDGE node.

 

Start FLEDGE GUI

Now that all of the components are running in our Docker containers we can finally get to the fun part. Open your web browser and go to http://localhost. You should see the gui configuration screen below. Everything should default as needed so you should be able to hit the blue button to "Set the URL & Restart"

If it works you will see the default screen. It is time to start adding some plugins.

Add a South Plugin to Generate Data

Select South on the left hand side of the screen to being configuring a new South service. Next click the Add button in the top right hand corner.

We are going to add a Sinusoid plugin to generate sinusoid readings. If you are a PI geek, this should make you feel at home.

Scroll down the South Plugin list until you see "sinusoid". Select it and give it a name. This name is the name of the service that will be configured to host the south plugin. It helps you to identify services inside FLEDGE, but will have no impact on the actual data identifiers or tag names that the data is given. Click next.

Next we will configure an asset name. This is a simulator plugin, but normally we would be configuring a plugin to collect data from a device or asset. This name identifies where the readings come from. We will see later that the data generated by the plugin will contain this asset name. Click "Next".

This will return you to the South plugin screen. It will take a few seconds to initial the plugin so that it starts generating data. You should eventually see that it starts generating readings.

If we choose "Assets & Readings" on the left, we can see the asset sinusoid1 and that it has produced readings.

 

Clicking on the trend icon will bring up a trend of the data that has been generated.

We now have a south plugin collecting (generating in our case) readings from an asset. These readings are stored in an internal buffer in FLEDGE. By default that buffer is a SQLite database, but there is also an option to use Postgres SQL.

Now it is time to forward the data out of FLEDGE and into a destination system.

Configure a North Plugin

Add a new North plugin and scroll down to kafka_python. Give the service a name. Again, this is just the name of the internal FLEDGE process that will be spawned to forward the data and has no relation to the data itself.

We will be forwarding our readings. Enter broker:29092 into the Bootstrap Server field and you can leave the topic name as iot-readings.

 

It will take a little while to initialize the new plugin and begin sending data, but you should eventually see that the kafka plugin is enabled and sending data.

 

Going to the Dashboard screen you can see an overview of the data transfers of data coming in through the South plugin and data leaving via the North plugin. You have a functioning FLEDGE node.

 

Viewing the data in Kafka

In order to view the data in Kafka, we will use a tool called Kafka Tool.

https://www.kafkatool.com/

Download and install the tool on your workstation. Add a new connection under the file menu and configure it as shown below. Hit the "test" button and then add the cluster.

Configure the content types to be String types. If you hit the refresh button it should show you how many data messages have been sent to Kafka.

Next, select the "Data" tab and hit the play button. This will show you a list of the messages in Kafka. You can see the readings published by your FLEDGE node.

 

Now you can see the asset name that you configured. The "sinusoid" name in the readings is hard-coded into the plugin, but you can imagine collecting readings from a motor called Motor123 for the asset name and readings with names like amps, rpm, temperature, etc.

[
{
"asset": "sinusoid1",
"readings": {
"sinusoid": -0.978147601
},
"timestamp": "2021-09-02T20:08:48.866318Z",
"key": "e64002ea-fe10-4087-bb4c-ef345225d480"
},
{
"asset": "sinusoid1",
"readings": {
"sinusoid": -0.994521895
},
"timestamp": "2021-09-02T20:08:49.866333Z",
"key": "baf8c223-420e-487c-9c94-67f251476fdc"
}]

 

Congratulations, my young padawan, you have started your journey to becoming an IIoT Jedi.