Pi Zero Yumovis Tasks Dashboard

This repository implements a real-time display for Yumovis tasks and local weather on an E-ink display. It shows upcoming tasks, their due dates, and priority levels.

Status: ✅ Working (Display loop active)

This implementation follows the Raspberry Pi Service Deployment Skill (see pi_lab/skill.md).

Features

• Yumovis Task Management: Shows upcoming tasks due within the next 7 days, with priority indicators and time-to-due countdowns.
• Overdue Task Alerts: Tasks marked as overdue are displayed prominently in red.
• 3-Day Weather Forecast: Displays daily high/low temps and weather conditions via wttr.in (for reference/comparison).
• E-ink Optimized: Designed for Waveshare E-ink displays with a rotation-based view system.

How It Works

The application fetches tasks from your self-hosted Yumovis instance using the Yumovis API. Tasks are filtered to show only those due within the next 7 days (or overdue). The display alternates between showing tasks and weather information every 60 seconds.

Hardware Requirements

• Raspberry Pi (Zero, 3, 4, or 5)
• Waveshare E-ink Display (e.g., 2.13 inch V4)

Software Requirements

• Yumovis instance running on your local network (see Yumovis GitHub)
• API token from Yumovis (see setup below)

Deployment Workflow

1. Repository Setup

git clone <your-repo-url>
cd pi_zero

2. Python Virtual Environment

# Create the virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2.5 Waveshare Library Setup

If you encounter "Error: Waveshare library not found", you must fetch the driver library from the official repository.

# Clone the repository (temporary)
git clone --depth 1 https://github.com/waveshareteam/e-Paper.git temp-e-paper

# Copy the lib folder to your project root
cp -r temp-e-paper/RaspberryPi_JetsonNano/python/lib ./lib

# Clean up
rm -rf temp-e-paper

3. Yumovis Setup & API Token

Step 1: Install Yumovis on your server

Follow the official Yumovis installation guide to set up Yumovis on your home server or NAS.

Step 2: Get your Yumovis API Token

1. Log in to your Yumovis instance in the browser
2. Go to Settings → Admin → API Access
3. Click Create New Token
4. Give it a name (e.g., "Pi Zero Display")
5. Copy the generated token - you'll need this!
6. Set appropriate scopes (e.g., tasks:read)

Step 3: Configure the Pi Zero

Edit app.py and update:

• YUMOVIS_URL: Your Yumovis server's IP address or URL (e.g., "http://192.168.1.100:3000")
• YUMOVIS_API_KEY: Paste the API token you just generated
• TARGET_USERS: List of user emails to filter tasks for (optional, if left empty shows all household tasks)
• MAX_TASKS_PER_VIEW: How many tasks to display at once (default: 5)

4. Systemd Service Configuration

Create the service file to manage the process:

sudo nano /etc/systemd/system/ctatracker.service

Paste the contents of the ctatracker.service file provided in this repo. Ensure the User and WorkingDirectory paths match your installation.

5. Deployment

sudo systemctl daemon-reload
sudo systemctl enable ctatracker.service
sudo systemctl start ctatracker.service

Configuration Options

Edit app.py to customize:

Parameter	Default	Description
LOOP_DELAY	60	Seconds between screen updates
YUMOVIS_URL	"http://..."	Your Yumovis server URL
YUMOVIS_API_KEY	"your_api_key_here"	Your API token (use env var in production)
TARGET_USERS	["[email protected]"]	User emails to filter tasks for
SHOW_DUE_SOON	True	Show tasks due within next 7 days
SHOW_OVERDUE	True	Show overdue tasks
MAX_TASKS_PER_VIEW	5	Tasks per screen view

Environment Variables (Recommended for Production)

Instead of hardcoding your API key in app.py, use environment variables:

# Add to your systemd service file or /etc/environment
export YUMOVIS_API_KEY="your_actual_api_token_here"

Then in app.py, the code will automatically use: os.getenv("YUMOVIS_API_KEY", "your_api_key_here")

Display Views

The display alternates between two views every 60 seconds:

Tasks View

• Shows up to 5 upcoming tasks
• Priority indicators:
  • 🔴 Red = Overdue or urgent (due within 30 minutes)
  • 🟠 Orange = Due within 1 hour
  • ⚪ Gray = Due later than 1 hour
• Time labels show countdown to due date (e.g., "2h", "3d", "OVERDUE")

Weather View

• 3-day forecast from wttr.in
• Shows high/low temperatures and weather conditions

Debugging & Troubleshooting

Check Logs

# View all logs for the service
journalctl -u ctatracker.service

# Follow logs in real-time
journalctl -u ctatracker.service -f

Common Issues

"Authentication failed": Check that your YUMOVIS_API_KEY is correct and has the right scopes.

"No tasks showing":

• Verify your Yumovis URL is correct
• Check if you have any tasks due within 7 days
• Try removing TARGET_USERS to see all household tasks

Display not updating: Check that the Pi Zero can reach your Yumovis server (ping YOUR_YUMOVIS_SERVER_IP).

Testing Without Systemd

Run the app directly to test:

source venv/bin/activate
python3 app.py

Press Ctrl+C to stop.

API Reference

The app uses the Yumovis REST API:

• Base URL: {YUMOVIS_URL}/api/v1/tasks
• Authentication: Bearer token in Authorization: Bearer {API_KEY} header
• Filtering: Optional query parameter ?user={email} to filter by user

Security Notes

• Never commit your API key to version control. Use environment variables instead.
• The Yumovis API token only needs tasks:read scope for this application.
• Keep your Yumovis server behind a firewall if possible.

Credits

• Yumovis: Self-hosted household management app - https://github.com/ulsklyc/yuvomi
• Waveshare E-Paper: Hardware library - https://github.com/waveshareteam/e-Paper
• wttr.in: Weather API

License

MIT License - see LICENSE file for details.