1 General
2 Northbound API
- 2.1 LED_Config
- 2.2 MQTT reports
3 Southbound API
4 Appendix A: List of LED States

General

This feature reworks LED management in a way that allows easier configuration and overview of enabled LED states by introducing a new table LED_Config. All enabled LED states on the device are now saved as entries in LED_Config. Backward compatibility with the previous method of LED management via updating AWLAN_Node field led_config is ensured.

LED management is also enhanced by:

Support for managing several LEDs via the position field.
Support for custom LED patterns, controlled by the cloud, via the pattern field (only valid for the cloud LED state). Patterns may adjust LED color, on and off duration and add a breathing effect by slowly fading brightness in or out.
Prevention of related states which may not coexist (e.g. connecting and connected)

The list of valid LED states is defined as an enum in the OpenSync OVSDB schema field name of the LED_Config table. To support newly added functionalities, target layer updates are required.

Northbound API

LED_Config

Table for controlling LED behavior, by enabling or disabling LED states. If multiple LEDs are present on a device, they may be controlled separately by specifying the position parameter.

The enabled state with its priority set to the lowest integer value, indicating higher priority (e.g. 0 being higher priority than 10), will be considered active for a given position. On each update to the LED_Config table, the new status of enabled states and their priorities will be re-evaluated, and the active state will be updated accordingly.

Name	Type	Description

Name	Type	Description
name	enum	A named LED state, which must have a corresponding implementation of its behavior in the target layer. The exception is the `cloud` state, which will set a custom pattern, configured in the `pattern` field. List of valid states: `idle` `error` `connected` `connecting` `connectfail` `wps` `optimize` `locate` `hwerror` `thermal` `btconnectable` `btconnecting` `btconnected` `btconnectfail` `upgrading` `upgraded` `upgradefail` `hwtest` `iotalarm` `cloud`
priority	integer	The priority with which the state should be treated, with a lower integer value meaning higher priority. If priority is not explicitly specified, the default value -2 will be inserted. In this case, priority will be translated to the device’s default value for this state, which is defined in the target layer.
position	integer 0 - 255	Index of LED for which this state appies.
pattern	string [optional]	Custom pattern, used when the state is `cloud`. The value is formatted as a list of LED pattern elements, where each element controls LED behavior for a certain duration, based on specified values. The pattern is executed in a cycle. Each element consists of the following data: duration – total duration of this element, in milliseconds, including fade time color – RGB color red value, in range [0, 255] green value, in range [0, 255] blue value, in range [0, 255] fade – transition time from previous to this color, in milliseconds The pattern elements are formatted as a list enclosed insquare brackets (`[`, `]`). Each element is enclosed in double quotes (`"`). Element's data fields are by commas (`,`), while color’s sub-fields `red`, `green`, `blue` are separated by a semicolon (`;)`. Example pattern element: `"1000,255;255;255,0"` This element will turn on the LED to full brightness for 1000 ms. Example pattern, consisting of two elements, which will be run in a cycle: `["1000,255;255;255,0","1000,0;0;0,500"]` This pattern will turn on the LED to full brightness for 1000 ms, then start dimming its brightness, completely turning it off after 500 ms, and then leaving it turned off for another 500 ms.

MQTT reports

With the introduction of the position parameter to LED management, we can now have several LED states active on different positions. This must be reflected in device reporting by SM. Instead of reporting a single integer as the active led state, we now report the state along with the position value.

Device messages before LED management rework:

message Device {
...
    message Thermal {
    ...
        optional uint32           led_state        = 7;
    }
....
}

Device messages after LED management rework:

message Device {
...
    message Thermal {
    ...
        message LedState {
            optional uint32 position               = 1;
            optional uint32 value                  = 2;
        }
        repeated LedState         led_state        = 7;
    }
....
}

Southbound API

To support new LED management functionalities, such as position and custom LED pattern, changes need to be made to existing target layer functions:

osp_led_set_state():

/**
 * Set LED to specified business level state (high-level LED API)
 *
 * @param[in] state        LED state
 * @param[in] priority     LED state priority -- 0 is highest. A higher priority
 *                         state overrides current LED behavior.
 * @param[in] position     Position of LED whose state we are trying to set. Allows
 *                         setting different patterns on systems with multiple LEDs.
 * @param[in] pattern_els  List of LED custom pattern elements where each element
 *                         controls LED behaviour for a certain duration based on
 *                         specified values. The pattern is executed in a cycle.
 *                         Only applicable to the "cloud" state.
 * @param[in] pattern_els_count  Number of elements in LED pattern
 *
 * @return 0 on success, -1 on error
 */
int osp_led_set_state(
        enum osp_led_state state,
        uint32_t priority,
        uint8_t position,
        struct osp_led_pattern_el *pattern_els,
        int pattern_els_count);

osp_led_get_state():

The LED system initialization function has been changed to no longer include an outgoing parameter indicating the number of LEDs, since this information has now been moved into a kconfig option OSP_LED_COUNT:

osp_led_init():

Since entries in LED_Config may have default priority, which is defined in the device’s target layer, a new function has been exposed, which returns a state’s default priority on the device. This allows us to get the highest priority state in SM device reporting:

osp_led_get_state_default_prio():

Appendix A: List of LED States

The list of valid LED state names is defined as a list of strings in the OpenSync OVS schema’s field name of LED_Config. Each element must have a corresponding integer value in OSP LED enum osp_led_state, and an entry in OSP LED constant array led_state_str, to allow translation between the string and the corresponding integer value. MQTT reports send the integer value of the state with highest priority.

The list of enum values which are reported as the value in led_state messages and their corresponding names are:

enum value	string name

enum value	string name
0	`idle`
1	`error`
2	`connected`
3	`connecting`
4	`connectfail`
5	`wps`
6	`optimize`
7	`locate`
8	`hwerror`
9	`thermal`
10	`btconnectable`
11	`btconnecting`
12	`btconnected`
13	`btconnectfail`
14	`upgrading`
15	`upgraded`
16	`upgradefail`
17	`hwtest`
18	`iotalarm`
19	`cloud`