leosongyyy/zectrix-friday-weather

E-paper 'Is it Friday today?' + Weather Page

Renders a fun page for Zectrix 400×300 monochrome e-paper, inspired by the open-source project eyaeya/today-is-friday (MIT). This skill re-layouts for black-and-white screens and overlays local weather.

See assets/preview.png for effect:

• Top: Left shows 'Is it Friday today?', right shows the user's area (e.g., 'Chengdu·Chenghua')
• Left column: Opening line + two rows of fun phrases, switching pools by weekday/timeslot, shuffling and drawing without repeats within a round
• Right column: Large weather icon + large temperature + condition + UV index + HI/LO
• Bottom: 3-day forecast boxes + a dressing suggestion based on real weather (umbrella for rain, sunscreen for heat, extra layers for cold, temperature difference alerts, UV sunscreen reminder)

Time and color scheme rules (same as the original project logic):

Time	Opening line	Color scheme
Monday–Thursday	Not today.	White background, black text
Before 16:00 Friday	It's Friday!	Black background, white text
After 16:00 Friday	It's Friday! + 'Retreat' seal top right	Black background, white text
Saturday–Sunday before 19:00	Rest.	Black background, white text
After 19:00 Sunday	Tomorrow is Monday.	White background, black text

Phrase pools: 9 (Mon–Thu / Fri daytime / Fri evening / Sat / Sun daytime / Sun evening), 65 phrases each, stored in scripts/friday_phrases.json, editable to add phrases.

1. First use: Must initialize (no built-in secrets)

This skill contains no API keys, device IDs, or coordinates – all must be provided by the user. Must initialize before first run.

cd ~/.workbuddy/skills/zectrix-friday-weather/scripts
python3 init.py            # interactive wizard, recommended
# or non-interactive:
python3 init.py --api-key zt_xxx --device AA:BB:CC:DD:EE:FF --place "Chengdu Chenghua" --label "Chengdu·Chenghua"

Requires three pieces from the user (all mandatory; do not guess or use example values):

1. Zectrix API Key: Obtain from the Jiquyun console, starts with zt_. Unsure? Run python3 init.py --api-key zt_xxx --list-devices to check if it lists devices.
2. Device ID: Device MAC, like AA:BB:CC:DD:EE:FF; can be taken from the output of the above command.
3. Location: Chinese place name, e.g., 'Chengdu Chenghua', 'Shanghai Xuhui', 'Shenzhen Nanshan'. The script calls Open-Meteo geocoding service to resolve to lat/lon; interactive selection if multiple candidates, non-interactive picks the first.

Initialization checks if the Key matches the device (warns and exits on mismatch; add --no-verify if you're sure about identification), then writes to ~/.config/zectrix-friday-weather/config.json:

{
  "api_key": "zt_xxx",
  "device_id": "AA:BB:CC:DD:EE:FF",
  "page": "5",
  "location": {"label": "XX·XX District", "lat": 30.0000, "lon": 104.0000, "timezone": "Asia/Shanghai"}
}

Configs and state are in ~/.config/zectrix-friday-weather/ (can be overridden by env var ZECTRIX_FRIDAY_CONFIG_DIR), not inside the skill directory, so the skill can be safely shared/updated without exposing secrets.

2. Daily use

cd ~/.workbuddy/skills/zectrix-friday-weather/scripts
ZECTRIX_NO_PUSH=1 python3 zectrix_friday_push.py   # render preview only, outputs /tmp/zectrix_friday_screen.png
python3 zectrix_friday_push.py                     # render and push to e-paper

If not initialized, the script prints NEED_INIT: and exits with code 2 – then guide the user to complete config as per the previous section, do not fabricate keys.

3. Rendering and layout tips (must follow when modifying styles)

• Render natively at 400×300, 1:1, do not enlarge then shrink. Binarization threshold THRESHOLD=128, dither=false for push (hard threshold for sharpest text)
• Font: Default uses the repo's included assets/fonts/Zfull.ttf bitmap font (8-24px pixel-perfect sharp, best for e-paper, clone and it works; no extra install). Override with $ZECTRIX_FONT=/path/to/xxx.ttf, fallback to system PingFang / Heiti / Noto CJK
• Icons: draw_icon() draws twice (outline color first, then fill background color) to get thick outlines without inner lines; clouds naturally hide the sun behind. Multi-byte symbols like ▲▼ may be missing glyphs at small sizes in bitmap fonts, always draw with code
• All text uses default weight, no bold or outline (bold will blur into a mess on 1-bit screen)
• Right column icon+temperature centered as a block: First measure temperature width with d.textlength(), then calculate combined start point based on the right column's midline; sun's rays extend outward, so allocate extra width
• Seal rotation uses fillcolor=255 to avoid black corners; for inverted-color scenes, use img.paste(tcol, box, mask) to paste based on frame color

4. Scheduled push

Device uses pull refresh; API returns code:0 on success, the screen updates on next poll. Phrases change by time period. Recommended to set automation for daily push at 10:00; to show 'Tomorrow is Monday.' after Sunday 19:00 and 'Retreat' seal after Friday 16:00, add another push at 19:00.

5. File description

File	Description
scripts/init.py	Initialization wizard: collect key/device/location, geocode, write config
scripts/zectrix_friday_push.py	Render + push main script
scripts/dev_render_sample.py	Generate sample images for docs (specify weekday/time/weather, no push)
scripts/friday_phrases.json	9×65 phrase pool, editable directly
assets/fonts/Zfull.ttf	Built-in bitmap font (default render font, distributed with repo)
assets/preview.png	Preview image
assets/sample-friday.png	Friday evening sample (inverted colors + 'Retreat' seal)

Weather data from Open-Meteo (free, no registration required). UV index used is the day's uv_index_max.