homebridge-weather

Homebridge plugin for displaying the weather from openweathermap.org

Usage no npm install needed!

<script type="module">
  import homebridgeWeather from 'https://cdn.skypack.dev/homebridge-weather';
</script>

README

homebridge-weather

Homebridge plugin for displaying the weather, humidity and min- or max-temperature from openweathermap.org

NPM version Dependency Status PRs Welcome Downloads

If you find my work useful you can buy me a coffee, I am very thankful for your support.

Buy Me A Coffee

Installation

  1. Install Homebridge using: (sudo) npm install -g --unsafe-perm homebridge
  2. Install this plugin using: (sudo) npm install -g homebridge-weather
  3. Get an API-Key from openweathermap.org
  4. Find your city (make sure the query only returns a single result!). Alternatively you can use a different query parameter (see 'Fields')
  5. Update your Homebridge config.json using the sample below (append in the block 'accessories' not 'platforms').

Configuration

Weather

Example for configuration by City

"accessories": [
    {
      "accessory": "Weather",
      "apikey": "YOUR_KEY_HERE",
      "location": "Stuttgart,de",
      "name": "OpenWeatherMap Temperature"
    }
]

By ID

replace location with

"locationById": "2172797",

By Coordinates

replace location with

"locationByCoordinates": "lat=48.70798341&lon=9.17019367",

Celsius/Fahrenheit (you probably don't have to change anything here)

iOS should take care of the correct unit, HomeApp converts the values internally.

If you want a different unit than your OS' settings, you can change the unit explicitly by adding unit with one of the following values:

"unit": "metric",

for Celsius (default)

or

"unit": "imperial",

for Fahrenheit

Forecast

To show daily min/max values, you have to add two additional accessories:

"accessories": [
  {
     "accessory":"Weather",
     "apikey":"YOUR_KEY_HERE",
     "locationByCoordinates":"lat=48.70798341&lon=9.17019367",
     "name":"Today Min",
     "type":"min"
  },
  {
     "accessory":"Weather",
     "apikey":"YOUR_KEY_HERE",
     "locationByCoordinates":"lat=48.70798341&lon=9.17019367",
     "name":"Today Max",
     "type":"max"
  }
]

Cloudiness

To show cloudiness in percent configure as follows:

"accessories": [
  {
     "accessory":"Weather",
     "apikey":"YOUR_KEY_HERE",
     "locationByCoordinates":"lat=48.70798341&lon=9.17019367",
     "name":"Cloudiness",
     "type":"clouds"
  }
]

Wind-speed

To show wind-speed in meter/sec configure as follows:

"accessories": [
  {
     "accessory":"Weather",
     "apikey":"YOUR_KEY_HERE",
     "locationByCoordinates":"lat=48.70798341&lon=9.17019367",
     "name":"Wind",
     "type":"windspeed"
  }
]

To display in miles/hour additionally configure

   "unit": "imperial"

Sunrise/noon/sunset

This type publishes a value between 0 and 100 that indicates how far through the day we are where 0% is the sunrise (and everything before) and 100% is sunset (and everything after). 50% is noon accordingly.

For using this value as trigger, you have to define a "pollingInterval" as well, otherwise the value only gets updated while having HomeApp in foreground.

"accessories": [
  {
     "accessory":"Weather",
     "apikey":"YOUR_KEY_HERE",
     "locationByCoordinates":"lat=48.70798341&lon=9.17019367",
     "name":"Sun",
     "type":"sun",
     "pollingInterval": 10
  }
]

Hint

You can add multiple accessories if you want to display additional information like min/max or the temperature of different locations. Just make sure that the field name is unique

Polling

By default, no polling-interval is specified. That means, the temperature is only updated when the Home-App is opened. There might be scenarios though, where you would want to periodically update the temperature e.g. as source for trigger-rules.

OpenWeatherMap has a generous amount of free calls per API-key: you can poll the temperature up to 60 times a minute. Beware that just because you can doesn't mean you should

I'd also suggest that you add a polling-interval only for the type current, since min and max are forecasts and probably won't change throughout the day.

Temperature profile with Elgato Eve App (FakeGato support)

With the enableHistory flag, the FakeGato-service is used to log temperature and humidity. This doesn't work with the default Home-App, you have to use the Elgato Eve App.

eve-example

Since FakeGato requires to log an entry at least every 10 minutes, this feature only becomes active if you set enableHistory to true AND define an pollingInterval!

I suggest the following settings:

"accessories": [
    {
       "accessory": "Weather",
       "apikey": "YOUR_KEY_HERE",
       "location": "Stuttgart,de",
       "name": "OpenWeatherMap Temperature",
       "pollingInterval": 10,
       "enableHistory": true
     }
]

Config file

Take a look at the example config.json

Fields:

  • accessory must be "Weather" (required).
  • apikey API-Key for accessing OpenWeatherMap API (required).
  • location city-name query string (resembles to q-parameter) (required).
  • OR locationById cityid query string (resembles to cityid-parameter) (required).
  • OR locationByCoordinates geo query string (resembles to geo-parameter) (required).
  • OR locationByZip zip query string (resembles to zip-parameter) (required).
  • name is the name of the published accessory (required).
  • showHumidity weather or not show the humidity (optional, only works for current weather not forecast, defaults to true).
  • nameHumidity humidity can have a different name (optional, only works if showHumidity is true, defaults to the same as name).
  • showTemperature weather or not show the temperature (optional, setting to false only makes sense if showHumidity os set to true, defaults to true).
  • type the type of the displayed value, either min, max, current, clouds, sun or windspeed (optional, defaults to current)
  • pollingInterval the time (in minutes) for periodically updating the temperature (optional, defaults to 0 which means polling only happens when opening the Home-App)
  • enableHistory flag for enabling the FakeGato-service (see above) for temperature and humidity logging (optional, defaults to false, only works when polling is enabled)
  • unit change the temperature unit to Celsius or Fahrenheit explicitly (optional, defaults to metric (Celsius), for Fahrenheit use imperial. Beware that iOS usually does the job correctly)

Known Issues

  • Default Home-App can't trigger scenes: try Hesperus App instead

Advanced usage

If you need more features like a more detailed forecast, take a look at homebridge-weather-plus (here), it now supports OpenWeatherMap as well.

Current Conditions in Elgato Eve app History graph in Elgato Eve app

(c) Screenshots are taken from the Elgato Eve app