OLED SSD1309 Plugin for Volumio (Experimental)

[Zhapox]

Hi all,

I wasn’t entirely sure whether to post this, but I thought it might be interesting for some of you.

Background

I’m still running a setup based on a Raspberry Pi 4 with a 2.42" OLED display. For years, I’ve been using the MPD_OLED plugin, which has been a fantastic contribution to the community.
With Volumio’s ongoing development, I started running into compatibility issues though. Since many users have moved to color displays, the demand for a simple OLED plugin seems to have faded so I decided to try solving it myself.

Disclaimer

Before going further, a few important notes:

• This project is experimental and may not comply with Volumio’s plugin guidelines.
• I have very limited programming experience (basic Java ~15 years ago, never used since).
• I’m not able of fully reviewing or validating the code in terms of quality, robustness, or security.
• I’m aware that AI is not a substitute for experienced developers this is more of an experiment than a production-ready solution.

The Idea

I challenged myself to create an OLED plugin without writing a single line of code manually, using AI tools.

The process started with defining a clear prompt describing what I wanted:

• No interference with the MPD service
• Display:
  • Title & artist
  • Clock
  • Volume
  • Progress bar
  • Current position (mm:ss)
  • Total track time
  • Bit depth & sample rate

I used ChatGPT to refine the prompt into a structured specification.

Development Process

I then used Claude (Opus 4.6) to actually generate the plugin.

• First iteration took ~5–10 minutes
• Output included:
  • Complete plugin code
  • Installation guide
  • SSD1309 display driver integration

Claude seemed to:

• Understand Volumio’s documentation
• Use the socket.io API to read playback data (no MPD interference)
• Follow Volumio’s plugin structure conventions

First Test

Skeptical but curious, I installed it and surprisingly:

• Volumio recognized the plugin
• The OLED displayed a flickering “Volumio” logo

So… it actually worked… kind of.

Initial Issues

The first version had several problems:

• Display flickering (wrong communication parameters)
• Blank plugin configuration page
• Plugin enable/disable state not handled correctly
• Display stayed on after shutdown instead of turning off

Iteration & Fixes

After 2–3 iterations (~2 hours total), I had:

• A working OLED plugin using socket.io
• Idle screen:
  • Large digital clock
  • Date
  • Volume (%)
• Playback screen:
  • Title & artist
  • Clock
  • Volume
  • Progress bar
  • Position + total time
  • Bit depth & sample rate

Additional Features

Further iterations focused on usability and polish:

• Automatic I2C address detection upon plugin installation
• Boot/loading screen until Volumio UI is available
• Multiple playback layouts available (classic, minimal, clock focus)
• Volume overlay (shown for 2 seconds on change)
• Auto-dimming after 2 minutes of inactivity
• Screensaver after 5 minutes (to prevent burn-in):
  • Moving clock
  • Moving Volumio logo
  • Moving pixel
  • Blank screen
• Configurable parameters:
  • Timeouts
  • Display rotation
  • Various behaviour settings

Current State

• ~2’500 lines of code (generated by Claude)
• Additional AI-based code reviews applied
• ~15-page PDF documentation generated by AI

Mockups and Pictures

Reflection

I honestly didn’t expect it to be this easy to get a working piece of software without writing code myself.

What surprised me most:

• Debugging required mostly user-level feedback, not technical analysis.
• AI was often able to identify root causes on its own, occasionally gave clear instructions to extract logs.
• The interaction felt more like a client ↔ developer workflow.

I suspect this worked particularly well because Volumio is well-documented so credit to the Volumio team for that.

Final Thoughts

This is definitely not meant as a replacement for properly developed plugins but more as an experiment showing what’s already possible with AI-assisted development.

If there’s interest/positive resonance, I’m happy to share more details or the plugin code itself.

Curious to hear your thoughts.

[Zhapox]

I‘ve managed to put the plugin on GitHub for anyone who’s interested:

GitHub - Zhapox/oled_display_ssd1309: OLED SSD1309 Display Plugin for Volumio – shows...

Obviously use only at own risk!

[tweed77]

Raspberry Pi 4 - 4 GB RAM - 32 GB SD card - I2C OLED white display - Khadas Tone1 DAC

I’m testing it and it works stably. It only displays the day and month in English.
It doesn’t display the Polish letters “ą,” “ę,” “ś,” “ć,” etc.

“czego dziś chcę”

I quickly checked the German ones.
As you can see in the photos.
The menu in Volumio is set to language Polish.

[Josh2000]

don‘t play Helene Fischer - it may burn the display

[Zhapox]

Hi @tweed77,

Thanks for trying out my plugin and your feedback! Happy to see it on another display.

I’ll be looking at those findings. There are certain limitations on the OLED font in regards of special characters though. Result might be that not all Polish characters can be displayed and some might be mapped instead (“ę” turns to “e” for example). That would at least prevent placeholders to be displayed. I’ll see how far I can get.
I’ll also try to include language files for the plugin configuration page and adjust the date displaying on the idle screen. Will post once I have news!

Thanks!
Kevin

[Zhapox]

@tweed77:

I uploaded a new version to GitHub with the changes below. Happy to hear your feedback!

v1.7.16

Improvement:

1. Configurable date format. New dropdown in the Display Options section with four formats: “Day + Month name” (Thu 02 Apr 2026, uses localized names), “DD.MM.YYYY” (02.04.2026), “MM/DD/YYYY” (04/02/2026), and “YYYY-MM-DD” (2026-04-02). The dropdown labels are translated in all 7 languages.

v1.7.15

New features:

1. Extended character set. Added Unicode support for Central European languages. Lowercase accented characters with marks above (ć, ń, ś, ź, č, ř, š, ž, ä, ö, ü, é, ñ, etc.) display correctly using accent overlays. Hand-designed glyphs for special shapes (ł, ż, ď, ť, ı). Uppercase accented characters and characters with marks below the baseline (ą, ę) are mapped to their unaccented base letters — a pragmatic choice since the 5×7 pixel font has no room for accents above uppercase or tails below the baseline.
2. Localized date display. The idle screen date now shows day and month names in the user’s language (e.g. “Do 02 Apr 2026” for German, “Czw 02 Kwi 2026” for Polish). The date format order follows the language convention. Language data is loaded from i18n string files (EN, DE, FR, PL, ES, IT, NL) based on Volumio’s GUI language setting.
3. Multilingual section labels. The plugin configuration page section headers (Hardware / Display) are translated via Volumio’s i18n system. Content labels and descriptions remain in English for compatibility.

[tweed77]

The latest version of your plugin is installed.

Images from the English and Polish versions of the plugin menu.

Volumio 4.119 version Lifetime + Tidal

Basic information without unnecessary bells and whistles

[Zhapox]

Happy to see it working, much appreciated!

[tweed77]

Warum nicht Helene Fischer

@Zhapox

I also test with Raspberry Pi 3A+ / Volumio 3.912 works ok.

[Zhapox]

Thanks for testing, that’s great news! I think the plugin is now stable. Perhaps there is a chance I can submit it to the plugin store.

[tweed77]

Plugin v 1.7.17 working ok with Volumio 3.912 / Raspberry Pi 3A+.

Sorry for the confusion
I tried installing with the sudo su option.

[Zhapox]

Thanks! It was just a minor fix on the install script to be compliant to the plugin submission checklist for the plugin store. Hope it gets accepted.

[tweed77]

Plugin 80s80s Radio not working correct with Oled SS1309 - Check it out if you haven’t used the 80s80s Radio plugin before.

[Zhapox]

In general the OLED plugin and the 80s80s plugin should not interfere with each other as both have completely separate functions.

I just tested the 80s80s plugin (note I use Volumio 4) and have the following findings:

• Playback works properly, can switch between channels, Volumio GUI shows artist + song and station name.
• OLED display shows playback screen, displaying Artist + Song, Station name, runtime of song with progress, bit depth and sample rate.

What I noticed though is that the song information does not get updated in time when the radio station plays the next song. This is visible as well on the Volumio GUI and console as well (volumio status). Looks like the information is not propagated/pulled in time but that looks more like an issue related to either the radio station or the 80s80s plugin. Nothing I can influence.

Do you have any more specific description of the issue you’re seeing?

Thanks!

[tweed77]

I turn on any station with the 80s80s / 90s90s plugin.
The display doesn’t show what’s playing.
I turn off the OLED 1309 plugin and turn it on.
Only then does it correctly show what’s playing with the 80s/80s - 90s/90s plugin.
Similarly, I switch Tidal or other internet radio to the 80s/80s - 90s/90s plugin.
I have to turn off and on the OLED1309 plugin, only then does it show what’s playing.

Volumio 3.912 + Raspberry Pi 3A+
Volumio 4.119 + Raspberry Pi 4 with 4GB RAM
Raspberry Pi 4 and 3A+ connected to the router via Wi-Fi

[Zhapox]

Thanks! I was able to reproduce the issue. Here’s what I found:

The OLED display reads track information from Volumio the same way the web interface does. When you start an 80s80s station, the web interface itself shows “MPD” instead of the station name for a few seconds. This means Volumio/80s80s plugin isn’t yet announcing what’s playing during that window, so neither the web interface nor the OLED can show it correctly. Once the announcement comes through, the web interface updates. The OLED appears not to update because by then it has already been told (incorrectly) that nothing is playing and the 80s80s plugin doesn’t always seem to send a follow-up announcement.
There also seems to be an issue with updating the track data (equally on GUI, console via “volumio status” and OLED). While the station is already playing the next track the previous one is still displayed since it doesn’t seem to be properly updated by the 80s80s plugin.

This is something I can’t seem to fix on my end. I suspect the issue is in how the 80s80s plugin announces playback to Volumio. Building a workaround for that in the OLED plugin would introduce new risks for bugs or misbehaviours which I’d like to avoid.

In the meantime, the disable/re-enable workaround you found does work because it forces the OLED to ask Volumio directly “what’s playing right now?” which gives the correct answer. So the data is there it just isn’t being broadcast properly during station startup.

Btw. The 80s80s stations are also available in Volumio’s web radio library. Playing them from there, not via the 80s80s plugin, shows correct track info and updates properly on track change so the station does provide correct info. The gap really seems to appears when using the 80s80s plugin.

[Zhapox]

Updated to version v1.7.20 to address an issue where the display wouldn’t turn off but stay stuck on the last frame instead when rebooting or shutting down on Volumio Premium. I can’t explain why this makes a difference on Premium but it occurred after I purchased my subscription. Now it should work reliably on Volumio free and Premium.

Edit: Updated to version v1.7.21 for updated install instructions using the volumio plugin install command instead of manually running the install script. This ensures that the uninstall button on the Volumio GUI will function. Otherwise it will generate an error when trying to uninstall the plugin.

Changelog:

v1.7.21

Documentation only:

1. Install instructions updated to recommend volumio plugin install. This is Volumio’s own plugin manager command — invoked from inside the extracted source folder, it copies files into place, runs install.sh, and registers the plugin. No manual folder creation and no manual file copying. A reboot is still required after install for the I2C baudrate change in /boot/userconfig.txt to take effect, but the reason is now documented honestly. The previous manual-extraction method is kept as a fallback section for older Volumio versions where the CLI may not work.

v1.7.20

Bug fix (corrects v1.7.19):

1. Display now reliably powers off on system reboot and shutdown. v1.7.19 attempted to fix this by adding onReboot and onShutdown lifecycle methods, but those names don’t match what Volumio actually looks up. The Volumio log lines PLUGIN onReboot : <name> and PLUGIN onShutdown : <name> are human-readable shorthand — the real method names checked on the plugin prototype are onVolumioReboot and onVolumioShutdown (see volumio3-backend/app/pluginmanager.js lines 636 and 682). v1.7.20 uses the correct names. The shared _systemPowerOff(reason) helper clears the framebuffer, flushes, and powers off the display synchronously inside the hook, before Volumio invokes systemctl reboot/poweroff. The previous SIGTERM and socket-event handlers are retained as defensive backups.

v1.7.19

Initial attempt at the reboot/shutdown power-off fix. Used the wrong method names (onReboot/onShutdown) — Volumio silently ignored them. Superseded by v1.7.20.