⏰ 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 Saturday 7 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