Skip to content

Latest commit

 

History

History
132 lines (99 loc) · 9.07 KB

README.md

File metadata and controls

132 lines (99 loc) · 9.07 KB
Raw

WallberryTheme: A MagicMirror² Module

The WallberryTheme module re-themes MagicMirror² to look like a beautiful photo-box wall display. It adds a new font, styles, and periodically changing background image pulled from Unsplash.com.

The WallberryTheme also comes packaged with two companion modules for displaying the time (WB-clock) and weather (WB-weather).

REQUIRED API KEYS:

  • A (free) Unsplash API key is required and can be obtained from Unsplash.com.
  • For the weather module, a (free) OpenWeatherMap API key is required and can be obtained at OpenWeatherMap.org/api.

New and Shiny in 3.0.0

The WB-weather companion module has now been completely refactored with some great new features:

  • OpenWeatherMap is now the default weather provider (RIP DarkSky, you were taken too soon).
  • WB-weather still supports DarkSky as a provider for existing users with API keys, but expect the API to be shuttered officially by Apple by end of 2021.
  • New weather providers can be easily integrated by subclassing WB-weather's new WBProvider class.
  • New config option for choosing which display template to use, so you can easily change how the weather is displayed by adding new templates.

Go check out the details in WB-weather's README.

Screenshots

Now With More Options For Bright Images!

WallberryTheme has new options for dealing with light text on bright background images!

  • The addBackgroundFade option allows you to add soft gradient backgrounds to the top and bottom regions of your magic mirror, providing more contrast for the modules in those regions. These gradients use Unsplash's color data to automatically shift to the general color hue of the photo, so they blend better with the image.

  • The autoDimOn feature auto-detects bright images and automatically dims them, ensuring bright images don't wash out your text and dark images remain vibrant.

No background fade, auto dim set to off:

With addBackgroundFade and autoDimOn (on their default settings):

Using the module

To use this module and its companion modules:

  1. Copy the WallberryTheme folder to your MagicMirror/modules directory
  2. Add the modules to the modules array in the config/config.js file like in the following example:
modules: [
  // Base WallberryTheme adds new font, styles, and a rotating background image pulled from Unsplash.com
  {
    module: "WallberryTheme",
    position: "fullscreen_below", // Required Position
    config: {
      unsplashAccessKey: "Your Unsplash API Key", // REQUIRED
      collections: "2589108" // optional - leave empty for a random photo
    }
  },
  // WB-clock adds local time (Optional Module)
  {
    module: "WallberryTheme/WB-clock",
    position: "top_bar", // highly suggest using top_bar position
    config: {
      localCityName: "Seattle", // optional
      otherCities: [
      	{name: "DC", timezone: "US/Eastern"}, // optional
      	{name: "Anchorage", timezone: "US/Alaska"} // optional
      ]
    }
  },
  // WB-weather adds weather (Optional Module)
  {
    module: "WallberryTheme/WB-weather",
    position: "bottom_bar",  // Highly suggested location
    config: {
      // See "Configuration options" for more information.
      apiKey: "Your openweathermap API key", // REQUIRED
      latitude:   47.603230, // REQUIRED
      longitude: -122.330276 // REQUIRED
    }
  }
]

Configuration options

The following properties of WallberryTheme can be configured. For more information on how to configure the WB-clock and WB-weather modules see their individual README files.

Option Type Description
unsplashAccessKey String Your Unsplash API access key. Sign up for free at https://unsplash.com/developers. Demo accounts are allowed 50 API requests per hour.

This value is REQUIRED
collections String A comma-separated list of Unsplash collection IDs that photos should be pulled from. Collection IDs can be found in the URL of the collection, shown in the highlighted part of this screenshot:

Example: "1538150,162213"
Default value: "" (no collection, theme will use a random Unsplash photo)
queries Array A list of queries to search for on Unsplash. When multiple queries are specified, one gets randomly picked every refresh.

Example: ["cars", "new york", "black cat"]
Default value: []
updateInterval Number How often the photo should change (Milliseconds).

Default value: 300000 (5 minutes)
orientation String What screen orientation photos should be optimized for.

Possible values: "portrait", "landscape", or "squarish"
Default value: "portrait"
backgroundOpacity Number Controls the darkness of the background photo.

Possible values: Any number from 0.0 (black screen) to 1 (fully bright image)
E.G.: 0.5 would be the background at half brightness
Default value: 1
brightImageOpacity Number Controls the darkness of bright photos (determined by autoDimOn). Only used when autoDimOn is true.

Possible values: Any number from 0.0 (black screen) to 1 (fully bright image)
Default value: 0.85
autoDimOn Boolean Automatically darkens bright photos to the value set by brightImageOpacity.

Possible values: true (on) or false (off)
Default value: true
addBackgroundFade Array Adds darker gradient backgrounds to the top bar region and/or bottom bar regions of MagicMirror (helps with readability for bright or busy background images).

Possible values: "top" will add a gradient background to the top bar region, "bottom" will add a gradient background to the bottom bar region. Set to an empty list to remove all gradients.
Default value: ["top", "bottom"]
clearCacheOnStart Boolean Clears Electron's cache on MagicMirror startup, preventing an issue where Electron would sometimes encounter a CORS error when trying to load a previously cached background image (see this issue here for details).

Possible values: true (on) or false (off)
Default value: true
imageHeight String or Number Use "auto" to use your screen's height, or specify a hardcoded width in pixels.

Default value: "auto"
imageWidth String or Number Use "auto" to use your screen's width, or specify a hardcoded width in pixels.

Default value: "auto"
imageOptions String See Unsplash documentation for supported parameters.

Default value: "fit=crop"

Contributing

Contributions of all kinds (pull requests, bug reports, feature suggestions, documentation, etc) are all welcome and encouraged.

If you're enjoying the WallberryTheme and wanna make my day:

  • ☕ Buy me a coffee ☕ and fuel my motivation for open source development ;)
  • Post a screenshot of your MagicMirror running WallberryTheme in the GitHub discussion.

Huge thanks to everyone who has contributed and made the WallberryTheme better!

Guidelines for Pull Requests

  • Pull Requests should be submitted to the dev branch
  • If there isn't one already, it's helpful to open an issue detailing the feature/bug your PR will address before you submit it.
  • Add a short description of your change to the Changelog file file under the [Unreleased] section.

Attributions & Special Thanks

Changelog

Visit the Changelog file to see the latest changes to the project :)