Cloud Connection Status LED

ESF can report the status of the cloud connection and of the device provisioning process through an LED of the gateway. The LED is driven by the CloudConnectionStatusService, which collects the status notifications coming from the cloud connection and provisioning components and translates them into an LED pattern.

LED patterns

The following table describes the LED patterns and their meaning.

LED pattern	Timing	Meaning
Off	-	The device is not connected and no connection is expected: automatic connection is disabled, the device was manually disconnected, or no cloud connection is active.
Slow blinking	300 ms on, 300 ms off	The device is not connected and the DataService is waiting to retry the connection (see DataService Connection Monitor).
Fast blinking	100 ms on, 100 ms off	A connection attempt to the remote broker is in progress. During provisioning, the device is waiting for the connection to the provisioning broker.
On	Steady	The device is connected to the remote broker.
Heartbeat	Two 150 ms pulses separated by 150 ms, followed by a 600 ms pause	Device provisioning is in progress.

Cloud connection

When automatic connection is enabled in the DataService, the LED typically goes through the following sequence:

Slow blinking while the DataService waits for the next connection attempt.
Fast blinking while the MqttDataTransport is connecting to the broker.
On once the connection is established. If the connection attempt fails, the LED goes back to slow blinking until the next attempt.

If the connection is lost, the LED goes back to slow blinking while the DataService tries to reconnect. If the device is manually disconnected, or automatic connection is disabled, the LED is off.

Device provisioning

While the Provisioning Service is running, its status takes precedence over the cloud connection status:

Heartbeat when the provisioning process starts.
Fast blinking while waiting for the connection to the provisioning broker to be established.
Heartbeat once connected, while the provisioning request is sent and the device waits for the provisioned configuration.

When provisioning completes, either successfully or after the maximum number of attempts, the LED goes back to showing the cloud connection status as described in the previous section. For example, after a successful provisioning the LED turns on once the device connects using the provisioned configuration.

Status priority

When more than one component reports a status at the same time, the LED shows the status of the one with the highest priority:

Provisioning Service
MqttDataTransport, during a connection attempt
DataService

📘
Note
If more than one cloud connection is configured, the LED shows the status of only one of them, and which one is not guaranteed. The LED does not combine the status of all the cloud connections.

Configuration

The LED used for the notifications is configured through the ccs.status.notification.url property in the /opt/eurotech/esf/framework/kura.properties file. The property is read when ESF starts, so ESF must be restarted for a change to take effect.

The property supports the following values:

Value	Description
`ccs:none`	Status notifications are disabled. This is the default if the property is missing or not valid.
`ccs:log`	The status is only written to the ESF log (for example `Notification LED fast blinking`). No LED is driven.
`ccs:linux_led:<path>`	Drives an LED exposed by the Linux LED subsystem, where `<path>` is the LED directory under `/sys/class/leds` (for example `ccs:linux_led:/sys/class/leds/led1-green`).
`ccs:led:<terminal>` or `ccs:led:terminal:<terminal>`	Drives an LED connected to the GPIO with the given terminal number, through the GPIO Service (for example `ccs:led:115`).
`ccs:led:name:<name>`	Drives an LED connected to the GPIO with the given name, through the GPIO Service (for example `ccs:led:name:LED_1`).

For ccs:led values, append :inverted to invert the GPIO logic, for LEDs that are on when the GPIO is low (for example ccs:led:115:inverted).

Multiple values can be combined, separated by ;. If both a linux_led and a led value are configured, the linux_led LED is used when its path exists on the device, and the GPIO LED is used otherwise. If neither LED is available, the status is written to the log.