WSAL12725 – RGB LED HAT/en

Documentation notice: This technical documentation was independently rewritten from an archived supplier source. Check technical details and commands against the product version and manufacturer documentation before use.

Summary

The RGB LED HAT is a Raspberry Pi expansion using a WS2812B controller chip driven over a single data line.

Related products at JW Tech

WSAL12725 – True color RGB LED HAT for Raspberry Pi, colorful display

Technical overview

Connection: On the Raspberry Pi, plug directly into the GPIO header; on other devices, solder pin headers to the 5V, GND, DIN and DOUT pads.
Pin definitions: 5V = power supply, GND = ground, DIN = control signal input, DOUT = control signal output.
The WS2812B integrates the control circuit and RGB chip in a 5050 package with a digital input, data latch and signal-shaping stages.
Transfer protocol: Single-wire NRZ communication; after reset, DIN receives 24-bit color data for the first pixel, then internal shaping forwards it through DO to the next cascaded pixel.
Timing parameters: TH+TL = 1.25 µs ±600 ns; T0H ≈ 0.4 µs, T1H ≈ 0.8 µs, T0L ≈ 0.85 µs, T1L ≈ 0.45 µs; frame time (RES) ≥ 50 µs.
Color format: Default RGB888 (8 bits per channel, 24 bits total); for the WS2812B the order must be converted from RGB to GRB because the chip transmits in that order.
Library installation: sudo apt-get install python3-pip -y and sudo pip3 install rpi_ws281x -y.
Example run: Download and extract the demo files, set permissions, and launch with sudo python3 ws2812.py; on success the RGB LED blinks.
Web control: Use Bottle under /web/ via main.py; access through a browser on port 8000; modes “static”, “breath” and “flash” are available.
Error case: If “Hardware revision is not supported” appears, the library can be recompiled and installed from source code.

Commands and examples – verify before use:

sudo apt-get install python3-pip -y
sudo pip3 install rpi_ws281x -y
wget https://files.waveshare.com/upload/b/b2/RGB_LED_HAT.zip
unzip RGB_LED_HAT.zip
sudo chmod 777 -R RGB_LED_HAT
cd RGB_LED_HAT
sudo python3 ws2812.py
hdmi_force_hotplug=1
hdmi_force_edid_audio=1
sudo apt-get install python3-bottle
cd RGB_LED_HAT/web/
sudo python3 main.py
sudo pip uninstall rpi_ws281x
git clone --recurse-submodules https://github.com/rpi-ws281x/rpi-ws281x-python
cd rpi-ws281x-python/library/
sudo python setup.py install

Notes and version constraints

The DMA-driven RGB LED may occupy the video-output DMA channel; adding the hdmi_ lines to /boot/config.txt can make the headphone jack unusable.
When using the RGB LED HAT (B), LED_COUNT in main.py must be changed to 64.
If “Hardware revision is not supported” persists after updating, refer to GitHub issue #483.
Exact compatibility with specific Raspberry Pi hardware revisions is not specified and should be verified beforehand.
All steps requiring system-file changes should be performed by someone with root privileges.
No prices, stock levels, certifications or warranty information are provided.

Source and revision record

RGB LED HAT - Waveshare Wiki
Source revision: 79628
Captured: 2026-08-30T03:31:12+00:00
SHA-256: 91d3c9012494413329a9a2b98fd774c88cb10bcd38a0bc423b1084e3ffa9ed71