Messaging Service

The Messaging Service handles the communications between the devices and Everyware Cloud. Sending telemetry or logs from device to EC or execute device management operation from EC to a device require a Messaging Service instance. A Message Service instance can be a single broker or a network of brokers (later on called Broker Cluster). To let devices of an account connect to a Messaging Service instance, the account must be assigned to the instance. For the following accounts the assignment must be done explicitly by the platform administrators:

The root account (ec-sys)
The level-one child accounts (the children of the root account)

For all the other accounts the assignment is inherited from the ancestor account and cannot be changed. This means that all the account offspring of a level-one account share the same message service instance.

🚧
Missing to assign the account with its message service will prevent devices of that account to establish a connection with every existing messaging service.

Create a Messaging Service Instance

Within Everyware Cloud, each Messaging Service instance is identified by a name. The name is bound to a physical Broker Cluster instance that is deployed at the infrastructure level. Follow the steps at Installation and Scaling to create a new Broker Cluster deployment.

The Broker Cluster instance can currently support the following communication protocol options:

Plain MQTT over plain TCP protocol (potentially insecure)
Secure MQTT over TLS/SSL protocol
Secure MQTT over TLS/SSL protocol with Mutual Authentication

The communication protocols options configured for a Broker Cluster instance are available to all the accounts associated to the cluster. Each account, however, can have specific configurations defined in the Account Settings.

Check TLS parameters configuration in the installation guide.

📘
Secure MQTT and secure MQTT with Mutual Authentication require TLS is enabled and configured for the instance.

View Available instances

When a Broker Cluster instance is created and started it will be visible from within Everyware Cloud. Login to the Admin Console as a root account user and navigate to the Messaging Service view, an entry with the name assigned to the Broker Cluster at the step above should appear automatically.

Define Endpoints

Each Messaging Service instances must have Endpoints associated with it. The Endpoints define the address used by the devices to access the service. An Endpoint is defined by the following attributes:

Name	Default Value	Description
Schema		The URI scheme (e.g. mqtt, mqtts, ws, wss)
Domain Name		The host name of the Endpoint (e.g. broker-env.domain.com)
Port		The port to which the Endpoint is exposed
Secure	False	Whether the communication with Endpoint is using encryption or not (e.g. TLS).

To add a new endpoint you must connect as root account user with an administrator role. Switch the current account to the account to which the endpoints should be associated. then Select Endpoints view and click the Add button

When all the values are defined press the Submit button.

🚧
Endpoints can be updated or deleted. Deleting or changing endpoints in use can be dangerous and may impact the functionality of the system.

Publish Endpoints

Defining the Endpoints in Everyware Cloud doesn't automatically make them reachable from devices in the field.

Typically endpoints need to published to a name server (like a DNS) and linked to the address of the Broker Cluster instance that they represent. The way this step is implemented depends on the infrastructure layer used for the deployment and your specific infrastructure configuration. Contact your system administrator if you need to add and publish new endpoints for a Messaging Service instance.

Assign e new child account

After creating a new first level account named new-account:

Connect to the admin console using an ec-sys account administrator user
Select the Messaging Service on the left menu
Select the cluster entry you want to modify in the Messaging Service table
Select the Accounts tab in the lower part of the screen
Click on the Add button
Select new-account
Submit

Un-assign an already assigned account

An account can be unassigned from a message service instance and assigned to another one:

Connect to the admin console using an ec-sys account administrator user
Select the Messaging Service on the left menu
Select the cluster entry you want to modify in the Messaging Service table
Select the Accounts tab in the lower part of the screen
Select the account you want to remove
Click on the Remove button
Submit

🚧
While an account is in unassigned state its devices cannot establish connections with the previous messaging service (and any other).

After unassignment the account can be assigned to a new broker cluster.

Configure Connections

Once the account is assigned to a Messaging Service instance you should configure the type of device connections the Account is allowed to handle. The options currently available are:

Plain MQTT over TCP protocol (potentially insecure)
Secure MQTT over TLS/SSL protocol
Secure MQTT over TLS/SSL protocol with mutual authentication

For more info regarding connection configuration see Cluster Service configuration in this guide.

📘
Account settings are restricted by the underlying Broker Cluster instance configuration. For example an account cannot be configured to handle TLS/SSL connections if the associated Broker Cluster instance is not configured to support TLS/SSL protocol.