Troubleshooting

Troubleshooting

In order of likelihood. The display service's lines are in the journal: sudo journalctl -u just-oled -b, prefixed just-oled:.

Nothing on the panel at all

Power first: VCC and GND, 3.3 V unless the module's page says it takes 5 V. An OLED has no backlight; a dead panel and a wrong bus look the same. Then the bus:

ls /dev/i2c-* /dev/spidev* /dev/gpiochip*
sudo i2cdetect -y 1

What it shows	What it means
No /dev/i2c-1	The I2C bus is not enabled or i2c-dev is not loaded; the installer writes both. A restart after the install is needed.
No /dev/spidev0.0	SPI is not enabled; the installer writes dtparam=spi=on into /boot/userconfig.txt, which takes a restart.
i2cdetect shows nothing	SDA and SCL swapped, or on the wrong pins, or the module is on another bus. Four-pin modules print their pins in either order.
3c or 3d	An OLED controller answers. If the panel stays dark, the entry or the address is wrong: set the address the scan shows, press Test display.

The journal says what the daemon did: which device it opened, which entry it drives, or why it is waiting.

Test display shows something, but wrong

The test picture is made so one look says what is off: a one-pixel frame all round, a small square in the top-left corner, a diagonal from that corner to the opposite one, three bars across the middle in the order red, green, blue from left to right (three greys on a greyscale panel, three blocks on a one-bit panel), and under them a ramp from black at the left to white at the right.

What you see	What it means
The frame does not reach one or more edges	The window is too small for the glass: a larger entry of the same controller.
The picture fills the top half, the bottom is dark	A 128x32 entry on a 128x64 panel: choose the 128x64 entry.
Every other row is drawn, the picture is squashed	A 128x64 entry on a 128x32 panel: choose the 128x32 entry.
Two blank columns at one edge and the other edge wrapped	An SH1106 driven as SSD1306: choose the SH1106 entry.
The picture shifted two columns	An SSD1306 driven as SH1106: choose the SSD1306 entry.
The square is in another corner	Orientation: the module is mounted the other way; set Upside down. A square top-right or bottom-left means the glass is mirrored on one axis, which an entry's remap setting would fix; say so on the issues page with the module's name.
Bars blue, green, red	The module's colour order differs from the entry's; say so on the issues page with the module's name.
Fine lines missing, or a dim picture on a 256x64 panel	A 4 bpp greyscale panel driven as 1 bpp or the other way round: the entry's Format column on Displays says which the controller is.
The ramp is banded or shows colour fringes	The pixel packing does not match the controller: a near neighbour of the entry chosen.

The bars do not move

The display shows the track but the spectrum sits still, or shows "no audio tap". The tap is not in the player's output chain. Volumio builds the chain at start from every enabled plugin's contribution, so the first start after the install needs a restart; the plugin asks for it. To look:

grep -c "Just OLED section" /etc/asound.conf   # 1 when the tap is in the chain
ls /dev/shm/justoled.*                         # the ring, while music plays

A ring that exists while the bars stand still is a daemon problem: sudo journalctl -u just-oled -b.

The level is not where expected

The tap measures the stream the player hands to the output chain, before Volumio's software volume where that is in use, so the bars follow the recording's level, not the volume knob. With a hardware mixer there is no difference.

The boot message never gives way

The plugin is installed but turned off. The service is disabled with the plugin, so after the next restart the panel stays dark; until then, turn the plugin on, or uninstall it.

The clock is wrong

The daemon reads the player's time zone at start; a time zone changed in Volumio's settings is read at the next start of the service (sudo systemctl restart just-oled) or at the next boot.

Installing a newer version

volumio plugin install refuses a plugin that is installed already ("Plugin just_oled already exists"). A newer zip goes in with volumio plugin update, from a fresh folder as the install did, the zip outside it:

mkdir just_oled && cd just_oled
miniunzip ../just_oled-<version>.zip
volumio plugin update

It replaces the plugin's folder, runs the installer again and keeps the settings; the running plugin and display service go on with the old version until the player restarts, so restart it afterwards. Once the plugin is in the store, updates come through the Plugins page.

Command line

The daemon answers on the player as the volumio user:

cd /data/plugins/system_hardware/just_oled
scripts/run.sh --list                 # every panel the daemon knows
scripts/run.sh --probe                # the buses and GPIO chips this machine has, and the settings
scripts/run.sh --test                 # the test picture for ten seconds (--hold 0 leaves it up)
scripts/run.sh --say "row 1|row 2"    # a message on the panel for three seconds (--hold S)
scripts/run.sh --ping                 # how the running daemon is, as one line of JSON
scripts/run.sh --version

--probe lists each /dev/i2c-N with the catalogued addresses that answer on it, each /dev/spidevB.C, each /dev/gpiochipN with its label and which one is the header, and then the settings as the daemon reads them, with present, MISSING, answers or SILENT against the device the panel needs. --test asks the running daemon for the picture, or, when no daemon runs, opens the panel itself and draws it. --ping answers with the panel the daemon drives (or why it cannot), whether the audio ring is live, the phase (boot, ready, player, message, test, farewell) and the player's status. Both take --config PATH and --socket PATH when the daemon runs with other than the defaults.