Metaballs mode flickering more than with Obegränsad firmware

[Solmath]

Version

main

What happened?

On my device the metaballs mode is flickering really hard, while the blob plugin in the Obegränsad firmware is buttery smooth.

Could this be related to the PWM frequency or the increased number of gray levels?

There were also some changes to the blob plugin lately.

Note
I'm not using a level shifter yet. So this could also be related to my hardware setup.

Steps to Reproduce

No response

What did you expect to happen?

No response

Which ESP32 board are you using?

No response

Relevant Logs or Error Messages

Any other helpful information?

No response

[JanPetterMG]

	ph1p/ikea-led-obegraensad	VIPnytt/Frekvens
Pixel bit depth (gray levels)	6-bit (64)	8-bit (256)
Refresh rate (timer interval)	5 000 Hz (200 µs)	15 360 Hz (~65 µs)
Frame rate (equivalent)	~78 FPS	60 FPS
PWM bit depth (levels)	8-bit (256)	14-bit (16 384)

Disclaimer: I haven't tested ph1p/ikea-led-obegraensad since last spring. I took inspiration from the Metaballs PR, and made my own custom implementation of it, but I never tested the original.

---

I think you're onto something, the PWM frequency (maybe also the number of gray levels) largely affects the performance, and I'll admit it flickers heavily at low brightness levels on my Obegränsad device. On my Frekvens device hover, it's perfectly fine, maybe not butter smooth, but quite smooth, even at the lowest brightness setting.

My recommendation is therefore to max out the brightness.

Both Obegränsad and Frekvens are using the same SCT2024 PWM-controller chips, so in theory there shouldn't be any difference between the two devices. The only major difference is the LED-diodes itself, so my guess is that the ones in Obegränsad are slower to respond, and therefore respond negatively to the higher PWM frequency.

You could try to experiment with a higher frame rate #define FRAME_RATE 78 // fps, just to get comparable results. In case the ESP32-S3 freezes, you might also have to increase the SPI frequency too, as I'm not sure how high the current SPI frequency will allow you to go. It's hard coded at about 8 MHz, but it works perfectly fine at 13 MHz too, which should give you plenty of headroom.

EDIT: ESP32-S3 works perfectly fine with 78 fps, so there's no need to change the SPI frequency.

[JanPetterMG]

This raises a valid point about performance, but it doesn’t currently point to something directly actionable, so I’m converting it to a discussion.

Performance is still important—if anyone has ideas, insights, or potential improvements, feel free to share them there.

[JanPetterMG]

TL;DR

• Higher FPS (e.g. 114) improves smoothness, especially in Metaballs
• Low-brightness lag is not caused by FPS, but by ledc + software PWM overlap
• Full software PWM removes the overlap, but performs worse overall on ESP32
• Fewer per-pixel brightness levels (like in ph1p/ikea-led-obegraensad) significantly reduce the issue
• This is fundamentally a trade-off between grayscale resolution, frame rate, and low-end stability

---

Increasing the frame rate to 114 FPS (from the default 60 FPS) does improve the visual appearance of the Metaballs mode, making motion noticeably smoother. However, it does not eliminate the lagging that appears at the lowest brightness levels.

The main issue seems to be the interaction between hardware and software PWM. Global brightness is controlled via ledc (14-bit on ESP32-S3), while per-pixel brightness is handled in software (since the SCT2024 has no grayscale support). At low brightness levels, these two PWM layers interfere with each other, which manifests as visible lagging.

Theoretically, the original ESP32 (“classic”) could behave differently here due to its higher ledc resolution (up to 20-bit), but it is also slower overall. I haven’t tested this configuration specifically in this context, but it could potentially reduce the overlap issue enough to be beneficial.

Switching to full software PWM was also tested. This slightly reduced lag in higher brightness ranges, but made the low end significantly worse. The lagging became much more pronounced, and even static content (like clocks) started flickering heavily. In practice, this suggests that full software PWM is not a viable solution on ESP32-class hardware, even if it might work on more capable systems like e.g. Raspberry Pi Zero 2W.

For comparison, ph1p/ikea-led-obegraensad performs better here for two main reasons. It uses significantly fewer brightness levels (roughly a quarter), which reduces the per-frame workload at the cost of grayscale precision. It also runs at a higher frame rate (~78 FPS vs 60 FPS), which improves smoothness in motion-heavy modes.

The frame rate difference is easy to experiment with — setting #define FRAME_RATE 78 already gives a noticeable improvement. It doesn’t solve the low-brightness lag, but it helps. Slower variants like the ESP32-C3 may struggle here, while the S3 handles it without issues.

In my testing, ~114 FPS appears to be the practical upper limit, and reaching it required increasing the SPI clock to ~13.3 MHz.

Overall, the behavior points to a fundamental trade-off: grayscale resolution vs frame rate vs visual stability at low brightness. The current lagging is not primarily a frame rate issue, but a consequence of mixing hardware and software PWM.

[JanPetterMG]

#535 introduces scaling of the ledc bit depth with frame rate. Higher frame rates automatically reduce bit depth, lowering overlap/interference and improving visual output.

SPI frequency now also scales with frame rate, removing the need for manual adjustments in the source.

The default frame rate remains unchanged at 60 FPS. Increasing FPS raises the minimum brightness as well as making it more nonlinear, so tuning is still a trade-off.

[JanPetterMG]

Add this to ./firmware/include/config/secrets.h:

#define PWM_DEPTH 8

That basically resolves the flickering. 🎉

Trade-off: lowering the PWM depth shifts the gamma/brightness curve. The lower end becomes heavier, the upper range has less visible effect, and the minimum brightness becomes brighter.