Connecting the Screen

The OLED display comes with an expansion board and a ribbon cable. The cable connects the expansion board to the display while the other side of the board has jumper wires which need to be connected to specific GPIO pins on the Pi. Thankfully, Waveshare has a wiki that provides step-by-step instructions for connecting their display to the Pi and using SPI to show stuff on the display.

Unfortunately, no project is simple. The wires on my expansion board were mostly different colors than the diagram, so I actually had to look at what signal each wire was supposed to carry, what pin it connected to, then translate that to my own wires based on how they attached to the board. I got everything connected properly. I powered the Pi on and connected to it via SSH. At some point I noticed that the display was getting incredibly hot, which worried me about mounting it inside a helmet really close to my eye, but eventually I learned that I had connected the ribbon cable from the board to the display upside down. There are apparently tiny numbers on the ribbon cable that identify which edge is Pin 1 and which edge is Pin 20. Those same numbers are also printed on the expansion board, and I needed to ensure that my ribbon cable was inserted correctly.

Configuring the Pi

The next step was to run `sudo raspi-config` and go to the Interface option, then enable the SPI and I2C interfaces. After that, I believe the Pi required a reboot. It will usually say it needs to reboot for changes to take affect if that is necessary, based on the settings changed.

On the Waveshare wiki, there is a note "If you use bookworm system, you can only use lgpio library, bcm2835 and wiringPi can't be installed and used." Personally, I find that wording somewhat confusing. Do they mean only the lgpio library can be installed on Bookworm, and that bcm2835 and wiringPi can't be installed? Or do they mean the lgpio library and the bcm2835 library can be installed and used but wiringPi can't? If you'd read the wiki and seen the other grammar mistakes that I had, you'd understand my confusion on this point. Grammatically, their statement should mean one thing, but there were enough other mistakes to cast doubt. So I just installed what I could.

wget http://www.airspayce.com/mikem/bcm2835/bcm2835-1.71.tar.gz

tar zxvf bcm2835-1.71.tar.gz

cd bcm2835-1.71/

sudo ./configure && sudo make && sudo make check && sudo make install

That installed the bcm2835 library, which ran without any issues that I can recall. I may have actually installed the lgpio library first and it might have needed bcm2835 as a dependency, but I don't remember specifically. I do know for certain that I was able to successfully install both libraries and my screen works.

wget https://github.com/joan2937/lg/archive/master.zip

unzip master.zip

cd lg-master

sudo make install

Once both lgpio and bcm2835 were installed, the Waveshare wiki says to run the usual Raspberry Pi update commands, but there are also some libraries that the Python script will use.

sudo apt-get update

sudo apt-get install python3-pip python3-pil python3-numpy

sudo pip3 install spidev

sudo apt-get install python3-smbus

I'm not sure why python3-smbus gets installed using the apt package manager after spidev is installed using the Python3 Package manager, pip3, but I left them in that order and didn't have any issues.

Testing the Display

With the expansion board properly connected and not heating the display to boiling and all the proper libraries downloaded and installed, it was time to actually test out the display with the example code.

sudo apt-get install p7zip-full

sudo wget https://files.waveshare.com/upload/2/2c/OLED_Module_Code.7z

7z x OLED_Module_Code.7z

cd OLED_Module_Code/RaspberryPi/python/example

This downloads the Waveshare example code and unzips it. There are directories for other boards, and for the Pi, there is code for C or Python. In my case, I found the script for my board, which is the 1.51" Transparent OLED. I ran the script with `python OLED_1in51_test.py` and got the example output!

Setting up the Library

In `OLED_Module_Code/RaspberryPi/python/lib`, there is a directory called `waveshare_OLED` which contains different files for the various OLED displays that Waveshare makes. Any script that I wrote which needed to output to the display needs to include `from waveshare_OLED import OLED_1in51`. I wanted the ability to put my script anywhere in my filesystem and have it still run, so the `waveshare_OLED` directory needed to be placed in a dircetory where Python checks for installed modules.

Determining the correct directory was accomplished by running `python -c "import site; print(site.getsitepackages())"` which in my case returned this array: `['/usr/local/lib/python3.11/dist-packages', '/usr/lib/python3/dist-packages', '/usr/lib/python3.11/dist-packages']`. I chose to copy the `waveshare_OLED` to the `/usr/lib/python3.11/dist-packages` directory, using `sudo cp waveshare_OLED /usr/lib/python3.11/dist-packages`. It might have yelled at me for trying that, even as a super user, in which case I moved it using these commads:

$ sudo su

# cp waveshare_OLED /usr/lib/python3.11/dist-packages

# exit

The last `exit` command returns to the regular user mode. Doing this allowed me to use the `waveshare_OLED` module in scripts anywhere in my file structure.

Conclusion

Since I didn't have the microphone or speakers for the Pi yet, there was no reason to setup the Caller ID functionality yet. However, I did have the phone connecting to the Pi and I noticed that it was sending information about the currently playing track. That got me thinking it would be cool to have a "Now Playing" screen, maybe with a circular progress indicator for how long the track was. I threw out the idea of the progress circle pretty quick because the phone doesn't send enough information to update that indicator. Initially I wanted to have three columns across the top of the display: one for the Title, one for the Artist, and one for the Album. And if the text for any one of those was too big for the alloted space, the text should scroll. If the text fits within the space, it can just be static. Getting that logic to work, and apply only to the Track, Artist, or Album information was a challenge. Ultimately, once I actually had it working, I decided I didn't like it anyways.

I ended up chaning the format of the "Currently Playing" info. Now I'm using the format "Track Title - Artist Name". That scrolls across the top of the screen in a seamless loop. Once it returns to the starting position where the Track Title is in the top left corner of the screen, it will pass for a few seconds before looping again. I'll add a picture or video some time, if I think of it.