🕐 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
🖼️ Rotating Backgrounds - Beautiful images from local directory
😄 Dad Jokes - Random jokes to brighten your day (optional)

Requirements

Python 3.8+
Raspberry Pi (tested on Pi 3/4) or any Linux system
Google Calendar API credentials
OpenWeatherMap API key (free tier)

Quick Start

1. Clone the Repository

git clone ssh://git@gitea.meyfamily.co.nz:2222/luddie/Calender.git
cd Calender

2. Install Dependencies

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Configure Environment Variables

cp .env.example .env

Edit .env and add your API keys:

# Get your OpenWeatherMap API key from: https://openweathermap.org/api
OPENWEATHER_API_KEY=your_api_key_here

# Your Google Calendar ID (found in Google Calendar settings)
GOOGLE_CALENDAR_ID=your_calendar_id@group.calendar.google.com

# Generate a secret key for Flask
FLASK_SECRET_KEY=your_random_secret_key

4. Set Up Google Calendar API

Go to Google Cloud Console
Create a new project or select existing one
Enable the Google Calendar API
Create credentials (OAuth 2.0 or Service Account)
Download the credentials JSON file
Save it as credentials/google_calendar_credentials.json

5. Add Background Images

Place your images in the static/backgrounds/ directory:

cp /path/to/your/images/*.jpg static/backgrounds/

Supported formats: JPG, PNG, GIF, WebP

6. Run the Application

python app.py

Visit http://localhost:5000 in your browser.

Raspberry Pi Deployment

Auto-start Flask Application

Create a systemd service:

sudo nano /etc/systemd/system/calendar-display.service

Add the following content:

[Unit]
Description=Calendar Display Flask App
After=network.target

[Service]
User=pi
WorkingDirectory=/home/pi/Calender
ExecStart=/home/pi/Calender/venv/bin/python app.py
Restart=always
Environment="PATH=/home/pi/Calender/venv/bin"

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable calendar-display.service
sudo systemctl start calendar-display.service

Configure Chromium Kiosk Mode

Edit the autostart file:

mkdir -p ~/.config/lxsession/LXDE-pi
nano ~/.config/lxsession/LXDE-pi/autostart

Add these lines:

@xset s off
@xset -dpms
@xset s noblank
@chromium-browser --kiosk --noerrdialogs --disable-infobars --disable-session-crashed-bubble http://localhost:5000

Disable screensaver and cursor (optional):

sudo apt-get install unclutter
echo "@unclutter -idle 0" >> ~/.config/lxsession/LXDE-pi/autostart

Reboot

sudo reboot

The display should now start automatically on boot!

Configuration

Edit .env to customize:

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)

Project Structure

Calender/
├── app.py                      # Main Flask application
├── config.py                   # Configuration management
├── requirements.txt            # Python dependencies
├── .env                        # Environment variables (create from .env.example)
├── .env.example               # Environment template
├── static/
│   ├── css/style.css          # Styling
│   ├── js/app.js              # Frontend JavaScript
│   └── backgrounds/           # Background images directory
├── templates/
│   └── index.html             # Main display template
└── credentials/
    └── google_calendar_credentials.json  # Google API credentials

API Endpoints

GET / - Main display page
GET /api/weather - Weather data (cached for 15 min)
GET /api/calendar - Calendar events (cached for 5 min)
GET /api/background - Random background image
GET /api/joke - Dad joke (cached for 1 hour)

Troubleshooting

Weather not loading

Check your OpenWeatherMap API key is valid
Ensure you're not exceeding the free tier rate limits (60 calls/min)

Calendar not loading

Verify Google Calendar API credentials are set up correctly
Check the calendar ID is correct
Ensure the service account has access to the calendar

Display not starting on boot

Check systemd service status: sudo systemctl status calendar-display.service
View logs: sudo journalctl -u calendar-display.service -f

Background images not showing

Ensure images are in static/backgrounds/
Check file permissions: chmod 644 static/backgrounds/*

Contributing

Feel free to submit issues or pull requests!

License

MIT License - Feel free to use and modify for personal use.

Credits

Built with:

Flask - Web framework
OpenWeatherMap API - Weather data
Google Calendar API - Calendar integration
icanhazdadjoke - Dad jokes API