There are lots of guides for HyperBian running on a Raspberry Pi with a HDMI splitter & USB HDMI capture (See Inspo 1 & 2).
There are also some videos showing Hyperion on ubuntu/docker with WLED installed on a D1 mini behind the TV and Hyperion Grabber app for capture (See Inspo 1 & 2).
I didn't find much information on the latter option, let alone mixing the two together, so I've decided to create a guide mostly inspired by the videos above. I have also included some tips using the WLED option if you already have a server running and would like to use that to run Hyperion instead of a Raspberry Pi/HyperBian, they will be rendered as tips - please ignore these if you're sticking with the Raspberry Pi/HyperBian option.
| Name | Specs | URL | ~$AU |
|---|---|---|---|
| TV | Android TV or Nvidia Shield or Chromecast TV | ||
| LEDs | 5V WS2812B or 12V WS2815 | url | $20 |
| Power Supply | 5V 10A or 12V 10A | url | $23 |
| Raspberry Pi Power Supply | 12V->5V 3A USB Step down module or 5V 3A power supply | url | $6 |
| Power Supply Barrel Adaptor | Female | url | $1 |
| Raspberry Pi | Zero WH or newer | url | $26 |
| SD Card | 2GB or larger | url | $2 |
| Jumper Wires | Female to male | url | $2 |
You'll need an Android enabled TV that can install third party apps.
Note
For my setup I used an NVIDIA Shield TV Pro connected to a Samsung 55" TV.
Tip
If you are going with the server option instead of the Pi, you can purchase a WeMos D1 Mini ESP8266 Micro instead of the Pi/SD card above. It will still be powered by the same step down module.
Measure the perimeter of your TV and purchase LEDs that either match or exceed this length.
There are 2 options for LEDs, 5V WS2812B and 12V WS2815. Either are fine however there can be some noticeable voltage drop across the 5V WS2812B for longer distances, yet additional power supply injections can mitigate this.
You'll want 60 LEDs per metre for consistent lighting although 30 will still yeild decent results.
For protection rating, IP30 is fine. Noting the higher the rating the more coating the LEDs will have. There is adhesive backing for the IP30 & IP65 and none for the IP67, but you shouldn't need high water proofing (unless your watching TV in the rain, in which case i'm impressed).
Colour doesn't matter but black PCB can help to blend into the back of your TV a little.
Note
For my setup I went with 4m, 12V WS2815, 60 LEDs/m, IP30, Black PCB.
This is dependent on 3 things:
-
Total number of LEDs you'll be using (this will give us the total amps required).
Remember:Power = Voltage * Amps (P = V * I).
Your power supply will need to meet the amperage required for each LED. You'll need somwhere between the minimum 0.02a per LED and the maximum 0.06a per LED.
If purchasing 4m of 60 LEDs/m, you'll have a total of 240 LEDs.
To find the minimum amperage:240 LEDs * 0.02A per LED = 4.8 amps min.
To find the maximum amperage:240 LEDs * 0.06A per LED = 14.4 amps max.
In Australia, you can get a maximum of 10A from a wall socket, so we'll use this our as power supply amperage.
To double check,10A / 240 LEDs = 0.04a per LEDs, which lies between the recommended bracket per LED. -
5V or 12V LEDs purchased (this will give us the total voltage and total power required).
If we continue to use the 10A example:
5V LEDs:5V * 10A = 50W power supply.
12V LEDs:12V * 10A = 120W power supply. -
Whether you power the Raspberry Pi from this same power supply or use a separate power supply (this will indicate whether we need a step down module or another power supply).
A Raspberry Pi 3B+ requires 5V 3A. A step down module will take this 5V 3A from the original power supply and use it to power your Raspberry Pi. If we want to connect this to the same power supply we'll need to subtract this from the above 10A requirements to see if there is still enough amperage for the LEDs.
7A / 240 LEDs = 0.03 per LED, which is still in the bracket.
Make sure you get a step down module that meets the power requirements on your Pi and has the correct USB power interface. It's better to power your Pi through the USB port as opposed to the GPIO pins as you keep your Pi power safety features.
If powering the Pi separately, your LEDs will consume the original 10A.
If powering the Pi through a 5V power supply, you won't need a step down module but the same principle applies.
Note
For my setup I went with 120W, DC 12V, 10A, AU power supply with a DC 12V->5V 3A Micro USB step down module.
This isn't 100% necessary but it allows easier connection into your power supply port by plugging in an adaptor instead of stripping and soldering wires.
The power supply linked has a 5.5mm long port and fits into both 2.5mm/2.1mmm wide inlets.
The barrel purchased needs a female interface that matches these measurements.
Some adaptors have specified a max transmission voltage (0V-38V) or power (300W) but this one has been working fine for my 12V 10A setup.
Note
For my setup I went with a single 5.5mm x 2.1mm female adaptor.
Your Pi us going to need 3 main features.
- Welding Pin Header (Female to Male)
- Wi-Fi
- SD Card (2GB+)
The Pi Zero with a 2GB SD card holds the minimum hardware to meet these requirements and any model above this will work well.
A jumper wire with a female to male header will connect the welding pin header on the Pi into the LED strip socket. Some LED strips may have differing interfaces, so you can purchase the 120pcs set of wires to be safe. These wires come in handy and can be used on other projects.
Note
For my setup I went with a Raspberry Pi Model 3 B+ 1GB, 16GB SD Card, 120pcs 10cm jumper wire set.
Tip
If you're going with the server option instead of the Pi, install Hyperion on your server using the following sudo apt-get install hyperion and install WLED on your D1 mini using the WLED site. Simply plug in your D1 mini via usb and it will detect and flash it automatically - very intuitive. Connect to its Wi-Fi AP: wled-ap with default password: wled1234. Change the wireless settings for it to connect to your network. Get its new IP addres and access it via web browser. Change the LED count to what you've already counted and reboot. Some other settings i liked to change for performance included disabling Wi-Fi sleep, disabling amp limit, and removing SSID & MDNS. You can skip down to configuring Hyperion.
I think the hardest part is the research preparation to order the correct equipment. Now that we have everything delivered we are ready to build the kit.
I've taked most of the steps from here on how to install HyperBian on your Pi. HyperBian is Raspberry Pi OS Lite with Hyperion pre installed.
Download HyperBian.zip from here and extract it so you can see HyperBian.img.
Install Raspberry Pi Imager from here.
Plug your SD card into your PC and run Raspberry Pi Imager.
Follow the steps choosing Custom OS and the HyperBian-XXXX.img package downloaded.
Use the SD card as the storage target.
Click next and apply OS custimisation settings. (If you want to use WiFI, select edit settings, tick configure Wireless LAN, add your SSID, password and select your wireless LAN country)
Continue with the steps and wait for the flash.
Optional: Once completed, open your SD card called boot, create another file called ssh with no filename extension to enable SSH for troubleshooting.
Note
The Pi B+ doesn't have 5GHz Wi-Fi so double check which Wi-Fi credentials you're connecting to.
Once completed, safely eject the SD card and insert it into your Pi. You can now power on your Pi and test you can see it connected from your router console and access the Hyperion portal from your web browser 192.168.1.XXX:8090.
Once on the portal click the spanner icon in the top right and change the settins level to Expert.
On the left side under LED Instances, LED Output, change Controller type to ws281x
If using 12V change the RGB byte order to RGB.
If using 5V change the RGB byte order to GRB.
Change your Maximum LED count and Hardware LED count to the maximum LEDs identified earlier and press save.
Navigate to the LED Layout tab on the same page.
Open Classic Layour (LED Frame) and enter some temporary numbers that are add up to less than the total number of LEDs and press save. We will return to this later once everything is setup to enter the exact counted LEDs.
Note
If you're receiving this error under System, Log (ERROR) Device disabled, device 'ws281x' signals error: 'Hyperion must run with "root" privileges for this device. Current user is: "pi", you will have to ssh into the Pi to fix this. Open cmd on your pc and type sudo [email protected] with password ambientlight.
Once logged in type this command to fix sudo updateHyperionUser -u root.
Tip
If you're continuing with the server option instead of the Pi, click Hyperion LED output, LED controller, Wireless, WLED, and add the IP address of WLED or scan for it. Configure its LED preferences as above and disable enable automatic brightness limiter. If you navigate back to the WLED web page, it should have notification saying Hyperion is taking of the control of WLED - "WLED if receiving live DDP data".
You can turn off your Pi now.
Starting with the power supply, connect the barrel adaptor to your power supply port.
Find the beginning of your LED strip by looking for arrows on the PCB pointing away from the connector.
Your LEDs should come with a female connector consisting of positive and a negative wires. 1 data wire for 5V or 2 data wires for 12V (12V has a backup data wire) and some extra voltage wires already exposed.
Open the positive and negative terminals of the barrel adaptor and connect the exposed positive and negative wires from the beginning of your LED strip.
If you have a 5V power supply for your LEDs and want to power your Pi from it as well, sacrifice an old USB micro charging cable by stripping then connecting the positive and negative wires into the terminals of the barrel adaptor and connecting the usb micro side into the Pi power port. Secure the terminals of the barrel adaptor now. (If you have data wires in your usb cable then safely tape these up)
If you have a 12V power supply for your LEDs and want to power your Pi from it as well, connect the stripped positive and negative wires from your step down module into the terminals of the barrel adaptor and connect the micro usb side into your Pi power port. Secure the terminals of the barrel adaptor now.
So we have power for both the LEDs and the Pi now, the last cable we need to connect is the data cable to transmit information from the Pi into the LEDs.
For 5V LEDs, connect the female end of your jumper wire into GPIO socket 18 of the Pi (6 down from the corner), and the male end into the middle data port of the connector at the beginning of your LEDs.
Your wires should be connected like the below for 5V.
For 12V LEDs, you'll need 3 jumper wires. Connect a female end of a jumper wire into GPIO socket 18 of the Pi (6 down from the corner), and 2 male ends into the middle data ports of the connector at the beginning of the LEDs. You'll need to strip and splice the 2 males and the single female jumper wires together. Be sure to cover any remaining exposed wires with tape.
Your wires should be connected like the below for 12V.
Tip
If you're doing the server option instead of the Pi, The hyperion LED layout instructions should be the same with the exception of using D4 / GPIO 2 on the D1 Mini instead of GPIO 18 on the Pi.
Before installing, let's perform a quick test. Power on the Pi and the LEDs. The LEDs should light up on boot, otherwise you can play around with the Effects tab under LED instances on the Hyperion web portal. If you're having issues at this point feel free to troubleshoot via the hyperion documentation or video links above to double check everyting is setup correctly.
It's time to remove the adhesive and attach your LEDs to the back of your TV. I started from the bottom left of my TV and navigated clockwise until reaching the starting point again with a few LEDs left over. You dont need to go to the complete edge of the TV, a few cm from the edges will do fine. Regarding corners, the LEDs strips bend and don't need to be stuck down completely at all points.
You're going to want to keep the Pi close to the LEDs/TV to avoid purchasing and wiring a logic level converter. I used double sided tape and velcro to attach the kit securely to the back of my TV.
We need to modify the LED layout in Hyperion to be the exact number of LEDs counted on our TV. Go around your TV and count the exact number of LEDs on each side.
I counted 72 LEDs on the top and bottom of my TV, and 41 LEDs on the left and right. That means I'm only using 226 out of the toal 240 LEDs and 14 are left powered off. I can cut these remaining LEDs off or leave them hidden behind the TV.
The default input position starts from the top left. If you're like me and started your LED strip from a position other than the top left, you'll need to count how many LEDs to offset this starting position by.
To obtain the Input postion number for the bottom left starting point, we have to count clockwise from the default starting point of the top right. 72 across the top + 41 down the right side + 72 across the bottom = position 185, aka bottom left.
Download the hyperiongrabber.tv.apk from here and put it on a USB for installation on the TV.
On your TV Play Store, install any file browser app temporarily to browse to your USB and install the downloaded apk, you wont need this after installation.
Once Hyperion Android Grabber is installed, open it and navigate to settings.
Configure the host address, port and horizontal/vertical LED counts and save. I also increased my message priority to 100 and adjusted my FPS to match my media.
By default Hyperion should allow network screen capturing, so you can press the power button on the home screen and hopefully your LEDs are lighting up in sync with the image displayed on your TV.
Congratulations! 🎉 You've setup ambilight and can now enjoy the immersive experience through your preferred video app such as Plex or Kodi. Please let me know of any feedback or edits to this guide are necessary and I can ammend.
Amazing work, mate! Thanks for the handy and detailed tutorial. I'm about to order all the stuff to start next week on this project. Just before I jump into this DIY, I wanted to ask:
Does this mixed method allow you to play 4K content on Kodi? What about 4K HDR? Is that possible at all?
Also, will it work on other apps such as YouTube and Twitch?
Thanks for putting this together. I appreciate it!