Generalize code and improve documentation

Remove personal information and improve setup documentation:

**Code Generalization:**
- Updated .env.example with placeholder values
- Removed personal API keys and calendar IDs
- Removed all personal background images (15 images deleted)
- Added backgrounds directory README with usage instructions
- Updated .gitignore to exclude background images

**Documentation Improvements:**
- Added comprehensive Weather API setup instructions
  - How to get OpenWeatherMap API key
  - How to find location coordinates using LatLong.net
- Added detailed Google Calendar setup instructions
  - Public iCal feed method (easiest, no auth required)
  - Alternative Google Calendar API method
- Added background image specifications
  - Supported formats, recommended resolution
  - Where to add images and how to change rotation interval
- Added configuration section explaining all settings
  - Environment variables documentation
  - JavaScript intervals configuration
  - How to change image rotation time in both .env and app.js
- Added dynamic text color feature to feature list

**Setup Instructions Now Include:**
- Step-by-step Weather API key acquisition
- Google Calendar public iCal URL setup
- Background image guidelines and rotation configuration
- All configuration options clearly documented

Users can now easily set up their own calendar display without any personal information in the codebase.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.env.example

@@ -1,20 +1,25 @@
 # Flask Configuration
-FLASK_SECRET_KEY=your_secret_key_here
+FLASK_SECRET_KEY=calendar-display-secret-key-change-this
 
 # OpenWeatherMap API
-OPENWEATHER_API_KEY=your_api_key_here
+# Get your free API key from: https://openweathermap.org/api
+OPENWEATHER_API_KEY=your_openweather_api_key_here
 
-# Weather Location (Hamilton, New Zealand)
+# Weather Location
-WEATHER_LOCATION=Hamilton,NZ
+# Find coordinates at: https://www.latlong.net/
-WEATHER_LAT=-37.7870
+WEATHER_LOCATION=YourCity,CountryCode
-WEATHER_LON=175.2793
+WEATHER_LAT=0.0000
+WEATHER_LON=0.0000
 
 # Google Calendar
+# Option 1: Use public iCal URL (easiest - no authentication needed)
+# Get from: Google Calendar Settings > Calendar > Integrate Calendar > Public URL to this calendar (iCal format)
 GOOGLE_CALENDAR_ID=your_calendar_id@group.calendar.google.com
+GOOGLE_CALENDAR_ICAL_URL=https://calendar.google.com/calendar/ical/your_calendar_id%40group.calendar.google.com/public/basic.ics
 
 # Update Intervals (seconds)
-IMAGE_ROTATION_INTERVAL=300
+IMAGE_ROTATION_INTERVAL=60
 WEATHER_UPDATE_INTERVAL=900
 CALENDAR_UPDATE_INTERVAL=300
 JOKE_UPDATE_INTERVAL=3600
-CALENDAR_DAYS_AHEAD=7
+CALENDAR_DAYS_AHEAD=5

.gitignore

@@ -43,3 +43,8 @@ Thumbs.db
 
 # Logs
 *.log
+
+# Background Images (users should add their own)
+static/backgrounds/*
+!static/backgrounds/README.md
+!static/backgrounds/.gitkeep

README.md

@@ -7,9 +7,10 @@ A smart display application for Raspberry Pi that shows time, weather, calendar
 ## Features
 
 - 🕐 **Real-time Clock** - Current time and date display
-- 🌤️ **Weather** - Current weather and 3-day forecast for Hamilton, New Zealand (OpenWeatherMap)
+- 🌤️ **Weather** - Current weather and 3-day forecast (OpenWeatherMap)
-- 📅 **Google Calendar** - Family calendar events display
+- 📅 **Google Calendar** - Calendar events display (supports public iCal feeds)
 - 🖼️ **Rotating Backgrounds** - Beautiful images from local directory
+- 🎨 **Dynamic Text Color** - Automatically adjusts text color based on background brightness
 - 😄 **Dad Jokes** - Random jokes to brighten your day (optional)
 
 ## Requirements
@@ -55,26 +56,80 @@ GOOGLE_CALENDAR_ID=your_calendar_id@group.calendar.google.com
 FLASK_SECRET_KEY=your_random_secret_key
 ```
 
-### 4. Set Up Google Calendar API
+### 4. Get OpenWeatherMap API Key
+
+1. Go to [OpenWeatherMap](https://openweathermap.org/api)
+2. Sign up for a free account
+3. Navigate to "API keys" section
+4. Copy your API key
+5. Add it to your `.env` file as `OPENWEATHER_API_KEY`
+
+**Find Your Location Coordinates:**
+1. Go to [LatLong.net](https://www.latlong.net/)
+2. Search for your city
+3. Copy the latitude and longitude values
+4. Add them to your `.env` file as `WEATHER_LAT` and `WEATHER_LON`
+
+### 5. Set Up Google Calendar
+
+**Option 1: Public iCal Feed (Easiest - No Authentication)**
+
+1. Open [Google Calendar](https://calendar.google.com/)
+2. Go to Settings (⚙️ gear icon)
+3. Select the calendar you want to display
+4. Scroll down to "Integrate calendar"
+5. Copy the **"Public URL to this calendar"** in iCal format
+   - The URL looks like: `https://calendar.google.com/calendar/ical/...@group.calendar.google.com/public/basic.ics`
+6. Add this URL to your `.env` file as `GOOGLE_CALENDAR_ICAL_URL`
+7. Also copy the Calendar ID (looks like `abc123...@group.calendar.google.com`)
+8. Add it to your `.env` file as `GOOGLE_CALENDAR_ID`
+
+**Note:** Your calendar must be set to "Public" for this method to work.
+
+**Option 2: Google Calendar API with Credentials (Advanced)**
+
+If you prefer to use private calendars with authentication:
 
 1. Go to [Google Cloud Console](https://console.cloud.google.com/)
 2. Create a new project or select existing one
 3. Enable the Google Calendar API
-4. Create credentials (OAuth 2.0 or Service Account)
+4. Create credentials (Service Account)
 5. Download the credentials JSON file
-6. Save it as [credentials/google_calendar_credentials.json](credentials/google_calendar_credentials.json)
+6. Save it as `credentials/google_calendar_credentials.json`
+7. Share your calendar with the service account email
 
-### 5. Add Background Images
+### 6. Add Background Images
 
-Place your images in the [static/backgrounds/](static/backgrounds/) directory:
+Place your images in the `static/backgrounds/` directory:
 
 ```bash
 cp /path/to/your/images/*.jpg static/backgrounds/
 ```
 
-Supported formats: JPG, PNG, GIF, WebP
+**Supported formats:** JPG, JPEG, PNG, GIF, WebP
 
-### 6. Run the Application
+**Recommended specifications:**
+- Resolution: 1920x1080 or higher
+- Aspect ratio: 16:9 (for full-screen displays)
+- File size: Keep under 5MB for faster loading
+
+**Changing Image Rotation Interval:**
+
+Edit your `.env` file:
+```bash
+# Time in seconds (60 = 1 minute)
+IMAGE_ROTATION_INTERVAL=60
+```
+
+Or edit `static/js/app.js`:
+```javascript
+const INTERVALS = {
+    BACKGROUND: 60000,  // Milliseconds (60000 = 1 minute)
+    ...
+};
+```
+
+### 7. Run the Application
 
 ```bash
 python app.py
@@ -153,13 +208,50 @@ The display should now start automatically on boot!
 
 ## Configuration
 
-Edit [.env](.env) to customize:
+### Environment Variables (`.env` file)
 
-- `IMAGE_ROTATION_INTERVAL` - Seconds between background changes (default: 300)
+**Weather Settings:**
-- `WEATHER_UPDATE_INTERVAL` - Seconds between weather updates (default: 900)
+- `OPENWEATHER_API_KEY` - Your OpenWeatherMap API key
-- `CALENDAR_UPDATE_INTERVAL` - Seconds between calendar updates (default: 300)
+- `WEATHER_LOCATION` - City name and country code (e.g., "London,UK")
-- `JOKE_UPDATE_INTERVAL` - Seconds between joke updates (default: 3600)
+- `WEATHER_LAT` - Latitude of your location
-- `CALENDAR_DAYS_AHEAD` - Number of days ahead to show events (default: 7)
+- `WEATHER_LON` - Longitude of your location
+
+**Calendar Settings:**
+- `GOOGLE_CALENDAR_ID` - Your calendar ID
+- `GOOGLE_CALENDAR_ICAL_URL` - Public iCal feed URL (easiest method)
+- `CALENDAR_DAYS_AHEAD` - Number of days ahead to show events (default: 5)
+
+**Update Intervals (in seconds):**
+- `IMAGE_ROTATION_INTERVAL` - Background image rotation (default: 60)
+- `WEATHER_UPDATE_INTERVAL` - Weather refresh interval (default: 900)
+- `CALENDAR_UPDATE_INTERVAL` - Calendar refresh interval (default: 300)
+- `JOKE_UPDATE_INTERVAL` - Dad joke refresh interval (default: 3600)
+
+**Other:**
+- `FLASK_SECRET_KEY` - Flask session secret key
+
+### JavaScript Configuration (`static/js/app.js`)
+
+For more precise control over update intervals, edit the `INTERVALS` object:
+
+```javascript
+const INTERVALS = {
+    TIME: 1000,              // 1 second
+    WEATHER: 900000,         // 15 minutes
+    CALENDAR: 300000,        // 5 minutes
+    BACKGROUND: 60000,       // 1 minute (change this for image rotation)
+    JOKE: 3600000           // 1 hour
+};
+```
+
+**To change image rotation time:**
+1. Open `static/js/app.js`
+2. Find the `INTERVALS` object at the top
+3. Change `BACKGROUND: 60000` to your desired value in milliseconds
+   - 30000 = 30 seconds
+   - 60000 = 1 minute
+   - 120000 = 2 minutes
+   - 300000 = 5 minutes
 
 ## Project Structure
 

static/backgrounds/README.md

@@ -0,0 +1,48 @@
+# Background Images
+
+This directory is where you place your background images for the calendar display.
+
+## Adding Images
+
+1. Copy your image files to this directory:
+   ```bash
+   cp /path/to/your/images/* static/backgrounds/
+   ```
+
+2. Supported formats:
+   - JPEG/JPG
+   - PNG
+   - GIF
+   - WebP
+
+3. Recommended image specifications:
+   - Resolution: 1920x1080 or higher
+   - Aspect ratio: 16:9 (for full-screen displays)
+   - File size: Keep under 5MB for faster loading
+
+## Image Rotation
+
+Images automatically rotate at the interval specified in your `.env` file.
+
+To change the rotation interval, edit the `.env` file:
+
+```bash
+# Time in seconds (default: 60 seconds = 1 minute)
+IMAGE_ROTATION_INTERVAL=60
+```
+
+Or directly in `static/js/app.js`:
+
+```javascript
+const INTERVALS = {
+    BACKGROUND: 60000,  // Milliseconds (60000 = 1 minute)
+    ...
+};
+```
+
+## Tips
+
+- Use high-quality images for best display
+- The app will randomly select images from this directory
+- Delete or move images you no longer want displayed
+- Images are cached by the browser, so you may need to hard-refresh (Ctrl+F5) to see new images immediately