WeatherStar 4000+

A live version of this project is available at https://weatherstar.netbymatt.com

About

This project aims to bring back the feel of the 90s with a weather forecast that has the look and feel of The Weather Channel at that time but available in a modern way. This is by no means intended to be a perfect emulation of the WeatherStar 4000, the hardware that produced those wonderful blue and orange graphics you saw during the local forecast on The Weather Channel. If you would like a much more accurate project please see the WS4000 Simulator. Instead, this project intends to create a simple to use interface with minimal configuration fuss. Some changes have been made to the screens available because either more or less forecast information is available today than was in the 90s. Most of these changes are captured in sections below.

What's your motivation

Nostalgia. And I enjoy following the weather, especially severe storms.

It's also a creative outlet for me and keeps my programming skills honed for when I need them for my day job.

Included technology

I've kept this open source, well commented, and made it as library-free as possible to help others interested in programming be able to jump right in and start working with the code.

From a learning standpoint, this codebase make use of a lot of different methods and technologies common on the internet including:

• The https://api.weather.gov REST API. (documentation).
• ES 6 functionality
  • Arrow functions
  • Promises
  • Async/await and parallel loading of all forecast resources
  • Classes and extensions
  • Javascript modules
• Separation between API code and user interface code
• Use of a modern date parsing library luxon
• Practical API rates and static asset caching
• Very straight-forward hand written HTML
• Build system integration (Gulp, Webpack) to reduce the number of scripts that need to be loaded
• Hand written CSS made easier to mange with SASS
• A linting library to keep code style consistent

Quick Start

Ensure you have Node installed.

git clone https://github.com/netbymatt/ws4kp.git
cd ws4kp
npm install
npm start

Open your browser and navigate to https://localhost:8080

Does WeatherStar 4000+ work outside of the USA?

This project is tightly coupled to NOAA's Weather API, which is exclusive to the United States. Using NOAA's Weather API is a crucial requirement to provide an authentic WeatherStar 4000+ experience.

If you would like to display weather information for international locations (outside of the USA), please checkout a fork of this project created by @mwood77: - ws4kp-international

Deployment Modes

WeatherStar 4000+ supports two deployment modes:

Server Deployment (Recommended)

• Includes Node.js server with caching proxy for better performance (especially when running on a local server for multiple clients)
• Server-side request deduplication and caching
• Weather API observability and logging
• Used by: npm start, DIST=1 npm start, and Dockerfile.server

Static Deployment

• Pure client-side deployment using nginx to serve static files
• All API requests are made directly from each browser to the weather services
• Browser-based caching
• Used by: static file hosting and default Dockerfile

Other methods to run Ws4kp

Development Mode (individual JS files, easier debugging)

npm start

Development Mode without proxy caching

STATIC=1 npm start

Production Mode (minified/concatenated JS, faster loading)

npm run build
DIST=1 npm start

Production Mode without proxy caching (simulates static Docker deployment)

npm run build
STATIC=1 DIST=1 npm start

For all modes, access WeatherStar by going to: http://localhost:8080/

Key Differences

Development Mode (npm start): - Uses individual JavaScript module files served directly - Easier debugging with source maps and readable code - Slower initial load (many HTTP requests for individual files) - Live file watching and faster development iteration

Production Mode (DIST=1 npm start): - Uses minified and concatenated JavaScript bundles - Faster initial load (fewer HTTP requests, smaller file sizes) - Optimized for performance with multiple clients - Requires npm run build to generate optimized files

Docker Deployments

To run via Docker using a "static deployment" where everything happens in the browser (no server component, like STATIC=1):

docker run -p 8080:8080 ghcr.io/netbymatt/ws4kp

To run via Docker using a "server deployment" with a caching proxy server for multi-client performance and enhanced observability (like npm run build; DIST=1 npm start):

docker build -f Dockerfile.server -t ws4kp-server .
docker run -p 8080:8080 ws4kp-server

To run via Docker Compose (shown here in static deployment mode):

---
services:
  ws4kp:
    image: ghcr.io/netbymatt/ws4kp
    container_name: ws4kp
    environment:
      # Each argument in the permalink URL can become an environment variable on the Docker host by adding WSQS_
      # Following the "Sharing a Permalink" example below, here are a few environment variables defined. Visit that section for a
      # more complete list of configuration options.
      - WSQS_latLonQuery=Orlando International Airport Orlando FL USA
      - WSQS_hazards=false
      - WSQS_current_weather=true
    ports:
      - 8080:8080 # change the first 8080 to meet your local network needs
    restart: unless-stopped

Serving a static app

There are several ways to deploy WeatherStar as a static app that runs entirely in the browser:

Manual static hosting (Apache, nginx, CDN, etc.): Build static distribution files for upload to any web server:

npm run build

The resulting files in /dist can be uploaded to any web server; no server-side scripting is required.

Docker static deployment: The default Docker image uses nginx to serve pre-built static files:

docker run -p 8080:8080 ghcr.io/netbymatt/ws4kp

Node.js in static mode: Use the Node.js server as a static file host without the caching proxy:

STATIC=1 npm start          # Use Express to serve development files
STATIC=1 DIST=1 npm start   # Use Express to serve (minimized) production files

What's different

I've made several changes to this Weather Star 4000 simulation compared to the original hardware unit and the code that this was forked from.

• Radar displays the timestamp of the image.
• A new hour-by-hour graph of the temperature, cloud cover and precipitation chances for the next 36 hours.
• A new hourly forecast display for the next 24 hours is available, and is shown in the style of the travel cities forecast. (off by default because it duplicates the hourly graph)
• The SPC Outlook is shown in the style of the old air quality screen. This shows the probability of severe weather over the next 3 days at your location. SPC outlook only displays if you're within one of the highlight areas over the next 3 day. You can view the maps and pick a location within one of the risk categories to see if the screen is working for you.
• The "Local Forecast" and "Extended Forecast" provide several additional days of information compared to the original format in the 90s.
• The original music has been replaced. More info in Music.
• Marine forecast (tides) is not available as it is not reliably part of the new API.
• "Flavors" are not present in this simulation. Flavors refer to the order of the weather information that was shown on the original units. Instead, the order of the displays has been fixed and a checkboxes can be used to turn on and off individual displays. The travel forecast has been defaulted to off so only local information shows for new users.

Sharing a permalink (bookmarking)

Selected displays, the forecast city and widescreen setting are sticky from one session to the next. However if you would like to share your exact configuration or bookmark it, click the "Copy Permalink" (or get "Get Permalink") near the bottom of the page. A URL will be copied to your clipboard with all of you selected displays and location (or copy it from the page if your browser doesn't support clipboard transfers directly). You can then share this link or add it to your bookmarks.

Your permalink will be very long. Here is an example for the Orlando International Airport:

https://weatherstar.netbymatt.com/?hazards=false&current-weather=true&latest-observations=true&hourly=false&hourly-graph=true&travel=false&regional-forecast=true&local-forecast=true&extended-forecast=true&almanac=false&spc-outlook=true&radar=true&wide=false&kiosk=false&scanLines=false&speed-select=1.00&units-select=us&latLonQuery=Orlando+International+Airport%2C+Orlando%2C+FL%2C+USA&latLon=%7B%22lat%22%3A28.431%2C%22lon%22%3A-81.3076%7D

You can also build your own permalink. Any omitted settings will be filled with defaults. Here are a few examples:

https://weatherstar.netbymatt.com/?latLonQuery=Orlando+International+Airport
https://weatherstar.netbymatt.com/?kiosk=true
https://weatherstar.netbymatt.com/?units-select=metric

Kiosk mode

Kiosk mode can be activated by a checkbox on the page. This will start Weatherstar in a fullscreen-like view without the play/volume/etc toolbar and scaled to fill the entire space. This does not activate the browser's fullscreen or kiosk mode. Those can only be activated by user interaction or by launching the browser with specific parameters such as --start-fullscreen or --kiosk.

When using kiosk mode (via the checkbox), there will be no way to exit the fullscreen-like view of weatherstar. Reloading the page should remove the kiosk checkbox and return you to the normal view. This is deliberate as a browser's kiosk mode it intended not to be exited or significantly modified. A separate full-screen icon is available in the tool bar to go full-screen on a laptop or mobile browser.

It's also possible to enter kiosk mode using a permalink. First generate a Permalink, then to the end of it add &kiosk=true. Opening this link will load all of the selected displays included in the Permalink, enter kiosk mode immediately upon loading and start playing the forecast.

Default query string parameters (environment variables)

When serving this via the built-in Express server, it's possible to define environment variables that direct the user to a default set of parameters (like the Permalink above). If a user requests the root page at http://localhost:8080/ the query string provided by environment variables will be appended to the url thus providing a default configuration.

Environment variables can be added to the command line as usual, or via a .env file which is parsed with dotenv. Both methods have the same effect.

Environment variables that are to be added to the default query string are prefixed with WSQS_ and then use the same key/value pairs generated by the Permalink above, with the - (dash) character replaced by an _ (underscore). For example, if you wanted to turn the travel forecast on, you would find travel-checkbox=true in the permalink, its matching environment variable becomes WSQS_travel=true.

When using the Docker container, these environment variables are read on container start-up to generate the static redirect HTML.

Settings

Speed: Controls the playback speed multiplier of the displays, from "Very Fast" (1.5x) to "Very Slow" (0.5x) with "Normal" being 1x

Display Mode: - Standard: Classic 4:3 display with the classic (not enhanced, below) screen layouts. - Widescreen: Stretches the background to 16:9 to avoid "pillarboxing" on modern displays - Widescreen Enhanced: Stretches as above, and makes use of the additional space to provide wider maps, more weather data and/or additional days in the forecast - Portrait Enhanced: (in progress) Rotates the screen to a 16:9 portrait orientation and enhances the original displays by adjusting them to fit the new orientation and filling with additional data where possible

Kiosk: Immediately activates kiosk mode, which hides all settings. Exit by refreshing the page or using Ctrl-K. (Kiosk mode is similar to clicking the "Fullscreen" icon, but scales to the current browser viewport instead of activating the browser's actual "Fullscreen" mode.)

Sticky Kiosk: When enabled, stores the kiosk mode preference in local storage so the page automatically enters kiosk mode (maximizing the size of the main weather display without any settings) on subsequent visits. This feature is designed primarily for iPhone and iPad users who want to create a Home Screen app experience, since Mobile Safari doesn't support PWA installation via manifest.json or the Fullscreen API:

For iOS/iPadOS (Mobile Safari):

1. Tap the Share icon and choose Add to Home Screen
2. Adjust the name as desired and tap Add
3. Launch the newly-created Home Screen shortcut
4. Configure all settings
5. Tap to enable Sticky Kiosk
6. Make sure everything is configured exactly like you want it!
7. Tap Kiosk

For Android and Desktop browsers: The included manifest.json file enables PWA (Progressive Web App) installation. To get the best app-like experience:

1. Configure all your settings first (ignore the "Kiosk" and