Connector-as-a-Service (Aka PdaaS) Publisher Reference

This page provides information for managing & Publishing IoT-Connectors-as-a-Service to enabling connecting multiple custom to a centralized IoT-Connector.

If you haven't yet, read the Connector-as-a-Service introduction

Connector As-a-Service re-use all concepts from Murano standard IoT-Connectors and we assume on this page you are familiar with the related concept and connectivity questions.

Table of Contents

To learn how to integrate User applications, refer to the IoT User documentation.


Creating a Connector-as-a-Service

As an official extension of a Standard IoT-Connector you can follow the Create a Murano IoT-Connector product guide with the difference of selecting the Connector-as-a-Service template item.

It will display as any other IoT-Connectors on the Home solution list page.

Notes:

The next step is to customize the micro-site branding for your product.

At this point, the Connect-as-a-Service is still private to your account. Read the Publish on the Exchange Marketplace section for making it public.


Management with Device Tags

Connector-as-a-Service uses Tags metadata to manage Device ownership. Tags can be managed from the IoT-Connector page under the Devices tab.

Connector-as-a-Service uses the following device tags:

Tag name Usage Format
claim_code The claim codes(s) for user to claim the device Any string, by default set to the Device ID
expires The expiration time of the claim code Unix Timestamp in seconds eg. 1572768760
apps The application(s) allowed to access the device data. Murano App ID, eg. i18ocqqozws800000. External Apps starts with the ext_ prefix followed by a random unique number.
app:<app id>:<name> Application defined tag. And name-spaced for isolation. Eg. app:i18ocqqozws800000:mytag.
users The owner(s) of the device. The user ID is the one from the End Users tab.

While Tags metadata are managed by the Connector-as-a-Service you can also use the Tag edition interface to manually assign their value.

Usage Example:


Claiming Management

Claiming is the mechanism allowing to associate a device with its owner.

IoT-Connector-as-a-Service provides a default setup for this purpose.

  1. When provisioning a Device: a Claim Code is provided or generated (Default to device ID) and saved in each device metadata tags.
  2. The Claim Code or its QR code format must be provided to the User acquiring a device.
  3. The user enter the Claim Code in the IoT-Connector Portal or in a compatible application. Find more details.

Note: A single Claim code can be assigned to multiple devices. Once claimed the user get ownership of all devices at once.

Claim QR Code

For ease of the Device Owner, we suggest to provide the Claim Code as a printed QR Code targeting the Connector-as-a-Service Portal URL.

The user can then use any QR code reader on his mobile device to Claim devices in a single click.

QR Code Url format:

First open the created Connector-as-a-Service management page from the Murano IoT-platform list of Connectors.

You will need to get the following information:

top left icons

Note: If the Claim Code contains special characters, you must URL encode it.

Now you can build the follow Url for each Device:

https://<Connector Domain>/#/?claim=<Claim Code>&product=<Connector Id>

And use one of the many tools for generating simple or branded QR codes from the URL (Eg. www.qr-code-generator.com).

To avoid the need of printing the QR Codes, you can instead provide the full claiming URL by electronic mean.

If you do not wish to generate a different QR Code for each device.

You can generate a single QR Code with URL:

https://<Connector Domain>/#/?claim=

And provide the Claim Code separately for user to type manually.

Input Enabled Devices

For Devices with input capabilities, the Claim Code can be fully by-passed and instead at first start the user is prompt to enter his email address.

The device firmware then uses the Device API claim functionality to pass the user email to the Connector-as-a-Service which notify the user with a welcome email.

Note: Claiming from the Device-API only works if the Device has no current Owner.


Device API

Connector-as-a-Service uses the device API to enable devices to interact with the Claim logic. For that purpose following device resources state are used and can be interact with from the device firmware:

Resource name Usage Format
pdaas_claim_code Set the claim code by one generated by the Device. Useful if devices is able to dynamically generate and display the Claim QR-Code. Any string
pdaas_user_email The new owner email. Will not apply if a current owner exists. Valid email address
pdaas_reset Hard reset: Remove device apps & users. Claim-codes remains for user to claim the device again. true

User Management

Connector-as-a-Service use the user service as user management system and accessible on the End Users tab of the Connector UI.

From there you can list/search/create/update/block or set a user password.

Application Access

To define which application a user has access to, PDaaS is utilizing the User Data accessible on the details view of the End Users panel.

In User Data the applications are defined using an app_ key prefix followed by the app ID. The value is a JSON string containing the user options for this app.

Supported options:

Option key Usage Format
default Indicate if the app have to be added by default to all new devices from that user Boolean

Example: app_i18ocqqozws800000 = {"default": true}

Assigning Devices

To assign manually a device to a user, navigate to the device details panel and add a tag with name = users and value = . See Management with Device Tags.


Publishing

By default the Connector-as-a-Service is only available to Apps in the same Murano Business account.

Follow next steps to make it available publicly on the Exchange IoT Marketplace.

  1. Navigate to the Connector management page
  2. On the bottom left, click on the PUBLISH AS A SERVICE button
  3. Input the various required information
    • Important the Element name cannot be changed later, choose a relevant name to the device Brand and Model connecting to the connector. Eg. Mybrand gateway device model XX
  4. Click PUBLISH TO EXCHANGE

Share Privately

It is possible to only share the IoT-Connector to targeting Businesses (and not to public to all).

First, you need the target Business Id(s). Then navigate to the IoT-Connector page under the Services -> Interface setting page.

You will find a whitelist option. Click on the right icon to add a new entry and past the above target Business Id.

Click Apply to complete the operation.


Branding

The Connector-as-a-service expose a Web Portal for the user to claim and managed his devices.

As a hardware provider, you want to show case your product and the branding ability will make user agnostic of Exosite brand.

For setting up your branding you only need to upload the related Static Web Assets using the Connector management page under the Web Assets panel.

Note:

Following files are use for the branding:

File name Usage Format
/vendor/branding.json A Json encoded structure defining textual information. JSON encoded. See branding fields for the details
/vendor/brandlogo.png Your brand main logo displayed in the Portal header. Image in png format
/vendor/device.png Device model picture, displayed on the Portal landing page. Image in png format
/vendor/favicon.ico The brand Icon. Eg, used for web-browser tab. Icon in png format

Note: All branding changes will persist Connector-as-a-service version update.

Branding fields

The /vendor/branding.json contains information displayed on the Portal as well as the colors to use. To update to your own, we suggest to first download the default file, update the needing fields and upload it again.

{
  "title": "Product portal",
  "description": "Product consumer portal page description",
  "companyName": "Exosite",
  "theme": {
    "primary": "#2C9DB6",
    "secondary": "#222736",
    "accent": "#F15C2E",
    "error": "#FF5252",
    "success": "#4CAF50"
  },
  "themeType": "dark",
  "links": {
    "info": "https://exosite.com",
    "terms": "https://exosite.com/terms-conditions",
    "contactUs": "https://info.exosite.com/contact-us",
    "help": "https://docs.exosite.com/quickstarts/iot-connector",
    "helpDevice": "https://docs.exosite.com/quickstarts/iot-connector#device",
    "helpApp": "https://docs.exosite.com/quickstarts/iot-connector#app"
  },
  "landingPage": {
    "mainSlogan": "This is your main slogan here",
    "secondarySlogan": "This is a secondary, more lengthy slogan right underneath",
    "deviceName": "B-L475E-IOT01A (model)",
    "deviceSpecs": [
      "Ultra-low-power STM32L4 Series MCUs ",
      "64-Mbit Quad-SPI",
      "(Macronix) Flash memory",
      "Bluetooth® V4.1 module (SPBTLE-RF)"
    ]
  }
}

Welcome Email

When a new user subscribes, a welcome email is sent for validation.

The email will use the branding files above for a consistent experience. However you can go further and customer the email content.

The email is stored in the vendor.template module and you can edit it directly on the Connector management page under the Modules panel.

That file contains 3 sections:

  1. globals : A map of variables to use in all the templates. Can contains either the string value or a function returning it. Use the format <%%VARIABLENAME%%> to define the variable and <%VARIABLENAME%> to user them in the template.
  2. types : The different emails type content. Each entry is a map of variables for that email type. Currently the only supported type is signup. Type content can contain global variables.
  3. t.TEMPLATE : The Html template including defined variables.

Data-Transformation

A typical need is to apply data transformation before forwarding the data to the applications.

For this purpose you can modify the vendor.transform module.


Customizing

Additional Services for the Product line

Because the OEM / VAR (Product publisher) owns the root IoT Connector profile, although end-customers interact with the device, the OEM/VAR is able to also view and manage devices, profiles, and data post-deployment. This is a significant benefit to support desk functions as well as for any applications in which the OEM / VAR provides value-added services around the end application the users may be using to interact with the devices. The PDaaS can be customized to add additional functionalities. Benefits Device health monitoring & predictive maintenance Fleet wide statistics

https://github.com/exosite/pdaas_template


Managed Application

Managed Application are apps displayed by default on the user portal and are provided by the Connector-as-a-Service publisher or authorized app provider.

Requirement: Any compatible User App can be used as Managed Application as long as they support multi-tenancy. Which means new End-Users can subscribe by themselves and have a fully isolated experience from other users.

The Managed App MUST use the same email as subscribed in the User portal for authentication. It is recommended that the Managed App use the Connector-as-a-Service provided and read-only 'users' device tag to manage the device ownership.

Set App as Managed

First connect your multi-tenant application to your Connector-as-a-Service instance. (Follow the user guide) and verify device data are routed as expected.

  1. Define your app metadata: Name, Description, Url & Logo of the application A. For Murano App, edit the settings on the Connector settings from the Application management Services B. For External App, edit on the portal app page
  2. Copy the App ID
  3. Navigate to the Connector-as-a-Service management page under the 'Settings' panel
  4. Next to the connectivity settings you will find the application variables tab
  5. Past the App ID in the 'Managed Apps' text box & apply your change
  6. All done! All users will now see the configured app in their Portal account

TIPS: You can specify multiple apps by separating them by commas. However mind to keep a good user experience as to many apps will make a crowded page for the user.