Quick Start

Quick Start

A handful of wires, one zip, a restart.

1. Wire the display

Power the module from the Pi's 3.3 V pin (pin 1) unless the module's own page says it takes 5 V, GND to GND. Then:

Bus	Module pins	Raspberry Pi
I2C	SDA, SCL	GPIO 2 (pin 3), GPIO 3 (pin 5)
SPI, generic wiring	DIN (MOSI), CLK (SCK), CS, DC, RST	GPIO 10 (pin 19), GPIO 11 (pin 23), CE0 (pin 24), GPIO 24 (pin 18), GPIO 25 (pin 22)
SPI, Waveshare wiring	DIN (MOSI), CLK (SCK), CS, DC, RST	GPIO 10 (pin 19), GPIO 11 (pin 23), CE0 (pin 24), GPIO 25 (pin 22), GPIO 27 (pin 13)

The Wiring page has a drawing for each module and the module pin names as the vendors print them; the settings page's Wiring selector names these three and takes a custom one.

2. Install the plugin

Until the plugin is in Volumio's store, it goes in by hand from the command line. Download the plugin zip, just_oled-<version>.zip, from the releases page and copy it to the player's home directory, with scp or a USB stick:

scp just_oled-<version>.zip volumio@volumio.local:

Then, on the player, as the volumio user. The zip stays outside the folder it is unpacked into:

ssh volumio@volumio.local
mkdir just_oled && cd just_oled
miniunzip ../just_oled-<version>.zip
volumio plugin install

Answer yes to Volumio's warning about plugins installed by hand. volumio plugin install compresses the folder it is run in and hands the result to the player's plugin manager, which unpacks it under /data/plugins/system_hardware/just_oled and runs its installer: it checks the I2C and SPI buses and enables what is missing in /boot/userconfig.txt, puts the volumio user in the i2c, spi and gpio groups, writes the display service and the plugin's sudo rule, and enables the service. A second zip inside the folder makes the hand-over fail with mv: target '/tmp/plugins/just_oled.zip': No such file or directory, which is why the zip is unpacked from the parent directory.

Afterwards the folder in the home directory can go: cd && rm -r just_oled.

Once the plugin has been through field testing and Volumio's review, it will be in the store under Plugins, and this step becomes one press of Install there.

3. Choose the panel, turn it on, restart once

In Volumio, open Settings, Plugins, Installed Plugins, and turn Just OLED on. On its settings page choose the wiring you used and the panel (the controller and pixel size, as printed on the module or its page; Detect says what the I2C bus finds), then press Test display: a frame round the edge, a small square in the top-left corner, a diagonal, three bars (red, green, blue on a colour panel) and a ramp from black to white should appear. If the picture is offset, mirrored or the wrong size, the panel is a near neighbour of the one chosen; Displays says which to try, and Troubleshooting reads the picture.

The audio tap joins the player's output chain when Volumio builds it. Current Volumio 4 images rebuild the chain the moment the plugin is turned on, and the bars move at the first play; an image that builds the chain only at start shows the player's state but no levels until a restart, and the plugin says so and offers it.

4. What the panel shows

While the player boots, the boot text; once Volumio is up, the ready text for a moment. Playing: the face chosen on the settings page, the spectrum with the track by default: the title and the artist (and the album where the panel has the rows), the time played and the track's length, the sample rate and bit depth, the volume, the connection, and a progress line; a single level bar stands in for the spectrum on DSD, which has none. Paused: the pause text. Stopped: the time and date, large, with the player's address; after half an hour the panel goes dark until something plays. On shutdown or restart the farewell text, then the panel is switched off. The face, the standby page and the messages are all on the plugin's settings page. Screens shows every page on every panel class.

When nothing shows

Troubleshooting goes through it: the bus, the address, the panel entry, the tap in the chain.