Management & Publishing¶

This page provides information for managing & publishing EveryCloud IoT Connectors.

EveryCloud re-use all the concepts from standard IoT Connectors and it is assumed you are familiar with the related concept and connectivity information.

Creating an EveryCloud IoT Connector¶

As an official extension of a standard IoT Connector you can follow the building connected devices IoT Connector information with the difference of selecting the Connector-as-a-Service IoT Connector template from the Exosite marketplace.

It will display as any other IoT-Connector on the Home solution list page in your Exosite account.

At this point, the IoT Connector service is still private to your account but can be published publicly on the Exchange Marketplace .

Management with Device Tags¶

EveryCloud connectors use the Tags functionality in IoT Connectors to manage Device ownership. Tags can be managed from the IoT Connector Management page under the Devices tab.

EveryCloud uses the following device tags:

While Tags are handled by the EveryCloud built-in functionality, you can also use the IoT Connector management interface to manually assign each device's tag values.

Usage Example:

• Update a device claim_code tag to change to a new claim code for a new device owner / transfer.
• Remove the users tag to reset a device Ownership.
• Add an application ID to the apps tag of a device to route device data to the application without the need of a user claim.
• Fetch all devices own by a given user with the tag search functionality. On the devices list select the tag column to users. Then type the user email in the search bar.

Claiming Management¶

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

EveryCloud provides a default setup for this purpose.

1. When provisioning a device, a claim code is provided or generated (default is the device's unique 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 enters the claim code in the device registration portal or in a compatible application.

Claim QR Code¶

For ease of the device owner, we suggest to provide the claim code as a printed QR code targeting the EveryCloud Portal URL.

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

The QR code is generated using one of the following Claiming URL formats.

Standard Format

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

ExoSense Only Format

Only works with ExoSense, will not take device owners to the device registration portal

<productid>.<claim code>

To get this information, open the management page for the EveryCloud IoT Connector in your Exosite account.

You will need to get the following information:

• The IoT-Connector Portal Domain URL, from the top left |www| icon.
• The Connector Id, from the from the top left ID icon.
• The Claim Code for each device (See Tags above)

The claim URL format above can be used with one of the many tools for generating simple or branded QR codes (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 Claiming¶

EveryCloud 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:

User Management¶

EveryCloud uses the Murano user service as user management system and accessible on the End Users tab of the IoT Connector management page in your Exosite account.

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, EveryCloud 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:

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 the Device Tags section above.

Publishing¶

By default the EveryCloud IoT Connector is only available to Applications in the same Murano Business account.

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

1. Navigate to the IoT Connector management page
2. On the bottom left, click on the PUBLISH AS A SERVICE button
3. Input the required information

Important: the Element's 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

1. 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 Registration Portal¶

The EveryCloud exposes a web portal for the user to claim and managed his devices.

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

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

Note:

• To update a file make sure the path matches exactly the default one.
• All branding files can be found under the /vendor path. You can use the search box to only display them.

Following files are use for the branding:

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.io/",
    "helpDevice": "https://docs.exosite.io/",
    "helpApp": "https://docs.exosite.io/"
  },
  "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

Although end-customers interact with the device, the OEM / VAR (Product publisher) owns the root IoT Connector profile and thus 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 application 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. 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.

Firmware OTAU¶

Manage Firmware versions and make device firmware updates available for devices owners. This relies on Exosense OTAU (Over the Air Update) scheme available here. You can directly add your firmware package in IoT Connector by uploading it on Content tab. Note you need to provide a json containing metadata of your file, such as name, version... And note that a firmware is presently exposed to all devices. There isn't such tag system to expose firmware updates to a limited set of devices. It may change in the future.

Requirement: First of all, you need to add an env variable. Go to Settings-> ENV VARIABLES. Choose EnableFirmwareUpdate and change value to enabled.

Go to Content and start uploading your firmware packages. Upload also corresponding metadata in a json file. Metadata filename must start with package_ and be in json format. Example of metadata file:

{
    "author": "example@mail.com",
    "product": "myConnectorwithOTAU",
    "config_otau": {
        "version": "1.0.1",
        "name": "new-version-otau",
        "description": null,
        "type": "URL_LIST",
        "payload": [
            "test-otau-1.0.1.tgz"
        ]
    }
}

Then conform uploaded packages with accurate metadata will be exposed on platform, and device owners will be notified of potential updates. They will have possibility to update or not, and choose any version of firmware.

Note : You can use the IoT-Connector API feature if needed, for example if you want to directly update firmwares instead of let choice to device owners. This endpoint can update a batch of devices, that must be managed by you (authorization in header for request must be filled with the token associated with user session). POST /api/firmware/update Add in request body :

{
  "message": "<config_otau_resource_json>",
  "devices": ["<identity_device_1>", "<identity_device_2>", ..., "<identity_device_n>"]
}