Quick start

Introduction

1. Must read
2. HyperHDR basics
3. How to create and enable your first LED strip (instance)
4. Manual LED layout editing and testing
5. Add your second instance e.g. Philips Hue lamps
6. Configuring and testing your USB video grabber
7. How to read HyperHDR statistics
8. Infinite Color Engine 🆕

Performance pro-tips:

Although the use of WiFi LED drivers tempts with simplicity, in fact, for the entire duration of the session that requires constant data transmission, you will be at the mercy of the quality of the radio connection, the reliability and compatibility of your router with your esp8266 / esp32 model, the quality of the latter and the reliability of the given version e.g. Espressif SDK which was used to build the firmware. In addition, LED control can often lead to conflict with WiFi communication (especially "IRQ thunderstorm" if popular RMT method is used). You have been warned ⚠️

Note

• Use the highest framerate for your USB grabber. General rule: highest framerate, lowest resolution.
• The best image quality after LUT calibration is definitely provided by the raw P010 codec. For SDR, you can also try using NV12 (or YUV) or MJPEG, although much depends on how much the grabber’s internal processing will degrade the signal. A good example of how easily even an SDR signal can be ruined by faulty firmware — either “improved” by sellers or simply due to its default settings — are the MS2109 and MS2130 grabbers, although certain remedies are available for them.
• Avoid using high recording resolutions (e.g., 1080p) unless explicitly required by the selected codec, such as P010. Higher resolutions have negligible influence on ambient light measurements but impose a significant load on system resources. When operating at such resolutions or when using the NV12 format, it is recommended to downscale the captured image to 25% within the grabber settings. Note that NV12 inherently includes redundant luminance information at the expense of chroma data, so additional downscaling has little practical impact on the resulting image quality.
• Because the communication speed between the unit and the video grabber directly affects latency, we strongly recommend using hosts and grabbers that support USB 3.0. Therefore, as a minimum, we suggest platforms such as the N100 or Raspberry Pi 4. Of course, USB 2.0 grabbers can also be used, but you should be aware that they introduce an additional delay of approximately 50 ms compared to USB 3.0 systems. This limitation is purely hardware-related.
• Maintain realistic "Smoothing" processing settings. Do not use a 60 Hz refresh rate for smoothing, for example, if your LED driver based on Arduino or using integration with Home Assistant or ZigBee can only output 20-25 Hz. Otherwise, you will clog the communication.

---

First steps

Ok let's get started. Connect to HyperHDR using the address: http://IP_OF_HYPERHDR:8090

Main menu is located on the left part of the page:

The instance switch button is disabled for now because there is only one instance at the beginning. There is a warning about setting a new password, so it's a good idea to do it now. Follow the link or go to the "Advanced" tab to change the password:

You may also be greeted with an error warning. Don't panic and go to the logs. In the example below, I made a mistake when entering the IP address of my Philips Hue Bridge:

---

Configuring the LED strip

First give a friendly name for our instance:

The LED strip is controlled by USB high-speed HyperSerialWLED/HyperSerial8266/HyperSerialESP32. So go to the LED devices and select 'LED hardware' tab then adalight from the list.

On Raspberry Pi the COM list could be different. Remember that Rpi 3 & 4 has available Bluetooth device that is enabled on default. Its exact path (e.g. ttyAMA0 here) may vary.

Because we use non-standard highspeed AWA protocol @2Mb we need to configure two more things:

Now we need to set geometry of the LED strip. For example let's assume we have: input in the middle of the bottom, 50 LEDs at the top, 25 LEDs on the left/right. At the bottom we 40 LEDs and a gap of 10 LEDs so you must put 50 LEDs (40 + 10) as bottom and set gap as 10.

Still there is a problem with the input position. Set gap & input position to 95 (top 50 + right 25 + one of bottom part 20)

---

Manual LED layout and testing

If you are not satisfied with the automatically generated layout, you can correct it manually. Right-click on the selected LED and a context menu will be displayed. You can manually adjust its position (Move) or size (Properties), disable it (it will never be lit) or remove it (Delete) from the system altogether.

Use 'Identify' to test a particular diode or check its physical location. This will cause it to blink for a few seconds.

---

Second instance (Philips Hue lamps)

First create new instance for our Philips Hue lamp:

Now switch to the new instance:

Before proceeding you must create an 'Entertainment group' for your lamps in the Philips Android or IOS mobile application. Don't even try without doing it first. Your Hue Bridge should also to be working for at least 2-3 minutes to avoid connection problems during configuration at startup. You should try first to send a color from the Philips mobile app to make sure it's working and your 'Entertainment group' is created.

Then add Philips Hue light source and run the wizard:

HyperHDR should find the Philips Hue bridge in the same sub-network. Some custom router's firewall rules or enabling WiFi isolation can cause the process to fail.

Click the 'Create new user and and clientkey' button. Now it's time to click a large hardware button located on your Hue bridge. It allows to authorize the HyperHDR's access. If everything goes OK you should have the Username and Clientkey filled in automatically. Identificator of 'Entertainment group' should also be found automatically.

Proceed with clicking the 'use group...' button.

Now you can assign area of the TV to single, selected lamp in the entertainment group. Because I have 2 lamps on the floor (one just on the right of the TV and second to the left) I selected following options.

---

Configuring video & system grabber

Now we configure the video source for HyperHDR: it can be an USB grabber or system screen capture. Go to the 'Video capturing tab' and select your USB grabber.

The yellow 'Info' button will appear after you select the grabber. Click it to open the dialog. Ezcap 321 offers very high capturing modes. I choose the lowest NV12. You should not go above 720p, because it causes drain of CPU resources & introduces video processing lag and gives very little to our ambient effect.

Next I check 'Quarter to frame mode' option. It will reduce the frame dimensions (to 50%) & size (to 25%) but will not reduce color's data due to NV12 codec properties.

Click the 'Video preview & LED visualization' button in the upper left corner:

The video stream colors are washed-out and overall luminescence is low. That's because we have captured a HDR10 video stream and almost none of USB grabbers can process HDR metadata so important part of information about the image is lost. Let's back to the Capturing hardware tab and enable 'HDR to SDR tone mapping'.

---

How to read HyperHDR statistics

The statistics are available on the main HyperHDR application page (the 'Overview' tab)

1. Overall CPU usage with per core visualization (by all running applications, not only HyperHDR)
2. Available system memory
3. Temperature reported by your hardware.
4. Verify that the Raspberry Pi's built-in hardware sensor reported an under-voltage event to the system logs. Note that over-voltage events are not reported but often accompany under-voltage events and only the fuse remains in the way to prevent damage to the Raspberry Pi in the extreme case (the fuse does not protect if you are powering the Raspberry Pi via GPIO). Cheap power supplies, when unable to provide enough power, tend to spike voltage too high in response to the situation. Problems caused by insufficient or unstable power supply are very difficult to diagnose. Most likely, your USB grabber will fail first, but this is not always the case: Raspberry Pi modules, such as the embedded USB controller or network card, may also stop working properly.
5. USB grabber performance: FPS and average time to decode a frame. You also usually want the FPS to be as high as possible with the lowest resolution possible at the same time. There are settings in the USB grabber configuration that can help reduce the resolution if the grabber doesn't have a hardware scaler. Keep decoding time below 20ms.
6. Each user configured light source is listed here. Each instance takes input from e.g. your USB grabber or flatbuffer source and forwards it further: directly to the LED device if smoothing is off or to the smoothing sampler unit otherwise.
7. If smoothing processing is enabled, it can increase or decrease the frame rate of the stream delivered by the instance. The result is then routed to the final LED device driver.
8. Light source/LED strip driver. Here you have information on how many frames were received directly from the smoothing unit or from the instance, and how many actually went to the device. Note that some protocols do not guarantee that the frames actually arrived on the device, e.g. UDP used by WLED or the Philips Hue Entertainment API (and no error will be detected or reported).