270 lines
9.2 KiB
Markdown
270 lines
9.2 KiB
Markdown
# ws4kp-linhanced
|
|
|
|
`ws4kp-linhanced` is a Linux-focused fork of [`netbymatt/ws4kp`](https://github.com/netbymatt/ws4kp) by `markmental`.
|
|
|
|
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
|
|
* 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
|
|
* SPC Outlook
|
|
|
|
## 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-retro`
|
|
* `oceanview`
|
|
* `slackware`
|
|
* `twc-linhanced`
|
|
|
|
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 <repourlgoeshere>
|
|
cd ws4kp-linhanced
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
Then open:
|
|
|
|
```text
|
|
http://localhost:8080/
|
|
```
|
|
|
|
## 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
|
|
* 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 and the fastfetch + LWN Linux News integration will not work when running the static build by itself.**
|
|
|
|
## 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 and original technology belong to The Weather Channel. This project is a fan-made, non-commercial recreation and reinterpretation.
|