leosongyyy/zectrix-friday-weather

Pantalla de tinta electrónica «¿Hoy es viernes?» + Clima

Renderiza una página divertida para la pantalla de tinta electrónica monocromática Zectrix 400×300. La idea proviene del proyecto de código abierto eyaeya/today-is-friday (MIT). Esta habilidad la rediseña para pantallas monocromáticas en blanco y negro, y le añade el clima local.

Ver assets/preview.png para ver el resultado:

• Parte superior: izquierda «¿Hoy es viernes?», derecha la ubicación del usuario (ej. «Chengdu·Chenghua District»)
• Columna izquierda: saludo + dos líneas de frases divertidas, cambiando según el día de la semana y el periodo horario, con un sistema de baraja para evitar repeticiones en una misma ronda
• Columna derecha: icono grande del clima + temperatura grande + estado + nivel de rayos UV + HI/LO
• Parte inferior: pronóstico de tres días (hoy/mañana/pasado mañana) + una recomendación de vestimenta generada según el clima real (llevar paraguas si llueve, protección solar si hace calor, abrigarse si hace frío, alerta de温差, protector solar si hay UV)

Reglas de periodo horario y combinación de colores (según la lógica del proyecto original):

Hora	Saludo	Color
Lunes–Jueves	No.	Fondo blanco, texto negro
Viernes antes de las 16:00	¡Es viernes!	Fondo negro, texto blanco
Viernes después de las 16:00	¡Es viernes! + sello «退朝» en esquina superior derecha	Fondo negro, texto blanco
Sábado, Domingo antes de las 19:00	Descanso.	Fondo negro, texto blanco
Domingo después de las 19:00	Mañana es lunes.	Fondo blanco, texto negro

El grupo de frases tiene 9 conjuntos (lunes–jueves / viernes día / viernes noche / sábado / domingo día / domingo noche), cada uno con 65 frases, almacenadas en scripts/friday_phrases.json. Puedes añadir más frases directamente editando el archivo.

1. Primer uso: inicialización obligatoria (sin secretos, sin claves integradas)

Esta habilidad no contiene ninguna API Key, ID de dispositivo ni coordenadas. Todo debe ser proporcionado por el usuario. Debes inicializarla antes del primer uso.

cd ~/.workbuddy/skills/zectrix-friday-weather/scripts
python3 init.py            # Guía interactiva, recomendado
# O no interactivo:
python3 init.py --api-key zt_xxx --device AA:BB:CC:DD:EE:FF --place "Chengdu Chenghua District" --label "Chengdu·Chenghua District"

Necesitas recopilar tres datos del usuario, todos son obligatorios (no adivines, no uses valores de ejemplo):

1. Clave API de Zectrix: El usuario la obtiene desde la consola de Jiquyun, comienza con zt_. Si no está seguro, ejecuta primero python3 init.py --api-key zt_xxx --list-devices para ver si puede listar dispositivos.
2. ID del dispositivo: La dirección MAC del dispositivo, con formato AA:BB:CC:DD:EE:FF; se puede obtener de la salida del comando anterior.
3. Ubicación: Nombre de lugar en chino, ej. «Chengdu Chenghua District», «Shanghai Xuhui», «Shenzhen Nanshan». El script llamará al servicio de geocodificación de Open-Meteo para convertirlo en coordenadas; si hay múltiples candidatos, se selecciona interactivamente; en entorno no interactivo, se toma el primero.

La inicialización verifica que la clave coincida con el dispositivo (si no, muestra advertencia y sale; si hay problemas de identificación, se puede añadir --no-verify), luego escribe en ~/.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"}
}

La configuración y el estado se almacenan en ~/.config/zectrix-friday-weather/ (se puede sobrescribir con la variable de entorno ZECTRIX_FRIDAY_CONFIG_DIR), no dentro del directorio de la habilidad, por lo que la habilidad se puede compartir y actualizar de forma segura sin exponer claves.

2. Uso diario

cd ~/.workbuddy/skills/zectrix-friday-weather/scripts
ZECTRIX_NO_PUSH=1 python3 zectrix_friday_push.py   # Solo renderizar vista previa, genera imagen en /tmp/zectrix_friday_screen.png
python3 zectrix_friday_push.py                     # Renderizar y enviar a la pantalla de tinta electrónica

Si no se ha inicializado, el script imprimirá NEED_INIT: y terminará con código de salida 2; en ese caso, guía al usuario para que complete la configuración como se indica en la sección anterior, sin inventar claves.

3. Experiencia de renderizado y maquetación (obligatorio al modificar el estilo)

• Renderizado nativo 400×300, relación 1:1, no amplíes y luego reduzcas; umbral de binarización THRESHOLD=128, dither=false al enviar (umbral duro, texto más nítido)
• Fuente: Por defecto se usa la fuente de mapa de bits assets/fonts/Zfull.ttf incluida en el repositorio (8-24px, nítida a nivel de píxel, muy recomendada para tinta electrónica; clonar el repositorio ya la activa, no necesita instalación adicional). Se puede sobrescribir con $ZECTRIX_FONT=/path/to/xxx.ttf, y luego se recurre a PingFang / Heiti / Noto CJK del sistema
• Iconos: draw_icon() se dibuja dos veces (primero el color de borde expandido, luego el color de fondo de relleno) para obtener un contorno grueso sin líneas internas; las nubes pueden ocultar naturalmente el sol detrás. Los símbolos multibyte como ▲▼ pueden faltar en la fuente de mapa de bits a tamaños pequeños, así que se dibujan con código
• El texto siempre en peso normal, sin negrita ni contorno (el negrita en una pantalla de 1 bit se vuelve borroso)
• Icono y temperatura de la columna derecha centrados como conjunto: primero se mide el ancho real de la temperatura con d.textlength(), luego se calcula el punto de inicio tomando como referencia la línea central de la columna derecha. El brillo del icono de sol se expande, por lo que el ancho de la posición debe ampliarse por separado
• Rotación del sello: usar fillcolor=255 para evitar esquinas negras; en escenarios de inversión de color, el sello debe pegarse con img.paste(tcol, box, mask) según el color del marco

4. Envío programado

El dispositivo se actualiza mediante extracción (pull), la API devuelve code:0 si es exitoso, y la pantalla se actualizará en el próximo sondeo. Las frases cambian según el periodo horario; se recomienda configurar una automatización para enviar una vez al día a las 10:00. Para que después de las 19:00 del domingo muestre «Mañana es lunes.» y después de las 16:00 del viernes aparezca el sello «退朝», es necesario añadir otro envío a las 19:00.

5. Descripción de archivos

Archivo	Descripción
scripts/init.py	Asistente de inicialización: recopila clave/dispositivo/ubicación, geocodificación, escribe configuración
scripts/zectrix_friday_push.py	Script principal de renderizado + envío
scripts/dev_render_sample.py	Genera imágenes de ejemplo para documentación (especifica día de semana/periodo/clima, sin envío)
scripts/friday_phrases.json	9 conjuntos × 65 frases, se puede editar directamente para ampliar
assets/fonts/Zfull.ttf	Fuente de mapa de bits incluida (fuente de renderizado por defecto, distribuida con el repositorio)
assets/preview.png	Imagen de vista previa
assets/sample-friday.png	Ejemplo de viernes por la tarde (fondo negro, texto blanco + sello «退朝»)

Los datos meteorológicos provienen de Open-Meteo (gratuito, sin necesidad de clave de registro), el índice UV se toma del uv_index_max del día.