DeskClock

A fullscreen clock and weather kiosk app for the Raspberry Pi 3B (or any Linux system) with a 1024×600 touchscreen. Built with Python and pygame, running directly on the framebuffer via SDL2/kmsdrm — no X11 or Wayland needed.

curl -sSL https://raw.githubusercontent.com/frogswiper/deskclock/master/install.sh | bash

---

Screenshots

Clock Screen — Dark theme

Clock Screen — Light theme

Large time display with blinking colon, current date, temperature, humidity, wind speed, sunrise/sunset times, current weather icon and condition, city name, 5-day forecast strip, and a scrolling news ticker at the bottom.

Settings — General

Configure city, timezone, temperature units (°C/°F), clock format (12h/24h), night dimming, and theme (Dark / Light / Auto). A live weather API status indicator (green / orange / red dot) next to the city field shows whether the API key is working, data is stale, or an error occurred.

Settings — WiFi

Scan for networks, view signal strength and security, connect/disconnect — all via on-screen touch.

Settings — Hotspot (USB adapter selected)

When a USB WiFi adapter is detected, the hotspot runs on it — keeping the built-in wlan0 connected to your existing network.

Settings — Hotspot (active, with connected devices)

Shows gateway IP, DHCP range, and connected device MAC addresses with signal strength.

Settings — Hotspot (single adapter)

With only the built-in adapter, a warning indicates the client WiFi connection will pause while the hotspot is active.

Settings — Spotify

Enter your Spotify app credentials, then tap Connect — a QR code appears. Scan it on your phone, log in, accept the one-time certificate warning, and the Pi catches the callback automatically. Shows your connected account name with a green dot once authenticated.

Clock Screen — Spotify Now Playing

When something is playing on your Spotify account, a Now Playing widget appears in the right panel with track title, artist, and prev / play-pause / next controls. Tapping the buttons controls the active Spotify device on your account.

---

Features

• Clock — large bold time display (12h or 24h), blinking colon, full date
• Live weather — current temperature, humidity, wind speed, sunrise/sunset via OpenWeatherMap free API
• Weather icons — all drawn programmatically with pygame.draw (no image files); day/night-aware (e.g. 01n shows a crescent moon instead of a sun)
• 5-day forecast — daily high/low, weather icon, and rain probability
• Scrolling news ticker — BBC World News RSS headlines scroll across the bottom; uses time-delta movement for smooth scrolling at any framerate
• Theme switching — Dark, Light, and Auto (follows night/day hours) — switchable from settings
• Settings screen — touchscreen-friendly UI with on-screen QWERTY keyboard
• WiFi management — scan, connect, and disconnect from the touchscreen using wpa_cli
• Hotspot / Access Point — turn the Pi into a WPA2 WiFi AP via hostapd + dnsmasq; shows connected devices with signal strength
• Dual-adapter hotspot — automatically uses a USB WiFi adapter (wlan1) for the AP so the built-in wlan0 stays connected to your network
• Spotify integration — Now Playing widget on the clock screen (track, artist, prev/play-pause/next buttons); authenticate via QR code from your phone; controls the active Spotify device on your account
• Night dimming — configurable dimming overlay between set hours (default 23:00–07:00)
• Auto-start on boot — launches from TTY1 autologin, no desktop environment required

---

Bill of Materials

#	Component	Details	Price
1	7" IPS Touchscreen 1024×600	IPS LCD, capacitive touch, optional speakers, Raspberry Pi compatible	~€40
2	Raspberry Pi 3B	aarch64, BCM43438 WiFi/BT, 1 GB RAM	~€35
3	USB WiFi dongle (optional)	Any Linux-supported 802.11n USB adapter (wlan1) — enables hotspot while staying connected	~€5
4	MicroSD card	8 GB+ recommended	~€5
5	5V/2.5A USB-C or micro-USB PSU	Stable power supply recommended	~€8

Estimated total: ~€85 (without optional USB dongle)

Hardware

Component	Details
Board	Raspberry Pi 3B (aarch64)
OS	Ubuntu 25.10 (Questing Quokka)
Display	7" IPS 1024×600 capacitive touchscreen
Input	Touchscreen (evdev)
Optional	USB WiFi adapter for simultaneous hotspot + client

---

Dependencies

pip install pygame requests spotipy qrcode

pygame 2.6.1+ required for SDL2/kmsdrm support. requests is used for OpenWeatherMap API calls. spotipy and qrcode are required for Spotify integration (optional — the app runs without them). All other dependencies are Python stdlib.

---

Configuration

On first run, config.json is created in the app directory with these defaults:

Key	Default	Description
city	Oslo	City for weather lookup
timezone	Europe/Oslo	System timezone
api_key	—	OpenWeatherMap API key
units	metric	metric (°C) or imperial (°F)
clock_24h	false	24-hour clock format
theme	dark	dark, light, or auto
night_mode	true	Enable night dimming overlay
night_start	23	Hour dimming starts
night_end	7	Hour dimming ends
night_brightness	15	Brightness % during night (0–100)
hotspot_ssid	DeskClock	Default AP network name
hotspot_password	—	WPA2 password for the AP
hotspot_iface	auto	auto (prefer USB adapter) or specific interface name
spotify_client_id	—	Spotify app Client ID (from developer.spotify.com)
spotify_client_secret	—	Spotify app Client Secret

All settings can be changed from the on-screen settings menu (tap the gear icon, bottom-right).

---

Installation

One-click install

curl -sSL https://raw.githubusercontent.com/frogswiper/deskclock/master/install.sh | bash

The script will prompt for your city, timezone, and OpenWeatherMap API key, then handle everything automatically:

• Installs system packages (hostapd, dnsmasq, iw, fonts)
• Installs Python packages (pygame, requests)
• Clones the repo to ~/deskclock
• Writes config.json with your settings
• Configures passwordless sudo for WiFi, timezone, and hotspot management
• Adds your user to the video and input groups
• Sets up TTY1 autologin
• Adds the autostart block to ~/.profile

Reboot after the script finishes — DeskClock starts automatically on the display.

Hotspot: Runs on a USB WiFi adapter automatically if one is plugged in (keeps wlan0 connected). Without a USB adapter, the client connection pauses while the hotspot is active. Both hostapd and dnsmasq are installed by the script.

---

Architecture

main.py               — Entry point, SDL init, screen/event loop (15 FPS)
clock_screen.py       — Main display: clock, weather, forecast, news ticker, Spotify widget
settings_screen.py    — Settings UI: General + WiFi + Hotspot + Spotify tabs, on-screen keyboard
weather_service.py    — Background thread, OpenWeatherMap current + forecast
news_service.py       — Background thread, BBC World News RSS ticker
wifi_service.py       — wpa_cli wrapper: scan, connect, disconnect, status
config_manager.py     — JSON config persistence with defaults
theme.py              — Dark/Light/Auto colour palettes
hotspot_service.py    — WiFi AP lifecycle manager (wraps hotspot.sh)
hotspot.sh            — Shell script: hostapd + dnsmasq setup (runs via sudo)
icons.py              — All weather icons drawn with pygame.draw; day/night variants (moon, night-cloud)
keyboard.py           — On-screen QWERTY virtual keyboard (touch input)
spotify_service.py    — Spotify Web API integration: OAuth, playback polling, prev/play-pause/next

Hotspot adapter selection

hotspot_service.get_interfaces() enumerates /sys/class/net/wlan* via sysfs, checking whether each interface is USB-attached. best_hotspot_iface() auto-selects the first USB adapter found, falling back to wlan0. The selected interface is shown as a segmented button row in the Hotspot settings tab.

hotspot.sh accepts the interface name as a parameter for all commands (start, stop, status, clients), using per-interface PID files so multiple adapters can be tracked independently.

Display layout (1024×600)

+-------------------------+-------------------+
|  Time (large)           |  Weather icon     |
|  Date                   |  Description      |
|  Temp  Humidity  Wind   |  City, Country    |
|  Sunrise  Sunset        |  Feels / Wind     |
|                         +-------------------+
|                         |  ♪ Track title    |
|                         |  Artist           |
|                         |  [◄◄] [▐▐] [►►]  |
+-------------------------+-------------------+
|  Mon    Tue    Wed    Thu    Fri  (forecast) |
+---------------------------------------------+
|  Scrolling news ticker                 [gear] |
+---------------------------------------------+

The Spotify Now Playing widget appears in the lower-right of the clock screen only when something is actively playing. Tapping prev/play-pause/next controls the active Spotify device on your account.

---

SDL Notes (Ubuntu 25.10 arm64)

• fbcon is not available in SDL2 on Ubuntu 25.10 arm64 — use kmsdrm
• kmsdrm requires a real logind session — the TTY1 autologin approach provides this
• Setting SDL_VIDEODRIVER=kmsdrm must happen before pygame.init()