MMM-OpenWeatherForecast

MMM-OpenWeatherForecast is a weather module for MagicMirror².

It displays current, hourly and daily forecast information using data from the OpenWeather One Call API.

Installation

Just clone the module into your modules directory and install the dependencies:

cd ~/MagicMirror/modules
git clone https://github.com/Tom-Hirschberger/MMM-OpenWeatherForecast
cd MMM-OpenWeatherForecast
npm ci

Update

Just enter the module's directory, pull the update and install the dependencies:

cd ~/MagicMirror/modules/MMM-OpenWeatherForecast
git pull
npm ci

Configuration

At a minimum you need to supply the following required configuration parameters:

• apikey
• latitude
• longitude

apikey needs to be specified as a string, while latitude and longitude can be specified as either a string or a number. Both work fine.

You need to create a free account with OpenWeather in order to get an API key: https://home.openweathermap.org/users/sign_up.

Make sure to subscribe to the new 3.0 API first and wait a couple hours till the subscription is activated. You will need to provide payment information for the new subscription but as long as you stay under the daily free limit (1000 calls at the moment) you will not be charged.

Find out your latitude and longitude here: https://www.latlong.net/.

Minimal Configuration

  {
    module: "MMM-OpenWeatherForecast",
    position: "top_right",
    header: "Forecast",
    config: {
      apikey: "a1b2c3d4e5f6g7h8j9k0", // only string here
      latitude: 51.490230,            // number works here
      longitude: "-0.258810"          // so does a string
    }
  },

Other optional parameters

Option	Description
apiBaseURL	An alternative API URL you want to use. I.e. https://api.openweathermap.org/data/3.0/onecall? for the new One Call 3.0 API. Type String Defaults to https://api.openweathermap.org/data/3.0/onecall?
updateInterval	How frequently, in minutes, to poll for data. Type Number Defaults to 10
requestDelay	In milliseconds, how long to delay the request. If you have multiple instances of the module running, set one of them to a delay of a second or two to keep the API calls from being too close together. Type Number Defaults to 250
updateFadeSpeed	How quickly in milliseconds to fade the module out and in upon data refresh. Set this to 0 for no fade. Type Number Defaults to 500 (i.e., 1/2 second).
language	The language to be used for display. Type String Defaults to the language set for MagicMirror, but can be overridden with any of the language codes listed here: https://openweathermap.org/api/one-call-api#multi
units	One of the following: standard (e.g., degrees Kelvin), metric (e.g., degress Celcius), or imperial (e.g., degrees Fahrenheit). Type String Defaults to "metric"
displayKmhForWind	When "standard" or "metric" are used for units OpenWeather's API returns wind speed in m/s. Set this to true if you would like to see wind speed displayed in km/h. This parameter has no effect if units is set to "imperial". Type Boolean Defaults to false
concise	When set to true, this presents less information. (e.g., no precipitation accumulation, no wind gusts, etc.) Type Boolean Defaults to true
iconset	Which icon set to use. See below for previews of the icon sets. Type String Defaults to "1c"
colored	Whether to present the module in colored or black-and-white. Note, if set to false, the monochromatic version of your chosen icon set will be forced. Type Boolean Defaults to true
useAnimatedIcons	Whether to use the animated icon set. When set to true, this will override your choice for iconset. However, flat icons will still be used in some instances. For example if you set the animateMainIconOnly parameter to true, daily and hourly forecasts will not be animated and instead will use your choice for iconset. Inline icons (i.e. used to prefix weather extras) will always be flat. A good iconset match for the animated set is 1c. NOTE: This may lead to higher than normal CPU usage on low-powered devices such as a Raspberry Pi. You may also want to set animateMainIconOnly to true to keep things under control. Type Boolean Defaults to true
animateMainIconOnly	When set to true, only the main current conditions icon is animated. The rest use your choice for iconset (1c is a good match for the animated icon). If you are running on a low-powered device like a Raspberry Pi, performance may suffer if you set this to false. In my testing on a Pi 3b, enabling this ramped up CPU temperature by 15° - 20°, and fade transitions were not smooth. Type Boolean Defaults to true
animatedIconStartDelay	If you're using animated icons and they are not appearing, it might be timing issue, especially if you're using a slower system like a Raspberry Pi. Add a delay before the call to start the animation is made, in milliseconds Type Number Defaults to 1000
showFeelsLikeTemp	Makes the temperature display for current conditions and hourly forecast show the "feels like" temperature instead of the actual temperature. Type Boolean Defaults to false
showCurrentConditions	Whether to show current temperature and current conditions icon. Type Boolean Defaults to true
showSummary	Whether to show the forecast summary. Weather alerts will also appear here. Type Boolean Defaults to true
showExtraCurrentConditions	Whether to show additional current conditions such as high/low temperatures, precipitation and wind speed. Type Boolean Defaults to true
extraCurrentConditions	What items to show when showExtraCurrentConditions is set to true. See the Extras section below for details on how to specify this. Type Object Defaults to Hi/Lo Temp, Sunrise/Sunset, Precipitation, Wind and UV Index
forecastHeaderText	Text for the header above the forecast display. Set to "" to hide this header altogether. Also doesn't appear if showHourlyForecast and showDailyForecast are both set to false. Type String Defaults to "Forecast"
forecastLayout	Can be set to tiled or table. How to display hourly and forecast information. See below for screenshot examples of each. Type String Defaults to tiled
showHourlyForecast	Whether to show hourly forecast information. when set to true it works with the hourlyForecastInterval and maxHourliesToShow parameters. Type Boolean Defaults to true
showHourlyTableHeaderRow	Whether to show the table header text and icon column headers on the hourly forecast table. Type Boolean Defaults to true
hourlyForecastTableHeaderText	The title text to be used for the hourly forecast table. Set to "" if you do not want a title. Type String Defaults to "Hourly"
hourlyForecastInterval	How many hours apart each listed hourly forecast is. Type Number Defaults to 3
maxHourliesToShow	How many hourly forecasts to list. This is a maximum. The API returns 48 hours of hourly forecast data. So if this in combination with hourlyForecastInterval exceeds what's available in the API, you'll only see what's provided. You won't get an error. You'll just see less than what you might have been expecting. Type Number Defaults to 3
hourlyExtras	Hourly forecast items will always show the temperature (either actual or "feels like" depending on your setting for showFeelsLikeTemp). You can configure additional items to be shown. See the "Extras" section below for details on how to specify this. Type Object Defaults to Precipitation and Wind.
showDailyForecast	Whether to show daily forecast information. when set to true it works with the maxDailiesToShow parameter. Type Boolean Defaults to true
showDailyTableHeaderRow	Whether to show the table header text and icon column headers on the daily forecast table. Type Boolean Defaults to true
dailyForecastTableHeaderText	The title text to be used for the daily forecast table. Set to "" if you do not want a title. Type String Defaults to "Daily"
maxDailiesToShow	How many daily forecasts to list. This is a maximum. The API returns 7 days of daily forecast data. So if you set this greater than 7, you'll only see 7 days. (actually 6, because the current day is not shown within the dailies -- current day conditions are covered in the hourlies and the current conditions displays.) Type Number Defaults to 3
dailyExtras	Daily forecast items will always show the high/low temperature predictions. You can configure additional items to be shown. See the "Extras" section below for details on how to specify this. Type Object Defaults to Precipitation and Wind.
label_maximum	The label you wish to display for prefixing wind gusts. Type String Defaults to "max".
label_high	The label you wish to display for prefixing high temperature. Type String Defaults to "H".
label_low	The label you wish to display for prefixing low temperature. Type String Defaults to "L".
label_hourlyTimeFormat	How you want the time formatted for hourly forecast display. Accepts any valid moment.js format (https://momentjs.com/docs/#/displaying/format/). For example, specify short 24h format with "k[h]" (e.g.: 14h) Type String Defaults to "h a" (e.g.: 9 am)
label_sunriseTimeFormat	How you want the time formatted for sunrise/sunset display. Accepts any valid moment.js format (https://momentjs.com/docs/#/displaying/format/). For example, specify short 24h format with "k[h]" (e.g.: 14h) Type String Defaults to "h:mm a" (e.g.: 6:45 am)
label_days	How you would like the days of the week displayed for daily forecasts. Assumes index 0 is Sunday. Type Array of Strings Defaults to ["Sun", "Mon", "Tue", "Wed", "Thur", "Fri", "Sat"]
label_ordinals	How you would like wind direction to be displayed. Assumes index 0 is North and proceeds clockwise. Type Array of Strings Defaults to ["N", "NNE", "NE", "ENE", "E", "ESE", "SE", "SSE", "S", "SSW", "SW", "WSW", "W", "WNW", "NW", "NNW"]

Extras

For each of current conditions, hourly forecast and daily forecast, there are additional data that can be optionally displayed. Set the corresponding value for each key to either true or false to show or hide the item respectively.

Valid options for extraCurrentConditions

This shows all available options:

  extraCurrentConditions: {
    highLowTemp: true,
    precipitation: true,
    sunrise: true,
    sunset: true,
    wind: true,
    barometricPressure: true,
    humidity: true,
    dewPoint: true,
    uvIndex: true,
    visibility: true
  },

This shows just Hi/Low temp display and precipitation:

  extraCurrentConditions: {
    highLowTemp: true,
    precipitation: true,
    sunrise: false,
    sunset: false,
    wind: false,
    barometricPressure: false,
    humidity: false,
    dewPoint: false,
    uvIndex: false,
    visibility: false
  },

Valid options for hourlyExtras

  hourlyExtras: {
    precipitation: true,
    wind: true,
    barometricPressure: true,
    humidity: true,
    dewPoint: true,
    uvIndex: true,
    visibility: true
  },

Valid options for dailyExtras

  dailyExtras: {
    precipitation: true,
    sunrise: true,
    sunset: true,
    wind: true,
    barometricPressure: true,
    humidity: true,
    dewPoint: true,
    uvIndex: true
  },

Sample Configuration

  {
    module: "MMM-OpenWeatherForecast",
    position: "top_right",
    header: "Forecast",
    config: {
      apikey: "********************",
      latitude: 43.653225,
      longitude: -79.383186,
      units: "metric",
      iconset: "3c",
      colored: true,
      concise: true,
      requestDelay: "2000",
      showFeelsLikeTemp: true,
      showCurrentConditions: true,
      showSummary: true,
      showExtraCurrentConditions: true,
      extraCurrentConditions: {
        highLowTemp: true,
        precipitation: true,
        sunrise: true,
        sunset: true,
        wind: true,
        barometricPressure: false,
        humidity: true,
        dewPoint: false,
        uvIndex: true,
        visibility: false
      },
      forecastLayout: "table",
      forecastHeaderText: "",
      hourlyForecastTableHeaderText: "By the hour",
      showHourlyForecast: true,
      showHourlyTableHeaderRow: true,
      hourlyForecastInterval: 1,
      maxHourliesToShow: 10,
      hourlyExtras: {
        precipitation: true,
        wind: true,
        barometricPressure: false,
        humidity: false,
        dewPoint: false,
        uvIndex: false,
        visibility: false
      },
      dailyForecastTableHeaderText: "Throughout the week",
      showDailyForecast: true,
      showDailyTableHeaderRow: true,
      maxDailiesToShow: 5,
      dailyExtras: {
        precipitation: true,
        sunrise: false,
        sunset: false,
        wind: true,
        barometricPressure: false,
        humidity: false,
        dewPoint: false,
        uvIndex: false
      },
    }
  },

Icon Sets

Layouts

Styling

This module is set to be 320px wide by default. If you wish to override it, you can add the following to your custom.css file:

.MMM-OpenWeatherForecast .module-content {
  width: 500px; /* adjust this as desired */
}

Most important elements of this module have one or more class names applied. Examine the MMM-OpenWeatherForecast.css, mmm-openweather-forecast.njk, or inspect elements directly with your browser of choice to determine what class you would like to override (Pro tip: If you start MagicMirror with npm start dev you'll get Chrome dev tools that will allow you to directly inspect any HTML element in the module).

For Module Developers

This module broadcasts a notification when it receives a weather update. The notification is OPENWEATHER_FORECAST_WEATHER_UPDATE and the payload contains OpenWeather's JSON weather forecast object for the One Call API. For details on the weather object, see https://openweathermap.org/api/one-call-3.

Contributing

If you find any problems, bugs or have questions, please open a GitHub issue in this repository.

Pull requests are of course also very welcome 🙂

Developer commands

• node --run lint - Run linting checks.
• node --run lint:fix - Fix linting issues.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

This module based on MMM-DarkSkyForecast from Jeff Clarke.