This document describes the administration tools available using the ESF Gateway Administration Console. This web interface provides the ability to configure all services and applications that are installed and running on the gateway and is shown in the following screen capture:

This section describes the functionality and configuration of the standard services included in ESF. Other sections describe the management of the applications that may be installed on top of ESF.

ClockService

The ClockService handles the date and time management of the system. If enabled, it tries to update the system date and time using a Network Time Protocol (NTP) server.

To manage the system date and time, select the ClockService option located in the Services area as shown in the screen capture below.

The ClockService provides the following configuration parameters:

• enabled - sets whether or not this service is enabled or disabled. (Required field.)

• clock.set.hwclock - defines if the hardware clock of the gateway must be synced after the system time is set. If enabled, the service calls the Linux command "hwclock --utc --systohc".

• clock.provider - specifies either Java NTP client (java-ntp), or a direct call to the native Linux ntpdate command (ntpd). (Required field.)

• clock.ntp.host - sets a valid NTP server host address.

• clock.ntp.port - sets a valid NTP port number.

• clock.ntp.timeout - specifies the NTP timeout in milliseconds.

• clock.ntp.max-retry - defines the number of retries when a sync fails (retry at every minute). Subsequently, the next retry occurs on the next refresh interval.

• clock.ntp.retry.interval - defines the interval in seconds between each retry when a sync fails. If the clock.ntp.refresh-interval parameter is less than zero, there is no update. If the clock.ntp.refresh-interval parameter is equal to zero, there is only one try at startup. (Required field.)

• clock.ntp.refresh-interval - defines the frequency (in seconds) at which the service tries to sync the clock. Note that at the start of ESF, when the ClockService is enabled, it tries to sync the clock every minute until it is successful. After a successful sync, this operation is performed at the frequency defined by this parameter. If the value is less than zero, there is no update. If the value is equal to zero, syncs only once at startup.

CloudService

The CloudService provides an easy-to-use API layer for the M2M application to communicate with a remote server. It operates as a decorator for the DataService, providing add-on features over the management of the transport layer.

In addition to simple publish/subscribe, the CloudService API simplifies the implementation of more complex interaction flows like request/response or remote resource management. The CloudService abstracts the developers from the complexity of the transport protocol and payload format used in the communication.

The CloudService allows a single connection to a remote server to be shared across more than one application in the gateway, providing the necessary topic partitioning. Its functions include:

• Adds application topic prefixes to allow a single remote server connection to be shared across applications.

• Defines a payload data model and provides default encoding/decoding serializers.

• Publishes life-cycle messages when the device and applications start and stop.

To use this service, select the CloudService option located in the Cloud Services area as shown in the screen capture below.

The CloudService provides the following configuration parameters:

• device.display-name - defines the device display name given by the system. (Required field.)

• device.custom-name - defines the custom device display name if the device.display-name parameter is set to "Custom".

• topic.control-prefix - defines the topic prefix used for system and device management messages.

• encode.gzip - defines if the message payloads are sent compressed.

• republish.mqtt.birth.cert.on.gps.lock - when set to true, forces a republish of the MQTT Birth Certificate when a GPS correct position lock is received. The device is then registered with its real coordinates. (Required field.)

• republish.mqtt.birth.cert.on.modem.detect - when set to true, forces a republish of the MQTT Birth Certificate when the service receives a modem detection event. (Required field.)

• enable.default.subscriptions - manages the default subscriptions to the gateway management MQTT topics. When disabled, the gateway will not be remotely manageable.

• birth.cert.policy - specifies the birth cert policy to be used. The possible selectable options are:

  • Disable publishing - No birth message will be sent
  • Publish birth on connect - Publishes a birth message at the first connection event
  • Publish birth on connect and reconnect - Publishes a birth message at connection and reconnection events.

• payload.encoding - specifies the encoding for the messages sent by the specific CloudService instance.

  • Kura Protobuf - when this option is selected, the Kura Protobuf encoding will be used
  • Simple JSON - the simple JSON encoding will be used instead. More information is available here. An example below.

{
  "sentOn" : 1491298822,
  "position" : {
    "latitude" : 45.234,
    "longitude" : -7.3456,
    "altitude" : 1.0,
    "heading" : 5.4,
    "precision" : 0.1,
    "speed" : 23.5,
    "timestamp" : 1191292288,
    "satellites" : 3,
    "status" : 2
  },
  "metrics": {
    "code" : "A23D44567Q",
    "distance" : 0.26456E+4,
    "temperature" : 27.5,
    "count" : 12354,
    "timestamp" : 23412334545,
    "enable" : true,
    "rawBuffer" : "cGlwcG8gcGx1dG8gcGFwZXJpbm8="
  },
  "body": "UGlwcG8sIHBsdXRvLCBwYXBlcmlubywgcXVpLCBxdW8gZSBxdWEu"
}

DataService

The DataService provides the ability to connect to a remote broker, publish messages, subscribe to topics, receive messages on the subscribed topics, and disconnect from the remote message broker. The DataService delegates to the MqttDataTransport service the implementation of the transport protocol that is used to interact with the remote server.

The DataService also adds the capability of storing published messages in a persistent store function and sending them over the wire at a later time. The purpose of this feature is to relieve service users from implementing their own persistent store. Service users may publish messages independently on the DataService connection status.

In order to overcome the potential latencies introduced by buffering messages, the DataService allows a priority level to be assigned to​ each published message. Depending on the store configuration, there are certain guarantees that stored messages are not lost due to sudden crashes or power outages.

To use this service, select the DataService option located in the Cloud Services area as shown in the screen capture below.

The DataService offers methods and configuration options to manage the connection to the remote server including the following (all required) parameters described below.

• connect.auto-on-startup - when set to true, the service tries to auto-connect to the remote server on start-up and restore the connection every time the device is disconnected. These attempts are made at the frequency defined in the connect.retry-interval parameter until the connection is established.

• connect.retry-interval - specifies the connection retry frequency after a disconnection.

• enable.recovery.on.connection.failure - when enabled, activates the recovery feature on connection failure: if the device is not able to connect to a remote cloud platform, the service will wait for a specified amount of connection retries. If the recovery fails, the device will be rebooted. Being based on the Watchdog service, it needs to be activated as well.

• connection.recovery.max.failures - related to the previous parameter. It specifies the number of failures before a reboot is requested.

• disconnect.quiesce-timeout - allows the delivery of in-flight messages to be completed before disconnecting from the broker when a disconnection from the broker is being forced.

• store.db.service.pid - The Kura Service PID of the database instance to be used. The PID of the default instance is org.eclipse.kura.db.H2DbService.

• store.housekeeper-interval - defines the interval in seconds used to run the Data Store housekeeper task.

• store.purge-age - defines the age in seconds of completed messages (either published with QoS = 0 or confirmed with QoS > 0) after which they are deleted (minimum 5).

• store.capacity - defines the maximum number of messages persisted in the Data Store.

• in-flight-messages.republish-on-new-session - it specifies whether to republish in-flight messages on a new MQTT session.

• in-flight-messages.max-number - it specifies the maximum number of in-flight messages.

• in-flight-messages.congestion-timeout - timeouts the in-flight messages congestion condition. The service will force a disconnect attempting to reconnect.

• enable.rate.limit - Enables the token bucket message rate limiting.

• rate.limit.average - The average message publishing rate. It is intended as the number of messages per unit of time.

• rate.limit.time.unit - The time unit for the rate.limit.average.

• rate.limit.burst.size - The token bucket burst size.

MqttDataTransport

The MqttDataTransport service provides the ability to connect to a remote broker, publish messages, subscribe to topics, receive messages on the subscribed topics, and disconnect from the remote message broker. To use this service, select the MqttDataTransport option located in the Cloud Services area as shown in the screen captures below.

The MqttDataTransport service provides the following configuration parameters:

• broker-url - defines the URL of the MQTT broker to connect to. For the Everyware Cloud sandbox, this address is either mqtt://broker-sandbox.everyware-cloud.com:1883/ or mqtts://broker-sandbox.everyware-cloud.com:8883/ for an encrypted connection. (Required field.)

• topic.context.account-name - defines the name of the account to which the device belongs.

• username and password - define the username and password that have been assigned to the device by the account administrator (generally username is account-name_broker). (Required field.)

• client-id - defines the identifier of the MQTT client representing the device when connecting to the MQTT broker. If left empty, it is automatically determined by the client software as the MAC address of the main network interface (in general numbers and uppercase letters without ':'). This identifier has to be unique within your account. (See screen capture below.)

• keep-alive - defines the "keep alive" interval measured in seconds. It specifies the maximum amount of time that should pass without communication between the client and the server. The client will ensure that at least one message travels across the network within each keep alive period. In the absence of a data-related message during this time period, the client will send a very small MQTT "ping" message that the server will acknowledge. The keep alive interval enables the client to detect when the server is no longer available without having to wait for the long TCP/IP timeout. (Required field.)

• timeout - sets the timeout used for all interactions with the MQTT broker. (Required field.)

• clean-session - controls the behavior of both the client and the server at the time of connection and disconnection. When this parameter is set to true, the state information is discarded at connection and disconnection; when set to false, the state information is maintained. (Required field.)

• lwt parameters - define the MQTT "Last Will and Testament" (LWT) settings for the client. In the event that the client unexpectedly loses its connection to the server, the server publishes the LWT message (lwt.payload) to the LWT topic on behalf of the client. This allows other clients (subscribed to the LWT topic) to be made aware that the client has disconnected. LWT parameters that may be configured include:

  • lwt.topic
  • lwt.payload
  • lwt.qos
  • lwt.retain

• in-flight.persistence - defines the storage type where in-flight messages are persisted across reconnections. They may be stored in memory, or in a file on the disk. (Required field.)

• protocol-version - defines the MQTT Protocol version to be used. This value may be 3.1 or 3.1.1 (April 2014).

• SSL parameters - define the SSL specific settings for the client. SSL parameters that can be configured include:

  • ssl.default.protocol
  • ssl.hostname.verification
  • ssl.default.cipherSuites
  • ssl.certificate.alias

CommandService

The CommandService provides methods for running system commands from the web console. This service also provides the ability for a script to execute using the File option of the Command tab in the Everyware Cloud Console as shown in the screen capture below. This script must be compressed into a zip file with the eventual, associated resource files.

Once the file is selected and Execute is clicked, the zip file is sent embedded in an MQTT message on the device. The Command Service in the device stores the file in /tmp, unzips it, and tries to execute a shell script if one is present in the file. Note that in this case, the Execute parameter cannot be empty; a simple command, such as "ls -l /tmp", may be entered.

To use this service, select the CommandService option located in the Services area as shown in the screen capture below.

The CommandService provides the following configuration parameters:

• command.enable - sets whether this service is enabled or disabled in the Everyware Cloud Console. (Required field.)

• command.password.value - sets a password to protect this service.

• command.working.directory - specifies the working directory where the command execution is performed.

• command.timeout - sets the timeout (in seconds) for the command execution.

• command.environment - supplies a space-separated list of environment variables in the format key=value.

When a command execution is requested in the Everyware Cloud Console, it sends an MQTT control message to the device requesting that the command be executed. On the device, the Command Service opens a temporary shell as root in the command.working.directory, sets the command.environment variables (if any), and waits command.timeout seconds to get command response.

PositionService

The PositionService provides the geographic position of the gateway if a GPS component is available and enabled.

When this service is enabled and provides a valid geographic position, this position is published in the gateway birth certificate and its location is updated on the Everyware Cloud Console.

The GPS connection parameters must be defined in order to allow the service to receive the GPS frames.

For a device that is not connected to a GPS, it is possible to define a static position by entering latitude, longitude, and altitude. In this case, the position is returned by the PositionService as if it were an actual GPS position. This may be useful when a gateway is installed in a known place and does not move.

To use this service, select the PositionService option located in the Services area as shown in the screen capture below.

This service provides the following configuration parameters:

• enabled - defines whether or not this service is enabled or disabled. (Required field.)

• static - specifies true or false whether to use a static position instead of a GPS. (Required field.)

• latitude - provides the static latitude value in degrees.

• longitude - provides the static longitude value in degrees.

• altitude - provides the static altitude value in meters.

• port - supplies the USB or serial port of the GPS device.

• baudRate - supplies the baud rate of the GPS device.

• bitsPerWord - sets the number of bits per word (databits) for the serial communication to the GPS device.

• stopbits - sets the number of stop bits for the serial communication to the GPS device.

• parity - sets the parity for the serial communication to the GPS device.

ProvisioningService

The ProvisioningService allows for out-of-the-box device provisioning. This feature may be used for easy and fast deployment of a large number of devices that have similar configurations, applications, or areas of application. The entire process is described in the Remote Access section

The main goal of device provisioning is to allow a user to automatically configure a new device without the need to directly interact with the device. The Everyware Cloud platform takes care of the configuration of the device with the parameters given by the user.

In order to connect to the provision account, select the ProvisioningService option located in the Services area as shown in the screen capture below.

This service provides the following configuration parameters needed for this connection to be established:

• Broker URL - supplies the broker URL as one of the following, depending on where your account is:

  • Sandbox: mqtts://broker-sandbox.everyware-cloud.com:8883
  • Production: mqtts://broker-eurotech-provision.everyware-cloud.com:8883

• Client ID - supplies the unique client identifier within the whole account. Our platform uses MAC addresses of the main network card of the device (columns removed) to obtain a unique client identifier. This identifier must follow the naming convention defined by the v.3.1.1 MQTT specification.

• Username - identifies the username that matches the one that was provided when the provision request was created on the platform. If it does not match, the device will not be able to connect to the Provision Broker. If left empty, this is automatically determined by the client software, e.g. as the MAC address of the main network interface (generally uppercase and without ':') followed by '-' and the device serial number. The serial number is obtained from the kura.serialNumber property of the kura.properties file.

• Password - identifies the password that matches the one that was provided when the provision request was created on the platform. If it does not match, the device will not be able to connect to the Provision Broker.

VpnClient

The VpnClient service allows remote access to the device by connecting to a VPN server. To use this service, select the VpnClient option located in the Services area. The VpnClient service provides the configuration parameters for username and password, which must be set according to those configured for the VPN user in the Everyware Cloud Users management console as shown in the screen captures below.

To establish a VPN connection between your laptop and the gateway, first connect the gateway to the VPN server using the VPN tab of the Everyware Cloud Devices console.

Then, connect your laptop to the same VPN server using the same username and password. This process is explained in more detail in the VPN menu of Everyware Cloud Console.

WatchdogService

The WatchdogService provides methods for starting, stopping, and updating a hardware watchdog if it is present on the system. Once started, the watchdog must be updated to prevent the system from rebooting.

To use this service, select the WatchdogService option located in the Services area as shown in the screen capture below.

This service provides the following configuration parameters:

• enabled - sets whether or not this service is enabled or disabled. (Required field.)

• pingInterval - defines the maximum time interval between two watchdogs' refresh to prevent the system from rebooting. (Required field.)

• Watchdog device path - sets the watchdog device path. (Required field.)

• Reboot Cause File Path - sets the path to the file that will contain the reboot cause information. (Required field.)