Huidu HD-WF2 ESP32-S3 / Huidu HD-WF1 ESP32-S2 controller card

[hn]

The Huidu HD-WF2 is a cheap LED Matrix controller card (with 2 HUB75E ports, labeled X1 and X2) based on an 8MB ESP32-S3, a Datasheet is available for download. It can be found in various 128x32 displays sold on Amazon (e.g. 'Leadleds P4 WiFi LED shield', ASIN B08XYT1JDL).

The PCB has a serial port and GPIO0 exposed (label silkscreend on PCB back), so it's quite easy to up- and download firmware. There also is a USB-A port available and USB OTG may work, didn't test that. Update: OTG does work, just pull GPIO0 to ground and conveniently flash via USB.

The pin config (reverse engineered) is as follows:

#define WF2_X1_R1_PIN 2
#define WF2_X1_R2_PIN 3
#define WF2_X1_G1_PIN 6
#define WF2_X1_G2_PIN 7
#define WF2_X1_B1_PIN 10
#define WF2_X1_B2_PIN 11
#define WF2_X1_E_PIN 21

#define WF2_X2_R1_PIN 4
#define WF2_X2_R2_PIN 5
#define WF2_X2_G1_PIN 8
#define WF2_X2_G2_PIN 9
#define WF2_X2_B1_PIN 12
#define WF2_X2_B2_PIN 13
#define WF2_X2_E_PIN -1        // Currently unknown, so X2 port will not work (yet) with 1/32 scan panels

#define WF2_A_PIN 39
#define WF2_B_PIN 38
#define WF2_C_PIN 37
#define WF2_D_PIN 36
#define WF2_OE_PIN 35
#define WF2_CLK_PIN 34
#define WF2_LAT_PIN 33

#define WF2_BUTTON_TEST     17  // Test key button on PCB, 1=normal, 0=pressed
#define WF2_LED_RUN_PIN     40  // Status LED on PCB
#define WF2_BM8563_I2C_SDA  41  // RTC BM8563 I2C port
#define WF2_BM8563_I2C_SCL  42
#define WF2_USB_DM_PIN 19
#define WF2_USB_DP_PIN 20

#define PANEL_RES_X 64     // Number of pixels wide of each INDIVIDUAL panel module. 
#define PANEL_RES_Y 32     // Number of pixels tall of each INDIVIDUAL panel module.
#define PANEL_CHAIN 2      // Total number of panels chained one to another

HUB75_I2S_CFG::i2s_pins _pins_x1 = {WF2_X1_R1_PIN, WF2_X1_G1_PIN, WF2_X1_B1_PIN, WF2_X1_R2_PIN, WF2_X1_G2_PIN, WF2_X1_B2_PIN, WF2_A_PIN, WF2_B_PIN, WF2_C_PIN, WF2_D_PIN, WF2_X1_E_PIN, WF2_LAT_PIN, WF2_OE_PIN, WF2_CLK_PIN};
HUB75_I2S_CFG::i2s_pins _pins_x2 = {WF2_X2_R1_PIN, WF2_X2_G1_PIN, WF2_X2_B1_PIN, WF2_X2_R2_PIN, WF2_X2_G2_PIN, WF2_X2_B2_PIN, WF2_A_PIN, WF2_B_PIN, WF2_C_PIN, WF2_D_PIN, WF2_X2_E_PIN, WF2_LAT_PIN, WF2_OE_PIN, WF2_CLK_PIN};

HUB75_I2S_CFG mxconfig(
  PANEL_RES_X,   // module width
  PANEL_RES_Y,   // module height
  PANEL_CHAIN,   // Chain length
  _pins_x1       // pin mapping for port X1
);

Basic tests done, LED matrix seems to work fine. Currently having WiFi issues but this seems to be a different story.

Update: I recommend to use ESPHome as an alternate firmware for the device. Super-easy to setup, very easy to maintain.

[DarrylStrong]

That PCB has 2 HUB75 ports, how are they mapped/addressed?

[hn]

That's currently unknown (at least for me). My display came with two 32x64 panels daiys-chained to the (left) port labeled 75EX1.

Update: Just a guess: from the pin numbering one might conclude that the second port R1/2 is pin 3/4, G1/2 is pin 8/9 and so on. I just closed the case and cleaned my desk so I might check that sometime else.

[mrcodetastic]

Would be interesting to see if this library is what this product uses.

Somebody do a firmware dump.

[hn]

I have an 8MB dump of the stock firmware. I can't post it to the public because it may contain intelectual property of Huidu.

From a quick string grep: based on ESP-IDF, no obvious signs of other non-core libraries.

I think Huidu uses some proprietary LED matrix "operating system" for their products. I actually never used it, so when Amazon delivered the package, I directly unscrewed the case and flashed via serial port.

[mrcodetastic]

Hi @hn - Do you by any chance have a stock firmware for the WF1? I lost my backup, and would like to revert for testing purposes.

[hn]

@mrcodetastic Sorry, I only have a WF2 device.

[pavel-spacil]

@mrcodetastic I just bought WF1 and dumped the stock FW, lmk if you still want it

[mrcodetastic]

How much are one of these controllers?

[hn]

On AliExpress, the WF2 is about 15 €/$ and I just saw they also have a 4 port version (WF4) for roughly the same price (uh?).

The complete 128x32 display (2 panels, metal case, controller and power supply) was about 140€ on Amazon.

[mrcodetastic]

The specs in the PDF say it can drive a chain up to 768*64 px...

I'd love to see how it does that. Would be interesting to see with an oscilloscope. Certainly wouldn't be with 24bpp colour.

[Kamal-Sonani]

Can you post that controller's snap shot?

I don't think that WF2 have Esp32S3 or if so which version's card you've?

[board707]

The specs in the PDF say it can drive a chain up to 768*64 px...

Pixel figures means nothing without of color depth.

[hn]

Ok guys, if you want it, some PCB pron for you ;-)

WF2 PCB V7.1.0-2, ESP32-S3

4 pins serial port: GND-RX-TX-5V (bottom to top, 5V pin has the little triangle next to it)
2 pins: GND and GPIO0 (the rectangular pin), short-circuit during power-on to enter programming mode

Full PCB inside panel housing (panel label P4-2121-64*32-16S-HL1.2, 2PS688B), serial port connected with jumper cables:

Stock firmware boot log (no more output after this):

ESP-ROM:esp32s3-20210327
Build:Mar 27 2021
rst:0x1 (POWERON),boot:0xb (SPI_FAST_FLASH_BOOT)
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fcd0108,len:0x1730
load:0x403b6000,len:0xbcc
load:0x403ba000,len:0x3304
entry 0x403b6250
I (24) boot: ESP-IDF v4.4-274-g09c8eef954-dirty 2nd stage bootloader
I (25) boot: compile time 15:06:14
I (25) boot: chip revision: 0
I (28) boot.esp32s3: Boot SPI Speed : 80MHz
I (33) boot.esp32s3: SPI Mode       : DIO
I (38) boot.esp32s3: SPI Flash Size : 8MB
I (42) boot: Enabling RNG early entropy source...
I (48) boot: Partition Table:
I (51) boot: ## Label            Usage          Type ST Offset   Length
I (59) boot:  0 nvs              WiFi data        01 02 00009000 00004000
I (66) boot:  1 otadata          OTA data         01 00 0000d000 00002000
I (73) boot:  2 phy_init         RF data          01 01 0000f000 00001000
I (81) boot:  3 ota_0            OTA app          00 10 00010000 00100000
I (88) boot:  4 ota_1            OTA app          00 11 00110000 00100000
I (96) boot:  5 app_data         unknown          40 06 00210000 00500000
I (103) boot: End of partition table
I (108) esp_image: segment 0: paddr=00110020 vaddr=3c0a0020 size=1150ch ( 70924) map
I (129) esp_image: segment 1: paddr=00121534 vaddr=3fc9a2a0 size=0414ch ( 16716) load
I (133) esp_image: segment 2: paddr=00125688 vaddr=40378000 size=0a990h ( 43408) load
I (144) esp_image: segment 3: paddr=00130020 vaddr=42000020 size=95548h (611656) map
I (254) esp_image: segment 4: paddr=001c5570 vaddr=40382990 size=0790ch ( 30988) load
I (261) esp_image: segment 5: paddr=001cce84 vaddr=50000000 size=00010h (    16) load
I (268) boot: Loaded app from partition at offset 0x110000
I (268) boot: Disabling RNG early entropy source...

[mrcodetastic]

Good information. Even if I didn't want a hub75 controller, it's a decent way to get an esp32-s3 board with the gpio pins exposed.

I guess there's a real time clock connected to one of the pins given the battery.

[hn]

I've absolutely no clue about LED panels or controllers or if there are better options on the market. For this thing, I had an alternative open-source software running on the device about two hours after the parcel arrived, so I'm pretty happy with my purchase. Thanks again for your work on this library!

And yes, it has a buffered RTC, time is correct even after power-cut.

[mrcodetastic]

It's a good find so thanks for sharing. Best part is it's actually quite price competitive to buying an S3 devkit.

I'm going to buy one.

[hn]

The HUB75E ports are routed through 74hc245 transcievers (likely for 3v3-5v level shifting) and I think you might not be able to use them as inputs (so they are more GPO rather than GPIO ...). Only if you want to use it for something other than driving LED panels.

You see, I'm not a Huidu sales representative ;-)

[mrcodetastic]

The HUB75E ports are routed through 74hc245 transcievers (likely for 3v3-5v level shifting) and I think you might not be able to use them as inputs (so they are more GPO rather than GPIO ...). Only if you want to use it for something other than driving LED panels.

Very good point. With that said I've ordered myself the WF1 because I like cheap. Hopefully it's an S3 device as well as I can use it to continue testing S3 support without the need for jumper cables. Not sure if it'll come with any psram though.

[ewwink]

Hi, I need help, I'm using HD-WF2 (stock firmware) and LedArt and want to mirror a "Time/Watch" like a "Text". It is possible to edit the program using USB-A or any other way?

[GrimorJander]

Hi, I need help, I'm using HD-WF2 (stock firmware) and LedArt and want to mirror a "Time/Watch" like a "Text". It is possible to edit the program using USB-A or any other way?

PC program Huidu "HD2020" is more powerful than phone app.

[ewwink]

PC program Huidu "HD2020" is more powerful than phone app.

HD2020 doesn't have mirror effect, even for a Text.

[ewwink]

solved, it in Screen Settings > Advance Settings > Data Mirror, and set High Enable

[HiRez00]

Hoping someone can help me with my HD-WF2 - I am using the HD2020 software to program my board via Wifi connection.

Everything works fine if I keep my total program under 4.7MB, (the HD-WF2 board is supposed to have 8MB onboard flash memory), but if I go over 4.7MB with my programs, it will not complete loading onto the board.

I also tried this via using a USB and similarly I get the same issue which is "Error 2" on the LED panel which is "Excessive program content".

Not sure if I am missing a step or something, but I am stuck as to how to be able to utilize the full 8MB it supposedly has (which BTW the HD2020 software verifies this board has 8MB).

Any thoughts or suggestions?

Thank you in advance.

[netmindz]

I've seen similar trying to load WLED onto it. I can write an image with a partition table set for 8MB, but when it boots up and tries to format it's littlefs partition it fails

Has anyone managed to do a full flash erase? It just sits there doing nothing for me when I put the item into the mode I use to flash an image

[raulzanardo]

I'm using Platformio and was having problems with the Flash on the HD-WF1, was too slow, had to change the chip, after that it got better.

On the HD-WF2 I had to put this on the my platformio.ini for the LittleFS to work:

board_build.partitions = file_system.csv
board_build.flash_mode = dio

thats the "file_system.csv"
ota_0, app, ota_0, 0x10000, 0x1A0000,
ota_1, app, ota_1, , 0x1A0000,
otadata, data, ota, 0x350000, 0x2000,
nvs, data, nvs, , 0x6000,
spiffs, data, spiffs, , 0xA8000,

[HiRez00]

Unfortunately I am not using Platformio and hoestly I don't understand anything you wrote. lol. sorry.

Neither the LEDArt app or the program HD2020 (which are the 2 recomended programs / apps to use with the controller card) don't have any of the setting or features you mention. Both recognize that the module has 8MB of flash space and show 4.7M / 8M in the info area.

[EngHamze]

I think you have exceeded the total number of areas inside one of your programs. "Hdsign or hd2020 or hd2018"
The thread is about wf2 and how can we use it, uploading codes using different ide or programming softwares (arduino, vs and etc..)
Good luck

[mrcodetastic]

Neither the LEDArt app or the program HD2020 (which are the 2 recomended programs / apps to use with the controller card) don't have any of the setting or features you mention. Both recognize that the module has 8MB of flash space and show 4.7M / 8M in the info area.

You'll need to contact Huidu or whoever the Chinese supplier is of the device and/or app. People here don't use the software and hack these devices to use their own code.

[mmm-it]

Hello,
I have received a Huidu HD-WF4 card and it works fine with the HD2020 software, but I would need to make my own software using this card and when asking Huidu for the sorces to understand what happens inside the HD2020 software they told me they don't give out the Sources, so how can I program this card without having some source sample code ?
Anybody has access to the HD2020 sources to share them ?
Or does anybody know if the HSDK vom Huidu is compatible to this card ?
I can preprogram the card with the HD2020 but then the change of the digits should be done in a simplier way then from the HD2020 where I have first to select the Digit zone to be able to change a value .... I just want to pass through a command to change one digit then with another button pressed the other digit ...
So I can now either analyse the whole protocol via a network sniffer to understand what's going on or I can hope to find an openminded technichian from Huidu who will explain me the functionality ... ?
It would be preferable if the software access would be free accessible for these informations ....
So please if anybody can help me on this - feel free to take contact with me on mmayr @mmm-it.com

[GrimorJander]

Why did you decided that the colors has a 3bits limit?

My WF2 board using either Huidu phone app or HD2020 only allow 8 colors including white and black, so 3 bits. I can't t display a jpg or gif with so poor color palette. Only "retro pixel art".

[board707]

HD2020 only allow 8 colors including white and black, so 3 bits.

It is not a "3bits color", it is a one bit
One bit for each color channel - Red, Blue and Green

[GrimorJander]

OK, In video editing (color depth) we used to name it "3 bits".
If you realize how to turnaround that limitation let me know.

[mmm-it]

I got two different SDK from Huido (the Secondary Development Kit in V2.0) and a lower level SDK V3.0) if you are interested you can allways contact me ....
Huidu_Gen6SDK_V2.0.zip
The v3 is to big to be transferred here ....

[EngHamze]

U cannot increase depth color of control card huidu wf4 even if you get sdk.
The sdk is only for making custom softwares for windows operating system using there dll. File that has all necessary methods to be imported in your project and their roles adding contents to led matrix.
If you want to increase depth color change to other series of huidu controller such as C16L.

[mmm-it]

Hello,

I got some original HD-WF1 WF2 and WF4 cards here for some tests and I would like to create a Arduino Interface allowing to set Digit Values as done on the PC by the SetDigit Commands ... The programm on the controller is defined and depending on the Area ID I would like to change values from an Arduino best way via serial connection from the arduino. The idea is to have some push buttons on GPIO s on the arduino which will trigger the different Digital value changes on the Panel. Anybody has experience with this kind of manipulation from an Arduino (using Micro Arduino cards) but the protocol on what to send to the HD-WFx cards is not really documented (or at least I didn't find it yet).
Please if somebody knows about this contact me here or on mail mmayr (at) mmm (minus) it (dot) com

Thanks for your help in advance

Max

[rigorka]

As I mentioned in my response to your earlier post on the matter - there's very little that you can do with the stock Huidu firmware, and this repo is certainly not the right place to find help with the stock Huidu firmware. Huidu SDK is of no use at all for your task, as these are Windows DLLs indeed.

What you could do however is to develop your own custom firmware for WF2 using the excellent library presented in this repo. You can then attach your push buttons directly to your WF2 board (using the GPIO0, TX and RX pins available) and process your input right on the WF2, without the need for external Arduino. You could even use the existing onboard button of WF2 for your own needs too.

You can develop that firmware using the Arduino coding style and even Arduino IDE if needed (though I find using PlatformIO way easier). This repo contains the instructions and example which make this development a fairly straightforward task.

[beta-tester]

i am wondering that these last few questions have to do with the ESP32-HUB75-MatrixPanel-DMA project?
why not asking Huidu, how to use/access their API of the original stock firmware?
if Huidu don't give information, make your own firmware with use of this project.
for questions about this project, then this repository is the right place to ask.

it's annoying to see these questions in this repository

[rigorka]

Yep, I was kinda trying to explain this in my responses above. It looks like sometimes people are getting lost and driven here by Google when looking for things like "Huidu WF2 firmware". I guess it might be worth spending a minimal effort trying to let them know what their options are.

[mrcodetastic]

And a reminder that there's a github repo with a Proof of Concept for the WF1.

https://github.com/mrcodetastic/HD-WF1-LED-MatrixPanel-DMA

[mmm-it]

[mrcodetastic]

Thank you. Let me confirm the instructions and get back to you.

Edit: I have deleted this private information before it gets indexed.

[mmm-it]

[mmm-it]

Didn't even remark my email adress is masked - I will check why ....

[mrcodetastic]

What the other user is saying (and this has happened with me hence why I no longer reply to github notifications using email), is that github has masked your email address in your response, but included everything else in your email signature such as your phone number, address etc.

Something to be aware of. I have deleted your original message as a result. Thank you for offering help. I will get back to you with the instructions to download the firmware.

[pavel-spacil]

Hello, I've just bought WF2 board with a V7.2.0.-2 revision, which looks slightly different from the photos above. Mine has E pins wired together so both connectors should support x64 panel.

Does anyone know by any chance which GPIOs the serial pins are connected to? Is it UART0?

[beta-tester]

and here #667 (comment) user hn gave the pins for the serial port on the earlier revision - i don't think that the port changed its pin out.

[pavel-spacil]

Yes, the 4 pins are labeled on the bottom of the board. I'm interested about their wiring to the ESP32. If I understood its functionality correctly, they should be wired to the UART0?

[TonivdW]

the user vortigont here in the thread #667 (comment) mentioned, that it is possible with an USB-A to USB-C cable to flash the ESP32-S3 without using the serial port, instead of using a rare USB-A to USB-A cable.

I have tried this, but the board is not even powering on using a standard USB-C to (male)USB-A cable. Tried both my computer with USB-C as well as a power bank.

[beta-tester]

Yes, the 4 pins are labeled on the bottom of the board. I'm interested about their wiring to the ESP32. If I understood its functionality correctly, they should be wired to the UART0?

my assumption is:
it should be RX0, TX0, otherwise they waste GPIOs pins and standard flashing the firmware would not work.
when you watch the pinout and have a continuity tester with sharp probes, you can measure yourself.

[netmindz]

Just use the A to A cable and short the pins listed

[selam2]

ESP32 S3 processor . I found the GPI0 pin, but I still can't assign data. The computer sees and then goes . Can you help me?

[netmindz]

That's a different board you have there. I don't know what hardware the HD-WF4 has

[selam2]

No Wf4 ESP S3

[toaster-robotics]

hello, hopefully this isn't too off topic. I'm trying to compile circuitpython for use with the WF2 board. I'm getting stuck with the mpconfigboard.mk file. The end result is that when circuitpython is compiled and loaded onto the board it can't seem to access the internal flash storage. I messed around using the generic ESP32-s3 Micropython firmware and that seems to work fine.

mpconfigboard.mk

USB_VID = 0x303a
USB_PID = 0x81A3
USB_PRODUCT = "WF2"
USB_MANUFACTURER = "Huidu"

IDF_TARGET = esp32s3

CIRCUITPY_ESP_FLASH_MODE = qio
CIRCUITPY_ESP_FLASH_FREQ = 80m
CIRCUITPY_ESP_FLASH_SIZE = 8MB

# Disable ESPCamera since you have no PSRAM
CIRCUITPY_ESPCAMERA = 0

# Ensure Internal Flash is used for CircuitPython storage
INTERNAL_FLASH_FILESYSTEM = 1

# Ensure QSPI Flash is enabled if using QSPI (Adjust if your board uses SPI)
QSPI_FLASH_FILESYSTEM = 1
SPI_FLASH_FILESYSTEM = 0

# Disable USB HID (prevents board from appearing as a keyboard/mouse)
CIRCUITPY_USB_HID = 0

# Enable USB Mass Storage (so CIRCUITPY appears as a drive)
CIRCUITPY_USB_MSC = 1

[toaster-robotics]

hello, hopefully this isn't too off topic. I'm trying to compile circuitpython for use with the WF2 board. I'm getting stuck with the mpconfigboard.mk file. The end result is that when circuitpython is compiled and loaded onto the board it can't seem to access the internal flash storage. I messed around using the generic ESP32-s3 Micropython firmware and that seems to work fine.

mpconfigboard.mk

USB_VID = 0x303a
USB_PID = 0x81A3
USB_PRODUCT = "WF2"
USB_MANUFACTURER = "Huidu"

IDF_TARGET = esp32s3

CIRCUITPY_ESP_FLASH_MODE = qio
CIRCUITPY_ESP_FLASH_FREQ = 80m
CIRCUITPY_ESP_FLASH_SIZE = 8MB

# Disable ESPCamera since you have no PSRAM
CIRCUITPY_ESPCAMERA = 0

# Ensure Internal Flash is used for CircuitPython storage
INTERNAL_FLASH_FILESYSTEM = 1

# Ensure QSPI Flash is enabled if using QSPI (Adjust if your board uses SPI)
QSPI_FLASH_FILESYSTEM = 1
SPI_FLASH_FILESYSTEM = 0

# Disable USB HID (prevents board from appearing as a keyboard/mouse)
CIRCUITPY_USB_HID = 0

# Enable USB Mass Storage (so CIRCUITPY appears as a drive)
CIRCUITPY_USB_MSC = 1

just got it working with the below changes

CIRCUITPY_ESP_FLASH_MODE = dio
CIRCUITPY_ESP_FLASH_FREQ = 40m

[selam2]

Hello I have ESP32 S3 Wf4 I can't assign data to this I bought both an external USB drive I tried the internal You can help

tx to rx rx to tx I tied it up in shape And these pins go to Espnin Tx Rx Pins

[beta-tester]

with very sharp probes, can you measure the voltage on pin 5 (GPIO), or with a continuity tester/ohm meter, where the pins 5, 50, 49 go?
maybe the pins are pulled hard to the wrong potential.

[selam2]

@hn