Rukenshia/pomodoro: ESP32-based pomodoro timer with an epaper display and rotary dial

This is the repository for an ESP32 based pomodoro timer. It uses an ePaper display and a rotary dial for input.
The code in this repository will not be ready-to-use, as some assets and fonts have been removed. However, if you really want to you should be able to adapt the code to your needs.

• ESP32 (I used an AZDelivery ESP32 NodeMCU)
• WaveShare 4.26inch e-Paper display HAT, 800×480 (link)
• KY-040 rotary encoder with button
• A single WS2812 LED (could be replaced with a simple RGB LED)A
• A USB-C connector (like this one)
• 3d printed case (onshape file)
• Some resistors and 0.1uF capacitors

I love trying out different productivity techniques – some say that the quest to optimize your productivity is the ultimate procrastination method, so maybe that is what drove me to this project. I also have a habit of committing time (around a month of work outside my normal job) once a year to a project that benefits someone else. Last year, I bought a 3D printer (BambuLab X1C) and wanted to put it to good use. I have previously finished an apprenticeship as an electronics
engineer before pivoting to software engineering, so I also wanted to come back to my roots and build something physical.
My friend struggles with time management throughout the day sometimes – lots of different tasks to organize, and little focus. So I thought to myself: Why not make them a pomodoro timer? So, I set out with a few goals:

• It should be a physical device
• It should be fun
• It should be intuitive to use

There are some cool projects out there (arguably much cooler than this, for example the Focus Dial by Salim Benbouziyane), but I wanted to build something from scratch. I also
never built something with an ePaper display and thought it might be a good fit for something that is mostly idling and doesn’t require a backlight.

This was my second dive back into building things with microcontrollers in a long time. I knew ESP32 well enough to feel comfortable diving back in, so that was the main choice here. I did some research before to see what kinds of displays would be supported.

I needed some sort of display, or at least I wanted some sort of display. One of the main motivations for this project was that it should be out of your way – until it is time to finish your current focus and move on. For me, this meant that I wanted a display without any backlight.

The display should also be large enough that you can put the whole device somewhere on your desk and still be able to read it. After ordering and playing around with a few WaveShare ePaper displays, I settled on the 4.26″ variant for multiple reasons:

• Great resolution (which seems to be really hard to find for “hobbyist” displays)
• The size felt right
• The display supports partial refreshes (0.3s, no distracting “black and white flashes” while refreshing)

Initially, I really wanted to use a black/white/red display and found one that I liked, but the refresh time
was a whopping 16 seconds with no support for partial refreshes which was a dealbreaker for me.

The final bonus feature: it won’t work at night. If your desk is not bright enough, you won’t be able to read the display. This is a feature, not a bug. Too dark outside? Stop working already!

From the start, I knew that I wanted some sort of dial as an input – it made the most sense to me. This came at the cost of some complexity when designing the menus, and you really need to make sure that you debounce the input correctly. I also added .1uF capacitors to the CLK and DT pins to help with smoothing out the signal.

In the first few iterations, there was no plan for an LED. My genius plan of having a display without backlight came at a cost: it could be too subtle when your current focus time ended. I experimented with a few different ideas:

• A buzzer: this would just make you jump. A truly horrible experience
• Speakers: I don’t know why, but speakers felt hard. So much noise and whining with the setup I tried, but I will blame this on a skill issue
• LED: I had some WS2812 LEDs lying around and thought they might be a good fit. You can animate them with the NeoPixel library, and they are really easy to use. The additional benefit of not needing to commit many more output pins was also a big plus

The LED ended up working great, allowing me to display different states. It might be subtle, but I also added a little shroud to the case and added a diffusion layer in front of the LED to make it look nicer.

The case comes in two parts: the base and a lid. One unfortunate design choice I made is that the display frame is printed as one piece as part of the base, so the top edge tends to warp a little bit during printing. Since CAD (or product design) isn’t my strongest suit, there will certainly be better choices to design this for a better final look.

One thing that I wished I learned earlier is that it might not have been the best idea to put the dial in the front: because the print and electronics are so lightweight, pressing the switch on the dial will tend to just slide the whole device back. Luckily, I could solve this by adding some rubber feet and weights (the ones usually used to balance tires) to the bottom of the case. This worked out great, and I am happy with how it turned out.

The software is written in C++ and uses the Arduino framework. I used PlatformIO to manage the project (at least that is what seemed to be a popular choice, but I am not so sure about that anymore). This project relies heavily
on the GxEPD2 library for the display. I won’t lie, the code in this repository is a bit of a mess – I had to get things done in time, which led to quite a bit of copy and pasting and not revisiting earlier parts of the code.
Some parts were generated by AI (Claude, for the most part) to help me finish the project in the deadline I set myself.

Since this was a project for my friend, I also wanted to include some easter eggs and fun. You would think that adding some random facts while you are supposed to be focused would be a bad idea, but I think it is a fun little addition.

When the device starts up, you can either change some settings or go into preset selection mode. From there, you can choose one of three presets:

The timer will then start and let you know once the time is up (by flashing the LED and displaying a message on the screen). You can keep working (not recommended, but necessary if you want to finish something) and then start the break.

During the pause, you can view some statistics. Every few iterations (4 by default), your pause will be longer to give you some time to recover.

Keep your files stored safely and securely with the SanDisk 2TB Extreme Portable SSD. With over 69,505 ratings and an impressive 4.6 out of 5 stars, this product has been purchased over 8K+ times in the past month. At only $129.99, this Amazon’s Choice product is a must-have for secure file storage.

Help keep private content private with the included password protection featuring 256-bit AES hardware encryption. Order now for just $129.99 on Amazon!

Help Power Techcratic’s Future – Scan To Support

If Techcratic’s content and insights have helped you, consider giving back by supporting the platform with crypto. Every contribution makes a difference, whether it’s for high-quality content, server maintenance, or future updates. Techcratic is constantly evolving, and your support helps drive that progress.

As a solo operator who wears all the hats, creating content, managing the tech, and running the site, your support allows me to stay focused on delivering valuable resources. Your support keeps everything running smoothly and enables me to continue creating the content you love. I’m deeply grateful for your support, it truly means the world to me! Thank you!