DFAtmo the driver for Atmolight controllers for XBMC and xinelib based video players
License
durchflieger/DFAtmo
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
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 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: 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: 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 <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. 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:<expr> 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] proto:<descriptor> 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 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:<baud> Serial port transmission speed. Default is 38400. 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
About
DFAtmo the driver for Atmolight controllers for XBMC and xinelib based video players
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published