Hyperk Installation Guide (Wireless LED Controller)¶

Chapter 1: Hardware Preparation and Firmware Flashing¶

Before starting, ensure you have a compatible device and a stable USB connection. Hyperk supports various microcontrollers, but the flashing process depends on the specific hardware architecture you are using.

1.1 Supported Devices¶

The following chips are currently supported:

Espressif Systems: ESP8266, ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, and WT32-ETH01.

Tip

ESP32-C5 features dual-band Wi‑Fi 6 (2.4GHz and 5GHz), while ESP32-C6 supports Wi‑Fi 6 on the 2.4GHz band only. For LED controlling applications, this standard provides crucial stability and responsiveness in congested wireless environments, rather than just raw throughput.

Raspberry Pi Pico W: RP2040 and RP2350.
- Important: The "W" in "Pico W" is essential. Standard Pico boards without it do not have a Wi-Fi module and are not compatible.

1.2 Web Installer¶

The easiest way to flash your device is via the official web installer: 👉 https://hyperk.hyperhdr.org

installer

1.3 Flashing Raspberry Pi Pico W¶

For Pico boards, the process uses Mass Storage Mode rather than direct Web Serial flashing:

Enter DFU Mode:
- If your Pico has one button (BOOT): Press and hold it while connecting the board to your USB port. Release the button once connected.
- If your Pico has two buttons (BOOT and RESET): Connect it to the USB port. Press and hold both buttons, release RESET, then release BOOT.
The Pico board will appear on your computer as a removable drive.
Copy Firmware: Download the appropriate firmware file from the installer page and copy it directly onto the Pico drive. The device will automatically update and reboot.

1.4 Flashing ESP32 / ESP8266¶

These chips can be flashed directly from the web installer if you are using a compatible browser. If the board is not detected automatically, you may need to enter the DFU mode manually.

Warning

You must use a browser that supports the Web Serial API (such as Google Chrome, Microsoft Edge, or Opera). Firefox is not supported as it does not allow web-based serial communication.

If you encounter issues, you can flash the factory firmware manually using esptool. If you are unsure of the button combination for your specific board to enter DFU, consult its documentation or use an AI (like Gemini) to find the correct combination. E.g. for ESP32-S2 to enter DFU mode: Press and hold Rst + 0, release Rst, then release 0.

Example usage of esptool for ESP32-S2 board in DFU mode:
esptool.py write_flash 0x0 Hyperk_0.0.2-beta_esp32s2_factory.bin.
All the settings will be erased and the bootloader will be restored.

Note: After the firmware is successfully flashed, a power cycle (unplug and replug the USB cable) is highly recommended.

Chapter 2: First boot and WiFi configuration¶

Once the firmware has been successfully flashed, the device will boot into Access Point (AP) mode. In this state, it hosts its own WiFi network, allowing you to connect and configure your local network credentials.

2.1 Connecting to the Device¶

On your mobile device, scan for available WiFi networks.
Find and connect to the network named "Hyperk-Setup".
A notification should appear stating that a "Network login" is required. Tap it to automatically open the Hyperk Configuration Page.

2.2 Configuring WiFi Settings¶

Navigate to the Settings tab.
Under the WiFi section, you will see a list of nearby networks detected by the board. You can select your network from the list or manually enter your SSID.

Note

Currently, the ESP32-C5 is the only supported board with Wi‑Fi 6 on 2.4GHz and 5GHz. ESP32-C6 supports Wi‑Fi 6 on 2.4GHz and other boards support legacy Wi-Fi 4 (802.11 b/g/n) on 2.4GHz. The ESP8266 may struggle with modern routers: to ensure stability, disable Airtime Fairness and Band Steering (combined 2.4/5GHz) in your router settings. Using a dedicated 2.4GHz SSID is highly recommended.

Optional: You may change the default mDNS address (hostname) to a custom name to make the device easier to identify on your network later.
Finally, select your WiFi network, enter the password, and click Save Wifi & Restart.

2.3 Connection & Fail-safe¶

After saving, the board will reboot and attempt to join your local WiFi.
Fail-safe: If the device cannot establish a connection within 12 seconds, it will automatically revert to Access Point mode so you can re-configure the settings.

2.4 Accessing the Interface¶

If the connection is successful, your device is now part of your home network. You can access the Hyperk interface from your PC or smartphone by:

Navigating to http://hyperk.local in your browser (if the default name was kept and is unique).
Checking your router's DHCP client list to find the specific IP address assigned to the board.

Chapter 3: Configuration¶

Once the device is successfully connected to your WiFi and you have accessed the configuration page, it’s time to finalize the setup.

3.1 Required Settings¶

To get your LEDs running, configure the following:

LED Type: Select the specific protocol/chipset of your LED strip.
LED Count: Enter the total number of LEDs in your setup.
GPIO Pin: Specify the data pin on the board where the LEDs are connected.

Make sure you saved these settings.

Note

All other settings are optional and can be adjusted later based on your preferences.

3.2 Firmware Updates¶

Under the settings, you will find the OTA (Over-The-Air) Update feature. This allows you to effortlessly upgrade to the latest firmware versions wirelessly, without needing to reconnect the device to your computer.

Chapter 4: Integration with HyperHDR, Home Assistant, and others¶

With the device connected and the hardware configured, you can now integrate it with your smart home ecosystem or bias lighting software, such as HyperHDR or Home Assistant.

4.1 HyperHDR Configuration¶

While you can use standard protocols like DDP or rawudp in HyperHDR, we highly recommend using the dedicated hyperk driver.

Auto-Discovery: The driver is designed to automatically locate your Hyperk device on the local network.
Advanced Features: Selecting this driver unlocks advanced RGBW calibration options and allows you to enable RGBW dithering.

Warning

LED Count Mismatch: Ensure that the number of LEDs configured in HyperHDR exactly matches the LED count you specified in the Hyperk web interface. Discrepancies here will cause display issues.

4.2 Home Assistant & WLED API Compatibility¶

Hyperk features a custom, lightweight implementation of the core WLED API. Because it speaks the same "language," any third-party software that supports WLED (like Home Assistant) should automatically discover and control your device without requiring additional plugins (as seen in the screenshot).

In addition to basic JSON commands for toggling power and setting static colors, the device exposes several UDP services tailored for high-speed, real-time color streaming:

Service	Port	Protocol / Description
Web GUI	`80`	Device configuration interface
UDP DDP	`4048`	DDP stream listener
UDP Raw RGB	`5568`	Raw color stream listener
UDP RealTime	`21324`	WLED real-time UDP stream listener