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>
2026-02-16 22:36:17 +13:00
parent ced41148ef
commit 4b33ac4bde
19 changed files with 173 additions and 23 deletions
--- a/README.md
+++ b/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)
- 📅 **Google Calendar** - Family calendar events display
+- 🌤️ **Weather** - Current weather and 3-day forecast (OpenWeatherMap)
+- 📅 **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_UPDATE_INTERVAL` - Seconds between weather updates (default: 900)
- `CALENDAR_UPDATE_INTERVAL` - Seconds between calendar updates (default: 300)
- `JOKE_UPDATE_INTERVAL` - Seconds between joke updates (default: 3600)
- `CALENDAR_DAYS_AHEAD` - Number of days ahead to show events (default: 7)
+**Weather Settings:**
+- `OPENWEATHER_API_KEY` - Your OpenWeatherMap API key
+- `WEATHER_LOCATION` - City name and country code (e.g., "London,UK")
+- `WEATHER_LAT` - Latitude of your location
+- `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