A library designed to provide an abstract interface for LED/lighting hardware to be easily controlled using pixel data.

[edit] Features

• different hardware/manufacturers easily combinable in the same setup
• standard XML file used to describe a setup - every application uses the same preferences file format
• realtime mapping - pixel -> component (color channel) -> light source brightness
• grouping of light-sources into "tiles" so larger clusters can be formed from smaller clusters
• arbitrary colorspace-conversion using libbabl
• hardware-plugin API to support new hardware quickly
• application API to quickly develop pixelframe generating programs

[edit] Abstract

• Every application takes a LED-setup XML file that describes the complete setup. (How LEDs map to input pixels, which hardware is used etc.)
• Using the libniftyled API, an application can feed pixel-data (image/video) to LEDs.
• there, pixels will be processed (if necessary):
  • colorspace conversion
  • translation to match position of source pixel with physical position of LED
• brightness values will be sent to the configured hardware output plugins.

Data flows like this:

[edit] Installation

[edit] Gentoo

Emerge layman if you don't have it already.

emerge -va layman

Add the niftyled overlay (if you don't have already)

layman -f -o http://gentoo.niftylight.de/layman.xml -a niftyled

Emerge:

emerge --autounmask-write niftyled

[edit] Compile manually

[edit] Prerequisites

to compile from sources:

• compiler e.g. gcc
• autotools (autoconf, autoheader, ...)
• niftylog + dev headers
• niftyprefs + dev headers
• libdlfcn / dlfcn.h header
• libbabl + dev headers

to run:

• *nix OS
• niftylog
• niftyprefs
• libdlfcn / dlfcn.h
• libbabl

[edit] Get sources

[edit] Compile

to compile & install, run:

autoreconf -is
./configure
make
sudo make install

To freshly rebuild a previously built tree, do (you can skip this if you just checked out the sources):

make maintainer-clean

Checkout additional options by running:

./configure --help

[edit] Documentation

[edit] pixel → LED mapping

• Read about LED mapping to learn how the "pixel → LED" translation works
• Read about LED-setup XML to learn how a setup is defined (you can use ledset or Niftyconf to help you create a configuration)

[edit] Environment variables

All libniftyled applications can use environment variables to set or override certain preferences:

[edit] Development

add

#include "<niftyled.h>"

to your source and compile like:

gcc -o yourprog yourprog.c `pkg-config --cflags --libs niftyled`

[edit] Examples

• minimal example to send brightness values to LEDs

[edit] Further documentation

• Doxygen autogenerated API docs for developers
• There's a whole category of development docs

[edit] Hardware plugins

Multiple output controller devices can be connected at the same time. Each one defined in the config using a <hardware> tag.

Currently maintained hardware-plugins:

More info on hardware plugins: Libniftyled hardware-plugins

[edit] Applications

Some applications using libniftyled:

• Niftyconf - LED setup configuration GUI
• Ledcap - Screen-capture → LEDs
• Ledcat - image/raw/pipe → LEDs
• Ledset - light one single LED in a setup

Other applications using libniftyled.

[edit] Issues

Please report anything via the issue tracker.

[edit] Changes

• s. commit log

[edit] Roadmap

[edit] Version 0.1.1

• verfiy configure.ac (CFLAGS)
• remove unused functions from API/move to internal API
• strip unneded symbols
• include "contrib" dir into libniftyled
• seperate "cli" dir into own niftyled-utils repo (or include into libniftyled build)
• decent custom properties API for LedHardwarePlugins
• package working dummy config
• rework doxygen stuff to be main dev documentation
• check that plugin parameters can only be registered in plugin _init and only be unregistered in _deinit (if !initialized). Log warning/error otherwise. That will prevent unnecessary trouble with applications and dynamic registering of plugin parameters won't be necessary.
• testing
• release

[edit] Version 0.1.2

• thread safety (rework)
  • support & test asynchrounus led_hardware_send() - if one plugin can't send all data to its hardware, remember the amount of values sent, cycle throught other plugins and come back to the slow plugins to send remaining data (using "offset" parameter). Then, when everything is sent, do led_hardware_show() on all plugins.
• colorspace conversion
  • threshold parameter for color -> greyscale -> monochrome conversion
  • gamma parameter for float -> u32 -> u16 -> u8 conversion
• "property" mechanism
  • descriptions for hardware plugin properties
  • prefsFromObj and prefsToObj functions for properties
  • replace dynamic plugin properties with new mechanism
  • replace element properties with new mechanism
  • array properties
    • gamma LUT support for hardware-plugins
• transparent conversion between hardware plugin pixelformat and provided pixelformat (format negotiation in plugin init)
• seperate hardware.c into hardware.c and hardware-plugin.c (app API and Plugin API)
• encapsulate "relation" mechanism
  • pull "relation" plugin into API to get rid of all those *_list_get_next() etc. functions
• add "configured_ledcount" property to <hardware>, to get an initial ledcount for LedHardwares that don't have a chain, yet (e.g. if led_hardware_initialize() inside prefs->hardware function fails). It should reflect the requested ledcount at initial hardware-initialization. The hardware can still initialize a different ledcount, for cases, where the hardware-plugin knows better how much LEDs are currently controlled/connected.
• provide ubuntu deb
• working hardware-plugin API version handling practice

[edit] Version 0.2

• decent unit tests (http://check.sourceforge.net)
• bindings to Processing OSC
• working API version handling practice
• working prefs-file version handling practice
• create & test OLA output plugin

[edit] Version 0.3

• (online) LedTileLibrary to organize LedTile's that are referenced from other LedTile

[edit] Version 0.x

• abstract plugin code (LedHardwarePlugin -> LedPlugin)
• abstract object (linked list) relation code