Preface

The complete description of the way LEDs are accessed from a niftyled application is saved in an XML config file.

This includes:

hardware plugin(s) configuration

amount of LEDs connected to hardware

colorspace of LEDs (e.g. RGB)

plugin specific configuration options

pixel mapping configuration

colorspace of input pixels/frames

position and color channel in input frames for each configured LED

Overview

libniftyled uses libniftyprefs to provide a uniform mechanism to load, parse and save the XML config file. This file is the central configuration to describe a lighting setup for a niftyled application. It can be edited with any text-editor or using Niftyconf as GUI. (You can also use ledset in interactive mode to create a setup for a single <tile> from the commandline.)

The root element <niftyled> includes a list of adapter-hardware plugins. It must contain at least one <hardware> element which itself must contain at least one <chain> element (to tell how many light-sources are controlled by the hardware). Thus a minimal config-file looks like this:

This would describe a hardware interfacing 1 monochrome light-source that use values from 0 to 255 for brightness control. (The plugin type "dummy" is builtin and just prints brightness values to stdout.)

Since niftyled can also map a pixmap to your light setup, you can define the position of lighting devices within the input frame. This is done by adding a <tile> element to the hardware which itself holds a <chain> that contains <led> elements describing the position and color component inside the input frame for each LED:

This describes a simple setup with 3 LEDs (R,G,B) that are mapped from the pixel at position (10,10) of an 8-Bit RGB input frame. (Since the hardware plugin expects "RGB u8" and the input frame is delivered as "RGB u8", no colorspace conversion is done.)
Learn more...

You can combine different colorspace formats - niftyled converts them on-the-fly to the format of the hardware chain.

To learn about defining an LED-setup, check out the introduction to LED mapping and the element description below.

Element description

Niftyled

LED setup root node.

A <niftyled> node contains one or more <hardware> nodes to describe a complete LED setup.

Hardware

Adapter hardware plugin interfacing with lighting devices.

A <hardware> can have:

exactly one <chain> to define total amount and color-model of connected LEDs

zero or one <tile> to define the position and color-model of connected LEDs relative to the pixel-frames sent to niftyled.

Every hardware node may contain any kind of additional child-nodes for plugin-specific parameters.

name

plugin

id

Unique id passed to the plugin to identify specific hardware. (e.g. "/dev/ttyS0", "pci:00:02.0", ...). Every plugin should accept "id="*"" to "open the first (autodetected) hardware that is available"

stride

Amount of LEDs in a group connected to one serial shift-register controller. The stride value is for special shift-register based hardware. If the physical chain-order of your LEDs doesn't match the virtual-order of the hardware-protocol, you should set this value != 0.

Example:
if you have a hardware with 2 chips that drive 3 LEDs each, the physical order would be:

This would mean a stride-value of 3. (You can use the ledset utility to find out the virtual order of your LED hardware)

Tile

A "tile" is used to hold either a <chain> or child-tiles. All children (chain or tile) of a tile are affected by a its properties. <tile>-nodes are parsed in reverse order - thus the last tile in a <hardware>-node represents the tile at the beginning of the chain (the one nearest to hardware-adapter).

children

Amount of child-tiles this tile has (internally used, you don't need to set this)

x

X-offset of this tile in pixels, relative to parent-tile (or pixel-frame origin if there are no parents)

y

Y-offset in pixels

width

total width of tile in pixels

height

total height of tile in pixels

rotation

rotation of tile around pivot (in degrees)

pivot_x

X coordinate of rotation center

pivot_y

Y coordinate of rotation center

Chain

A serial chain of LEDs. Imagine this like an open pearl necklet with n pearls and every pearl numbered sequentially from 0 to n-1. The position of the <led>-element in a <chain<-element must correspond to the (virtual) position of the physical LED that is represented by this element.

ledcount

length of chain (in LEDs)

pixel_format

Led

A LED is one light-source entity that can receive a greyscale-value to determine its current brightness. A value of 0 means "light off" and the maximum possible value means "full brightness" (e.g. 255 for 8-bit values). The maximum possible value is determined by the pixel_format of the chain containing this LED.

x

x-coordinate of a LED relative to tile-origin (in pixels)

y

y-coordinate of a LED relative to tile-origin (in pixels)

gain

optional gain-value for this LED

0 - LED off

49152 - normal brightness

65535 - full brightness (overdrive)

Most plugins won't change the gain between 49152 and 65535 but some can overdrive LEDs
BEWARE: You might damage hardware or reduce its lifetime when overdriving the gain

component

color-channel of this LED in a pixel (e.g. a green-led on a RGB setup -> R=0, G=1, B=2 -> would be channel="1")

XInclude

You can use the XInclude feature of the XML standard to include one XML into another. This can be a local file or from a remote server.
This is very useful when having multiple repetitions of the same tile. Also vendor- or 3rd-party provided definitions can be included while beeing provided serverside.