# DeviceTree

The LEDs and Buttons controlled by hui are configured via the device tree. Most parameters are generic, however device drivers may add parameters needed to work properly.

## Global Configuration

~~~{.dts}
avm-hui {
	compatible = "avm,hui";

	colors {
		normal = <0x23>, <0x50>, <0x0>;
		warn = <0x50>, <0x23>, <0x0>;
		error = <0x78>, <0x0>, <0x0>;
	};
};
~~~

The global configuration node for avm hui must exist in order to enable hui. This node can contain a colors node and multiple led/buttons nodes as needed.

The colors node contains the definition of the named colors used in overlays. If not set, the color codes are set to `<0xFF>, <0xFF>, <0xFF>`. Depending on the actual device driver, these codes may be RGB or  red, green, unused or something completely else. A color node can also be put into led-nodes and override the global colors.

## Common LED Configuration

LEDs have common configuration parameters, many of which are optional.

~~~{.dts}
my-led {
	compatible = "my-driver";
	led-type = "my-type";
	location = <1>;
	brightness-range = <50>, <230>;
	dimmable;

	colors {
		normal = <0x23>, <0x50>, <0x0>;
		warn = <0x50>, <0x23>, <0x0>;
		error = <0x78>, <0x0>, <0x0>;
	};
};
~~~

The node name (`my-led`) defines the name of the led, and if led-type is missing, also the led type. When `led-type` is specified, it is used to lookup the led type which contains the overlays used for this led.

The `location`-property (optional) denotes the physical location of the led. A value of `0` means, no location. All leds with an location should be numberes from `1` to `n` where `n` is the number of leds. This property is used for RSSI and VU overlay to show a value across multiple leds.

The `brightness-range`-property describes the destination brightness range of the led. The first value specified the min and the second the max value. Incoming brightness values from 0% to 100% will be remapped to the value specified. The values specified must be in the range of 0 to 255 and min must be greater or equal to max. If this led is not dimmable, the max brightness is passed to the device.

The `dimmable`-property designates leds that are dimmable. In order to actually dim the led, the device driver must also support this. If this property is specified, the led will receive adjusted brightness values, otherwise the incoming brightness is fixed at 100%. The incoming brightness is then mapped using the `brightness-range`.

The `colors`-node overrides the global `colors`-node.

## GPIOLIB LED Configuration

The gpiolib generic led driver, used gpios exposed by the gpiolib driver. It does not support dimming, and all color values other than 0 will be interpreted as on.

~~~{.dts}
my-led {
	compatible = "avm,hui-generic-led-gpio";
	gpios = <&tlmm 39 GPIO_ACTIVE_LOW>;
};
~~~

Use the default gpios-property to specified the gpio pins. Up to three gpios can be specified an will be mapped to the three color components. To make it consistent, try to map these as best as possible to RGB. For the format of the `gpios`-property, consult the [kernel doc](https://www.kernel.org/doc/Documentation/gpio/board.txt).

## PWM LED Configuration

The pwm generic led driver uses the pwm framework provided by linux. It does support dimming.

~~~{.dts}
my-led {
	compatible = "avm,hui-generic-led-pwm";
	pwms = <&pwm 2 2550 PWM_POLARITY_INVERTED>, <&pwm 3 2550 PWM_POLARITY_INVERTED>;
	pwm-names = "red", "green";
};
~~~

The pwms definition is described in the [kernel doc](https://www.kernel.org/doc/Documentation/devicetree/bindings/pwm/pwm.txt). The pwm-names is needed and must match the pwm property. The actual names provided are unused.

## LEDCLASS LED Configuration

The led-class generic led driver, uses led-class devices to provide leds. Depending on the hardware and device driver, these may be dimmable.

~~~{.dts}
my-led {
	compatible = "avm,hui-generic-led-class";
	leds = <&led_phandle>;
};
~~~

The `leds`-property contains up to 3 phandles pointing to the led-class device node.

## AVM GPIO LED Configuration

\attention
Avoid this driver for new devices. The avm gpio driver often uses gpiolib, pwm or led-class anyway, so use the actual low level driver.

The avm gpio generic driver, uses gpios exposed by the avm specific gpio implementation.


~~~{.dts}
my-led {
	compatible = "avm,hui-generic-led-avm";
	avm-gpios = <&led_power>;
};
~~~

The `avm-gpios`-property can contain up to 3 phandles pointing to the avm_gpio device nodes.

## AVM Ext LED Configuration

\attention
This driver is only uses for very odd hardware. Try to avoid using this!

The ext generic driver allows, external devices to register themself as gpio drivers. This is currently only used on the FRITZ!Repeater 1160 and can be hopefully be removed soon.

~~~{.dts}
my-led {
	compatible = "avm,hui-generic-led-ext";
	ext-group = "wlan";
	ext-pin = <1>;
};
~~~

The `ext-group` and `ext-pin` property describe where to deliver the led values to. Please see the source code for their meaning.

## LC882x LED Configuration

The lc882x driver supports spi based rgb leds. In contrast to other generic drivers, this driver must be declared inside the spi device node and contains multiple leds.

~~~{.dts}
&spi_0 {
	...

	avm-hui-lc882x@0 {
		compatible = "avm,hui-generic-lc882x";
		spi-max-frequency = <400000>;
		reg = <0>;

		my-led-1 {
			index = <1>;
		};

		my-led-2 {
			index = <0>;
		};
	};
};
~~~

Each led-node can contain all common led properties. The `index`-property describes it's location in the spi chain.

## STM32 LED Configuration

The stm32 led driver, unlike all other drivers, does not use the generic engine but delegates the interpretation of blink codes to hardware."

\attention
As this is a different blink engine, blinking is not synchronized between the stm32 and the generic engine. Therefore it is not recommended to mix generic- and stm32-leds in one system.

~~~{.dts}
&spi_0 {
	...

	avm-hui-stm32@0 {
		compatible = "avm,hui_stm32";
		spi-max-frequency = <400000>;
		frame-gpio = <&tlmm 39 GPIO_ACTIVE_LOW>;
		reg = <0>;

		my-led-1 {
			index = <1>;
		};

		my-led-2 {
			index = <0>;
		};
	};
};
~~~

The `frame-gpio`-property specifies the gpio used for framing. This is used instead of a normal chip select, as the stm32 has more specific requirements for it.

## GPIOLIB Button Configuration

The gpiolib generic button driver, will use gpios exposed via gpiolib as button inputs. Each button will be polled every 125ms.

~~~{.dts}
my-button {
	compatible = "avm,hui-generic-button-gpio";
	gpios = <&tlmm 46 GPIO_ACTIVE_LOW>;
};
~~~

The node name is used to look up the button type. The gpios is specified as described in the [kernel doc](https://www.kernel.org/doc/Documentation/gpio/board.txt).

## AVM Button Configuration

\attention
Avoid this driver for new devices. The avm gpio driver often uses gpiolib anyway, so use the actual low level driver.

The avm generic button driver, uses avm gpios as button inputs. Each button will be polled every 125ms.

~~~{.dts}
my-button {
	compatible = "avm,hui-generic-button-avm";
	avm-gpios = <&button_connect>;
};
~~~

The node name is used to look up the button type. The avm-gpios will contain one phandle, pointing to the device node of the corresponding avm_gpio.