Personal tools


LED-setup XML

From NiftyWiki
Jump to: navigation, search
Home Documentation Download Support Showroom Links


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


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:

<?xml version="1.0" encoding="UTF-8"?>
    <hardware name="Dummy Hardware" plugin="dummy" id="*">
        <chain ledcount="1" pixel_format="Y u8"/>

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:

For example:

<?xml version="1.0" encoding="UTF-8"?>
    <hardware name="Dummy Hardware" plugin="dummy" id="*">
        <chain ledcount="3" pixel_format="RGB u8"/>
            <chain ledcount="3" pixel_format="RGB u8">
                <led x="10" y="10" component="0"/>
                <led x="10" y="10" component="1"/>
                <led x="10" y="10" component="2"/>

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


LED setup root node.


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


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.


A freely choosable unique name for this instance


The name of the plugin-family to use


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"


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:

   .--------.   .-------.
 ->| Chip 1 |->| Chip 2 |->
   '--------'  '--------'
     | | |       | | |
     1 2 3       4 5 6

If you send them a buffer, LEDs light in that (virtual) order:

   .--------.   .-------.
 ->| Chip 1 |->| Chip 2 |->
   '--------'  '--------'
     | | |       | | |
     1 3 5       2 4 6 

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



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).


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


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


Y-offset in pixels


total width of tile in pixels


total height of tile in pixels


rotation of tile around pivot (in degrees)


X coordinate of rotation center


Y coordinate of rotation center



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.


length of chain (in LEDs)


The data-format this chain uses for its LEDs (e.g. "RGB u8", "Y u16", "CMYK float", ...). for valid pixel formats s.



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-coordinate of a LED relative to tile-origin (in pixels)


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


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


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")


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.

Example 1

<?xml version="1.0" encoding="UTF-8"?>
    <tile x="0" y="0" width="2" height="2" rotation="0" pivot_x="4" pivot_y="4">
        <xi:include xmlns:xi="" href=""/>

file.xml: (on remote "" server)

<?xml version="1.0" encoding="UTF-8"?>
<chain ledcount="4" pixel_format="RGB u8">
    <led x="0" y="0" gain="0" component="0"/>
    <led x="1" y="0" gain="0" component="0"/>
    <led x="0" y="1" gain="0" component="0"/>
    <led x="1" y="1" gain="0" component="0"/>

Example 2

<?xml version="1.0" encoding="UTF-8"?>
    <tile x="8" y="0" width="8" height="4" rotation="0" pivot_x="4" pivot_y="4">
        <xi:include xmlns:xi="" href="tile_8x4.xml"/>
    <tile x="0" y="0" width="8" height="4" rotation="180" pivot_x="4" pivot_y="4">
        <xi:include xmlns:xi="" href="tile_8x4.xml"/>


<?xml version="1.0" encoding="UTF-8"?>
    <tile x="0" y="0" width="4" height="4" rotation="0.000000" pivot_x="2" pivot_y="2">
        <xi:include xmlns:xi="" href="tile_4x4.xml"/>
    <tile x="4" y="0" width="4" height="4" rotation="0.000000" pivot_x="2" pivot_y="2">
        <xi:include xmlns:xi="" href="tile_4x4.xml"/>


<?xml version="1.0" encoding="UTF-8"?>
<chain ledcount="16" pixel_format="RGB u8">
    <led x="1" y="3" gain="0" component="0"/>
    <led x="3" y="3" gain="0" component="0"/>
    <led x="2" y="2" gain="0" component="0"/>
    <led x="3" y="2" gain="0" component="0"/>
    <led x="3" y="1" gain="0" component="0"/>
    <led x="2" y="1" gain="0" component="0"/>
    <led x="3" y="0" gain="0" component="0"/>
    <led x="2" y="0" gain="0" component="0"/>
    <led x="1" y="0" gain="0" component="0"/>
    <led x="0" y="0" gain="0" component="0"/>
    <led x="1" y="1" gain="0" component="0"/>
    <led x="0" y="1" gain="0" component="0"/>
    <led x="0" y="2" gain="0" component="0"/>
    <led x="1" y="2" gain="0" component="0"/>
    <led x="0" y="3" gain="0" component="0"/>
    <led x="2" y="3" gain="0" component="0"/>


The current data type definition for a niftyled config XML:

<!-- unique root-element, holds config for one setup -->
<!ELEMENT niftyled (hardware*)>

<!-- describe one hardware-controller plugin instance -->
<!ELEMENT hardware ANY>
<!ATTLIST hardware
   name             ID       #REQUIRED       
   plugin           NMTOKEN  #REQUIRED       
   id               ID       #REQUIRED          
   stride           CDATA    "0"   

<!-- one LED (light-source) -->
   x          CDATA    "0"   
   y          CDATA    "0"   
   component  CDATA    "0"   
   gain       CDATA    "0"   

<!-- a serial chain of LEDs -->
<!ELEMENT chain (led)>
<!ATTLIST chain
   ledcount CDATA          "0"   
   pixel_format   CDATA    "RGB u8"

<!-- describe one lighting "tile" -->
<!ELEMENT tile (chain|tile*)>
<!ATTLIST tile
   children CDATA    #IMPLIED        
   x        CDATA    "0"   
   y        CDATA    "0"   
   width    CDATA    #IMPLIED        
   height   CDATA    #IMPLIED        
   rotation CDATA    "0"   
   pivot_x  CDATA    "0"   
   pivot_y  CDATA    "0"