Calender/README.md

# Family Calendar Display

A smart display application for Raspberry Pi that shows time, weather, calendar events, and rotating background images.

**Project created:** February 14, 2026

## 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
- 🖼️ **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

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

### 2. Install Dependencies

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

### 3. Configure Environment Variables

```bash
cp .env.example .env
```

Edit [.env](.env) and add your API keys:

```bash
# 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

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)
5. Download the credentials JSON file
6. Save it as [credentials/google_calendar_credentials.json](credentials/google_calendar_credentials.json)

### 5. Add Background Images

Place your images in the [static/backgrounds/](static/backgrounds/) directory:

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

Supported formats: JPG, PNG, GIF, WebP

### 6. Run the Application

```bash
python app.py
```

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

## Raspberry Pi Deployment

### Auto-start Flask Application

Create a systemd service:

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

Add the following content:

```ini
[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:

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

### Configure Chromium Kiosk Mode

Edit the autostart file:

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

Add these lines:

```bash
@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):

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

### Reboot

```bash
sudo reboot
```

The display should now start automatically on boot!

## Configuration

Edit [.env](.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/](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](https://flask.palletsprojects.com/) - Web framework
- [OpenWeatherMap API](https://openweathermap.org/api) - Weather data
- [Google Calendar API](https://developers.google.com/calendar) - Calendar integration
- [icanhazdadjoke](https://icanhazdadjoke.com/) - Dad jokes API