Raspberry Pi – OLED Display Manual

This manual is written and tested by Kasper (kasperz@2heads.com) Do note: this document and it's scripts are still in development(!)

Hardware Requirements

• Raspberry Pi 5 - 8GB + active cooling
• OLED Display (SPI) – currently SSD1309 2.42" OLED Display(Amazon: HiLetgo i2c model)
• Temporary HDMI screen + keyboard/mouse

Pinout

OLED Pin	Raspberry Pi Pin
VIN	3.3V (pin 1)
GND	GND (pin 6)
Data	GPIO3 I2C (pin 3)
Clk	GPIO5 I2C (pin 5)

---

Instructions

Follow the instructions, and take time for each step. Be patient, for best result.

Do note: Use correct mode

Initial Setup

1. Wire everything up and prepare the board.
2. Use the Raspberry Pi Imager to create an image for the board:
   • Use the Raspberry Pi Bookworm OS (32-bit) with desktop environment.
   • Do not use custom settings.
3. Load the board with the image.
4. Set timezone to US.
5. Set username and password:
   • Username: galaxy
   • Password: separator
6. Set up WiFi temporarily with an internet connection.
7. Uninstall Firefox.
8. Update the system.
9. Grab yourself coffee and a snack (this takes some time).
10. Restart the board.

Setting Up the Board

1. Enable SSH and I2C in Raspberry Pi Configuration > Interfaces.
2. Run the following commands(make sure you have an active internet connection):

   sudo apt update && sudo apt upgrade -y
   sudo apt install python3-venv
   sudo apt install git -y

3. Install the required dependencies:

   sudo apt install libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libopenjp2-7-dev libtiff5-dev tk-dev tcl-dev libwebp-dev libharfbuzz-dev libfribidi-dev libxcb1-dev

   when prompted enter "Y" + enter to continue
4. Create and activate a virtual environment:

   python3 -m venv oled-env
   source oled-env/bin/activate

   (Use deactivate to exit the virtual environment when required.)
5. Check the OLED address:

   i2cdetect -y 1

   (Address should be visible 0x3D or 0x3C. If not, check the display wiring.) - Make sure to set address in the script
6. Clone the repository:

   run: 
   sudo apt update
   pip install --upgrade pip
   sudo apt install -y python3-dev python3-pip python3-setuptools python3-wheel libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libopenjp2-7 libwebp-dev tk-dev tcl-dev
   pip3 install --upgrade pip setuptools wheel
   sudo apt-get install python3-netifaces
   pip install luma.oled

   Note: for this step: the repo must set to public temporarily, contact author for this.

   git clone https://github.com/lavacode/oled.git

   • If cloning fails, ensure the LAN cable is temporarily disconnected and follow these steps:

     nmcli connection show
     sudo nmcli connection modify "<LAN Connection Name>" ipv4.never-default yes
     sudo nmcli connection down "<LAN Connection Name>" && sudo nmcli connection up "<LAN Connection Name>"

7. Activate the virtual environment if not activated:

   source oled-env/bin/activate

8. Navigate to the cloned repository and install requirements:

   cd oled
   cd scripts-single / ****_dual
   pip3 install -r requirements.txt

   when prompted enter "Y" + enter to continue
9. Test the setup:

   python3 oled-test.py

   This should result in "First test" on your display
10. Test the final code:

    python3 oled-src.py

11. Return to the home folder:

    cd

12. Remove the cloned repository:

    rm -rf oled

13. Download the final script:

    wget https://raw.githubusercontent.com/lavacode/oled/main/scripts-single/oled-src.py
    
    or, in dual mode:
    wget https://raw.githubusercontent.com/lavacode/oled/main/scripts-dual/oled-src.py
    

14. Verify the script is present:

    ls

    You should see the "oled-src.py"
15. Make the script executable:

    chmod +x oled-src.py

16. Create a systemd service:

    sudo nano /etc/systemd/system/oled.service

    Add the following content:

    [Unit]
    Description=Autostart OLED script
    After=network.target
    
    [Service]
    ExecStart=/home/galaxy/oled-env/bin/python3 /home/galaxy/oled-src.py
    WorkingDirectory=/home/galaxy
    Environment=VIRTUAL_ENV=/home/galaxy/oled-env
    Environment=PATH=/home/galaxy/oled-env/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    StandardOutput=inherit
    StandardError=inherit
    Restart=always
    User=galaxy
    
    [Install]
    WantedBy=multi-user.target

17. Save and exit (Ctrl + X, Y, Enter).
18. Reload systemd:

    sudo systemctl daemon-reload
    sudo systemctl enable oled.service
    sudo systemctl start oled.service
    sudo systemctl status oled.service

    This should result in "enabled"
19. Set up static network and check priority in "General" is set to 0. Also make sure it is set to manual(!)
20. Turn WiFi OFF
21. Reboot:

    sudo reboot

22. Test, if succesful everything should work as supposed. Only then continue.

Disable Desktop Environment

1. Access the board via SSH. Use external computer linked to board. use Mac or Windows terminal ```bash ssh galaxy@ip_address_of_pi

   Enter details. For fingerprint enter "Y". 
   
   *if the connection is succesful, you don't need a monitor + keyboard anymore for the Pi*
   

2. Run:

   sudo raspi-config

3. Navigate to:
   • System Options
   • Boot / Auto Login
   • Set to "Console Autologin".
4. Reboot.

Disable WiFi and bluetooth (if not required)

1. Edit the config file:

   sudo nano /boot/firmware/config.txt

2. Add the following line at the bottom:

   dtoverlay=disable-wifi
   dtoverlay=disable-bt
   

3. Change the setting

   camera_auto_detect=1
   

   update it to

   camera_auto_detect=0
   

4. Save and exit.

5. sudo reboot
   

---

UDP Commands Available

Destination Port: 12345

The following UDP commands can be sent to control the board:

• start: Starts the timer.
• stop: Stops the timer.
• pause: Pauses the timer.
• resume: Resumes the timer.
• DUR!###: Changes the timer duration (replace ### with the number of seconds).
• reboot: Reboots the board.

Response

All UDP commands will reply with command_rcv to acknowledge receipt of the command.

Troubleshooting

Common Issues

1. ISSUES? PERFORM A REBOOT! =)

2. Install required Python packages:

   sudo apt install python3-pip python3-pil python3-smbus python3-rpi.gpio
   pip install adafruit-circuitpython-ssd1306
   pip install adafruit-blinka
   pip3 install pillow
   pip3 install netifaces

3. Busio-related issues? Ensure SDA/SCL connections are not twisted.

4. Executing script results in "No I2C device detected" Check your screen connection and address

SSH issues

1. In case you get an error "IDENTIFICATION HAS CHANGED" Use the Pi directly

   cd /etc/ssh
   ls 
   sudo rm ssh_host_*
   sudo dkpg-reconfigure openssh-server
   sudo systemctl restart ssh

   Then on your remote computer:

   ssh-keygen -R <raspberry_ip>

Editing Code

1. Open the file:

   sudo nano oled-src.py

2. Make changes, then save and exit (Ctrl + X, Y, Enter).
3. Reboot:

   sudo reboot

Network changes/troubleshooting

1. Connect with ssh to the default IP of the Pi.

2.  sudo nmtui

   Here you can edit the connection. Still having issues? then follow the next steps

3.  sudo ls /etc/NetworkManager/system-connections/

   now you see all known connections, check which to modify and:

4. sudo nano /etc/NetworkManager/system-connections/'Wired connection 1.nmconnection' 

5. Update data and save

6.  sudo systemctl restart NetworkManager

7.  ip a

8. To remove a known wifi connection

   sudo rm /etc/NetworkManager/system-connections/'DTC-FLEX.nmconnection'

9.  sudo systemctl restart NetworkManager

10. You can decide to turn the EEE off. Please refer to google. Checking eee status:

    sudo ethtool --show-eee eth0

Connect to WiFi

Most easy way is with monitor and keyboard/mouse, but alternatively:

SSH:

Make sure wifi is allowed (in config.txt)

1. check if wifi is blocked:

   rfkill list

   In case: Soft blocked yes, do:

   sudo rfkill unblock wifi
   sudo ip link set wlan0 up

2. Scan networks:

   nmcli device wifi list

   in case no results set correct region.

   Check current region:

   sudo iw reg get

   Set region:

   sudo iw reg set US

   nmcli device wifi list

3. Connect:

   sudo nmcli device wifi connect "<SSID>" password "<password>"

4. Done

5. for disabling perform the action in config.txt and also remove the known wifi connection:

   sudo rm /etc/NetworkManager/system-connections/'DTC-FLEX.nmconnection'

6. After reboot, check with:

    ip a

   that the connection is gone.

---

Testing First Output

Follow instructions step 6 to 12. Run the test script:

python3 oled-test.py

This should display "First test" on the OLED screen.

---

Final Code

Compare with the GitHub version: oled-src.py

Having issues accessing the script? Contact: kasperz@2heads.com