DFAtmo the driver for Atmolight controllers for XBMC and xinelib based video players
C Python C++ Makefile Objective-C
Failed to load latest commit information.
patches First version of DFAtmo Sep 25, 2011
windows build new ready to use kodi plugin zip file Feb 12, 2017
.cproject Added new dfatmo vdr plugin Apr 26, 2012
.project Added new dfatmo vdr plugin Apr 26, 2012
.pydevproject First version of DFAtmo Sep 25, 2011
Makefile removed xbmc frodo addon Feb 12, 2017
atmodriver.c Optimize performance of image analysis algorithm: Nov 13, 2012
df10choutputdriver.c Support for config version 3 of DF10CH Nov 27, 2012
dfatmo.py migrate xbmc plugin for kodi v17 Feb 12, 2017
icon.png First version of DFAtmo Sep 25, 2011
serialoutputdriver.c Fix brocken build of serial driver for linux Feb 12, 2017
service.py Introduce separate service script for auto launch feature. Feb 10, 2013
testatmodriver.py Enhanced testatmodriver.py for testing script based output drivers Feb 1, 2012
vdrplug_dfatmo.cpp VDR plugin: Do send black color output only once when suspended. Feb 4, 2014


This is the README file of DFAtmo the driver for Atmolight controllers for
VDR, XBMC and xinelib based video players.

Written by: Andreas Auras (yak54@inkennet.de)

See the file COPYING for license information.

Project repository: git://github.com/durchflieger/DFAtmo.git


"DFAtmo" allows you to drive a colored back lighting for TVs similar to the
"Ambilight" of Philips televisions. The displayed color depends on the
actual shown video content.
Back lighting your TV is best done with light-emitting diodes (LEDs) that are
arranged as RGB light sources on stripes that could be mounted at the back
of your TV.
To drive these LED's a dedicated hardware is necessary that is called the
"Atmolight" controller. Beside some commercial products that you can simply buy
there exists several projects to build these hardware by yourself. 

DFAtmo continuously analyzes the video picture and generates output data
for these Atmolight controllers. DFAtmo supports VDR, XBMC and xinelib based
media players where it is installed as a plugin or addon. XBMC is supported
on Linux and Windows platforms.

To drive different Atmolight controller hardware DFAtmo uses it's own plugin
mechanism for output drivers. These output drivers are implemented as shared
libraries and are loaded dynamically at runtime.
Furthermore the python script based DFAtmo XBMC addon supports another plugin
mechanism for output drivers which are implemented as python scripts.
Currently there are output drivers implemented for controllers where the
communication is based on a serial port like the "classic" Atmolight
controller and for my own designed DF10CH "next generation" controller where
communication is done to over a proprietary USB protocol.

For debugging proposes there exists another output driver that is able to write
the color data to a file in a human readable layout.
And as an example for a script based output driver this file based output
driver is also implemented in python. 

Because of the modular plugin mechanism new output driver could be implemented
easily to support more hardware or even other targets.

For more detailed informations about "Atmolight" visit the VDR-Wiki:

Within XBMC V12.0 Frodo stable the DFAtmo support is brocken!!!
DFAtmo runs fine with stable XBMC V11.0 Eden, V12.1 Frodo
and with a recent git version after Feb. 10 2013.

Components of DFAtmo:

DFAtmo contains the following components:

1) Output drivers
2) Native Python "atmodriver" module
3) DFAtmo XBMC addon
4) DFAtmo xinelib plugin
5) DFAtmo VDR plugin

These components have dependencies among each other. The XBMC addon
needs 2) which in turn needs 1). The VDR and xinelib plugin needs 1).
The output drivers are shared by 3) 4) and 5)

Building the components:

The build process step by step:
There exists a common build target for the "atmodriver" module and the
output drivers.

For building the "atmodriver" module a python development environment is
required. The challenge here is that the version of the python environment
must be the same version your XBMC is compiled against.
For ubuntu this is currently the ordinary platform packet "python-dev".
For XBMC on Windows you currently have to download the XBMC source and
build dependencies and use the python libs from the build dependencies.

The output driver for the DF10CH controller depends on libusb-1.0 which
could be downloaded for Linux from:

For ubuntu you can use package "libusb-1.0-0-dev".

For windows you need a very recent version with windows support from here:

Before compiling the components you should decide at which place they should
be installed. This is controlled by the DFATMOINSTDIR make variable and the
default for Linux is "/usr/local". Please note that the XBMC addon currently
searches the components under "/usr" and "/usr/local". So you should use
one of these locations.

Compiling and installing the two components for Linux:
  make dfatmo
  make dfatmoinstall
For Windows the build process currently is not Makefile based.
There exists a Visual C++ 2010 project solution file in directory
"project" to build the components from within Visual Studio C++.
The XBMC source tree should be on the same directory level as
the DFAtmo source tree and should be called "xbmc" at top.
The same is it for libusb-1.0 and the top should be "libusb".

For Windows the generated "atmodriver.pyd" should be installed within the DFAtmo
XBMC addon script directory under "resources/lib.nt" and the output driver
dll's under "resources/lib.nt/drivers". This currently has to be done manually.

Building the DFAtmo XBMC addon as a installable zip file 'dfatmo-xbmc-addon.zip' for Linux:
  make xbmcaddon

Direct installation to $HOME/.xbmc/addons for Linux with:
  make xbmcinstall
For Windows there exists a Makefile target to build a installable zip file
"dfatmo-xbmc-addon-win.zip" which contains the addon and also the "atmodriver"
and output driver components. It could be executed from a cygwin environment:
  make xbmcaddonwin

In the git repository you will find already a recent version of
"dfatmo-xbmc-addon-win.zip" ready for installation.

For building the DFAtmo xinelib plugin you need a recent xine-lib-1.2
release from here:

For ubuntu you can use package "libxine2-dev".

Compiling and installation of the plugin:
  make xineplugin
  make xineinstall

For building the DFAtmo VDR plugin you need a recent VDR release >= 1.7

Compiling and installation of the VDR plugin for VDR 2.x versions with
pkg-config support:
  make vdrplugin
  make vdrinstall
Compiling and installation of the VDR plugin for older VDR versions without
pkg-config support:
  make -f vdrplug.mk all
  make -f vdrplug.mk install

For ubuntu there exists a debian package build you can use to build all components
in one step with:
  dpkg-buildpackage -b -D -tc -sd -us -uc
This generates three deb packages "dfatmo", "libxine-dfatmo-plugin" and
"vdr-plugin-dfatmo". The "dfatmo" package also contains the XBMC addon zip
file which will be installed to "/usr/lib/dfatmo".
To build only the "dfatmo" package there exists a dedicated debian control
file "debian/control-dfatmo-only". Copy this file to "debian/control" before
executing the dpkg-buildpackage command.
Additional patches located in sub directory 'patches':


This is a patch for the xine-ui player that extends the player with a 'DFAtmoEnabled' command
to switch the DFAtmo on/off.
The command can be bound to keyboard or LIRC keys but it is not supported by the remote interface.


This is a patch for the xineliboutput player that extends the player with a 'DFAtmoEnabled' command
to switch the DFAtmo on/off. Send slave command "DFAtmoEnabled" for toggling on/off,
"DFAtmoEnabled 0" for switching off or "DFAtmoEnabled 1" for switching on.
Also pressing keyboard key 'a' or sending LIRC command 'DFAtmoEnabled' toggles the DFAtmo.

Note that these patches do also support the older "atmo" xinelib plugin.

Configuration of the DFAtmo XBMC addon:

Installation of the DFAtmo addon zip file could be done with the usual XBMC
The addon could be configured by the user with the usual addon settings panel.

The addon could be started and stopped from the Program's menu. Alternatively
the addon could be started automatically by setting the auto launch option
in the addon settings menu.

Configuration of the DFAtmo xinelib plugin:

Load the DFAtmo plugin as a post plugin in your xinelib based media player.
For the VDR xineliboutput player or xine-ui player add a command line option like this:


When using DF10CH controller(s):

--post dfatmo:driver=df10ch

The plugin stores the actual parameter setting in the xinelib config file
under the key 'post.dfatmo.parameters'.
Plugin parameters specified at the command line are mandatory and always
override the parameters stored in the xinelib config file at startup time.
You should specify all static parameters like output driver or section layout
at the command line.
Parameters that you wish to trim while player is running should not be specified within the
command line. Players like xine-ui have GUI support for changing plugin parameters
(press <alt><shift>p to show the post processing panel).

Configuration of the DFAtmo VDR plugin:
Load the DFAtmo plugin by adding a command line option like this:

-P dfatmo

The log level for the DFAtmo plugin could be controlled by a plugin 
parameter like this:

-P "dfatmo -l 3"

The plugin could be configured by the user with the usual plugin setup menu.
With the auto launch option you can control if the Atmolight should be
switched on or off on startup of VDR.

With the plugin control menu you can temporarily switch on/off or change the
brightness of the Atmolight. These settings are not stored in setup.
Alternatively you can control these settings with the following hot keys:

@dfatmo ok     -> toggle Atmolight on/off
@dfatmo red    -> switch Atmolight off
@dfatmo green  -> switch Atmolight on
@dfatmo yellow -> increase brightness by 10
@dfatmo blue   -> decrease brightness by 10

You can control the plugin with the following SVDRP commands:

enabled yes    -> switch Atmolight on
enabled no     -> switch Atmolight off
enabled        -> return current enabled status (YES or NO)

Parameters understood by DFAtmo:

There are a hole bunch of parameters to control DFAtmo. 
Changes of Parameters marked with * will be immediately applied while the video player
is running. The other parameters will be applied after a stream stop/start sequence
(this happens already when switching a channel within VDR).

Parameter          Default          Description

driver             none             Selects output driver. Currently supported are:

                                    file     Write output data to file. Useful for 
                                             testing and debugging.
                                    serial   Send output data to serial port.
                                    df10ch   Output driver for my own designed 
                                             DF10CH 10 channel Controller(s).

driver_param                        Parameter for output driver:

                                    file:    File name of output file. If not specified
                                             "atmo_data.out" is used.
                                    serial:  Path to serial output device.
                                             Default is "/dev/ttyS0" for Linux and "COM1"
                                             for Windows.
                                             See description for serial output driver for
                                             further options.

                                    df10ch:  All connected controllers are scanned automatically.
                                             No parameter required here.

bottom_right       0                Number of sections (RGB channel groups) in area.
                                    For top, bottom, left and right area more then one section could be
                                    Valid values: 0 ... 128 for top, bottom, left, right
                                    Valid values: 0 ... 1 for center, top_left, top_right, bottom_left, bottom_right

                                    For DF10CH controller you do not have to specify these parameters here because they are read
                                    from the controller configuration data. Use the DF10CH setup program to configure your
                                    desired layout.
analyze_rate *     35/40            Rate of frame grabbing and video analysis. Unit milliseconds.
                                    Valid values: 10 ... 500

analyze_size *     1                Size of analyze window. The window width is calculated by (analyze_size+1)*64 pixel.
                                    The window height is calculated aspect correct according to the grabbed video
                                    window size. So a analyze size of 1 for a 16:9 video will give us a 128x72 pixel
                                    analyze window.
                                    Valid values: 0 ... 3

                                    For DF10CH controller you do not have to specify this parameter here because it is read
                                    from the controller configuration data. Use the DF10CH setup program to configure your
                                    desired analyze size.
overscan *         0                Ignored overscan border of grabbed video frame.
                                    Unit is percentage of 1000. e.g. 30 -> 3%
                                    Valid values: 0 ... 200

                                    For DF10CH controller you do not have to specify this parameter here because it is read
                                    from the controller configuration data. Use the DF10CH setup program to configure your
                                    desired overscan.
edge_weighting *   60               Power of edge weighting.
                                    Value is divided by 10 e.g. 80 -> power of 8
                                    Valid values 10 ... 200

                                    For DF10CH controller you do not have to specify this parameter here because it is read
                                    from the controller configuration data. Use the DF10CH setup program to configure your
                                    desired edge weighting.

weight_limit *     12               Limit for edge weighting.
                                    Pixel positions of the analyze image with a weight value below this limit are ignored.
                                    Valid values 0 ... 255

darkness_limit *   1                Minimum brightness of pixel. Values below are interpreted as black pixel.
                                    Used to detect and skip "black borders" in video.
                                    Valid values are 0 ... 100

hue_win_size *     3                Windowing size for HUE. Valid values 0 ... 5

sat_win_size *     3                Windowing size for saturation. Valid values 0 ... 5

hue_treshold  *    93               Threshold limit for change of color.
                                    Unit percentage of 100. Valid values 1 ... 100
brightness  *      100              Controls brightness of generated color values.
                                    Unit percentage of 100. Valid values 50 ... 300
                                    Note: When using DF10CH controller(s) it is better to use the white calibration or
                                    common brightness feature of the DF10CH setup program instead of this
                                    parameter because you will lose lesser or no PWM resolution.

uniform_brightness * 0              Enable/Disable uniform brightness calculation.
                                    Valid values: 0 (disabled), 1 ... 255 (enabled)
                                    When enabled only one uniform average brightness value is calculated
                                    for all sections. This is the behavior of the "classic" VDR Atmolight plugin.
                                    For calculating the average value only bright pixels are taken into consideration 
                                    which have a brightness value greater or equal than (darkness_limit * uniform_brightness).
                                    The "classic" VDR Atmolight plugin used a fixed uniform_brightness value of 10 and
                                    a standard darkness_limit of 5.
                                    When disabled a average brightness value is calculated for each
                                    section. This mode is more suitable when many sections for a area exists.   
filter *           combined         Select smoothness filter. Currently there are two filters
                                    supported: percentage and combined.
                                    Valid values: off, percentage, combined
                                    For every full video frame color values are calculated. To avoid flickering a kind of
                                    average is formed between the found colors.

                                    filter=percentage: Every anew calculated color value contributes a certain percentage
                                    to the indicated color. This contribution can be configured with the parameter
                                    'filter_smoothness'. Often this filter looks very nervous, but also wonderfully spontaneous.

                                    filter=combined: A running average from the calculated colors is formed. For which time
                                    span the average will be formed can be configured with parameter 'filter_length'.
                                    Greater values will result in more slowly fading to new colors. In addition, it is
                                    supervised whether there is a jump in the calculated color values (for example, within a
                                    scene change). A jump is recognized if the new color has the distance of the parameter
                                    'filter_threshold' from the average color. Greater values will result in more seldom
                                    recognized jumps. If a jump is recognized, the indicated color is corrected immediately
                                    to the new value. If no jump was recognized, the 'percentage' filter is used again and
                                    provides for a slightly gentle crossing. Greater values of parameter 'filter_smoothness' will
                                    result in a more softly crossing.

filter_smoothness * 50              Controls filter smoothness of percentage filter.
                                    Unit percentage of 100. Valid values 1 ... 100

filter_length *    500              Controls filter length of combined filter.
                                    Unit milliseconds. Valid values 300 ... 5000

filter_threshold * 40               Controls filter threshold of combined filter.
                                    Unit percentage of 100. Valid values 1 ... 100

filter_delay *     0                Controls delay of output send to controller.
                                    Unit milliseconds. Valid values 0 ... 1000
                                    Note: Delay should be specified as multiples of 20ms
wc_blue *          255              White calibration values for red, green and blue channel.
                                    Valid values 0 ... 255.
                                    Note: When using DF10CH controller(s) it is better to use the white calibration 
                                    feature of the DF10CH setup program instead of this parameter because you will
                                    lose lesser PWM resolution.

gamma *            0                Gamma correction factor for red, green and blue channel.
                                    Value is divided by 10 e.g. 25 -> gamma 2.5
                                    Valid values 0 ... 50. 0 means no gamma correction
                                    Note: When using DF10CH controller(s) it is better to use the gamma calibration 
                                    feature of the DF10CH setup program instead of this parameter because you will not
                                    lose PWM resolution.

output_rate *      20               Rate at which color information is send to the Atmolight controllers. Unit milliseconds.
                                    Valid values: 10 ... 500

start_delay *      250              Delay after stream start before first output is send [ms].
                                    The VDR plugin used this parameter also for polling the video device when in suspend mode.
                                    When the video device does not return a valid image on a grab request the DFAtmo plugin
                                    assume that the video output is suspended and enters suspend mode.
                                    While in suspend mode the DFAtmo grab and output thread rate is set to the start delay
                                    time to lower CPU usage.
                                    Currently this parameter is not supported by XBMC addon.
                                    Valid values 0 ... 5000.

enabled *          1                Enable/Disable output of color values to atmolight controller.
                                    Valid values: 0 (disable), 1 (enable)


Options of serial output driver:

The serial output driver understood some more options within the "driver_param" parameter.
These options are applied as keyword/value pairs separated by a colon. Several options
are separated by ampersand.

            For users with usb-to-serial converters the device could be specified as a
            regular expression on Linux platform that is looked up in "/proc/tty/driver/usbserial"
            to evaluate the /dev/ttyUSB device. The option is a regular expression which is
            used to match a corresponding entry in "usbserial".
            e.g.: usb:pl2303.*-[^6]

            Protocol descriptor string that describes the byte sequence that is send to
            the Atmolight controller.
            Within the descriptor you can specify constant values, color variables, 
            checksum variables and shortcut operators.
            Each position is separated by "|" and all letters are case insensitive.
            Do not include any whitespace within the descriptor string.
            Constant values could be specified as decimal or by prefixing with letter "x" as
            hexadecimal values:
              xFF -> constant value 255
              13  -> constant value 13

            For constant values a repeat count or fill up count could be specified to
            define a arbitrary number of bytes with the same constant value:
              56*15   -> 15 constant bytes of value 56
              xFA*20  -> 20 constant bytes of hexadecimal value FA
              23/512  -> Fill up the byte sequence with constant bytes of value 23 until
                         length of sequence reaches 512 bytes.

            The name for a color variable consists of the color code, area code and
            optional the section number.

            The color codes are: R = red, G = green, B = blue

            The area codes are: T = top, B = bottom, L = left, R = right, C = center,
                                TL = top left, TR = top right, BL = bottom left,
                                BR = bottom right

            Section numbers start at 1 and are counted in increasing order from left
            to right and top to bottom:
                            TL T1 T2 ... Tn TR
                            L1              R1
                            L2     C        R2
                            ..              ..
                            Ln              Rn
                            BL B1 B2 ... Bn BR
            Example: RL2 -> red color of left area section 2
                     BTL -> blue color of top left area
                     GB  -> green color of bottom area section 1  

            The checksum variables are:
              CX = One byte XOR checksum over all bytes of the sequence excluding the
                   checksum byte. The karatelight controller expected this checksum at
                   byte position 3. 

            A couple of RGB groups within the same area with monotone increasing or
            decreasing sections could be defined with the shortcut operators '+n' and
            '-n' where n is the number of following groups to generate:
                 "Rl1|Gl1|Bl1|+2" is equal to "Rl1|Gl1|Bl1|Rl2|Gl2|Bl2|Rl3|Gl3|Bl3"
                 "Gb5|Rb5|Bb5|-2" is equal to "Gb5|Rb5|Bb5|Gb4|Rb4|Bb4|Gb3|Rb3|Bb3"
            There are predefined protocol sequences that could be specified as the
            classic -> 255|0|0|15|Rc|Gc|Bc|Rl|Gl|Bl|Rr|Gr|Br|Rt|Gt|Bt|Rb|Gb|Bb
                       areas: Center, Left 1, Right 1, Top 1, Bottom 1
            df4ch   -> 255|0|12|Rl|Gl|Bl|Rr|Gr|Br|Rt|Gt|Bt|Rb|Gb|Bb
                       areas: Left 1, Right 1, Top 1, Bottom 1
            amblone -> xF4|Rl|Gl|Bl|Rr|Gr|Br|Rt|Gt|Bt|Rb|Gb|Bb|x33
                       areas: Left 1, Right 1, Top 1, Bottom 1
            karatelight -> xAA|x12|CX|24|Gl|Bl|Rl|Gr|Br|Rr|Gt|Bt|Rt|Gb|Bb|Rb|Gl2|Bl2|Rl2|Gr2|Br2|Rr2|Gt2|Bt2|Rt2|Gb2|Bb2|Rb2
                           areas: Left 1, Right 1, Top 1, Bottom 1, Left 2, Right 2, Top 2, Bottom 2
                           Note: Karatelight expected the number of colors in sequence at byte position 4.
            In case you do not specify a protocol descriptor the "classic" protocol
            for Atmolight 2 channel controller will be used as default.
            Protocol definition for this controller can be found here:

            Serial port transmission speed. Default is 38400.
            Supported values on Linux are: 1200,2400,4800,9600,19200,38400,57600,
            Supported values on Windows are: 1200,2400,4800,9600,19200,38400,57600,
            Enable protocol extensions for "amblone" controller (escape handling).
            Protocol definition for this controller can be found here:

Examples of driver parameter:


The following example is for a digital LED stripe installation with SEDU controller with
14 Leds at top/bottom, 8 Leds at left/right, 1 Led for each corner.
Each Led is a separate section for which a three byte color value in order R,G,B is send. 
First Led of chain starts at bottom right corner. Order of Leds is clock wise around the TV.
Mode A1 of SEDU miniDMX protocol is used with 256 data bytes.
Total frame length is 259 bytes.
Serial Port is "/dev/ttySEDU".

Python script output driver:

The DFAtmo XBMC addon supports output drivers written as python scripts. To use such a
driver set the "Output driver" parameter to "Custom" and enter the name of the python module
to load in the "Custom driver" parameter field.
The python module should be store in the DFAtmo XBMC addon directory under
There is already a example driver called "mydriver" that writes a file with color data
similar to the native file output driver. The name of the file is specified
in the "Driver parameters" field.

Performance hints:

Continuously analyzing the video picture is a cpu intensive job. Several parameters of DFAtmo have influence
on the amount of cpu load that DFAtmo will produce while running. As a hint for optimization the influence
on cpu load by the parameters shows the following table:

Parameter             increases CPU load                   decreases CPU load           Influence
analyze_size               greater                              smaller                   high
analyze rate               shorter                              longer                    high
edge weighting             lower                                higher                    high
weight_limit               lower                                higher                    moderate
number of sections         more                                 less                      moderate
windowing size (hue/sat)   bigger                               smaller                   moderate
darkness_limit             lower                                higher                    small