In this gist, is a **comprehensive, detailed guide** for installing and configuring the **1.14" 240x135 PiTFT** on your Raspberry Pi Zero W2 using the "hard way" method. This guide includes **advanced scripts** to automate the installation, handle updates, and ensure robust configuration management. By following these instructions, you'll set up your PiTFT to display the console seamlessly and maintain its functionality across kernel updates and different Raspberry Pi models.

In this gist, is a comprehensive, detailed guide for installing and configuring the 1.14" 240x135 PiTFT on your Raspberry Pi Zero W2 using the "hard way" method. This guide includes advanced scripts to automate the installation, handle updates, and ensure robust configuration management. By following these instructions, you'll set up your PiTFT to display the console seamlessly and maintain its functionality across kernel updates and different Raspberry Pi models.

Prerequisites
System Preparation
Setting Up Python Virtual Environment (Optional)
Physical Installation of PiTFT
Software Installation and Configuration
Advanced Installation Script
Automating Reinstallation After Kernel Updates
Repository Structure
Final Steps and Verification
Troubleshooting
Additional Resources

1. Prerequisites

Before you begin, ensure you have the following:

Hardware:
- Raspberry Pi Zero W2 (with SD card and power supply)
- 1.14" 240x135 PiTFT Display (v1.0)
- Two push buttons (optional, for interaction)
- Jumper wires (if needed)
- Micro SD card (with Raspberry Pi OS installed)
Software:
- Latest Raspberry Pi OS Lite image
- Internet connection for the Pi

2. System Preparation

Start by updating and upgrading your Raspberry Pi to ensure all packages are current. This helps prevent compatibility issues during installation.

Boot Up and Access the Terminal:

If you're using a headless setup, connect via SSH. Otherwise, connect a keyboard and monitor.

Update and Upgrade Packages:

sudo apt update -y
sudo apt-get update -y
sudo apt-get upgrade -y
sudo apt-get dist-upgrade -y

Reboot the Raspberry Pi:
```
sudo reboot
```

3. Setting Up Python Virtual Environment (Optional)

If you're using Raspberry Pi OS Bookworm or later, it's recommended to install Python modules within a virtual environment to avoid conflicts with system packages.

Install Python Virtual Environment Package:
```
sudo apt install python3.11-venv -y
```

Create a Virtual Environment:

python3 -m venv pitft_env --system-site-packages

Activate the Virtual Environment:
```
source pitft_env/bin/activate
```
Note: To deactivate, simply run deactivate.

4. Physical Installation of PiTFT

Carefully attach the PiTFT display to the Raspberry Pi’s GPIO header.

Shut Down the Raspberry Pi Safely:
```
sudo shutdown -h now
```
Connect the PiTFT Display:
- Align the Pins:
  - Ensure the rounded corner and mounting hole of the PiTFT align with the corresponding features on the Pi Zero W2.
  - The GPIO pins of the PiTFT should align with the Pi’s GPIO header.
- Secure the Connection:
  - Gently press the PiTFT onto the GPIO header until it is firmly seated.
Reattach Power and Boot Up:
```
# After connecting the PiTFT, plug in the power supply
```
The PiTFT should light up, but the screen may remain blank until software configuration is complete.

5. Software Installation and Configuration

A. Install Required Dependencies

Install Python Packages and Tools:

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

Upgrade pip:
```
sudo pip3 install --upgrade pip
```

B. Clone Adafruit's Installer Scripts

Adafruit provides a repository with installer scripts tailored for PiTFT displays.

Clone the Repository:

git clone https://github.com/adafruit/Raspberry-Pi-Installer-Scripts.git

Navigate to the Installer Scripts Directory:
```
cd Raspberry-Pi-Installer-Scripts
```

C. Run the PiTFT Installer

Execute the installer script with the appropriate parameters for your PiTFT model.

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x135 --rotation=270 --install-type=console

Parameters Explained:
- --display=st7789_240x135: Specifies the display type and resolution.
- --rotation=270: Rotates the display by 270 degrees (adjust as needed).
- --install-type=console: Installs the console display. Note: This does not provide a GUI.

D. Reboot the Raspberry Pi

After the installation completes, you'll be prompted to reboot. Do so to apply changes.

sudo reboot

Upon reboot, the console should appear on the PiTFT display.

6. Advanced Installation Script

To streamline the installation process and make it reproducible across multiple devices, create an advanced installation script. This script automates all necessary steps, handles potential errors, and logs the installation process for troubleshooting.

A. Create the Installation Script

Create a Directory for Scripts:
```
mkdir -p ~/scripts
cd ~/scripts
```
Create the Installation Script File:
```
nano install_pitft.sh
```

Add the Following Script:

#!/bin/bash

set -e  # Exit immediately if a command exits with a non-zero status
set -u  # Treat unset variables as an error

LOG_FILE=~/install_pitft.log

echo "Starting PiTFT Installation at $(date)" | tee -a "$LOG_FILE"

# Update and Upgrade
echo "Updating and upgrading system packages..." | tee -a "$LOG_FILE"
sudo apt update -y | tee -a "$LOG_FILE"
sudo apt-get update -y | tee -a "$LOG_FILE"
sudo apt-get upgrade -y | tee -a "$LOG_FILE"
sudo apt-get dist-upgrade -y | tee -a "$LOG_FILE"

# Install Dependencies
echo "Installing required dependencies..." | tee -a "$LOG_FILE"
sudo apt-get install -y git python3-pip python3-pil python3-numpy python3.11-venv | tee -a "$LOG_FILE"
sudo pip3 install --upgrade pip | tee -a "$LOG_FILE"

# Setup Virtual Environment (Optional)
echo "Setting up Python virtual environment..." | tee -a "$LOG_FILE"
python3 -m venv ~/pitft_env --system-site-packages | tee -a "$LOG_FILE"
source ~/pitft_env/bin/activate

# Clone Adafruit Installer Scripts
echo "Cloning Adafruit's Installer Scripts..." | tee -a "$LOG_FILE"
if [ ! -d ~/Raspberry-Pi-Installer-Scripts ]; then
    git clone https://github.com/adafruit/Raspberry-Pi-Installer-Scripts.git | tee -a "$LOG_FILE"
else
    echo "Raspberry-Pi-Installer-Scripts already cloned." | tee -a "$LOG_FILE"
fi

cd ~/Raspberry-Pi-Installer-Scripts

# Install PiTFT
echo "Running PiTFT installer..." | tee -a "$LOG_FILE"
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x135 --rotation=270 --install-type=console | tee -a "$LOG_FILE"

echo "PiTFT Installation Completed Successfully at $(date)" | tee -a "$LOG_FILE"

# Deactivate Virtual Environment
deactivate

# Reboot
echo "Rebooting the system..." | tee -a "$LOG_FILE"
sudo reboot

Save and Exit:

Press Ctrl + O, then Enter to save. Press Ctrl + X to exit the editor.
Make the Script Executable:
```
chmod +x install_pitft.sh
```

B. Execute the Installation Script

Run the script to perform a complete installation.

./install_pitft.sh

The script will log its progress to ~/install_pitft.log. After completion, the Raspberry Pi will reboot, and the console should appear on the PiTFT display.

7. Automating Reinstallation After Kernel Updates

Kernel updates can disrupt the PiTFT driver, necessitating a reinstallation. To automate this process, set up a system that detects kernel updates and reinstalls the PiTFT driver accordingly.

A. Create a Reinstallation Script

Create the Script File:
```
nano ~/scripts/reinstall_pitft.sh
```

Add the Following Script:

#!/bin/bash

set -e
set -u

LOG_FILE=~/reinstall_pitft.log

echo "Starting PiTFT Reinstallation at $(date)" | tee -a "$LOG_FILE"

# Check if Installer Scripts are Cloned
if [ -d ~/Raspberry-Pi-Installer-Scripts ]; then
    cd ~/Raspberry-Pi-Installer-Scripts
else
    echo "Raspberry-Pi-Installer-Scripts not found. Cloning now..." | tee -a "$LOG_FILE"
    git clone https://github.com/adafruit/Raspberry-Pi-Installer-Scripts.git | tee -a "$LOG_FILE"
    cd Raspberry-Pi-Installer-Scripts
fi

# Run PiTFT Installer
echo "Reinstalling PiTFT driver..." | tee -a "$LOG_FILE"
sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x135 --rotation=270 --install-type=console | tee -a "$LOG_FILE"

echo "PiTFT Reinstallation Completed Successfully at $(date)" | tee -a "$LOG_FILE"

# Reboot
echo "Rebooting the system to apply changes..." | tee -a "$LOG_FILE"
sudo reboot

Save and Exit:

Press Ctrl + O, Enter, then Ctrl + X.
Make the Script Executable:
```
chmod +x ~/scripts/reinstall_pitft.sh
```

B. Create a Systemd Service and Timer

Create the Systemd Service File:

sudo nano /etc/systemd/system/pitft-reinstall.service

Add the Following Content:

[Unit]
Description=Reinstall PiTFT After Kernel Update
After=linux-image.target

[Service]
Type=oneshot
ExecStart=/home/pi/scripts/reinstall_pitft.sh

Replace /home/pi/ with your actual home directory if different.

Save and Exit:

Press Ctrl + O, Enter, then Ctrl + X.

Create the Systemd Timer File:

sudo nano /etc/systemd/system/pitft-reinstall.timer

Add the Following Content:

[Unit]
Description=Timer to Reinstall PiTFT After Kernel Update

[Timer]
OnUnitActiveSec=1h
Unit=pitft-reinstall.service

[Install]
WantedBy=timers.target

This timer checks every hour if a kernel update has occurred and reinstalls the PiTFT driver.

Enable and Start the Timer:

sudo systemctl enable pitft-reinstall.timer
sudo systemctl start pitft-reinstall.timer

Verify the Timer is Active:
```
systemctl list-timers --all | grep pitft-reinstall
```
You should see pitft-reinstall.timer listed and active.

C. Optional: Hook Into Kernel Update Process

Alternatively, you can hook directly into the kernel update process to trigger the PiTFT reinstallation immediately after a kernel update.

Create a Post-Upgrade Hook Script:

sudo nano /etc/apt/apt.conf.d/99-pitft-reinstall

Add the Following Content:

DPkg::Post-Invoke { "bash /home/pi/scripts/reinstall_pitft.sh"; };

Ensure the script path is correct.

Save and Exit:

Press Ctrl + O, Enter, then Ctrl + X.

Now, every time a package upgrade occurs (including kernel updates), the PiTFT reinstallation script will run automatically.

8. Repository Structure

Organize your scripts and configurations within a Git repository to manage versions and facilitate deployments across multiple devices.

A. Repository Name

pitft-setup-scripts

B. Suggested Directory Structure

pitft-setup-scripts/
├── scripts/
│   ├── install_pitft.sh
│   ├── reinstall_pitft.sh
│   └── README.md
├── systemd/
│   ├── pitft-reinstall.service
│   └── pitft-reinstall.timer
├── configs/
│   └── adafruit-pitft/
│       ├── pitft.conf  # Any custom configurations if needed
├── logs/
│   ├── install_pitft.log
│   └── reinstall_pitft.log
├── docs/
│   ├── installation_guide.md
│   ├── troubleshooting.md
│   └── usage_examples.md
├── .gitignore
└── LICENSE

C. Initialize Git Repository

Navigate to Your Scripts Directory:
```
cd ~/scripts
```
Initialize Git:
```
git init
```
Create a .gitignore File:
```
nano .gitignore
```
Add:
```
*.log
pitft_env/
```

Commit Your Scripts:

git add .
git commit -m "Initial commit of PiTFT installation and reinstallation scripts"

Create a Remote Repository:
- GitHub/GitLab: Create a new repository named pitft-setup-scripts.

Add Remote and Push:

git remote add origin https://github.com/yourusername/pitft-setup-scripts.git
git branch -M main
git push -u origin main

9. Final Steps and Verification

A. Verify PiTFT Console Display

After rebooting, ensure that the console is displayed on the PiTFT:

Observe the PiTFT:
- The PiTFT should now show the Raspberry Pi console (login prompt, terminal output).
Log In:
- Use your keyboard to log in as usual. The terminal interactions should appear on the PiTFT.

B. Test the Installation Scripts

Check Installation Logs:
```
cat ~/install_pitft.log
```
Ensure there are no errors.
Check Reinstallation Logs:
```
cat ~/reinstall_pitft.log
```
Ensure the reinstallation process runs without issues.
Manually Trigger Reinstallation (For Testing):
```
~/scripts/reinstall_pitft.sh
```
The system should reinstall the PiTFT driver and reboot.

10. Troubleshooting

A. PiTFT Display Not Showing Console

Check Physical Connections:
- Ensure the PiTFT is firmly connected to the GPIO header.
- Verify that power (VCC and GND) is properly connected.
Verify SPI is Enabled:
```
sudo raspi-config
```
- Navigate to Interfacing Options > SPI and ensure it is enabled.
Review Installation Logs:
```
cat ~/install_pitft.log
```
- Look for any error messages during the installation.
Manually Reinstall PiTFT Driver:
```
sudo ~/scripts/reinstall_pitft.sh
```

B. PiTFT Display Flickering or Not Stable

Check Power Supply:
- Ensure the Raspberry Pi is receiving adequate power (at least 2.5A).
Inspect Cables and Connectors:
- Ensure all jumper wires and connectors are secure and not damaged.

Update Firmware:

sudo apt-get install --reinstall raspberrypi-bootloader raspberrypi-kernel -y
sudo reboot

C. Script Execution Issues

Check Script Permissions:
```
ls -l ~/scripts/*.sh
```
- Ensure scripts are executable (-rwxr-xr-x).
Verify Systemd Services and Timers:
```
systemctl status pitft-reinstall.service
systemctl status pitft-reinstall.timer
```
- Ensure they are active and not encountering errors.
Examine Log Files:
```
cat ~/reinstall_pitft.log
```
- Look for any errors or failed commands.

11. Additional Resources

Adafruit PiTFT Guide: Adafruit PiTFT Installation Guide
Raspberry Pi GPIO Pinout: Raspberry Pi GPIO Pinout
Python Virtual Environments: Python Virtual Environments Documentation
Systemd Service Management: Systemd Service Documentation
GitHub Repository Management: GitHub Docs

Summary

By following this detailed guide, you have:

Prepared Your Raspberry Pi: Updated the system and installed necessary packages.
Physically Installed the PiTFT Display: Connected it securely to the GPIO header.
Configured Software: Installed and configured the PiTFT driver to display the console.
Created Advanced Scripts: Automated installation and reinstallation processes with logging and error handling.
Set Up Automation for Kernel Updates: Ensured the PiTFT remains functional after kernel changes.
Organized Repository Structure: Maintained scripts and configurations in a Git repository for version control and scalability.
Verified Functionality: Confirmed that the PiTFT displays the console and that scripts operate as intended.
Addressed Troubleshooting: Provided steps to resolve common issues.

This setup ensures that your PiTFT display is robustly integrated with your Raspberry Pi Zero W2, capable of maintaining functionality across updates and adaptable to various Raspberry Pi models. The advanced scripts and automated processes streamline management, making it an essential tool for centralized infrastructure configuration and setup.

Feel free to customize the scripts and configurations further to suit your specific needs or to integrate additional functionalities. If you encounter any specific issues or require further customization, don't hesitate to ask!

Cdaprod/Pi_TFT_Console_Display.md

Table of Contents

1. Prerequisites

2. System Preparation

3. Setting Up Python Virtual Environment (Optional)

4. Physical Installation of PiTFT

5. Software Installation and Configuration

A. Install Required Dependencies

B. Clone Adafruit's Installer Scripts

C. Run the PiTFT Installer

D. Reboot the Raspberry Pi

6. Advanced Installation Script

A. Create the Installation Script

B. Execute the Installation Script

7. Automating Reinstallation After Kernel Updates

A. Create a Reinstallation Script

B. Create a Systemd Service and Timer

C. Optional: Hook Into Kernel Update Process

8. Repository Structure

A. Repository Name

B. Suggested Directory Structure

C. Initialize Git Repository

9. Final Steps and Verification

A. Verify PiTFT Console Display

B. Test the Installation Scripts

10. Troubleshooting

A. PiTFT Display Not Showing Console

B. PiTFT Display Flickering or Not Stable

C. Script Execution Issues

11. Additional Resources

Summary