AirGradient DIY Basic v4 - OLED Display freezes after 15-60s

Hi everyone. I recently built an AirGradient DIY Basic v4. This was my first project involving soldering, but I have experience in programming and software development.

I flashed the AirGradient firmware using the Arduino IDE, where I was able to confirm that the sensors were working and I was getting updates on the readings. However, the OLED display seems to freeze after 15-60 seconds and does not update anymore. I replaced the sensor readings in the firmware to a simple counter that writes a number to the OLED display and increases every second and saw the same behavior - the OLED display freezes after a short amount of time (while Serial.println logs continue to show in the console). When I reboot the device (unplug and plug in again), the display updates, but then freezes again after some time. The amount of time before the display freezes fluctuates a lot (the lowest was 2 seconds, the highest was 85 seconds).

This seems like a weird issue and I’m not sure what the cause could be. Is this just a faulty OLED display or could I have messed up the soldering in a very specific way?

Thanks in advance, Tim.

Try the latest firmware from the section about flashing through the browser

A lot of changes have been happening with the firmware and it is possible the version where you got the sketch is out of date

In general we see issues with the display of the basic kit. Sometimes it also stays blank and needs a power cycle. It could be a driver issue.
Please try the new version that @MallocArray mentions.

Thank you for the quick responses.

I have followed this guide: The AirGradient DIY Air Quality Sensor (Basic Version PCB Version 4.0+)
So I have a Wemos D1 Mini with an ESP8266. The software on the link that you provided says that this board is not supported. Is the guide that I used outdated?

I have pulled the newest version of the AirGradient library from Github (GitHub - airgradienthq/arduino) and the version number increased from v3.0.4 to v3.0.5, but I’m still having the same issue. If I find the time, I will try to read into the driver code and investigate a little bit.

Sorry, that is my mistake, I missed the exact model you have.
The link you provided is the correct one and it has a button to flash the latest code

You can also try using a previous release from Github to flash
airgradienthq/arduino at 2.4.15 (

I personally use ESPHome with all of my AirGradient devices and that works as well if you are still having issues and want to try a different approach.

I tried a few different versions, always ran into the same issue. However, I noticed that the library used for the OLED display Adafruit_SSD1306 was quite old (1.1.2 vs. current 2.5.9 found here: I ran the examples from the current release of the library and the display did not freeze yet (after about half an hour - I can report after some longer tests…). So I would assume that the issue is somewhere in the old version of this library or any of its dependencies (Adafruit GFX and Adafruit BusIO).

I removed the Display directory from the Airgradient library and replaced all instances of ag.display in the firmware with direct access to the display using the latest version of Adafruits’ library (GitHub - adafruit/Adafruit_SSD1306: Arduino library for SSD1306 monochrome 128x64 and 128x32 OLEDs). This patch seems to work for now and I also don’t have any issues with a blank screen after flashing the firmware; the screen updates instantaneously. Are you looking for contributors? I could try to upgrade the dependency in the Airgradient library since this seems to be the culprit.

I have spoken too soon, the display just froze again. I’m ordering a few more parts to check if my current display is just broken.

I have the exact same issue. Did you find a solution? I have tried both the browser and arduino flash.