Skip to content

jclarke0000/MMM-OpenWeatherForecast

Repository files navigation

MMM-OpenWeatherForecast

This a module for MagicMirror
https://magicmirror.builders/
https://github.com/MichMich/MagicMirror

Screenshot

A weather module that displays current, hourly and daily forecast information using data from the OpenWeather One Call API. This is a replacement module for MMM-DarkSkyForecast, now that Dark Sky no longer allows free API access. This maintains much of the same functionality and adds a few new features.

NOTE This module uses the Nunjucks templating system introduced in version 2.2.0 of MagicMirror. If you're seeing nothing on your display where you expect this module to appear, make sure your MagicMirror version is at least 2.2.0.

Installation

  1. Navigate into your MagicMirror modules folder and execute
    git clone https://github.com/jclarke0000/MMM-OpenWeatherForecast.git.
  2. Enter the new MMM-OpenWeatherForecast directory and execute npm install.

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.

e.g.,

  {
    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
    }
  },

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

Free tier is fine -- this module will not make anywhere near 60 calls per minute / 1,000,000 requests per month.

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

Other optional parameters

Option Description
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 Magic Mirror, 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 colour or black-and-white. Note, if set to false, the monochramtic 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 temprature 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 temperaure 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 showDailylyForecast 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: "********************", //SUPER SECRET
      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

Icon Sets

Layouts

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 mdoule).

For Module Developers

This module broadcasts a notification when it recieves 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-api.