Weather Now Dashboard

A custom, highly intelligent weather dashboard built specifically for the TRMNL e-ink display. It features dynamic forecasting summaries, intelligent array slicing for future time-blocks, and WMO weather-code text mapping.

The Problem (Why this architecture exists)

This project relies on the free tier of the Open-Meteo API. Open-Meteo tracks and rate-limits based on IP addresses. Running dynamic Javascript or a Liquid Webhook directly from TRMNL's shared German servers results in an immediate IP ban because Open-Meteo flags the datacenter IP as spam. This previously caused the TRMNL device to get permanently stuck or crash into a "Degraded State".

Architecture: The "Zero-Bloat, Zero-Ban" Strategy

To bypass the IP ban without paying for an Open-Meteo Developer API key, this dashboard uses a local Synology NAS as a hardware bridge:

1. Fetch: The Synology NAS wakes up every 15 minutes. It runs a Python script to fetch data from Open-Meteo using a residential home IP address, which is entirely immune to datacenter rate limits.
2. Build: The Python script injects the raw JSON data directly into a static HTML/JS template, generating a fully finalized, static index.html file locally.
3. Deploy: A bash script pushes this index.html file to GitHub Pages via SSH.
4. Zero-Bloat History: To prevent 35,000 automated commits a year from bloating the repository, the bash script uses git commit --amend and git push --force. This rewrites the exact same commit in perpetuity. The repository history will permanently remain at 1 commit.
5. Display: The TRMNL device uses the "Screenshot" plugin to photograph the static GitHub Pages URL. Because the HTML is pre-rendered, there is zero asynchronous loading time, and TRMNL captures a flawless image instantly.

File Directory & Server Paths

All files are stored on the Synology NAS at the following absolute path:
/var/services/homes/alex/scripts/weathernow/

• build.py: The Python generator. Uses standard libraries (urllib, json) to ensure it runs natively on Synology without requiring pip package installations.
• update.sh: The bash script triggered by the Synology Task Scheduler. Handles the Git force-pushing.
• index.html: The compiled, static webpage. (Auto-generated, do not edit manually).
• README.md: This documentation file.

Future Maintenance Requirements

This system is designed for extreme long-term stability. The theoretical maintenance points are:

1. SSH Deploy Key (Permanent): The NAS authenticates with GitHub using an ED25519 SSH Deploy Key. Unlike Personal Access Tokens (PATs), this key does not expire. No yearly rotation is required.
2. Synology DSM Major Updates: If you upgrade your Synology to a new major DSM version, ensure that Git Server and Python 3 remain installed and active in the Package Center.
3. Open-Meteo API Versioning: The script currently points to Open-Meteo v1. If Open-Meteo eventually deprecates v1 for v2, the URL string inside build.py will need to be manually updated.

Troubleshooting Guide

1. TRMNL Screen is stuck on old weather

• Diagnosis A (GitHub CDN Lag): GitHub Pages sits behind Fastly's global CDN. Occasionally, caching takes 1-3 minutes to clear. This is normal.
• Diagnosis B (Open-Meteo Outage): If Open-Meteo's API goes down, build.py is programmed to "fail silently." It leaves the previous index.html intact so your screen doesn't show a broken error, but the time will freeze. Visit https://api.open-meteo.com in a browser to check their status.
• Diagnosis C (Synology Network Drop): If your NAS temporarily lost internet access at the 15-minute mark, the push failed. It will retry automatically on the next 15-minute cycle.

2. Synology Task Scheduler is Failing

• Symptom: The weather hasn't updated in hours, Open-Meteo is online, and GitHub Pages is active.
• Fix: Open DSM Control Panel > Task Scheduler. Select the Weather task, click Action > View Result. Look at the script output.
• Common Error (Permission denied (publickey)): The Task Scheduler is likely running under a different user profile than the one that owns the SSH keys. Ensure the "User" in Task Scheduler exactly matches alex.

3. The Screen is Blank or Showing a 404 Error

• Symptom: TRMNL shows a generic error or a white screen.
• Fix: Visit the GitHub Pages URL (https://alexroddie.github.io/weathernow/index.html) on your smartphone.
  • If the browser shows a 404, the Synology NAS failed to push the file, or GitHub Pages was accidentally disabled in the repository settings.
  • If the browser shows the dashboard perfectly, TRMNL's Screenshot bot is experiencing a temporary timeout. Reboot the TRMNL device via their web interface.

Replication Guide: Full System Setup

If this system ever needs to be rebuilt from scratch, follow these exact steps to recreate the architecture.

Phase 1: Synology Preparation

The NAS must be configured to allow developer tools and SSH connections.

1. Install Packages: Open Synology Package Center. Install Git Server and Text Editor.
2. Enable User Home: Open Control Panel > User & Group > Advanced. Scroll down and check Enable user home service. (Crucial: This creates the hidden ~/.ssh directory needed for security keys).
3. Enable SSH: Open Control Panel > Terminal & SNMP. Check Enable SSH service (Port 22).

Phase 2: GitHub Repository Setup

1. Log into GitHub and create a New Repository.
2. Name it exactly: weathernow.
3. Set it to Public.
4. ⚠️ CRITICAL: Do NOT check "Add a README file". Leave the repository entirely blank. Click Create repository.

Phase 3: File Creation (Synology Web Interface)

Using the Synology File Station ensures file encoding remains pure.

1. Open File Station. Navigate to your home folder.
2. Create a folder named scripts. Inside scripts, create a folder named weathernow.
   Your absolute working path is now: /var/services/homes/alex/scripts/weathernow/
3. Create the Python Script (build.py) and paste the generator code. (Ensure the save path at the bottom of the python script strictly points to the absolute path above).
4. Create the Bash Script (update.sh) and paste the following:

#!/bin/bash
cd /var/services/homes/alex/scripts/weathernow/
python3 build.py
git add index.html README.md Readme.html
git commit --amend --no-edit --allow-empty
git push origin main --force

Phase 4: SSH Key Generation & Permissions

Your NAS must generate a secure key to push to GitHub without passwords.

1. Open your Mac Terminal. SSH into the NAS:

   ssh alex@[your_nas_ip]

2. Generate the key:

   ssh-keygen -t ed25519 -C "synology_weather"

   (Press Enter three times to accept defaults and skip passphrases).
3. Fix Permissions: SSH requires strict ownership of private keys. Run these two commands to lock the folder down:

   chmod 700 ~/.ssh
   chmod 600 ~/.ssh/id_ed25519

4. Copy the Public Key:

   cat ~/.ssh/id_ed25519.pub

5. Add to GitHub: Copy the output. Go to your weathernow repository on GitHub > Settings > Deploy keys > Add deploy key. Title it Synology NAS, paste the key, check Allow write access, and click Add.

Phase 5: Git Initialization & First Push

You must manually establish the Git connection for the first time. In your Mac Terminal, run these commands line by line:

cd /var/services/homes/alex/scripts/weathernow/

# Generate the initial index.html
python3 build.py

# Configure local Git identity
git config --global user.name "Synology Updater"
git config --global user.email "bot@local"

# Initialize repository
git init
git remote add origin git@github.com:alexroddie/weathernow.git

# Track files
git add index.html README.md Readme.html

# Create the master commit
git commit -m "Initial commit with docs"
git branch -M main

# Push to GitHub
git push -u origin main

⚠️ The Fingerprint Prompt: During the push, SSH will ask: Are you sure you want to continue connecting? You must type out the full word yes and hit Enter. Do not just hit Enter or type 'y', or the connection will abort.

Phase 6: GitHub Pages & Automation

1. Activate GitHub Pages: Go to the weathernow repository on GitHub > Settings > Pages. Set Source to Deploy from a branch, select main, leave folder as / (root), and click Save.
   (URL becomes: https://alexroddie.github.io/weathernow/index.html)
2. Synology Automation: Open Synology Control Panel > Task Scheduler.
   • Create a User-defined script.
   • General: Name it WeatherNow Updater. Set User to alex.
   • Schedule: Daily, Every 15 minutes.
   • Task Settings: Paste: bash /var/services/homes/alex/scripts/weathernow/update.sh
3. TRMNL Setup: Point the TRMNL Screenshot plugin to the GitHub Pages URL with a 15-minute refresh rate.