IoT-Connector (Aka. Product) Management Page

This reference manual breaks down each page of Murano's device connectivity feature set and provides descriptions of each component's functionality. All device connectivity offerings are located within the realm of your IoT-Connector Solution page.

The Murano management for IoT-Connectors is similar as the one for Murano Applications as both shared the same structure of script & events called Murano Solution. Look on the solution development page to learn more about Services, Endpoints, Modules, End-Users or Web-Assets.

Table of Contents


Devices

Devices tab

The Devices page is where you will add, list, and manage all your devices (real or simulated). Once you have populated your list of devices, you will have the capability to search, sort, and filter your device list to suit your needs.

Devices Empty

When you click the “+ NEW DEVICE(S)” button, you will have the option to add one device or many devices at once. Depending on your account tier, there may be a limit on the number of devices you are able to add.

Add device popup

NOTE: Near the top-left of the screen you will see a button that, when clicked, will copy the App Link to your clipboard. This link is the host name that has been created to receive your devices' outgoing API calls. If devmode is enabled (discussed in the Settings section, below), an additional endpoint is enabled for devices to connect to unsecured on port 80. This unsecured endpoint is nearly identical to the endpoint except https is changed to http and .m2. is changed to .devmode-m2. (e.g. http://09iolmnn8090ol.devmode-m2.exosite.io).

Copy domain

Devices information are powered by the Murano Device2 Micro-Service and are accessible from scripting. To Connect devices use one of the supported Device APIs.

Locking

This feature allows Murano administrators to revoke the communication privileges on a per-device basis. Marking a device as locked will cause all connection attempts by the device to be ignored. This can be useful, for example, in development or during in-field management to temporarily disable device communications.


Resources

Resources tab

The Resources page is where you may add attributes (or "alias"es) to your devices (e.g., temperature, status, etc.). Resources represent a device's digital twin in the cloud, like a data model shared by all devices. A resource is identified by its alias, and the resource's unit (e.g., °C) can be specified to further clarify the alias's measurement. It is possible to restrict values to ranges (0-100) or to discrete values ("open", "closed", "jammed"). The current resource value for a given device is visible when browsing the device in the project and is accessible to scripts, which can then act on reported values in any number of ways.

resources list

When you click "+ NEW RESOURCE", you will be prompted to choose your data format.

You will also be given the option to "modify this value from the cloud." Leaving this box unchecked will allow only the device itself to write to the alias. Checking this box will allow other applications to modify the value of the resource, depending on the permissions you have put in place.

resource popup

Limitation: Resources are limited in size to 64Kb each.

Learn more about resources on the Device2 micro-service reference or see the related Quickstart Example.

Un-defined resources

Devices are not restricted to write to only defined resources. Devices write to "alias"es which may or may not correspond to defined resources. All device messages are sent via the Device2 micro-service event handler to the script and can be processed as other device message, but only writes to defined resources will have the value stored in the device state under the "reported" values, available to devices via "read" and visible when viewing the device data.

Set resource to send data to the device

Typically, devices report values to resources that are "read-only" in the cloud. It is possible to enable sending data to the device with the "Send data from the cloud" option, which can be used to support command-and-control behavior. This is done through the setIdentityState Device2 micro-service function. All resources have a "reported" value which represents the last value written by the device (using the write API). Resources that are cloud-writeable have an additional "set" value containing the value to send to the device. The device is then expected to acknowledge the received value which updates the "reported" to match the "set". Devices will use either the read API or the long-polling API to receive control requests and then write appropriate resource updates to reflect its having acted on the request. When fetching the device state from the scripting you will have access to both values.

Notes: You can also disable the synchronization for a give resource, if so the "set" & "reported" will always be the same, and the data will not get pushed to the device. However the device can still actively access it on demand.


Content

Content tab

The Content page serves as a secure file store powered by the Murano Content Micro-Service. Click “+ NEW CONTENT” and follow the prompts to upload your files. Each content item has an ID, a MIME type, a size (in bytes), and a timestamp. In IoT-Connector, those files can be accessed by your devices through the device API. Devices may list available content, get content info, download and upload content using the HTTP Device API.

Content

There is no restriction as to the kind of content that can be made available to devices. Files can contain anything from audio/video content to config data, but the typical use case is to store firmware updates. For content that gets updated over time, such as with new firmware versions, it is recommended to include in the ID some kind of version tag. Whether this approach is taken or the content is updated in place and a timestamp is used to differentiate, devices will need a means to know which version they are at. Exosite recommends storing this information in a Resource. Additionally, if the resource is cloud-modifiable, the device can be notified when new firmware is available.

Note: Content items must be less than 64 MB in size.


Logs

Logs tab

The Logs page is where you may access a connection log of each device’s meta data and a "live" view that displays events associated with a product's API endpoint that came in while the Murano product UI was running. When devices connect, disconnect, make provision attempts, and publish data, these events will be logged. The logging events are not saved, so they can only be viewed in real time either by the Logs section in the IoT-Connector UI or Murano CLI. This is most useful in debugging and development applications.

Logs empty


Settings

Settings tab

The Settings page allows you to configure the Protocol, Identity-Format, Authentication, Provisioning and Public Key Infrastructure settings to control what protocol the devices will use to communicate with Murano, how they identify themselves and how they authenticate.

Settings


Protocol

Determine how your devices communicate with the platform.

NOTE: Enabling the "Enable Developer Mode" checkbox allows unsecured HTTP communications on port 80. Unsecured HTTP communications can be read by third parties who are able to intercept the communications, thereby potentially exposing sensitive information. Although this setting can be useful during certain stages of device development, or in unique payload-level-encrypted systems, it should not typically be enabled.

Settings protocol


Identity Format

This feature defines how connecting devices must identify themselves or be considered invalid and ignored in successive communication attempts. Devices are identified differently based on the authentication method chosen—Token or TLS Client Certificate. In the case of Token authentication, the identity of the connecting device is determined by the id field of the HTTP Device activate API method. In the case of TLS Client Certificate authentication, the identity of the connecting device is determined by the common name /CN value of the client certificate. In both of these methods, the Identity Format must be adhered to in order for the device to be recognized in communication requests.

NOTE: Devices that attempt to connect that do not match this format will be ignored for security reasons.

Settings provisioning


Provisioning

The Presenter Identity configuration setting allows devices to identify and provision themselves at the time they first connect to Murano. The Presenter Identity setting simply means that devices connecting to a Murano device gateway do not need to have their identity be whitelisted in advance and that the Murano device gateway will auto-whitelist the identity the device "presents."

When set to true (default), allows devices to provision themselves and any device identity to communicate with the Murano device gateway. When set to false, devices connecting must first be whitelisted onto the device gateway in order for its requests to be honored.

See our provisioning documentation for a complete guide.

NOTE: When provisioning a device, the device may present its own identity (assuming "Allow devices to register their own identity" is selected). Such devices will have an identity (such as a MAC address) that must match the specified format. It is possible for illegitimate devices to successfully provision; presented identity provides a slightly greater barrier due to its identity format validation.

IP Whitelisting

IP Whitelisting can be used to restrict device provisioning. The IP whitelisting manages known IP addresses that devices will connect from when connecting to Murano for the first time. This feature is useful to IoT vendors working closely with hardware manufacturers. If a connecting device's requests originate from an IP address not in the configured whitelist, then the device will be ignored. Once the device has connected from an IP address in this whitelist, it can make successive requests from any other IP, and its requests will be honored.


Authentication

The authentication setting defines how devices needs to security identify themselves to the cloud. Devices connect to Murano using their unique IoT-Connector domain. This fqdn (fully qualified domain name) can be found in the IoT-Connector UI as well as via the Device2 getGatewaySettings API method. Secure connection relies on TLS protocol and we invite you to our TLS reference page.

Also see our provisioning documentation for a complete guide.

Settings Authentication

Following options are supported:

Token

When the Token method of authentication is selected, a device can provision a private authentication Token to be used in subsequent communications to uniquely identify and authenticate itself to the Murano device gateway. If provisioning is disabled, then device authentication Tokens must be managed via Murano CLI and UI tools and manually associated and stored on the device.

NOTE: An authentication option available with the Token method can disable the use of TLS connections, allowing unsecured HTTP communication between a device and the Murano device gateway. The use of this option is highly discouraged and maintained in Murano as a development tool for easing the validation and development of firmware on a device connecting to Murano.

NOTE: Then Authentication Token is sometime mentioned as "CIK" as compatibility with Exosite legacy plateform.

Password

When the Password method of authentication is selected, a device can provision credentials for the given Password (at least 20 characters) to be used in subsequent communications to identify and authenticate itself to the Murano device gateway. If provisioning is disabled, then device authentication Password must be managed via Murano CLI and UI tools and manually associated and stored on the device.

TLS Client Certificate

When the TLS Client Certificate method of authentication is selected, a device uses a unique X509 private and public key that Murano uses to both authorize and identify the connecting device. Murano will use the X509 credentials (which can be provided by a PKI vendor or it can be self-signed) to identify and authenticate the device. Certificate based authentication has two flavors:

Without certificate verification

This allows clients to connect to Murano with a certificate (self-signed or signed by a Certificate Authority). Murano will extract the common name /CN=<value> from the certificate and use the <value> to identify the client. Then, it will use the certificate as a password to verify the client's authenticity.

With certificate verification against a Certificate Authority (CA)

It is possible to enable and configure a Certificate Authority (CA) for an IoT-Connector under its Protocol settings. If CA is enabled and configured, the certificate presented by the client will be verified against the configured CA. If the configured CA was its issuer and certificate has not yet expired, authentication will be successful. Otherwise, authentication will fail. If CA has not been enabled or it has been disabled and a client connects with a certificate, authentication will fall back to the authentication "Without certificate verification" method.


Public Key Infrastructure

A Public Key Infrastructure is a set of roles, policies, and procedures needed to create, manage, distribute, use store, and revoke digital certificates and manage public-key encryption, see our provisioning documentation page.

NOTE: This option is only relevant for TLS Client Certificate Authentication.

Settings PKI