HyperHDR: prepare for building & buying components, step 6: Installing HyperHDR software

Guide for building your own ambient system:

Navigate to the section:

Windows 10

Windows offers the best user friendly experience as always. 

  • Download build of HyperHDR for Windows from HyperHDR github project.
    For example: HyperHDR-

  • Uninstall previous version of Hyperion/HyperHDR (if applied). 

  • Run the installer. Windows probably will ask are you sure? Yes, you are ;) It's default behavior for the first time usage for files downloaded from the internet without EV certificate which costs a lot.

  • Then proceed with the installer... just click few times 'next' and 'finish'. Congratulation, you've got your HyperHDR system installed :)

  • Run the HyperHDR from the desktop shortcut.

  • The HyperHDR icon will show up in the right-bottom corner

  • Click it the right button. The menu will show up. Then select 'Settings'. The browser will open HyperHDR www panel.

  • Proceed with the configuration from this video as an example:



Raspbian for Raspberry Pi (SD image installation)

  • Download and extract the sd image from HyperHDR github release repository.

    For Raspberry Pi Zero,1,2 choose: SD-card-image-rpi012-armv6.zip

    For Raspberry Pi 3 and 4 choose: SD-card-image-rpi34-armv7.zip

  • Download and install Win32 Disk Imager

  • Insert prepared SD to the reader. Check the reader's letter assigned in Windows.

  • Run Win32DiskImager

    1. Verify that the program selected correct SD card drive's letter

    2.  Select the img file that you extracted from the downloaded archive.

    3. Click 'Save' to begin the process of writing

  • After the image is written successfully probably you want to configure the Wifi connection for Raspberry Pi.

    Create file named
    wpa_supplicant.conf in the boot folder on the SD card and edit its content.

    For example:

    ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
     ssid="Name of your wifi LAN"
     psk="Password for your wifi LAN"

  • Take the SD out of the card reader and put it into the Raspberry Pi.
    It is recommended to reboot the system after first boot because the user (pi) is just created then and the service may be unavailable during that session.

    After boot default host name is: HyperHDR
    Connect to the www panel using port 8090 (HTTP) or 8092 (HTTPS).
    Default user is: pi
    Default password is: raspberry
    SSH and SPI are enabled on default.

Raspbian for Raspberry Pi (package installation)

Are you ready for a fight on your own with Bluetooth device or console for UART serial port that you want for usage with the led strip on some Raspberry Pi platform... and you remembered to enable SPI in the raspi-config just in case? 

If so, please continue reading as you are advanced user ready for the Linux environment :)

  • First please get rid off of the previous version of Hyperion NG or HyperHDR (if applied):
    $sudo apt remove hyperhdr
  • Download the package from HyperHDR github release repo to the current directory.

    Raspberry Pi Zero,1,2: choose v6l suffix.
    For example: HyperHDR-

    Raspberry Pi 3 and 4: choose v7l suffix.
    For example:

  • Install the package that you have downloaded from the current directory.
    For example:
    $sudo apt install ./HyperHDR-
  • HyperHDR should be up and running on the 8090 (HTTP) or 8092 (HTTPS) port.

  • If the WWW panel is out of reach then run the following command to check what's happening:
    $/usr/bin/hyperhdr -d
  • to start/stop HyperHDR service on Raspberry Pi:
    $sudo systemctl start/stop hyperhdr@pi.service

macOS installation

Since version 16 HyperHDR offers direct support for USB grabbers for macOS (native x64 application, runs on Apple M1 in emulation also) and provides very friendly DMG installation container. Click following images to zoom them.

  • Download and run DMG container. Setup process will start:

  • After setup is finished you will have mounted volume with hyperhdr application. Click it to run it:

  • It will take some time (up to one minute) for a first run. HyperHDR icon will be "jumping" in the lower-right corner. Wait until it finishes:

  • After the application starts macOS will ask you about granting camera permission for hyperhdr application. It's required. If you missed the request you can always redo your choice in the macOS' system options. Similar dialog about granting microphone permission shows up when you use the sound effect for the first time (the application restart is required here).

  • HyperHDR application is running now. Click HyperHDR icon ('H') in the upper-right corner to bring the menu and then click the settings item. It opens the browser with HyperHDR configuration panel.

  • Now it's time to go through the typical HyperHDR configuration process. Below you have a screenshot with HyperHDR running video capturing and communicating with the LED strip using HyperSerialWLED connected to the USB port.

    macOS Catalina:

    macOS Big Sur is also supported:


Colin said…
Hi, is it possible to control the LEDs from GPIO18 on the pi? I know you run the following commands with Hyperion:

sudo systemctl disable --now hyperiond@pi
sudo systemctl enable --now hyperiond@root

But I get the following error when running the second command:

Failed to enable unit: Unit file hyperiond@root.service does not exist.
awawa said…
Installed from SD image or DEB package?
Unknown said…
I'm following in order, but it's not working.
wpa_supplicant.conf I can't see this either.

hyperion.ng deleted and is being reinstalled...It's totally different from the description.
Can you help me?
awawa said…
well.. as per instruction wpa_supplicant.conf file must be created by you.
And again as per instruction if the service does not start then run /usr/bin/hyperiond -d to see what's going on.
Unknown said…
Thank you. Good installation.
awawa said…
Glad it helped. For any further HyperHdr support full log from HyperHdr is needed after 2-3 minutes of work uploaded for example at pastebin.
Scotty said…
HyperHDR, I am having the same question. I used the latest image version 14.0.0 and I intend to run my WS2812b LEDs from GPIO18 (through a logic level shifter).

When I am configuring HyperHDR I go to change my controller type to WS281x but once I do that, the "Remote Control" tab shows "LED Device" as "OFF" and clicking it changes it to ON but nothing happens and if I refresh page, it is back to OFF.

I have been running Hyperion with this exact setup for months and no issues.

Does it have to do with running these commands?

sudo systemctl disable --now hyperiond@pi
sudo systemctl enable --now hyperiond@root

When I run:
sudo systemctl disable --now hyperiond@pi

I get:
Removed /etc/systemd/system/multiuser.target.wants/hyperiond@pi.service.

When I run:
sudo systemctl enable --now hyperiond@root

I get:
Failed to enable unit: Unit file hyperiond@root.service does not exist.

What am I doing wrong?

I did install:

So I had a power down button for my pi, I don't think that screwed anything up, did it?
When I run:
sudo systemctl enable --now hyperiond@root

I get an error:
Failed to enable unit: Unit file hyperiond@root.service does not exist.
awawa said…
SD image has some kind of workaround for installing HyperHDR service before Raspbian first booting is performed. That's why I asked what kind of installation was performed (SD image or deb package). Probably this will be changed in the next version of HyperHDR. If you want to maintain full service control on SD image there is one possible solution for now but I didn't test it:
- sudo systemctl disable --now hyperiond@pi as you did
- uninstall hyperhdr
- install hyperhdr from deb package this time
Jeireff said…

could ou please provide some kind of "how to upgrade" tutorial? I'm using v14 and would like to switch to v15. Since I have installed the v14 via the image and expanded the pi with some additional software, reinstalling the Pi with the image is no option for me. And to be honest, I have no idea how to update HyperHDR.

Thank you for your awesome work!
awawa said…
Sure, I understand. Created a guideline for that topic on github: https://github.com/awawa-dev/HyperHDR/discussions/43
Jeireff said…
Thank you so much! I'm really looking forward to the new audio option ;)
Unknown said…
Hey, Ive been running Hyperion on a Pi2/3 direct driving about 120 ws2801 LEDs for a few years now. My Denon AVR has dual hdmi outs, 2nd output goes to HDMI-> composite converter to UV USB grabber. Works great. BUT now its time to upgrade to a 4k/HDR TV soon. My biggest issue is finding a grabber that supports all the 4k/HDR resolutions so that my AVR doesn't downscale my TV (or strip ATMOS/DD audio). Is the Easycap 269 still the best solution? WyperHDR will fix the issues with washed out HDR colors right? I dont care about capture, just getting a video signal to the Pi for LEDs. thanks!
awawa said…
For 4k/HDR Ezcap 269 is still recommended as newer ezcap 320 has some drawbakcs. In your case you can consider to insert a HQ HDMI splitter before AVR and have one of its outputs connected directly to the TV and the second one to the AVR and let AVR do HDR->SDR processing for your current grabber if it works well. That option probably provides best quality thanks to the AVR unit.
awawa said…
Did you mean 'Forwarder' service? First configure it in the 'network service' to set target client and activate it there to see if everything is working OK (you need to switch to 'Expert level' in the upper right corner to see it, then check logs). I recommend to do it on the main (first) instance if you have multi-instance setup.
BigPickle said…
Hi, Thank you for all your effort and work.

Im trying to get my Pi4b to run HyperHDR through Ethernet but i cant log in on putty and the HyperHDR webpage cant be found.
Ive added headless for now but any direction on this would be really appreciated.
awawa said…
Are you using HyperHDR SD ready images? Specifically for them, SSH is enabled on default so Putty must work with default Rapsbian credentials. HyperHDR service also should start on default and nothing has to be changed. First I would verify the network if you can ping your Raspberry. If you can't ping it then you have an answer: the problem is in network or you put wrong firmware (for wrong architecture) and Raspberry Pi doesn't boot at all. Or broken SD card.