Cloud-Connectors

A common use case occurs when available hardware is already connected to a 3rd party API and you wish to connect them to your Murano Application (Eg. ExoSense or ExoHome).

For that purpose, Murano supports a standard Cloud-To-Cloud integration. This integration is compatible with Murano applications provided as IoT-Connector templates. Those Cloud-Connectors can be managed and connected to Application the same ways as Standard IoT-Connectors.

Table of Contents


Existing Cloud-Connectors

On Exchange IoT-Marketplace under IoT-Connector you will find the IoT-Connector Templates section.

This section contains various connectivity templates including popular 3rd party APIs like AWS IoT or Sigfox. Those templates are already customized to provide is zero-development integration experience.

The element details will inform you about the required configuration steps unique for each integration.

Select your template and click Create IoT-Connector.

Notable Integration

Sigfox
AWS-IoT
RadioBridge
ElectricImp
Ewon
MachineQ
OpenWeatherMap
TheThingsNetwork

Configuration

Follow the steps documented on the IoT-Connector exchange element details page. It usually requires to setup your 3rd party API access credentials by navigating to your IoT-Connector page under the Services -> <3rd party api name>.

Data transformation

Your hardware model might have some unique data structure not compatible with ExoSense data model.

For this purpose, Cloud-To-Cloud templates provided a set of customizable scripting modules allowing you to apply the data transformation to & from the 3rd Party API.

You can directly update those modules' logic through Murano scripting Editor under your Cloud-Connector Modules->vendor.c2c.transform. While not mandatory, you probably want to have a look at the Murano Scripting reference to give you more context on the scripting.

Note: The vendor name-space is 'safe' and will not be updated if the Cloud-Connector is updated to a newer version of the template. However any modification made outside of the vendor name-space will be lost.


Create Your Own

If you cannot find your 3rd party API listed on the Exchange Marketplace, you might need to do the integration using Murano scripting & integration capabilities.

Thankfully you can re-use the same base template, used by all standard Cloud-Connectors, to make your integration easier and ensure compatibility with Murano applications.

The Cloud-Connector base template is a public Github repository published by Exosite. You will find all the necessary information there.

You can create either a uni-directional (monitoring only) or a bi-directional (monitoring, configuration, and control) C2C Connector.

To create your own uni-directional C2C Connector from a web service that can POST to Murano:

  1. Deploy the standard Cloud 2 Cloud Example
  2. Click "Home" to see your list of the solutions and click the one you deployed to "Manage IoT Connector"
  3. In the upper left side of your screen, you will see a small "WWW" icon - click that and your browser will take you the external URL for your new C2C Connector. Copy the URL (e.g. https://testc2c101.apps.exosite.io/).
  4. In the external cloud service, enter the URL along with a "c2c/callback" at the end (e.g. https://testc2c101.apps.exosite.io/c2c/callback) - this is the specific URL the cloud service will POST data to
  5. If the external cloud service will send an Authorization header or a parameter with an authorizaton token in it, copy the token and go to the Services sub page for your C2C Connector, find the Web Service, and set the configuration parameter "callback_token" to the token you copied
  6. Go to the "Logs" sub page for your C2C Connector and view the Solution Logs. In the external cloud service, generate some activity that will POST data, and confirm you see logs generated in the Solution Log page. If no logs are generated, it probably means the POST URL was incorrect or the external cloud service is not sending data. To further debug that, try using https://requestbin.com as a target for your external cloud service to see if it can post data to a https://requestbin.com URL.
  7. If logs are coming in, it is time to configure the details... go to the "Modules" sub page for your C2C Connector - you will want to modify the "vendor" modules vendor.c2c.transform and vendor.configIO
  8. In vendor.configIO, modify the example already there to describe the data you want to send along to the app - the data types document has details on those settings.
  9. In vendor.c2c.transform, fixup the incoming clouddata to be in a JSON array format, with object identifiers matching those defined in configIO. Also, ensure the returned "identity" is a unique identifier for the entity (e.g. device or sensor) to which the data payload belongs (Murano will create virtual devices for each unique identifier).
  10. That should be it! If the Logs show "Endpoint POST /c2c/callback done with code=200" with every incoming POST, and new devices are populated in the Devices sub page whenever a new identity sends data, you are likely in business!
  11. To use your newly configured C2C Connector in an Application, you can either publish it as a Service and then use the IoT Marketplace to "Add to Solution" to associate it with your Application. Or, if you have sufficient Murano priveleges, you can click "Manage Application" from your Home page, go to the Services sub page, and enable your C2C Connector in the "IoT Connector Setup" service.

To create a bi-directional C2C Connector, you need to additionally define the remote API using OpenAPI v2 swagger and publish it as a Murano-Service on the Exchange Marketplace. Refer to the Module "c2c.murano2cloud" to see the desired default features a bi-directional implementation should support.

If you want to make more significant changes or to share your work with others:

  1. Fork & customize the Cloud-Connector base template to fit your integration need
  2. Publish your new template to Exchange
  3. Make both the Service (describes the external cloud APIs) and your new C2C Connector template Public

You may also want to become familiar with: