Installation Guide

This guide will walk you through the process of installing and setting up the Punch Card Display System.

Prerequisites

Before you begin, make sure you have the following:

• Python 3.7 or newer
• Git (for cloning the repository)
• OpenAI API key (optional, for AI-powered message generation)
• Pip (Python package manager)
• Terminal/Command Prompt access

Hardware Requirements

Minimum Requirements

• Any computer capable of running Python 3.7+
• 2GB RAM
• 100MB disk space

Optional Hardware

• Raspberry Pi (for physical LED matrix integration)
• LED matrix components (if building a physical display)

Installation Steps

1. Clone the Repository

# Clone the repository
git clone https://github.com/griffingilreath/Punch-Card-Project.git

# Navigate to the project directory
cd Punch-Card-Project

2. Install Dependencies

# Install required packages
pip install -r requirements.txt

3. Set Up Your OpenAI API Key

You have four options to set up your API key:

Method 1: Using the update_api_key.py script (RECOMMENDED)

# Run the script and follow the prompts - your key will never be displayed
python update_api_key.py

Method 2: Manually edit the secrets file

# Create a copy of the template in the secrets directory
cp secrets/api_keys.json.template secrets/api_keys.json

# Edit the api_keys.json file with your actual API key
# Replace "YOUR_OPENAI_API_KEY_HERE" with your real key

Method 3: Environment variables

# On macOS/Linux
export OPENAI_API_KEY=your_api_key_here

# On Windows
set OPENAI_API_KEY=your_api_key_here

Method 4: Settings file (LEAST SECURE - not recommended)

Edit the punch_card_settings.json file and replace "YOUR_API_KEY_HERE" with your actual key.

Running the Application

Basic Usage

# Run with default settings
python simple_display.py

# Run with the new black background theme and OpenAI integration
python simple_display.py --black-bg --openai

# Run with debug output
python simple_display.py --debug

Testing the System

# Run a minimal test with ASCII character set
python test_leds.py --test minimal --use-ui --char-set ascii

# Run hardware verification with star characters
python test_leds.py --test hardware --use-ui --char-set star

# Run animation test with circle characters
python test_leds.py --test animations --use-ui --char-set circle

Troubleshooting

Common Issues

1. API Key not recognized

   • Ensure your API key is correctly set in one of the locations described above
   • Check that the key is valid in your OpenAI account

2. Display issues

   • If the terminal UI does not render correctly, try using the --char-set ascii flag
   • Ensure your terminal window is large enough (at least 80x24 characters)

3. Module not found errors

   • Verify that all dependencies were installed correctly
   • Try running pip install -r requirements.txt again

4. Permission denied errors

   • On Unix-based systems, you may need to make scripts executable:

     chmod +x *.py
     

Getting Help

If you encounter any issues not covered here, please:

1. Check the FAQ page for common questions
2. Review the Known Issues section
3. Open an issue on the GitHub repository

Next Steps

After installation, check out these resources:

• Usage Guide - Learn how to use all features
• Configuration - Customize the system
• Hardware Integration - Set up physical hardware

---

Last updated: March 24, 2024