homebridge-netatmo-smart-schedules

homebridge-netatmo-smart-schedules is a Homebridge dynamic platform plugin that switches an existing Netatmo heating schedule once per day using ordered date rules and Open-Meteo weather rules.

The plugin does not create schedules, edit schedules, or set temperatures directly. It only selects one existing Netatmo schedule and applies it when needed.

Features

• Dynamic platform plugin for Homebridge
• Netatmo OAuth2 refresh-token flow with cached access tokens
• Automatic persistence of rotated Netatmo refresh tokens
• Ordered date and weather rules
• Daily evaluation in a configurable timezone
• Open-Meteo forecast integration only
• Skips Netatmo API schedule changes when the chosen schedule is already active
• Unit tests with Vitest

Requirements

• Node.js 20+
• Homebridge 1.8+
• Existing Netatmo heating schedules
• Netatmo API credentials:
  • clientId
  • clientSecret
  • refreshToken

Install

npm install -g homebridge-netatmo-smart-schedules

Configuration

Add the platform to your Homebridge config.json.

Rules are evaluated in array order. The first matching rule wins. If no rule matches, defaultScheduleId is used.

Date Rules

Date rules support these optional matchers:

• startDate
• endDate
• weekdays
• months
• monthDays

All configured matchers on the rule must pass.

Weather Rules

Weather rules use the nearest hourly Open-Meteo point for the evaluation time. They support these optional matchers:

• minTemperature
• maxTemperature
• minCloudCover
• maxCloudCover
• minPrecipitationProbability
• maxPrecipitationProbability
• minPrecipitation
• maxPrecipitation
• afterSunriseMinutes
• beforeSunsetMinutes

All configured matchers on the rule must pass.

Example

{
  "platforms": [
    {
      "platform": "NetatmoSmartSchedules",
      "name": "Netatmo Smart Schedules",
      "clientId": "your-netatmo-client-id",
      "clientSecret": "your-netatmo-client-secret",
      "refreshToken": "your-netatmo-refresh-token",
      "homeId": "01234567-89ab-cdef-0123-456789abcdef",
      "defaultScheduleId": "schedule-home",
      "latitude": 51.5072,
      "longitude": -0.1276,
      "timezone": "Europe/London",
      "evaluationHour": 5,
      "evaluationMinute": 0,
      "rules": [
        {
          "type": "date",
          "name": "Christmas break",
          "scheduleId": "schedule-holiday",
          "startDate": "2026-12-20",
          "endDate": "2027-01-03"
        },
        {
          "type": "weather",
          "name": "Cold and wet",
          "scheduleId": "schedule-winter",
          "maxTemperature": 4,
          "minPrecipitationProbability": 70
        },
        {
          "type": "weather",
          "name": "Bright spring day",
          "scheduleId": "schedule-light",
          "minTemperature": 12,
          "maxCloudCover": 35,
          "afterSunriseMinutes": 60,
          "beforeSunsetMinutes": 120
        }
      ]
    }
  ]
}

How It Works

1. Homebridge launches the dynamic platform.
2. The plugin refreshes the Netatmo access token only when needed.
3. The plugin loads the configured home and verifies the referenced schedule IDs exist.
4. The plugin fetches the daily Open-Meteo forecast for the configured coordinates and timezone.
5. The first matching rule selects the schedule.
6. If that schedule is already active, the plugin logs and stops.
7. Otherwise, it switches the home to the chosen schedule.
8. The plugin records the evaluation date and schedules the next daily run.

Development

npm install
npm run build
npm test

Notes

• Netatmo refresh tokens can rotate. This plugin persists the latest token in Homebridge storage so daily runs continue working after refresh.
• The plugin stores state in Homebridge user storage under homebridge-netatmo-smart-schedules.json.
• Startup evaluates immediately unless the current local date has already been processed.

References

• Homebridge dynamic platform template
• Open-Meteo forecast API
• Netatmo authentication
• Netatmo Home + Control and Energy docs are referenced for homesdata and heating schedule switching. The public documentation pages are currently sparse in text, so the implementation uses the documented Netatmo API base and endpoint naming convention with defensive parsing for active schedule fields.