Homebridge WS

Homebridge plugin for virtual weather station

Copyright © 2018-2024 Erik Baauw. All rights reserved.

This Homebridge plugin exposes one or more virtual weather stations to Apple's HomeKit. The weather is obtained from OpenWeatherMap.

Each weather station is exposed as a separate accessory, mimicking an Eve Weather, with separate services for Temperature, Humidity, and Air Pressure. In addition, Homebridge WS provides a Motion Sensor service, to receive HomeKit notifications for rain or snow. A custom Weather service contains a full weather report, including observation time, conditions, clouds, rain, snow, wind, min/max temperature, UV index, visibility, sunrise, and sunset. The Temperature, Humidity, and Motion sensors are supported Apple's Home app and by Siri. You need another HomeKit app, like Eve, for the Air Pressure sensor and the full weather report In Eve, you also get history for Temperature, Humidity, Air Pressure, and Motion (rain or snow).

Optionally, Homebridge WS exposes a second Forecast accessory per location, with a Motion Sensor service per hourly or daily forecast. This service includes the full weather report as well as temperature, humidity, and air pressure.

There are many other weather station plugins out there. I created this one for fun and for testing plugin designs. In particular, this plugin is the launching plugin for homebridge-lib.

Prerequisites

You need to obtain an API key from OpenWeatherMap. As Homebridge WS uses the onecall API endpoint, a One Call by Call subscription plan is needed for new API keys. Old API keys under the the Free plan of the Current weather and forecasts collection still work, but new API keys need the One Call by Call plan.

You need a server to run Homebridge. This can be anything running Node.js: from a Raspberry Pi, a NAS system, or an always-on PC running Linux, macOS, or Windows. See the Homebridge Wiki for details. I run Homebridge WS on a Raspberry Pi 3B+.

To interact with HomeKit, you need Siri or a HomeKit app on an iPhone, Apple Watch, iPad, iPod Touch, or Apple TV (4th generation or later). I recommend to use the latest released versions of iOS, watchOS, and tvOS.
Please note that Siri and even Apple's Home app still provide only limited HomeKit support. To use the full features of Homebridge WS, you might want to check out some other HomeKit apps, like the Eve app (free) or Matthias Hochgatterer's Home+ app (paid).

Installation

To install Homebridge WS:

• Follow the instructions on the Homebridge Wiki to install Node.js and Homebridge;
• Install the Homebridge WS plugin through Homebridge Config UI X or manually by:

  $ sudo npm -g i homebridge-ws

• Edit config.json and add the WS platform provided by Homebridge WS, see Configuration.

Configuration

In Homebridge's config.json you need to specify Homebridge WS as a platform plugin. Furthermore, you need to specify your OpenWeatherMap API key, and location(s):

  "platforms": [
    {
      "platform": "WS",
      "name": "Weather",
      "apikey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "locations": ["Amsterdam"]
    }
  ]

To expose weather forecasts, set "dailyForecasts": d (with d between 1 and 7) or "hourlyForecasts": h (with h between 1 and 47) in config.json. When either has been set, Homebridge WS exposes an additional Forecast accessory per location, with a Leak Sensor service per forecast. Home will only show Leak Detected per forecast, in Eve you can see the full weather reports.

Note that OpenWeatherMap's One Call API returns the current conditions and forecasts in a single API call, so enabling forecasts won't increase the number of outgoing API calls. The rate at which OpenWeatherMap is called can be changed using the Heartrate characteristic in the Leak Sensor service on the main accessory.

Troubleshooting

Check Dependencies

If you run into Homebridge startup issues, please double-check what versions of Node.js and of Homebridge have been installed. Homebridge WS has been developed and tested using the latest LTS version of Node.js and the latest version of Homebridge. Other versions might or might not work - I simply don't have the bandwidth to test these.

Run Homebridge WS Solo

If you run into Homebridge startup issues, please run a separate instance of Homebridge with only Homebridge WS (and Homebridge Config UI X) enabled in config.json. This way, you can determine whether the issue is related to Homebridge WS itself, or to the interaction of multiple Homebridge plugins in your setup. You can start this separate instance of Homebridge on a different system, as a different user, or from a different user directory (specified by the -U flag). Make sure to use a different Homebridge name, username, and (if running on the same system) port in the config.json for each instance.

Debug Log File

Homebridge WS outputs an info message for each HomeKit characteristic value it sets and for each HomeKit characteristic value change notification it receives. When Homebridge is started with -D, Homebridge WS outputs a debug message for each request it makes to OpenWeatherMap.

To capture these messages into a log file do the following:

• If you're running Homebridge as a service, stop that service;
• Run Homebridge manually, capturing the output into a file, by issuing:

  $ homebridge -CD 2>&1 | tee homebridge.log

• Interact with your devices, through their native app and or through HomeKit to trigger the issue;
• Hit interrupt (ctrl-C) to stop Homebridge;
• If you're running Homebridge as a service, restart the service;
• Compress the log file by issuing:

  $ gzip homebridge.log

Getting Help

If you have a question, please post a message to the #ws channel of the Homebridge community on Discord.

If you encounter a problem, please open an issue on GitHub. Please attach a copy of homebridge.log.gz to the issue, see Debug Log File. Please do not copy/paste large amounts of log output.

Caveats

Homebridge WS is a hobby project of mine, provided as-is, with no warranty whatsoever. I've been running it successfully at my home for years, but your mileage might vary.

The HomeKit terminology needs some getting used to. An accessory more or less corresponds to a physical device, accessible from your iOS device over WiFi or Bluetooth. A bridge (like Homebridge) is an accessory that provides access to other, bridged, accessories. An accessory might provide multiple services. Each service corresponds to a virtual device (like a lightbulb, switch, motion sensor, ..., but also: a programmable switch button, accessory information, battery status). Siri interacts with services, not with accessories. A service contains one or more characteristics. A characteristic is like a service attribute, which might be read or written by HomeKit apps. You might want to checkout Apple's HomeKit Accessory Simulator, which is distributed as an additional tool for Xcode.