How to Install and Configure Hyperion Ambient Lighting on Raspberry Pi

Hyperion is an open-source ambient lighting software that allows you to create immersive lighting effects and environments using LED lights connected to a Raspberry Pi. With Hyperion, you can synchronize your LED lights to react and change color based on whatever is displayed on your TV or computer monitor.

In this comprehensive guide, I will walk you through the entire process of installing, configuring and setting up Hyperion on Raspberry Pi from scratch.

Prerequisites

Before we get started, here is what you’ll need:

• A Raspberry Pi – any model should work but Pi 3B+ or Pi 4 is recommended
• An SD card with Raspbian OS installed
• LED lights – WS2812b LED strips or AdaFruit NeoPixels. The number of LEDs supported depends on the Pi processing power
• 5V power supply for powering the LED lights
• HDMI cable for connecting Pi to TV/monitor
• Ethernet cable or WiFi dongle (for connecting Raspberry Pi to network)

Once you have the hardware ready, you can proceed to install and set up the software.

Step 1 – Update Raspberry Pi

As with any software installation, it‘s good practice to ensure your Raspberry Pi‘s package list and packages are up to date.

Connect to your Pi via SSH or log in directly, then run the following commands:

sudo apt update
sudo apt upgrade

This fetches the latest package lists and installs all available upgrades.

Step 2 – Install Dependencies

Hyperion relies on some additional dependencies that need to be installed beforehand. Run the following to install them:

sudo apt install cmake protobuf-compiler libprotobuf-dev libqt4-dev libusb-1.0-0-dev pyqt4-dev-tools git build-essential

This installs cmake, protobuf, Qt4, libusb and some other compiler toolchains required for building software from source.

Step 3 – Clone Hyperion Repository

Now we will clone the official Hyperion GitHub repository to get the latest source code.

cd ~
git clone https://github.com/hyperion-project/hyperion.ng.git
cd hyperion.ng

This clones the repository into a hyperion.ng folder within your home directory.

Step 4 – Configure Hyperion

Before building Hyperion, we need to configure it to work with your specific LED light setup. This is done by editing the config/hyperion.config.json file.

nano config/hyperion.config.json

Scroll down and edit the following values:

Json section:

• "device": Set this to "spi"
• "rate" : Match this to your LED strip frequency (usually 400000 or 800000)

Led section:

• "output" – Set to appropriate output mode based on LED strip type
  • Use "ws2812spi" for WS2812b strips
  • Use "apa102" for AdaFruit DotStar strips
• "colorOrder" : Set the RGB order to match LED strip wiring
• "rate" : Should match the value set above

E131 section:

• "universe" : Set this to 1

Save the changes to hyperion.config.json once done (Ctrl+X followed by Y and Enter)

This configures Hyperion with SPI output to WS2812b LEDs at 400KHz bitrate and sets the DMX E1.31 universe to 1.

You can configure additional settings like number of leds, color depth etc later on.

Step 5 – Build and Install Hyperion

We are now ready to build and install Hyperion. Make sure you are in the hyperion.ng directory extracted previously and run:

mkdir build
cd build
cmake ..
make 

This runs cmake to configure the build files and then compiles the Hyperion binaries.

Once the compilation finishes without errors, run this to install Hyperion:

sudo make install

This installs Hyperion binaries to /usr/local/bin and support files to /etc/hyperion

Step 6 – Blacklist SPI Kernel Driver

By default, Linux uses the SPI interface for its own kernel drivers. So we need to blacklist them to give Hyperion exclusive control.

Edit blacklist file:

sudo nano /etc/modprobe.d/blacklist-hyperion.conf

And add in the following lines:

blacklist spi_bcm2708  
blacklist spidev

Save and exit the file.

Now reboot Raspberry Pi to allow changes to take effect:

sudo reboot

Once your Pi restarts, Hyperion SPI interface is ready to use.

Step 7 – Start Hyperion Service

To test if Hyperion is working, let’s start it’s service daemon:

hyperiond /etc/hyperion/hyperion.config.json

This launches the Hyperion daemon and should make your LED strip blink in rainbow colors.

Press Ctrl+C to stop the daemon for now.

We’ll configure the service properly in the next step.

Step 8 – Setup Systemd Service

For Hyperion to auto-start on boot and run smoothly in background, we’ll setup a Systemd service.

Create a service file:

sudo nano /lib/systemd/system/hyperion.service

Paste this configuration:

[Unit]
Description=Hyperion Daemon
After=network-online.target

[Service] 
ExecStart=/usr/local/bin/hyperiond /etc/hyperion/hyperion.config.json
User=pi  
StandardOutput=null
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target  

Now register the service:

sudo systemctl enable hyperion.service

This will make Hyperion start automatically when the Pi boots up.

Let’s go ahead and start it right now:

sudo systemctl start hyperion.service

Check status with:

systemctl status hyperion.service

You should see active Active: active (running) which means its working!

The LEDs should now be blinking with rainbow colors continuously.

Step 9 – Setup Boot Logo & Black Border

Whenever you power on the TV/monitor connected to the Pi, there can be a mismatch between the screen refresh rate and when Hyperion starts up.

This causes unwanted flashes of color bursts on LEDs.

To avoid this, we can configure a static boot logo and small black border in Hyperion.

Set Boot Logo

Navigate to /etc/hyperion and create a simple single color image:

cd /etc/hyperion
sudo touch bootlogo.png

Set the color you want using ImageMagick:

sudo convert -size 1x1 xc:black bootlogo.png

This creates a 1×1 black pixel image that will be used as the boot logo.

Now open config file:

sudo nano hyperion.config.json    

And update the bootsequence section:

"bootsequence": { 
    "duration_ms": 3000, 
    "image": "/etc/hyperion/bootlogo.png" 
}

This sets the logo duration to about 3 seconds.

Save and exit the config file.

Configure Black Border

We can also mask a few edge LEDs to always stay black while the central LEDs react to screen content.

This helps avoid overspill of colors onto walls during boot up.

Still in the config file, add the following border section:

"border" :{
 "width" : 4
}

This keeps 4 LEDs on each edge side black. Play around with different width values as per your setup.

Save config once done.

Now restart Hyperion for changes to apply:

sudo systemctl restart hyperion

The boot logo and black border should now take effect!

Step 10 – Control Hyperion Via Web UI

Hyperion comes with a handy web interface that can be used to configure colors, effects, components and other settings easily.

To access it, simply open a web browser and enter your Pi’s IP address with port 8090:

http://<raspberry_pi_ip>:8090 

For example: http://192.168.1.10:8090

You will be presented with Hyperion’s home page showing current effect, color and component values.

Click on “Settings” and then “Ui Configuration” on the left sidebar to customize the web UI to your liking.

From this interface, you can manually set colors, modify effects, adjust LED settings and also create JSON config files to descriptively outline your desired lighting states.

It’s self-explanatory so feel free to play around with the options available!

Step 11 – Setup Hyperion Grabber

Right now, the LED lights are randomly blinking with the boot sequence and colors we‘ve setup.

For real immersive experience, we need to link the LED colors with content being displayed on the TV/monitor connected to the Pi.

This is done using a "grabber" which essentially captures screenshot data and feeds it to Hyperion for processing.

Hyperion supports video grabs via:

• X11 – Captures content shown in X Window system
• Framebuffer – For GPIO output to displays
• Amlogic – For Amlogic media devices

I will be using the X11 grabber here since my Pi is connected to a monitor via HDMI.

Install X11 Grabber Dependencies

Connect to Pi via SSH or login console and execute:

sudo apt install libavutil-dev libavcodec-dev libavformat-dev libavdevice-dev \
libswscale-dev libxcb-shm0-dev libxcb-xfixes0-dev libxcb-image0-dev libjpeg-dev \
libavresample-dev x11-apps

This install all the image and video processing libraries required for screen capture via X11.

Note: If using Pi OS Lite or any OS installation without a Window System, the X11 grabber will not work. In such a case, use the Framebuffer grabber instead.

Configure Grabber in Hyperion

With dependencies installed, open up Hyperion config file:

sudo nano /etc/hyperion/hyperion.config.json

And at the very top, add the following grabber section:

"grabber": {
    "width": 1280,
    "height": 720, 
    "frequency_hz": 10,
    "priority": 900, 
    "cropLeft": 0,
    "cropRight": 0, 
    "cropTop": 0,
    "cropBottom": 0
},

Here:

• width and height should match your display resolution
• frequency_hz is the desired capture frame rate
• priority sets grabber thread priority level

Next, add a framegrabber section:

"framegrabber": {
    "width": 1280,
    "height": 720,
    "cropping": {
        "left": 0, 
        "right": 0,
        "top": 0,
        "bottom": 0  
    }
}

Again, set width and height as per your setup.

Save config once done.

Finally, restart the Hyperion service:

sudo systemctl restart hyperion

The LEDs should now be reacting to whatever content you are displaying on the connected monitor!

You can tweak the crop values in config to avoid unwanted overlays like TV channel logos or tickers from getting captured.

Step 12 – Advanced Control Options

While the web UI offers basic control, Hyperion capabilities can be enhanced using its remote JSON API, MQTT interface or DMX channels.

Here are some advanced ways to control your Hyperion-connected LED lights:

JSON API

You can send JSON requests to configure Hyperion remotely from any device in the same network.

Use this API endpoint:

http://<raspberry_pi_ip>:8090/json-rpc

Example showing all components:

{
   "command" : "component-getall"
}

Set static color:

{
    "command": "color", 
    "priority": 128,
    "color": [255, 0, 0],
    "duration": -1
} 

Create effects by chaining commands into arrays.

Python Scripts

Write your own Python scripts using the hyperion module to push notifications, effects, config changes etc. dynamically.

For example:

import hyperion

# Connect to Hyperion  
hyperion.instance(address="192.168.0.10")  

# Clear effects  
hyperion.clear()  

# Set color
hyperion.color(r=255, g=0, b=0, priority=50)

MQTT Control

You can publish MQTT messages to topics Hyperion subscribes to for wireless LED control from anywhere.

Enable MQTT support in hyperion.config.json first.

Then send data like colors, effects etc. to the configured broker URL which will be processed to control the LEDs in real time.

E1.31 (sACN/DMX512)

If you have experience working with such stage lighting protocols, Hyperion can be triggered via E1.31 channels as well.

Just ensure the Universe number matches in both Hyperion config and your DMX controller.

Conclusion

And that concludes my guide on setting up ambient Hyperion lighting effects on the Raspberry Pi!

I hope you found this step-by-step tutorial useful for installing, configuring and managing Hyperion for synchronized LED colors based on display content.

With Hyperion‘s versatile JSON API, MQTT and DMX interface combined with the power of Raspberry Pi, the possibilities for creating immersive lighting environments are endless!

Feel free to experiment around with the grabber settings, effects, and visual modification options available to create unique personalized setups.

Let me know in the comments if you have any questions.