Introduction: WebPixelFrame

About: I am good at building software, and am trying to improve my hardware and woodworking skills.

I set out to create a simple kit for 9 year olds. I wanted them to learn basic soldering techniques, as well as be able to modify the software to extend the project.

The ESP8266 captivated me. It is available for $4 from wemos.cc and when using the Arduino ide is easy to program and very easy to make something web controlled.

Luckily the NeoPixelBus library includes code to run the WS2812b neopixels using DMA. This gives us processor time for the web and our gif decoder, scrolling text, etc.


  • Wemos mini or d1 board
  • Ws2812 pixels (64 in our example)
  • Laser cut wood for the case
  • clear acrylic
  • velum
  • 3.3 to 5v power converter

Step 1: Create Case

Either use a mill or a laser cutter and cut out the wood pieces for the case and the diffuser.

The current drawings are on github. The CDR file is the original, I am not sure if the others will work as well.

Step 2: Mount Pixels and Solder

Cut 8, 8 pixel long strips. This will give us an 8x8 or 64 pixel display. Arrange the pixel strip in alternating rows so that we can solder the connections with short wires in the next step. The top row data goes from left to right, next it goes from right to left and continues to alternate.

Step 3: Wire Electronics

The LED strips have 3 connections. Power, Ground, and Data. The Data pin goes from the ESP8266 RX pin (through the voltage converter), to the DI (Data input) pin of the first LED. Each LED also has an output pin (DO). This should be wired to the next input pin. The strips come prewired, but we need to reattach the power, ground, and data in the places where we cut the strips. The strips alternate, so that the data flows from left to right on the top row, and then right to left on the next row. This continues until the last row. We found it best to drill holes (or laser cut them) in the board, and have the wires go through to gather in the back. It fits together better.

The circuit board connects the RX pin on the esp8266 with the 3-5v converter. The 3-5v converter also needs 3v and 5v power from the esp8266. The outputs are hooked to connectors on the board that go to the led strip.

Step 4: Upload Software

The software WebPixelFrame software is available on github. The esp8266 is programmed with the Arduino IDE. wemos has instructions. The SPIFFS file system can be built from the data directory in the github repository. Install this tool - SPIFFS file uploader to upload the data directory to the board. Beware, it will erase everything. you can use the upload script in the tools directory to reupload the important scripts after the initial install. If you create some pixel designs on the board, you will lose them when you reupload the entire SPIFFs system.

In the github README.md you will find some extra libraries that need to be installed to get the sketch to compile.

Step 5: Software Features

The software includes:

  • Async Web Server
  • Async Captive Portal
  • A clock display using NTP
  • Piskel ported to the display for a real-time pixel editor
  • Animated gif player (8x8)
  • Scrolling Text

There is a lot of room for improvement.

Step 6: Early Design Iterations

I originally wanted to create a display with ping pong balls. The led strips cut down on the soldering, but finding balls that were the right size to fit on the strip was difficult. It also didn't look great.

We cut a diffuser out of paper, and had a thick piece of white acrylic. It looked better, but clear acrylic, velum, and a laser cut grid turned out to be best.



  • Make it Move Contest

    Make it Move Contest
  • Clocks Contest

    Clocks Contest
  • Casting Contest

    Casting Contest

We have a be nice policy.
Please be positive and constructive.




I've been struggling with this for a few days now, it seems the documentation or files is not up to date? I tried using the upload script and it can't find some files etc... I'm not sure what to do. :|

14 replies

I haven't built the project in a while. It is possible that the esp8266 toolchain has advanced. What is the exact problem you are having? What parts and pieces are you using? I can try to update the github.

I'm using a WeMos D1 mini and a strip of 20 neopixels. The problem is that the upload script can't find files to upload etc. Here is the terminal output:

lapytopy:tools as$ sudo ./uploadpiskel.sh


cp: ../piskel/dest/prod: No such file or directory

No log handling enabled - using stderr logging

Created directory: /var/db/net-snmp

Created directory: /var/db/net-snmp/mib_indexes


Fatal error: Uncaught exception 'UnexpectedValueException' with message 'RecursiveDirectoryIterator::__construct(p): failed to open dir: No such file or directory' in /Users/as/Documents/Arduino/WebPixelFrame/WebPixelFrame/WebPixelFrame/tools/convertdir.php:13

Stack trace:

#0 /Users/as/Documents/Arduino/WebPixelFrame/WebPixelFrame/WebPixelFrame/tools/convertdir.php(13): RecursiveDirectoryIterator->__construct('p', 512)

#1 {main}

thrown in /Users/as/Documents/Arduino/WebPixelFrame/WebPixelFrame/WebPixelFrame/tools/convertdir.php on line 13

And then it just stops doing stuff

Did you checkout the piskel repo that is a submodule? Make sure to change the IP address in the upload script. Also, make sure line 4 of the shell script worked. Sorry the upload script is a bit cludgy.

Sorry for the late reply, I somehow broke my Arduino SDK on my mac so I am trying to fix this so I can test again.

I downloaded piskel in a zip file from github, I didn't clone it via the terminal. Looking at the contents of the zip (and the git repo), there's no subfolder called /dest/prod. Maybe they changed the structure?

I think you need to build piskel. That will create the prod directory.

I downloaded the "offline version" and extracted the prod dir. However I'm not sure if I am uploading correctly. I've tried both connected to the wifi hotspot it creates, and via the IP it gets when connected to my home wifi.

Here is a pastebin from when connected to the hotspot: http://pastebin.com/Sq9rhAMh

When I go to the IP it gets on my wifi the upload script give any errors but it also doesn't seem it uploads anything... any ideas?

I think you may have missed:

"The SPIFFS file system can be built from the data directory in the github repository. Install this tool - SPIFFS file uploader to upload the data directory to the board" - once you install the tool you need to run the "ESP8266 Sketch Data Upload" in the tools menu. This will upload the SPIFFS image.

No, I've done that step too. When I browse to it using my own wifi I can go to /edit and see files on the web server. But if I try browsing to it when connecting to the hotspot I just get 404 errors. This is mildly confusing.. :D I'm really sorry to bother you about my problems with this.

I bet the ESPAsync library changed.. I will try to update everything from scratch, rebuild and test. Not sure when I will get to it... In a few days.

No stress mate. I really appreciate your help. I don't want to be a P.I.T.A, you don't have to go through all that work just for me. :)

Nice, I seem to be a bit closer now! When I browse to the wemos now I get the ESP Monitor page. If I click "Piskel gallery" I get a dark grey background with large pixels and a "New" link that sends me to a 404 page. Connecting to the WebPixelFrame AP just gives me the wifimanager as usual. :)

Screen Shot 2017-03-14 at 21.27.34.png

Ah, okay. I will try to do that. :)

I created an account just to give a shout out to your clear acrylic & velum solution for the diffuser. I experimented with different white acrylic thicknesses, and different vinyl frosting solutions and wasn't happy with the result. after testing a $0.60 piece of this stuff, i was so pleased i tore apart both of my 512 light versions to replace them with this.

1 reply

I am glad you liked the velum. I had a few pieces of white acrylic that I wasn't happy with.. I kept putting a paper towel over my first design, and it looked better than all the complicated things I was doing. The idea comes from the GameFrame: https://ledseq.com/product/game-frame/

Post some pictures of your design!

Greets from Blinkenlights xD

So awesome! I've always love these types of pixel displays!