Getting Started with ioFog

Step 1. Pick the Installation Guide for your selected version of Linux

Follow one of the links to see installation instructions:

Step 2. Provision your ioFog for usage in ioAuthoring

  1. Access the ioAuthoring in a Web browser. If you don't have an account yet, sign up here: https://iotracks.com/signup
  2. Login here: https://iotracks.com/login. You can find a user guide for ioAuthoring here
  3. Create a new ioFog instance (drag and drop a fog instance on Fog page) and generate a provisioning key
  4. GENERATE PROVISION KEY
  5. Go to your Linux command line, type 'sudo iofog provision ABCDWXYZ' and replace the ABCDWXYZ with your provisioning key (it is case sensitive) and verify the results

The output will display a success message if the process is successful and will show an instance ID
If provisioning process was successful, type 'sudo iofog status' and verify that the 'controller connection' value is now listed as 'ok'
The output will display an error if provisioning process was not successful (a common problem is having the wrong network adapter set in the configuration). In this case:

Step 3. Start using your ioFog by going through the steps of three short demos:

  1. Demo 1 configures a simple hello web app.
  2. Demo 2 configures a new weather-streaming app and creates a RESTful endpoint that can be accessed via a URL or a dashboard or a device cloud.
  3. Demo 3 demonstrates how microservices can be used to transform the weather data stream.

DEMO 1 - HELLO WEB

  1. Press '+New track' button, enter name and press CREATE button
    create a new track
  2. Drag and drop the Hello Web Demo element
  3. Select the ioFog instance that you've just created (during provisioning process) in the 'ioFog to run this element' drop-down and fill in Name field
    drop Hello Web
  4. We now need to set the ports so that we can access the element from a browser
    • press 'MANAGE PORTS' button
    • set the 'internal port' to port '80', the 'external port' to any port - here we set it to '5501'.
      Set the external port to anything you want, but consider something above 5000 to avoid conflict with any other open ports on your machine.
    • check the 'Cloud Access' check box, and then click the "Add Port" button.
    • copy the Public Access URL that appears in the dialog box.
      manage ports
  5. Activate the Track by clicking ACTIVATE TRACK button at the top
  6. Open a browser window. Paste the URL into a browser URL bar.

Note: you need to wait some seconds. Refresh the browser window in 20-30 seconds. This is expected output:
hello web output

TIP 1. You can check whether the microservice is running with 'sudo docker ps' command in the command line
TIP 2. You can set the external port to anything you want, but consider something above 5000 to avoid conflict with any other open ports on your machine.

DEMO 2 - WEATHER-STREAMING APP

I. Setting up the source of weather data

  1. Press '+New track' button, enter some name and press CREATE button
  2. Drag and drop the Open Weather Map Data element, name the element: Weather Data Stream
  3. Select the ioFog instance in the 'ioFog to run this element' dropdown
  4. Click on Configuration JSON input field to enter a configuration script that connects to the open weather service. For example:

    {"citycode":"5391997","apikey":"6141811a6136148a00133488eadff0fb","frequency":1000}

    input configuration

II. Creating a RESTful endpoint and routing data between elements

This will allow the access the weather data in a browser or in any other application or any device cloud.

Consequently to transform the data generated by the first element (microservice) you have to 'link' or chain' it to the next element.

  1. Drag and drop the the JSON REST API element, name it if you want to
  2. Select your ioFog instance in the 'ioFog to run this element' dropdown
  3. Connect 2 elements together. (You can click on the Blue arrow to remove the existing routing if you need to delete connection)
    two elements
  4. Enter a configuration script for the JSON REST API element, for example:

    {"buffersize":5,"contentdataencoding":"utf8","contextdataencoding":"utf8","outputfields":{"publisher":"source","contentdata":"temperature","timestamp":"time"}}

  5. Select ioFog to run Open Weather Map Data and JSON REST API elements
  6. Now we need to set the output ports so that we can access the stream from a browser
    • click the MANAGE PORTS button on the element properties pane
    • set the 'internal port' to port '80', the 'external port' to any port - here we set it to '5050'.
    • check the 'Cloud Access' check box, and then click the "Add Port" button.
    • Copy the Public Access URL that appears in the dialog box.
  7. Activate the Track by clicking ACTIVATE TRACK button at the top
  8. Open a browser window and paste the URL into a browser URL bar. When the system has updated fully, you will see the stream of weather data appears in the browser
    two elements output

DEMO 3 - TRANSFORMING THE WEATHER DATA USING CUSTOM MICROSERVICES

In this demo we'll add more microservices to the Weather data Stream. Then we'll transform the data stream by filtering the content using following microservices:

  1. The JSON subselect and transform microservice filters the data to show only the temperature data
  2. The Temperature converter microservice converts the temperature data to degrees of Celsius or Fahrenheit

Also you'll add new microservices to the system, just like when you'll do when you have your own!

Your application should look like this when you are done at the end of this lesson:

four elements with custom

You can use built-in JSON Sub-Select and Temperature Converter microservices from the list on Build page instead of adding custom ones.
In this case your application will look like this when you are done

four elements standard

I. Adding new elements on the Publish page (adding custom microservices to ioAuthoring)

Let's say that you have already created Docker images for your microservices and pushed them into the Docker registry.
Now you'll see how to add them for usage!
All elements that you publish in the portal will be available only to you and other members of your organization. They will not be available to the general public.
Published elements will appear in the catalog alongside the publicly available elements at the bottom of the microservices list in the Build page.

  1. Navigate to the Publish page
  2. Drag and drop two New elements for Standard Linux (x86) onto layout
  3. Fill the "Name" and "Container Image" fields for both of them as follows:
custom subselect custom converter

II. Routing data between elements

  1. Drag and drop the following elements to the layout on the Build page:
    • Open weather Map data
    • JSON subselect (either built-in or created on the previous step)
    • temperature Converter (either built-in or created on the previous step)
    • JSON REST API
  2. Add the following configuration for the Weather Data Stream element:

    {"citycode":"5391997","apikey":"6141811a6136148a00133488eadff0fb","frequency":1000}

  3. Select ioFog to run this element
  4. Add the following configuration to JSON subselect:

    {"selections":[{"inputtype":"weather/mixed/open-weather-map","inputformat":"text/json","outputtype":"temperature","outputformat":"decimal/kelvin","outputs":[{"subselection":"main.temp","outputjsonarray":false,"fieldname":"temperature"}]}]}

  5. Select ioFog to run this element
  6. Add the following configuration for Temperature converter element:

    {"outputformat":"celsius"}

  7. Select ioFog to run this element
  8. Add the following configuration for JSON REST API element:

    {"buffersize":5,"contentdataencoding":"decimal","outputfields":{"publisher":"source","contentdata":"temperature","timestamp":"time"}}

  9. Select ioFog to run this element
  10. Connect all 4 microservices together (link them with blue arrows)
  11. Select the JSON REST API element, press 'MANAGE PORTS' button, type ports, check "Cloud access" and press "ADD PORTS" for the element. Then copy Public access URL
  12. Activate the Track by clicking ACTIVATE TRACK button at the top
  13. Open a browser window and paste the URL into a browser URL bar. When the system has updated fully, you should see the latest 5 messages of the stream containing temperature data:
four elements output

You can check whether 5 microservices are running with 'sudo docker ps' command in the command line. This is expected output:

docker ps 5 elements