⏰ Homebridge Cron Scheduler

Creating and maintaining Homebridge plugins consume a lot of time and effort, if you would like to share your appreciation, feel free to "Star" or donate.

Click here to review more of my plugins.

Info

Cron Scheduler plugin for Homebridge, which allows scheduling of triggers using cron expressions.

Installation

After Homebridge has been installed:

sudo npm install -g --unsafe-perm homebridge-cron-scheduler@latest

Example Config

{
  //...
  "platforms": [
    {
      "platform": "CronScheduler",
      "debug": true,
      "tasks": [
        {
          "taskName": "min-1-default",
          // uses default `taskActive` with value `true`
          // uses default `taskCronExpression` with value `* * * * *`
          // uses default `taskStateResetInterval` with value `0`
        },
        {
          "taskName": "min-3-inactive",
          "taskActive": false,
          // task will be inactive, but can be activated using Home app by switching corresponding switch
          "taskCronExpression": "*/3 * * * *"
          // task will be triggered every 3 minutes
        },
        {
          "taskName": "min-3-reset-1",
          // uses default `taskActive` with value `true`
          "taskCronExpression": "*/3 * * * *",
          // task will be triggered every 3 minutes
          "taskStateResetInterval": 1
          // task will be reset every 1 minute after it was triggered
        },
        {
          "taskName": "working-day-toggle",
          // uses default `taskActive` with value `true`
          "taskCronExpression": "0 9,17 * * *",
          // task will be triggered at 9:00 and 17:00
          "taskStateResetInterval": -1
          // task will toggle sensor state when triggered, so sensor will be active from 9:00 to 17:00 every day
        },
        {
          "taskName": "next-ny-once",
          // uses default `taskActive` with value `true`
          "taskCronExpression": "0 0 31 12 *",
          // 31st of December at 00:00
          "taskMaxRuns": 1
          // task will be triggered only once at next 31st of December at 00:00
        }
      ]
    }
  ]
}

| Config Field | Description | Default | Required | |--------------|---------------------------------------------------------------------------------------------------|-------------------|----------| | platform | Must always be CronScheduler. | "CronScheduler" | Yes | | debug | Enable for displaying debug messages. | false | No | | timezone | Timezone in 'Europe/Kiev' format to use for all tasks. Leave blank for using the system timezone. | undefined | No | | tasks | Array of cron tasks. | [] | No |

| Task Config Field | Description | Default | Required | |------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|----------------|----------| | taskActive | Defines whether the task is active or not. | true | No | | taskName | A unique name for the task. Will be used as the accessory name. | "task-name1" | Yes | | taskCronExpression | The cron expression to use for the task. | * * * * * | No | | taskMaxRuns | Maximum number of times the task can run. Leave blank for unlimited. | Infinite | No | | taskStateResetInterval | The interval in minutes after which the task state will be reset. Leave '0' for immediate reset, change to '-1' for enabling toggle mode. | 0 | No | | taskStartAt | Time at which the task should start. Leave blank for immediate start. ISO 8601 formatted datetime (2021-10-17T23:43:00) in local time. | undefined | No | | taskStopAt | Time at which the task should stop. Leave blank for no stop. ISO 8601 formatted datetime (2021-10-17T23:43:00) in local time. | undefined | No | | timezone | Timezone override in 'Europe/Kiev' format to use for this tasks. Leave blank for using the global timezone. | undefined | No |

Cron Expression

• Cron expressions support the following additional modifiers

• ? A question mark is substituted with cron initialization time, as an example - ? * * * * would be substituted with 8 * * * * if time is <any hour>:08. The question mark can be used in any field.
• L L can be used in the day of month field, to specify the last day of the month.

// ┌────────────── minute (0 - 59)
// │ ┌──────────── hour (0 - 23)
// │ │ ┌────────── day of month (1 - 31)
// │ │ │ ┌──────── month (1 - 12, JAN-DEC)
// │ │ │ │ ┌────── day of week (0 - 6, SUN-Mon) 
// │ │ │ │ │       (0 to 6 are Sunday to Saturday; 7 is Sunday, the same as 0)
// │ │ │ │ │
// * * * * *

| Field | Required | Allowed values | Allowed special characters | Remarks | |--------------|----------|-----------------|----------------------------|-------------------------------------------------------------| | Minutes | Yes | 0-59 | * , - / ? | | | Hours | Yes | 0-23 | * , - / ? | | | Day of Month | Yes | 1-31 | * , - / ? L | | | Month | Yes | 1-12 or JAN-DEC | * , - / ? | | | Day of Week | Yes | 0-7 or SUN-MON | * , - / ? | 0 to 6 are Sunday to Saturday7 is Sunday, the same as 0 |

Note Weekday and month names are case insensitive. Both MON and mon works.

See Cron Expression for more details.

Contributing

You can contribute to this homebridge plugin in following ways:

• Report issues and help verify fixes as they are checked in.
• Review the source code changes.
• Contribute bug fixes.
• Contribute changes to extend the capabilities
• Pull requests are accepted.

See CONTRIBUTING