Service Basics

Jacob Evans 2019-01-14

Prerequisites

Introduction

This lesson will cover the basic concepts of Cybus Services and how they relate to the Connectware. If you have read the technical overview of the Connectware lesson, the image below will be familiar to you.

Connectware Architecture

Here we will focus on the Services and how applications deployed as Services can take advantage of the Data Broker for accessing output from Devices on the Connectware, the Management cluster for gaining access to that output and the single entry point for providing new interfaces where users can take advantage of processed data.

What is a Service

While the Connectware gives interfaces for individually performing all actions (like managing users, setting permissions, starting containerized applications, etc.) the idea of Services is to bundle all this activities into a single point of configuration and execution. This means that when a Service is enabled it will perform a set of operations on the Connectware and when disabled these operations will be removed. Below you will find some examples of possible Service use cases.

Preprocessing

Think of a simple machine that produces a metal part. Whether a metal part is being made at any one point of time may not be the important but the average amount being made over a given time period may be useful for knowing if the machine is underperforming. We can accomplish this by connecting the Machine to the Connectware, and then deploying a Service along side that takes the raw data from the Data Broker, calculates the average over a given period of time, then uploads the result to the data broker for some other application to consume. This type of application is classified as a preprocessor as it allows us to preform some operation on the data before it is consumed elsewhere.

Device controller

Think of a machine that drills holes in a piece of material. When the machine is drilling we want to set a lamp to be green, when the machine is between drilling we want to set a lamp to be yellow and when the machine is powered off we want the light to be red. We can connect both the machine and the lamp to the Connectware as Devices then read the status of the machine from the Data Broker into a Service. This Service can perform a check on the status then write out to the Data Broker on a topic that controls the light to change colors. This type of application is classified as a Device controller as we are using input data to write to a Device connected to the Connectware.

Data visualization

Think an assembly line that outputs new products ready to be shipped. We can connect the sensors of the assembly line as Devices on the Connectware. We can then build a Service that provides a web dashboard that outputs different graphs for the average output, speed, temperature and power used throughout the day. Administrators can then sign in to the Connectware and view this dashboard to see the status of the assembly line. This type of application is classified as a Data Visualization as it takes data from the Connectware and provides visualizations to allow easier consumption of important data.

Much more

These are only a few examples of the types of Services that Cybus Connectware can deploy. As you will see below the Connectware is built on top docker so as long your application can be containerized your application can be deployed on the Connectware.

How to create a Basic Service

Like Devices Services are installed using a commissioning file. Within this text-base file, all users, permissions and containerized applications a Service uses are listed. Additionally, it is possible to register notifications (via web-hooks) for any Service event (like on-started, on-stopped , etc.). Below you will find an example Service Commissioning File that deploys a Grafana instance which we will configure to view data generated by a simulation Device. The Service will use one Cybus specific container to map mqtt to InfluxDB but the rest of the containers were taken from other projects and are easily integrated. If any section of the Service Commissioning File needs clarification please feel free to visit our documentation.

General

The first section of the Service Commissioning Files is the general section. This section contains the meta information for the Service that is being installed. Here we set a title, internal identifier, version number, give a description, provide an icon for the thumbnail of the Service, specify a provider, provide a homepage for the company providing the Service and define that this is a prototype Service.

#------------------------------------------------------------------------------#
# CYBUS SERVICE COMMISSIONING                                                  #
#------------------------------------------------------------------------------#
general:
  title: Example Grafana Dashboard
  identifier: example-dashboard
  version: 1.0
  description: >
    Example Grafana Dashboard
  icon: https://assets.packet.net/media/pages/images/a8849b052492b5106526b2331e526138/xCMw-grafana.png
  provider: cybus
  homepage: https://cybus.io
  terms: Prototype

Grantees

The next section of the Service Commissioning File is the grantees section. This section contains the specifications for users the Service itself needs in order to operate. In this case we need one user that will read in simulation data from the Data Broker so we can store it in InfluxDB and then visualization it in Grafana.

#------------------------------------------------------------------------------#
# LIST OF INTERNAL SERVICE USERS                                               #
#------------------------------------------------------------------------------#
grantees:
- identifier: example-dashboard-client
  credentials: token
  token: {{ Password }}
  purpose: To read simulation data for the Grafana Dashboard
  type: container

Policies

This section contains the policies for users the Service has generated from the grantees section above. In this case we assign a read permission for all topics under cybus/learn/simulation to the example-dashboard-client user. With this policy the client will be given access to read (ReadData) the simulation data. Sometimes the container needs to write (WriteData) data to the Data Broker as well.

#------------------------------------------------------------------------------#
# LIST OF SERVICE POLICIES                                                     #
#------------------------------------------------------------------------------#
policies:
- grantee: example-dashboard-client
  purpose: Read simulation data
  policy: ReadData
  constraints:
    topic: cybus/learn/simulation/#

Containers

The containers section contains the docker containers the Service will run. These containers can either come from the official Docker registry or from the Cybus registry. That means any application that is deployed on the Connectware can take full advantage of all the containerized software on Docker Hub and your custom containerized software delivered securely through the Cybus Registry. In the example below we pull the official Grafana and Influxdb containers from docker hub and then use a custom Cybus container to map the MQTT Data broker data to InfluxDB. The different options that can be used when configuring these containers can be found in the documentation.

#------------------------------------------------------------------------------#
# CONTAINERS THE SERVICE WILL OPERATE                                          #
#------------------------------------------------------------------------------#
containers:
- image: grafana/grafana:4.0.1
  name: dashboard
  env:
    - GF_SERVER_ROOT_URL=/services/cybus/example-dashboard/web
    - GF_AUTH_ANONYMOUS_ENABLED=true
- image: registry.cybus.io/cybus-services/influxdb-push:0.0.2
  name: influxdb-push
  env:
  - MQTT_HOST=172.17.0.1
  - MQTT_USER=example-dashboard-client
  - MQTT_PORT=1883
  - MQTT_PASS={{ Password }}
  - MQTT_ROOT_TOPIC=cybus/learn/simulation/#
  - INFLUX_HOST=influxdb
  - INFLUX_PORT=8086
  - INFLUX_DB=generic
  - HTTP_ROOT=/services/cybus/example-dashboard/web
- image: influxdb:1.6.2-alpine
  name: influxdb
  env:
    - INFLUXDB_DB=generic

Frontends

The frontends sections defines the interfaces that the Service will provide on a Connectware instance. These interfaces will then point to a specific port in Service container. This allows Services to provide web dashboards and REST APIs which can then be accessed through the HTTPS interface of the Cybus Connectware. In this case we define a dashboard endpoint and point it to the port 3000 on the Grafana container.

#------------------------------------------------------------------------------#
# FRONTENDS FOR THE SERVICE                                                    #
#------------------------------------------------------------------------------#
frontends:
- type: http
  slug: web
  name: Grafana
  description: Grafana Dashboard Frontend
  target:
    container: dashboard
    port: 3000
    path: ''
  buttons:
  - name: Dashboard
    href: /services/cybus/example-dashboard/web/

Making the Service Commissioning File configurable

In the Grantees section you probably noticed that we used {{ Password }}. This is a variable inside of the Service Commissioning File. When a Service is installed the Connectware will prompt the installing user to provide the specified variable in this case the password for the MQTT Client. This allows us to make Services dynamic since variables can be used anywhere in the Service Commissioning File. Note the syntax is always {{ Variable }}.

How to install a Service

Now that we know what a Service is and we have configured our own example we can install it on the Connectware. For this Service we will need the Service and a Simulation Device to output data. Both the simulation Device Commissioning File and the Service Commissioning File can be found on Github.

Install Simulation Device

  1. Open your Connectware instance and navigate to the Devices section. Devices view

  2. Click the menu button on the button right. Device menu

  3. Click the add button. Devices add

  4. Select the device-simulation-commissioning-file.yml on your computer and click install. Device added

Install Service

  1. Open your Connectware instance and navigate to the Services section. Services view

  2. Click the add button. Services add

  3. Select the service-example-commissioning-file.yml on your computer and click install. Services add

  4. Configure password for client. Services configure

  5. Click the enable button on your Service. Services configure

Explore Service

Now that you have successfully installed a Service we can use the provided dashboard and configure Grafana to visualize our simulation data.

  1. First click on the dashboard button on the Service. Explore button

  2. Click the side menu and select data sources. Explore menu

  3. Add a new datasource and fill out the configuration for the InfuxDB we are mapping MQTT data to. When you save it should say 'Data source is working`.

Explore datasource

  1. Go to the side menu and create a new dashboard. Explore create

  2. Select graph panel. Unconfigured Graph

  3. Double Click on the panel and select edit. Edit Graph

  4. Select the query and select one of the measurements from InfluxDB to graph. In this case we use cybus.learn.simulation.building-automation.airconditioner.1.humidity. Edit Query

The query editor for Grafana is incredibly powerful and can do much more then we will show in this tutorial. For more details read the documentation here.

  1. Select the general tab and modify the title to describe the graph we are making. In this case we will change it to be Humidity. Edit Name

  2. Click the save icon on the top navbar and name it First Dashboard. Edit Name

  3. Now you have configured dashboard Service that can be shared to other users. Edit Name

Share Service

  1. Open your Connectware instance and navigate to the users section and click on the roles tab. Roles Section

  2. Click the menu button on the button right. Roles Menu

  3. Click the add button. Roles add

  4. Create a new role called generic-dashboard. Roles Create

  5. Click on the row. Roles row

  6. Click API in Permissions section. Roles API

  7. Click the plus button and add a new Permission with readWrite on /services/cybus/generic-dashboard/# Add Permission

  8. Click the save button to save changes to role then press the back button. Save Role

  9. Go to users tab. Users Tab

  10. Create new user with username test and password test. Users Tab

  11. Click on user row. Users Row

  12. Click on roles section and add generic-dashboard role. Generic Role

  13. Click the save button to save the changes to the user. Generic save

  14. Logout. Logout

  15. Try to go to https://<hostname>/services/cybus/example-dashboard/web/ in your browser. Attempt Access

  16. Login with test user. Relogin

  17. Use dashboard. Use Dashboard

Summary

In this lesson we learned what Services are and made a basic Grafana Service. We then configured it to visualize humidity data from our Simulation Device. Lastly we create a new role that gives access to this dashboard, made a new user and added that role to the new user. This example shows how we can use the Connectware to take advantage of the data from Devices to create secure IoT applications.

Going further

To learn more about the Cybus Connectware check out our documentation or read more lessons here on Cybus Learn. To learn more on using you Grafana Service read the Grafana documentation.