# ws4kp-linhanced `ws4kp-linhanced` is a Linux-focused fork of [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) by `markmental`. Current release: `v0.2.1` It keeps the stronger, more stable foundation of the original `ws4kp` project while selectively incorporating international weather support and global map ideas from [`mwood77/ws4kp-international`](https://github.com/mwood77/ws4kp-international). The goal is not to become a kitchen-sink weather platform. The goal is a leaner, maintainable, Linux-oriented WeatherStar fork with a clear identity. This fork also explicitly embraces Slackware Linux / `weatherstar4k` branding as part of its mission. Broad platform neutrality is not a design goal here. ## What This Fork Is `ws4kp-linhanced` is a retro weather display project that preserves the classic WeatherStar-style feel while updating the data sources and map stack for modern use. This fork is built around a few priorities: * keep the classic WeatherStar presentation and pacing intact where practical * support international locations without dragging in unnecessary feature creep * prefer a stable, understandable codebase over maximum feature count * lean into Linux-oriented branding and integrations where they add character and usefulness It is not intended to be a perfect hardware emulation of the original WeatherStar 4000. If you want a project aimed more directly at hardware-faithful behavior, see the [WS4000 Simulator](http://www.taiganet.com/). ## Why This Fork Exists This fork exists because the original `ws4kp` codebase provided the best overall base to keep working from, but it remained too tightly tied to US-only weather sources. At the same time, `ws4kp-international` proved that Open-Meteo and global map support were viable, but it grew in directions that felt heavier and harder to maintain. This fork sits in the middle on purpose: * more international than upstream `ws4kp` * leaner and narrower in scope than `ws4kp-international` * more explicitly Linux-focused than either ## Fork Lineage This project builds on the work of: * [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) for the core WeatherStar implementation and overall application structure * [`mwood77/ws4kp-international`](https://github.com/mwood77/ws4kp-international) for Open-Meteo international weather direction and some global-map concepts This fork intentionally diverges from `ws4kp-international`. It selectively adapts the parts that fit this project and leaves behind the parts that would make the codebase harder to keep stable. ## Current Features Major features currently in this fork: * Open-Meteo-based international weather for the core forecast screens * ArcGIS-powered international location search and reverse geocoding * global RainViewer radar on a cached world basemap * global `Regional Observations` and nearby-city displays backed by expanded worldwide city coverage * `Latest Observations` screen for nearby city temperatures, conditions, and wind * `Hazard List` screen with MySQL-backed server history for encountered NOAA and derived hazards * `Ground View` screen powered by nearby Windy webcams (requires API key, see below) * Travel Forecast rebuilt around region buckets with a global fallback * optional screen-specific audio playback for supported displays * wind/gust-based condition inference for better condition names and icon matches when upstream data is too generic * live theme switching with auto-discovered theme folders * Server Observations powered by [fastfetch](https://github.com/fastfetch-cli/fastfetch) * server-side caching proxy for Open-Meteo, RainViewer metadata, and ArcGIS basemap tiles * static-build path fixes for subdirectory deployment Some NOAA-only products are still retained where they remain useful and there is no replacement yet: * Hazards (US only) * SPC Outlook (US only) For locations outside the US, a derived alert system provides best-effort hazard warnings based on available meteorological data when official NOAA products do not apply. ## Themes `ws4kp-linhanced` supports live asset theme swapping from the main page. Themes are discovered automatically from the `themes/` directory and can be changed from the `Theme` selector under the `More information` link without reloading the page. Current themes include: * `Default` * `azazel` * `debian` * `linhanced` * `linhanced-aero` * `linhanced-retro` * `oceanview` * `slackware` * `twc-linhanced` * `twc-aero` * `twc-classic` * `twc-stockholm` Currently supported themed assets include: These filenames represent the standard override set used by the built-in themes. * `logo-corner.png` * `1.png` * `1-chart.png` * `2.png` * `3.png` * `4.png` * `5.png` * `6.png` Additional themes can be added by creating a subdirectory under `themes/` with matching override filenames. ## Quick Start Ensure you have Node installed. ```bash git clone cd ws4kp-linhanced npm install npm start ``` Then open: ```text http://localhost:8080/ ``` ## API Keys ### Windy Webcams (Ground View) The `Ground View` screen requires a Windy Webcams API key. Create a file named `windy-api-key.txt` in the project root and paste your API key as plain text. If this file is missing, the `Ground View` screen will not work. You can obtain a free API key from [Windy Webcams API](https://api.windy.com/webcams). ## MySQL `Hazard List` is now backed by MySQL in server mode. The UI only shows the latest 7 hazards, but the database retains full history. Set these environment variables before starting the app: ```text WS4KP_MYSQL_HOST=127.0.0.1 WS4KP_MYSQL_PORT=3306 WS4KP_MYSQL_SOCKET_PATH=/var/run/mysql/mysql.sock WS4KP_MYSQL_USER=root WS4KP_MYSQL_PASSWORD=your-password WS4KP_MYSQL_DATABASE=ws4kp_linhanced ``` If your local MariaDB/MySQL instance is socket-only, set `WS4KP_MYSQL_SOCKET_PATH` and omit `WS4KP_MYSQL_HOST` / `WS4KP_MYSQL_PORT`. Create the required table: ```sql CREATE TABLE hazard_history ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, location_label VARCHAR(255) NOT NULL, location_key VARCHAR(128) NOT NULL, hazard_type VARCHAR(128) NOT NULL, source VARCHAR(64) NOT NULL, severity VARCHAR(64) DEFAULT NULL, latest_hazard_id VARCHAR(255) DEFAULT NULL, encountered_at DATETIME NOT NULL, last_seen_at DATETIME NOT NULL, ongoing TINYINT(1) NOT NULL DEFAULT 1, created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uq_logical_hazard (location_key, hazard_type, source), KEY idx_last_seen_at (last_seen_at), KEY idx_location_key (location_key), KEY idx_ongoing (ongoing) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; ``` The database retains full hazard history. The `Hazard List` UI shows only the latest 7 entries and only the most recent row per stored location. Nearby same-label locations are reconciled during updates to reduce duplicate location spam. In the current browser session, `Hazard List` updates immediately after new hazard history is synced. ## Running Modes This fork supports two main runtime styles. ### Server Mode Recommended for normal use. ```bash npm start ``` This mode includes: * Express server entry point * proxying and caching for weather/map requests * Fastfetch-backed Server Observations * MySQL-backed Hazard List history * automatic ongoing-hazard rechecks every 10 minutes for both NOAA and derived hazards * better shared performance when multiple clients use the same instance ### Static Mode Useful if you want to serve the built files directly. ```bash npm run build STATIC=1 DIST=1 npm start ``` Or upload the generated `dist/` directory to your web server after running: ```bash npm run build ``` The static build has been adjusted so frontend-generated paths no longer assume deployment at `/`, which makes subdirectory hosting more practical. **Also, features that require a backend server like the on-disk cache, Fastfetch-backed Server Observations, LWN Linux News, `Ground View`, and `Hazard List` will not work when running the static build by itself.** The public hosted instance at [https://mentalnet.xyz/ws4kp-linhanced-demo/](https://mentalnet.xyz/ws4kp-linhanced-demo/) now runs the full server-backed version, so backend-dependent screens like `Linux News`, `Server Observations`, `Ground View`, and `Hazard List` are expected to work there. ## International Support Core forecast functionality works internationally. That currently includes: * Current Conditions * Latest Observations * Hourly Forecast * Hourly Graph * Local Forecast * Extended Forecast * Almanac * Travel Forecast * Local Radar * Regional Observations Legacy NOAA-only screens still remain US-specific where applicable. ## Settings And Customization Important settings and customization features include: * playback speed * widescreen mode * kiosk mode * scan lines * US vs metric units * theme selection * optional screen audio toggle * custom bottom scroll text * display enable/disable checkboxes ### Permalinks Display selections, location, and major settings can be shared or bookmarked through the built-in permalink feature. ### Kiosk Mode Kiosk mode hides the surrounding controls and maximizes the display area for dedicated setups. It can be triggered from the UI or via permalink parameters. ### Custom Scroll Text The bottom text crawl can be customized using the built-in custom text setting. Multiple messages can be separated with `|` to rotate randomly. Example: ```text Welcome to Weatherstar|Thanks for watching ``` ### Custom Hook A customization hook is available as: ```text server/scripts/custom.js ``` A sample file exists at: ```text server/scripts/custom.sample.js ``` ## Audio The original WeatherStar atmosphere depended heavily on background music. This repo includes a small set of WeatherStar-inspired tracks, while keeping the total size manageable. If you want to use your own music, place `.mp3` files in: ```text server/music/ ``` The application will build or serve a playlist from those files depending on the runtime mode. Alert and screen-specific audio clips live in: ```text server/alert/ ``` `tone.mp3` is used for alert playback, and supported displays can also use matching screen-specific audio clips from the same directory. Screen audio is optional and can be disabled from the Settings UI. ## Build And Maintenance Notes This fork tries to stay practical not only at runtime, but also in how it is maintained. That includes: * keeping the codebase relatively small and understandable * avoiding unnecessary build complexity where possible * trimming or replacing dependencies when the benefit is low * addressing build-step vulnerabilities instead of ignoring them Recent cleanup includes removing vulnerable build-only sourcemap tooling from the main build pipeline. ## Motivation Part of the motivation is simple nostalgia: old Weather Channel presentation still has a very distinct charm. The other part is more practical. A Linux-friendly, self-hostable retro weather display is still a fun and useful thing to have around, especially when it stays light enough to keep hacking on without turning into an enormous platform project. ## Acknowledgements This project builds on earlier work from the WeatherStar community and related forks. Credits and thanks go to: * [Mike Battaglia](https://github.com/vbguyny/ws4kp) for the original project lineage * [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) for the upstream base this fork was built from * [`mwood77/ws4kp-international`](https://github.com/mwood77/ws4kp-international) for proving out the Open-Meteo international direction * [TWCClassics](https://twcclassics.com/) for WeatherStar reference material, fonts, and icon resources * the broader WeatherStar community for reference material and ongoing experimentation ## Disclaimer This project should **not** be relied upon in life-threatening weather situations or as a mission-critical public weather information source. Internet services fail, upstream data can be delayed, and browser-based applications are not a substitute for dedicated alerting systems. The WeatherSTAR 4000 name, Weather Channel logo and original technology belong to The Weather Channel. This project is a fan-made, non-commercial recreation and reinterpretation and is not affiliated with or run by the Weather Channel.