Description
This library utilizes USB serial connection for controlling externally connected leds to achieve high FPS and low latency ambient lighting experience. It has multiple profile support different led area configurations with color correction parameters.
For high frame rate capturing without performance issues, library uses native gfx library (libUTOPIA) to capture screen.
I highly recommend watching the demo
Features
- Easy to configure with testing features
- Multiple profile support
- TV Remote for controlling state, profiles and brightness (Only E/F for now)
- Automatic profile switching with black border detection
- HSV correction
- Brightness correction
- Uses native graphics library for high FPS and almost zero performance loss (not needed on H)
- Captures with or without OSD (Only E/F)
Hardware
TV has only FDTI and ACM kernel modules therefore you need to use an Arduino Pro Micro (Only on F/H) or FTDI USB serial converter (Fake ones will work too).
Only on F/H
You can use an Arduino Pro Micro/Leonardo or another board with USB CDC capability as is. This setup is recommended since it does not requires to connect an external hardware with onboard USB socket is used for connecting to TV. (You can use the attached ino with this configuration)
If you need WiFi, you can connect an ESP8266 NodeMCU to FTDI USB serial converter as shown below. Board can be powered via it's USB port rather than VIN pin if you want to. (You need to use the attached ino with this configuration!)
You can connect a Arduino Pro Mini to FTDI USB serial converter as shown below. (Not recommended for high number of leds!)
Firmware
Library uses Adalight protocol therefore you can use any Adalight compatible sketch as firmware. I if you are using an ESP8266 board with onboard USB Serial adapter, you need to use the attached sambilight-arduino.ino sketch.
Sketch: https://github.com/dmadison/Adalight-FastLED
More information
Configuration
Configuration parameters are similar to hyperion so you can use HyperCon config utility to easily determine values below.
Library can support multiple led area configurations. Profiles can be edited from libSambilight.config file and is switchable via remote control or automatically by black border detection.
01_99_Sambilight.init
- H_LEDS: Horizontal leds count (Top Side)
- V_LEDS: Vertical leds count (Left/Right Side)
- BOTTOM_GAP: Bottom side gap (Top Size - Bottom Size)
- START_OFFSET: Index of first led (Top Left is zero) (H_LEDS + V_LEDS + (H_LEDS - BOTTOM_GAP / 2))
- CLOCKWISE: Led order (Set to 0 for anti-clockwise)
Optional
- COLOR_ORDER: Capture color order
- CAPTURE_POS: Capture starts from bottom (Set to 1 for upside down and dont forget to change color order too)
- BLACK_BORDER: Black border detection for automatic profile switching (16:9, 21:9, 4:3, 3:2)
- TV_REMOTE: Enable control with TV remote buttons (Red, Green, Yellow, Blue) (SET TO 0 ON H)
- DEVICE: USB Serial device path (/dev/ttyUSB0)
- BAUDRATE: USB Serial baudrate. (921600 is highly recommended)
- GFX_LIB: Capture directly from graphics driver resulting +50 FPS and prevents UI from lagging during capture. (Not needed on H)
- CAPTURE_FREQ: Capture frequency in ms, increase this value if your TV having performance issues (Higher the value, lower the refresh rate.)
- CAPTURE_SIZE: Higher capture size resulting less flickering and more accurate blacks but it affects overall FPS (1=96x54 2=160x90 3=240x135 4=320x180 5=480x270 6=960x540)
- OSD_CAPTURE: Capture with OSD (Only works with GFX_LIB=1)
libSambilight.config (For profiles)
- name: Name of profile
- saturation_gain_percent: Saturation gain in percent
- value_gain_percent: Value gain in percent
- brightness_correction: Brightness correction value (To compensate TVs brightness setting)
- horizontal_depth_percent: Horizontal depth in percent
- vertical_depth_percent: Vertical depth in percent
- overlap_percent: Overlap in percent
- h_padding_percent: Horizontal padding in percent
- v_padding_percent: Vertical padding in percent
Installation
- Enable USB Serial support from factory menu. > Control > Sub Option > USB Serial > ON (Skip this step if you are not using FTDI)
- Install latest samyGOso if needed.
- Copy libSambilight.so and libSambilight.config to /mnt/opt/privateer/usr/libso
- Copy 01_99_Sambilight.init to /mnt/etc/init.d/ (Skip this step if you want to test the configuration first)
- Set file permissions with
Code: Select all
chmod +x /mnt/opt/privateer/usr/libso/libSambilight.so
Code: Select all
chmod +x /mnt/etc/init.d/01_99_Sambilight.init
Testing
If you want to test your led configuration, you can run library in single shot mode without copying the libSambilight.config file to init.d folder.
When you run library on singleshot mode, TV will render a test pattern for each led on it's capture area. You can verify that the each corresponding area is matching with it's led index and color. TV also saves a capture to /dtv/Sambilight.bmp so you can verify that your capture parameters are correct.
If everything is fine, BMP file, TV screen and led colors should match perfectly. (You can clear the test pattern by pressing any key on remote)
Behaviour of singleshot mode can be controlled with parameters below.
- TEST_PROFILE: Index of profile will be used on singleshot mode
- TEST_PATTERN: Set to 0 if you don't want to see the test pattern
- TEST_SAVE_CAPTURE: Set to 0 if you don't want to capture images as BMP to /dtv/Sambilight.bmp
For E/F Series
Code: Select all
samyGOso -d -A -B -l /mnt/opt/privateer/usr/libso/libSambilight.so H_LEDS:35 V_LEDS:19 BOTTOM_GAP:7 START_OFFSET:68 CLOCKWISE:1 BAUDRATE:921600 TEST_FRAMES:1 TEST_PATTERN:1 TEST_PROFILE:0 TEST_SAVE_CAPTURE:1
For rendering test pattern
Code: Select all
samyGOso -d -A -B -l /mnt/opt/privateer/usr/libso/libSambilight.so H_LEDS:35 V_LEDS:19 BOTTOM_GAP:7 START_OFFSET:68 CLOCKWISE:1 BAUDRATE:921600 TEST_FRAMES:1 TEST_PATTERN:1 TEST_PROFILE:0 TEST_SAVE_CAPTURE:0
Code: Select all
samyGOso -d -T -B -l /mnt/opt/privateer/usr/libso/libSambilight.so H_LEDS:35 V_LEDS:19 BOTTOM_GAP:7 START_OFFSET:68 CLOCKWISE:1 BAUDRATE:921600 TEST_FRAMES:1 TEST_PATTERN:0 TEST_PROFILE:0 TEST_SAVE_CAPTURE:1
To Do
- WLED Support
- gfx_lib for E Series
- gfx_lib for H Series
- Better configuration testing support
- Support for Non-MST H Series
- Arduino Pro Micro support for E series
- Remote control support for H series
- ECO sensor support for dynamic brightness adjustment
- USB HID or MSC device for not requiring an FTDI device
- Library as native executable app
- Socket support
- Smoothing for low frame rates (May not be needed)
- Custom ESP32 hardware and software (Work in progress)
Technical Details
Capturing
I basically reverse engineered the SdDisplay_CaptureScreen function from libSDAL.so static library and optimized it to take captures continuously without using mutexes. Turns out mali gpu has a feature to capture screen frames to a designated frame buffer and it can be configured to take screen captures continuously but exeTV or exeAPP does not use this feature to record any frames. I still use library on single shot mode because it is easier to handle frame buffer sync issues but i think this feature can also be utilized to record any source from TV without performance issues.
SdDisplay_CaptureScreen function uses native gpu functions for scaling down the image to another designated half size framebuffer but the original capture in 1920x1080 format.
This library uses only the static libraries already in TV for capturing, therefore it does not need to be injected in exeTV or exeAPP to work. It can be easily modified to compile and run as an arm executable.
Processing
I borrowed some features from hyperion and Prismatik projects but i wrote image processor completely from scratch. Library calculates led coordinates continuously according to the current selected profile therefore switching on the fly is possible. Library also handles the smooth transition of any profile setting in configuration. After calculating the average color values of each area, library makes color correction of each led according to the configuration settings.
I did not want to fully dynamic black border detection to prevent false positives on movies so i use black border detection only for profile switching. This way i can use completely different profile settings for 21:9 movies instead of only black border detection.
Currently library has no support for smoothing between frames to save CPU but it can be implemented on USB device.
Transporting
I tried too many things before finding out that when USB Serial support enabled from factory menu, OS loads ftdi_sio.ko and binds connected device to /dev/ttyUSB0.
I will find another way to communicate between TV and the USB device in the future. May be native USB HID driver can be utilized or an libusb virtual mass storage USB device can be configured to receive led data as files.. Later, I found a way to load cdc_acm.ko kernel module and map the usb cdc acm device with mknod. Now TV can attach a USB CDC device to /dtv/ttyACM* via this library without needing an external FTDI USB to serial adapter.
Important Notes
- Only FTDI USB Serial and USB CDC devices (Only on F/H) are supported for device connection. (Boards with cp210x or ch340 will not work!)
- TV_REMOTE must be set to 0 on H series.
- High baudrate is recommended for USB Serial connection.
- USB device must be connected before turning on the TV. There is no USB plug in detection.
- If you enable TV remote feature, you can use Red button for turning leds on/off, Green button for switching between profiles and Yellow button for adjusting brightness level of the leds.
- Black border detection is for only automatic profile switching. When enabled it adds a new profile named "Auto" that switches between other profiles by comparing its padding values with the black borders on the screen. You can still switch another profile from TV remote that and disables black border detection temporarily. You can select Auto profile to enable it again.
- Default profiles are optimized for 16:9, 21:9, 4:3 and 3:2 aspect ratios. I do not recommend to edit it's padding settings unless if you don't want to use black border detection feature. You can edit other parameters of default profiles or you can add another profiles if you want to.
- Library does not work well with libSoftPowerOff. Maybe fixed in the future.
- FPS drops while navigating on the TV menus due to performance limitations of injecting to the exeAPP, but you can fix it by disabling remote control support to inject with -T option.
- Native gfx library capture feature is only tested on F and still experimental (Not required for H) but necessary for smooth operation of the TV. If you are having crashes/reboots on your TV you should disable it. When this feature not enabled you have to increase capture rate and decrease capture size to prevent TV performance issues but smoothing must be handled on the usb device.
- If you have a TV with ECO sensor you may want to disable the eco feature because it interferes with the ambient lighting and panel looks dark all the time.
- Flashing lights may trigger epileptic seizure on certain people and I think that this is the reason of that original ambilight does not uses this kind of high FPS. Instead it uses some PID logic to change the colors by checking the duration on screen and smoothly fades between colors to prevent flashing lights.
- There may be bugs. I did not find time to test all configuration parameters for TV models other than F. If you are having crashes with specific configuration setting, please send me a pm and i will fix it as soon as possible i can.
Changelog
v1.0.4: First sable release
v1.0.5: Capture order feature
v1.0.6: Singleshot mode crash fix
v1.0.7: Baudrate config fix
v1.0.8: Test pattern and test capture feature
v1.1.0: CDC ACM support
v1.1.1: CDC Crash fix
v1.1.2: USB CDC fixes
v1.2.0: Load FTDI kernel modules dynamically
v1.2.1: USB CDC fixes
v1.2.9: Fixes for H Series
v1.2.10: Green flashing and black border detection fixes
v1.2.11: Brightness correction and serial not found fix
v1.3.0: E Series GFX_LIB support and ESP32 support
v1.3.1: Single-shot mode fix