CloudCat Service

The CloudCat Service replicates messages published to one CloudService instance to another one, performing the following operations:

1. The service obtains two CloudClients from two different CloudService instances specified in the service configuration.
2. For each CloudClient, the service subscribes to a set of topics specified in the configuration.
3. Message received by the service on one of the two CloudClients will be re-published on the other one.

This service allows for example to share an existing cloud connection to external applications using the Artemis broker. An example of this use case will be presented below.

Instance creation

In order to create an instance of the CloudCat component perform the following steps:

1. Press the + button under Services in the ESF Web UI.
2. Select org.eclipse.kura.misc.cloudcat.CloudCat from the Factory drop down list.
3. Enter an unique name for the new instance in the Name field and press Apply.

Service configuration

In order to review the configuration of a CloudCat instance, click on the corresponding entry under Services:

The following configuration options are available:

• Relay Enable: Enables or disables the CloudCat instance
• First/Second Cloud Service PID: These properties specify the Kura Service Pid of the CloudService instances to be used.
• First/Second CloudClient App ID: The application ID to be used by the CloudCat service on each cloud service.
• First/Second CloudClient Control Subscriptions: A list of control topics to subscribe to on on each CloudClient as a comma separated list of control-app-topic;Qos pairs.
• First/Second CloudClient Control Subscriptions: A list of data topics to subscribe to on each CloudClient as a comma separated list of data-app-topic;Qos pairs.

The CloudCat service will replicate all messages received on each of the control or data topics specified in the configuration to the other CloudClient, the complete topics will have the following structure

• Data Topics: #account-name/#client-id/#app-id/#data-app-topic
• Control Topics: #control-topic-prefix/#account-name/#client-id/#app-id/#control-app-topic

where:

• #account-name is the value of the topic.context.account-name configuration property of the MQTTDataTransport instance in use.
• #client-id is the value of the client-id configuration property of the MQTTDataTransport instance in use, if this parameter is empty, the MAC address of the primary network interface of the device will be used.
• #control-topic-prefix if the value of the topic.control-prefix configuration property of the CloudService instance in use.
• #app-id, #data-app-topic, #control-app-topic are obtained from the CloudCat configuration as described above.

When a CloudCat instance forwards a message from one CloudClient to another, only the #data-app-topic or #control-app-topic part of the topic is preserved, the remaining parts are translated to match the configuration of the CloudService on which the messages are published.

❗️

Note: The set of topics specified for data or control topic subscriptions on each CloudService instance should be disjoint. If this condition is not verified, and a CloudCat instances is subscribed to a same topic on each CloudService instance, message loops may occur.

Use case example

The example below shows how to share a cloud connection managed by Kura with an external javascript application using the embedded Artemis broker and CloudCat:

Enable the embedded Artemis broker instance

1. Connect the default CloudService instance to your favourite cloud platform.
2. Enable the Simple Artemis MQTT Broker service by configuring it as follows:

• Enabled: true
• MQTT address: 0.0.0.0
• MQTT port: 1883
• User name: artemis
• Password of the user: foo (or any other password)

3. Open the MQTT port specified above in the firewall configuration.

Connect a CloudService instance to the Artemis broker

1. Navigate to the Cloud Services section of the Web UI
2. Click on the New button and create a new CloudService instance with the org.eclipse.kura.cloud.CloudService-ARTEMIS Cloud Service PID.
3. Configure the new instance as follows:

• MqttDataTransport-ARTEMIS -> broker-url: mqtt://localhost:1883/
• MqttDataTransport-ARTEMIS -> topic.context.account-name: artemis
• MqttDataTransport-ARTEMIS -> username: artemis
• MqttDataTransport-ARTEMIS -> password: foo, (or any other password used at step 2)
• MqttDataTransport-ARTEMIS -> client-id: cloudcat-relay
• CloudService-ARTEMIS -> encode.gzip: false
• CloudService-ARTEMIS -> enable.default.subscriptions: false
• CloudService-ARTEMIS -> birth.cert.policy: Disable publishing
• CloudService-ARTEMIS -> payload.encoding: Simple JSON
• DataService-ARTEMIS -> connect.auto-on-startup: true

The settings above define a "raw" CloudService that uses JSON as payload encoding and does not perform gzip compression. This is intended to use a message format that is easily manageable by a external Javascript application. Default subscriptions and birth certificate publishing can be disabled as these features are not needed when connecting to the embedded Artemis broker.

Create and configure a CloudCat instance

1. Create a new CloudCat instance as shown above.
2. Configure the instance as follows:

• Relay Enable: true
• First CloudService PID: org.eclipse.kura.cloud.CloudService
• Second CloudService PID: org.eclipse.kura.cloud.CloudService-ARTEMIS
• First CloudClient App ID: cloudcat
• Second CloudClient App ID: external-app
• First CloudClient Control Subscriptions: leave blank
• Second CloudClient Control Subscriptions: leave blank
• First CloudClient Data Subscriptions: in;0
• Second CloudClient Data Subscriptions: out;0

Create the external Javascript application

Create an HTML file containing the following code:

<html>
<head>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/paho-mqtt/1.0.1/mqttws31.min.js" type="text/javascript"></script>
</head>
<body>

  <script>

  var HOST = 'gateway-ip'
  var CLIENT_ID = 'external-app'
  var USER_NAME = 'artemis'
  var PASSWORD = 'foo'
  var PUBLISH_TOPIC = USER_NAME + '/cloudcat-relay/external-app/out'
  var SUBSCRIBE_TOPIC = USER_NAME + '/cloudcat-relay/external-app/in'
  var PUBLISH_RATE_SECONDS = 10

  var log = (function () {
    var body = document.getElementsByTagName("body")[0];
    return function (message) {
      var paragraph = document.createElement('p')
      paragraph.textContent = message
      body.appendChild(paragraph)
    }
  })()

  var subscribe = function(topic) {
    log('subscribing to ' + topic + '...')
    client.subscribe(topic, {
      onSuccess: function() {
        log('subscribed to ' + topic)
        client.onMessageArrived = function (message) {
          log('received message on topic ' + message.destinationName)
          log('payload: ' + message.payloadString)
        }
      },
      onFailure: log
    })
  }

  var startPublishing = function(topic) {
    setInterval(function () {
      try {
        client.send(topic, JSON.stringify({
          metrics: {
            intMetric: 1,
            stringMetric: 'test string'
          }
        }))
      } catch (err) {
        log(err)
      }
    }, PUBLISH_RATE_SECONDS * 1000)
  }

  var client = new Paho.MQTT.Client(HOST, 1883, '/', CLIENT_ID)
  client.connect({
    timeout: 30,
    userName: USER_NAME,
    password: PASSWORD,
    useSSL: false,
    onSuccess: function () {
      log('connected')
      startPublishing(PUBLISH_TOPIC)
      subscribe(SUBSCRIBE_TOPIC)
    },
    onFailure: function (err) {
      log('connection failed')
      log(JSON.stringify(err))
    }
  })

  </script>
</body>
</html>

Modify the HOST constant in the code by replacing gateway-ip with the IP address of the gateway in use, and then open the created file in a browser.

This application uses the Paho javascript MQTT library to connect to the broker instance using WebSocket, the application subscribes to the artemis/cloudcat-relay/external-app/in topic and publishes messages to artemis/cloudcat-relay/external-app/out.
The topics above are mapped to the following topics on the device cloud connection by the CloudCat service:

Where #account-name and #client-id are the identifiers used on the cloud platform.

Messages published by the application can be viewed by using the Web console of the cloud platform used under the #account-name/#client-id/cloudcat/out topic.

Messages published on the #account-name/#client-id/cloudcat/in topic on the cloud platform will be received by the CloudCat and then forwarded to the external application that will log them on the browser window.