DFAtmo
DFAtmo copied to clipboard
durchflieger
DFAtmo the driver for Atmolight controllers for XBMC and xinelib based video players
This is the README file of DFAtmo the driver for Atmolight controllers for VDR, XBMC and xinelib based video players.
Written by: Andreas Auras ([email protected])
See the file COPYING for license information.
Project repository: git://github.com/durchflieger/DFAtmo.git
Description:
"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: http://www.vdr-wiki.de/wiki/index.php/Atmo-Light http://www.vdr-wiki.de/wiki/index.php/DF10CH http://www.vdr-wiki.de/wiki/index.php/Atmo-plugin
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 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:
- Output drivers
- Native Python "atmodriver" module
- DFAtmo XBMC addon
- DFAtmo xinelib plugin
- 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: http://www.libusb.org/wiki/libusb-1.0
For ubuntu you can use package "libusb-1.0-0-dev".
For windows you need a very recent version with windows support from here: http://www.libusb.org/wiki/windows_backend
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: http://hg.debian.org/hg/xine-lib/xine-lib-1.2
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':
xine-ui-dfatmo-switch.patch
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.
xineliboutput-dfatmo-switch.patch
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 functionality. 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:
--post=dfatmo:driver=serial,driver_param=/dev/ttyS0,top=1,bottom=1,left=1,right=1,center=1
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
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.
top bottom left right center top_left top_right bottom_left bottom_right 0 Number of sections (RGB channel groups) in area. For top, bottom, left and right area more then one section could be specified. 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_red wc_green 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.
usb:
proto:
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
descriptor:
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:
http://www.vdr-wiki.de/wiki/index.php/Atmo-plugin
speed:
Supported values on Linux are: 1200,2400,4800,9600,19200,38400,57600,
115200,230400,460800,500000,576000,921600,
1000000,1152000,1500000,2000000,2500000,
3000000,3500000,4000000
Supported values on Windows are: 1200,2400,4800,9600,19200,38400,57600,
115200,128000,256000
amblone: Enable protocol extensions for "amblone" controller (escape handling). Protocol definition for this controller can be found here: http://www.amblone.com/download/doc
Examples of driver parameter: "COM5&speed:115200&proto:classic"
"/dev/ttyUSB0&speed:57600&proto:255|0|0|12|Rl|Gl|Bl|Rr|Gr|Br|Rt|Gt|Bt|Rb|Gb|Bb"
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".
"/dev/ttySEDU&proto:x5A|xA1|Rbr|Gbr|Bbr|Rb14|Gb14|Bb14|-13|Rbl|Gbl|Bbl|Rl8|Gl8|Bl8|-7|Rtl|Gtl|Btl|Rt1|Gt1|Bt1|+13|Rtr|Gtr|Btr|Rr1|Gr1|Br1|+7|0/258|xA5"
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 "resources/lib/drivers". 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
Metadata
Owner
durchflieger
Metadata
DFAtmo the driver for Atmolight controllers for XBMC and xinelib based video players