Implement calendar display application
Built a full-featured smart display app with Flask backend and responsive frontend. Features: - Real-time clock display - Weather integration (OpenWeatherMap API) for Hamilton, NZ - Google Calendar integration (placeholder, needs credentials) - Rotating background images from local directory - Dad jokes display (icanhazdadjoke API) Technical stack: - Backend: Python Flask with API endpoints - Frontend: HTML/CSS/JavaScript with auto-updating data - Caching system to avoid API rate limits - Responsive design for various screen sizes Deployment ready for Raspberry Pi with systemd service and Chromium kiosk mode setup instructions. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
225
README.md
225
README.md
@@ -1,3 +1,224 @@
|
||||
# Calender
|
||||
# Family Calendar Display
|
||||
|
||||
Project created: February 14, 2026
|
||||
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 5-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
|
||||
|
||||
Reference in New Issue
Block a user