CloudGate - devicepartnerportal.softwareag.com

1 ©2019 Software AG. All rights reserved.

CloudGate

Overview

CloudGate is the M2M Gateway from Option. It provides competitively priced LAN to

WWAN routing and GPS functionality in a single basic unit certified by all major US

cellular operators (CDMA/EvDO and WCDMA/HSPA+). CloudGate is simple to configure

locally or remotely from your PC, tablet or smartphone.

In the following, we describe how to configure the CloudGate device so that you are able

to remotely manage the CloudGate device from Cumulocity and work with its connected

sensors and controls. This allows you to:

Install Firmware updates

Perform device-specific operations

Change the configuration

Send measurements, events and alarms

Configuration

After setting up the CloudGate device, make sure to have the latest firmware installed.

To install firmware on your CloudGate device, you can either register your CloudGate to

the Option provisioning server or you can upload it manually. In both cases you have to

create an account first.

http://www.option.com/

https://cloudgateuniverse.com/


To upgrade your CloudGate remotely

1. Log into CloudGate Universe.

2. Navigate to the Devices tab.

3. Before activating a new device, you first need to create a new group. Click New

group and provide the required information.

4. Click Activate new device and provide the required information.

5. Navigate to your device and click Change version in the Firmware section.

6. Select the version you want to install on your CloudGate device and click Apply

changes.

To upgrade your CloudGate manually

Log into CloudGate Universe.

Navigate to the Library tab.

Click View firmware in the Firmware section.

Search for the firmware matching your device type and click View details.

Click the download icon next to the version you want to install.

Access your CloudGate device via web browser.

Log into the CloudGate web interface. The default username and password are

both “admin”.

Navigate to the Provisioning tab and in the left menu select Upload device

provisioning file.

Click Browse and navigate to the zip archive.

Click Upload and wait for the file to be sent.

After the device has restarted, you can check the firmware version under Home >

System Information in the web interface of the CloudGate device.

To connect your CloudGate device to Cumulocity, the LuvitRED plugin needs to be

installed. The installation is similar to the firmware upgrade described above. The plugin

can be found in the Application section instead of the Firmware section.

If you upgrade your CloudGate device remotely, it will automatically check for updates.

This means that in case the version which is installed on your CloudGate device differs

from the version specified in your CloudGate Universe account, the device will





automatically download and install the version specified in your account. This is, for

example, useful if you have to perform a factory reset on your device which would reset

the firmware on the device.

LuvitRED

Overview

LuvitRED is a browser-based application which allows you to write applications without

any programming language. With the help of an editor, you can easily create workflows

by utilizing a set of nodes which perform certain tasks.

To view the LuvitRED editor, navigate to the Plugin tab in the CloudGate web interface

and select LuvitRED. Click Advanced Editor.

On the left, you will find a list of nodes which are ready to use. To check the function of a

node, click it and find a description on the right. Drag a node into the middle area to add

it to your current workflow.

Before creating a workflow, make sure that your device is connected to CloudGate,

otherwise the workflow will not work.


You have to include at least one “c8y” node in your workflow in order to connect to

Cumulocity. Type “c8y” into the search bar to view all the nodes which are related to

Cumulocity. The “c8y” nodes perform the following tasks:

c8y measurement: Sends a measurement to the Cumulocity server

c8y alarm: Sends an alarm to the Cumulocity server

c8y event: Sends an event to the Cumulocity server

c8y command: Receives a command sent by the Cumulocity server

c8y config: Receives a configuration update sent by the Cumulocity server

c8y response: Sends a response to commands to the Cumulocity server

Info: Nodes in LuvitRED which require the user to write code (e.g. the “function” node)

use Lua as a programming language.

Using LuvitRED with Cumulocity: An Example

Basic workflow

In general, a node can have an input and/or output, depending on its functionality.

Two nodes can be connected by linking the output of one node with the input of another

node.

Double-click a node to configure it in the resulting dialog box. After configuring the

nodes, the workflow is ready to be deployed. Click Deploy at the top right to start the

workflow.

If changes in the configuration have not yet been deployed, this is indicated by a blue dot

above the node. If at least one mandatory parameter in the configuration is not yet

specified, this is indicated by a red triangle above the node.

In the following example, the “inject” and “debug” node will be used. Drag both nodes

into the middle area and connect them by clicking on the output of the “inject” node,

holding the mouse and releasing it above the input of the “debug” node.


The “debug” node is used for displaying the input it gets on the console (the “debug” tab

on the right side of the editor) while the “inject” node is used for sending a customizable

value as output. In this case, the “debug” node will just display the value we will configure

in the “inject” node. To configure the “inject” node, double-click it.

Payload: Defines what will be sent as output.

o Select “string” as the type of the payload in the drop-down menu.

o Enter “test” as payload.

Repeat: Specifies when the payload will be sent.

o Check “Fire once at start”.

Name: Defines the name of the node which will be displayed in the user interface.

o Enter an arbitrary name.

After deploying the changes, you should be able to see the specified value in the “debug”

tab.


Basic workflow with Cumulocity

In the following example, we will simulate a periodic temperature measurement and send

it to Cumulocity. To do so, replace the “debug” node with a “c8y measurement” node.

To send random numeric values perdiodically, change the configuration of the “inject”

node. First, select “random integer” as payload type and choose a range of possible

values. Second, select “interval” in the “repeat” field and specify an interval.

Next, the “c8y measurement” node needs to be configured.


Type: Type of the measurement.

o Enter “c8y_Temperature” as type.

o Select “Temperature” in the drop-down menu. A predefined fragment will

be created depending on the selection.

o Click on the “add” button.

Platform: Defines the platform the node will use.

o Click on the “pencil” icon. Another dialog which represents the “c8y

platform” node will appear.


Provision: Defines if the credentials will be set manually or autoprovisioned.

o Select “Manually” in the drop-down menu.

Tenant: The tenant you want to register your device at.

o Enter the tenant name.

Username: The username which will be used for authentication.

o Enter your username.

Password: The password which will be used for authentication.

o Enter your password.

Name: Defines the name of the node which will be displayed in the user interface.

o Enter an arbitrary name.

For more information on the “c8y measurement” and “platform” node, see below.

After configurating the “c8y measurement”, the workflow is ready to be deployed. You

should be able to see the measurements sent by the device in the “Measurement” tab of

your device in the “Device Management” application of Cumulocity. You can also see the

amount of measurements which were sent in the status under the node.


LuvitRED Cumulocity Nodes

“c8y measurement” node

The following node allows you to send a measurement to the Cumulocity server. As input

it expects the payload to be a numeric value or in case of a measurement with multiple

series a field containing properties with a numeric value each.

To be able to run the node, the following parameters need to be defined:

Platform: Select a platform for this node.

Type: The type of the measurement.

Measurement:

o Type: The type of the fragment.

o Name: The name of the series.

o Value: The numeric value of the measurement or series.

o Unit: The unit of the series.

The following parameters are optional: - Enable queueing: Enables queueing messages

when there is no connection. - Q config: Select a queue configuration. Defines how many

message can be stored in memory.

If you want to add multiple series to a measurement, you have to add a new

measurement with the same type to the list.


For more information on measurements, refer to “Cumulocity’s domain model”.

For more information on the node, refer to the description which can be seen on the

“Info” tab on the right side when selecting the node.

“c8y alarm” node

The following node allows you to send an alarm to the Cumulocity server. As input it

expects the payload to be a string representing the textual description of the alarm.



Type: The type of the alarm.

Status: The status of the alarm.

Severity: The severity of the alarm.



https://cumulocity.com/guides/concepts/domain-model/


message can be stored in memory. - Default text: The text which will be used if there is

no payload.

For more information on alarms, refer to “Working with alarms”.



“c8y event” node

The following node allows you to send an event to the Cumulocity server. As input it

expects the payload to be a string representing the textual description of the event.



Type: The type of the event.



message can be stored in memory. - Default text: The text which will be used if there is

no payload.

https://cumulocity.com/guides/users-guide/device-management/#alarm-monitoring


For more information on events, refer to “Cumulocity’s domain model”.



“c8y command” node

The following node allows you to receive a command sent by the Cumulocity server. As

output it will initialize the payload with the command text. If the command fails, the

payload will be empty or the message object will have a “failed” field.



For more information on events, refer to “Shell”.



https://cumulocity.com/guides/concepts/domain-model/

https://cumulocity.com/guides/users-guide/device-management/#shell


“c8y config” node

The following node allows you to receive a command sent by the Cumulocity server. As

output it will initialize the payload with the configuration text. If the command fails, the

payload will contain a non string value or the message object will have a “failed” field.



For more information on events, refer to “Configuration”.



“c8y response” node

The following node allows you to send the result of a command to the Cumulocity server.

As input the node expects a message routed from the “c8y command” or “c8y config”

nodes.



“c8y platform” node

This node is not visible in the list of nodes as it is used as a configuration which can be

shared by multiple nodes. The configuration node defines the type of connection and the

credentials which will be used to communicate with Cumulocity.


To be able to use the configuration, the type of provision has to be specified (“Manually”

or “Automatically”).

In case of “Manually”, the user has to enter a tenant, username and password. After

starting the workflow, the nodes which use this configuration should be able to connect to

Cumulocity, provided that the credentials are correct.

In case of “Automatically”, the user can enter a servername and authentication string. If

not, the node will use default values. Before or after starting the workflow, the user has to

register the device with its serial number in the desired tenant. For more information on

registering devices, refer to “Connecting devices manually”. After accepting the device in

the tenant, the nodes which use this configuration should be able to connect to

Cumulocity, provided that the credentials are correct.

LuvitRED example

The following example workflow is a bit more complex but shows a possible use case.

Imagine that you have a device which measures the temperatures and publishes the

measurements via MQTT. With the help of the “MQTT” node in LuvitRED, we are able to

subscribe to the channel the measurements are published on.

https://cumulocity.com/guides/users-guide/device-management/#device-registration


After the measurement was received, the “json” node converts the input to JSON format.

Then the “switch” node decides to which node it will forward the input to depending on a

user-defined condition. In this case, if the temperature is above a certain threshold, an

alarm will be sent. Otherwise, a measurement will be sent to Cumulocity.

If you do not have a device which supports MQTT, you can use this workflow instead to

simulate such a device.

This workflow uses two “inject” nodes to simulate a measurement which triggers either

the “c8y measurement” node or the “c8y alarm” node in the other workflow.

Import/Export LuvitRED flows

To facilitate the reuse of workflows LuvitRED offers the possibility to import/export

workflows.

Export LuvitRED flows

To export your workflows, you can either use the LuvitRED or Cumulocity user interface.

If you want to use the LuvitRED user interface


Click on the icon in the top right corner to open the menu.

Go to the menu item “Export”.

Select “File - All nodes”.

Choose a name for your JSON file.

Click on the “OK” button.

If you want to use the Cumulocity user interface, you have to make sure that one of your

workflows contains a “c8y” node with a correctly configured “c8y platform” configuration

node. Moreover, the “Flow deploy ?” checkbox needs to be checked in this “c8y platform”

configuration node.

Navigate to your CloudGate device in the “Device Management” application.

Open the “Configuration” tab.

Click on the “Get new snapshot from device” button.

After the command successfully completed, you can find the JSON file in the

“Configuration repository” menu.

Note that if there is no correctly configured “c8y platform” configuration node in your

workflows, Cumulocity will not be able to communicate with the device and therefore will

not be able to retrieve the JSON file.

Note that when a “c8y platform” configuration node contains credentials (usernames and

passwords), these are not exported via the LuvitRED editor.

Import LuvitRED flows

To import your workflows, you can either use the LuvitRED or Cumulocity user interface.

If you want to use the LuvitRED user interface

Click on the icon in the top right corner to open the menu.

Go to the menu item “Import”.

Select “From File”.

Click on the “Choose a file” button.

Navigate to the JSON file you want to import and select it.


Click on the “OK” button.

If you want to use the Cumulocity user interface, you have to make sure that one of your

current workflows contains a “c8y” node with a correctly configured “c8y platform”

configuration node. Moreover, the “Flow deploy ?” checkbox needs to be checked in this

“c8y platform” configuration node. When importing, your current workflows will be

replaced with the workflows in the JSON file so make sure to save workflows that are not

to be replaced, too.

Navigate to your CloudGate device in the “Device Management” application.

Open the “Configuration” tab.

Go to the “Apply new snapshot” section and select the JSON file you want to

import in the drop-down menu.

Click on the “Put new snapshot to device” button.

After the command successfully completed, refresh the LuvitRED tab in your

browser. You should be able to see the imported workflows now.

Note that if there is no correctly configured “c8y platform” configuration node in one of

your current workflows, Cumulocity will not be able to communicate with the device and

therefore will not be able to push the JSON file onto the device.

The workflows should start automatically as soon as they are imported which means that

it is not necessary to deploy them, provided that the “c8y platform” configuration node(s)

in your imported workflows were configured correctly.

CloudGate - devicepartnerportal.softwareag.com

Documents

Transcript of CloudGate - devicepartnerportal.softwareag.com