Schedule

This service allows execution of RPC methods at defined instances in time, using a cron library. Basic CRUD interface is exposed for manipulating schedule configurations. There is a limit of 20 schedule instances per device. A revision number is maintained which is incremented on every update of the schedules. It is returned in the result of RPC calls and is also included in the Status object of the Sys component.

Cron Timespec

A timespec is a cron expression with 5, 6, or 7 whitespace-separated fields:

Fields	Format
5 fields	minute hour day-of-month month day-of-week
6 fields	second minute hour day-of-month month day-of-week
7 fields	second minute hour day-of-month month day-of-week year

When 5 fields are given, seconds defaults to 0. When 6 fields are given, year defaults to * (any).

Field ranges

Position (6-field)	Field	Range
1	Second	0–59
2	Minute	0–59
3	Hour	0–23
4	Day of month	1–31
5	Month	1–12
6	Day of week	0–7 (0 and 7 both mean Sunday)
7	Year	1970–2199 (optional)

Special characters

Character	Meaning	Allowed in	Example
*	Any value	All fields	*, */5
,	List separator	All fields	1,15,30
-	Range	All fields	1-5, MON-FRI
/	Step/interval	All fields	*/15, 0-30/5
?	No specific value	Day of month, Day of week	?
L	Last	Day of month, Day of week	L, L-3, 5L
W	Nearest weekday	Day of month	15W, LW
#	Nth occurrence in month	Day of week	2#1 (1st Tuesday)

L details:

• In day-of-month: L = last day of month; L-3 = 3 days before last day; LW = last weekday of month.
• In day-of-week: appended after a day number means "last X of month" — e.g. 5L = last Friday.

W details: 15W = nearest weekday to the 15th. If the 15th is Saturday, fires on Friday the 14th; if Sunday, fires on Monday the 16th. Does not cross month boundaries.

# details: 2#1 = first Tuesday of the month. Negative values count from the end: 2#-1 = last Tuesday. Valid range: -5 to 5.

Named aliases

Days (case-insensitive): SUN=0, MON=1, TUE=2, WED=3, THU=4, FRI=5, SAT=6

Months (case-insensitive): JAN=1, FEB=2, MAR=3, APR=4, MAY=5, JUN=6, JUL=7, AUG=8, SEP=9, OCT=10, NOV=11, DEC=12

Named aliases work in ranges: MON-FRI, JAN-MAR.

Shorthand aliases

Alias	Equivalent	Description
@yearly / @annually	0 0 0 1 1 *	Jan 1 at midnight
@monthly	0 0 0 1 * *	1st of month at midnight
@weekly	0 0 0 * * 0	Sunday at midnight
@daily / @midnight	0 0 0 * * *	Every day at midnight
@hourly	0 0 * * * *	Every hour at :00

Sunrise/Sunset expressions

@sunrise[OFFSET] [day-of-month month day-of-week]
@sunset[OFFSET]  [day-of-month month day-of-week]

If day/month/day-of-week fields are omitted, defaults to * * * (every day). The 3 trailing fields follow standard cron syntax.

Offset syntax: (+|-)DURATION where duration is one or more segments of the form NUMBER[UNIT]. Unit is h, m, or s; if omitted, seconds are assumed. Float values are allowed. Maximum offset: ±12 hours.

Example	Meaning
@sunrise	At sunrise daily
@sunrise+30m	30 minutes after sunrise
@sunset-1h30m	1.5 hours before sunset
@sunrise * * MON-FRI	At sunrise on weekdays only
@sunset+15m * 6-8 *	15 min after sunset, June through August

Requires device location to be configured (Sys.SetConfig with device.location.lat / lon).

Random expressions

@random:{"from":"CRON_EXPR","to":"CRON_EXPR","number":N}

Distributes N random firing points uniformly between the from and to cron windows. from must evaluate to an earlier time than to.

@random:{"from":"0 0 8 * * MON-FRI","to":"0 0 22 * * MON-FRI","number":10}

The above fires 10 times at random between 08:00 and 22:00 on weekdays.

Examples

0 0 8 * * *        — Daily at 08:00:00
0 30 22 * * *      — Daily at 22:30:00
0 0 */2 * * *      — Every 2 hours
0 */15 * * * *     — Every 15 minutes
0 0 8 * * MON-FRI  — Weekdays at 08:00
0 0 12 1 * *       — Noon on the 1st of every month
0 0 0 25 12 *      — Christmas midnight
0 0 0 L * *        — Last day of every month at midnight
0 0 0 LW * *       — Last weekday of every month
0 0 0 15W * *      — Nearest weekday to the 15th
0 0 0 ? * 2#1      — First Tuesday of every month
0 0 0 ? * 5L       — Last Friday of every month

note

All times are in the device's configured local timezone.

During spring-forward DST transitions, if the scheduled time falls in the skipped hour, that firing is skipped for that day. During fall-back transitions, the schedule fires once during the first (pre-rollback) occurrence of the repeated hour.

Schedule Object Structure

A schedule job is represented in JSON in the following format:

Property	Type	Description
id	number	Id assigned to the job when it is created. This is used in subsequent Update / Delete calls
enable	boolean	true to enable the execution of this job, false otherwise. It is true by default.
timespec	string	Cron expression as described in the Cron Timespec section above.
calls	array of objects	RPC methods and parameters to be invoked when the job gets executed. It must contain at least one valid object. There is a limit of 5 calls per schedule job Property Type Description method string Name of the RPC method. Required params object The parameters used to invoke the RPC call. If the call requires no parameters params will be omitted

Example:

Schedule job which will turn the Switch with id=0 OFF, every day at 17:34:

{
     "id": 1,
     "enable": true,
     "timespec": "0 34 17 * * SUN,MON,TUE,WED,THU,FRI,SAT",
     "calls": [{
         "method": "Switch.Set",
         "params": {
           "id": 0,
           "on": false
         }
       }
     ]
}

Schedule.Create

This method creates a new schedule job.

Request

Parameters (their meaning is defined by the schedule job format in the beginning of this page):

Property	Type	Description
enable	boolean	true to enable the execution of this job, false otherwise. It is true by default.
timespec	string	Cron expression as described in the Cron Timespec section above.
calls	array of objects	RPC methods and parameters to be invoked when the job gets executed. It must contain at least one valid object. There is a limit of 5 calls per schedule job Property Type Description method string Name of the RPC method. Required params object The parameters used to invoke the RPC call. If the call requires no parameters params will be omitted

Response

Attributes in the result:

Property	Type	Description
id	number	Id of the created job
rev	number	Current revision number of the schedule instances

Example:

Schedule job which will turn the Switch with id=0 ON, every day at 9:03:

{
    "enable":true, 
    "timespec":"0 3 9 * * SUN,MON,TUE,WED,THU,FRI,SAT", 
    "calls":[{
       "method":"Switch.Set", 
       "params":{
          "id":0, 
          "on":true 
         }
      }
   ]
 }

Schedule.Update

This method updates an existing schedule job.

Request

Parameters (their meaning is defined by the schedule job format in the beginning of this page):

Property	Type	Description
id	number	Id assigned to the job when it is created. This is used in subsequent Update / Delete calls
enable	boolean	true to enable the execution of this job, false otherwise. It is true by default.
timespec	string	Cron expression as described in the Cron Timespec section above.
calls	array of objects	RPC methods and parameters to be invoked when the job gets executed. It must contain at least one valid object. There is a limit of 5 calls per schedule job

Response

Attributes in the result:

Property	Type	Description
rev	number	Current revision number of the schedule instances

Schedule.List

This method lists all existing schedules for this device.

Request

This method takes no parameters.

Response

Attributes in the result:

Property	Type	Description
jobs	array of objects	Each entry is a schedule job object (described above)
rev	number	Current revision number of the schedule instances

Schedule.Delete

This method deletes an existing schedule job.

Request

Parameters:

Property	Type	Description
id	number	Id of the job to be deleted Required

Response

Attributes in the result:

Property	Type	Description
rev	number	Current revision number of the schedule instances

Schedule.DeleteAll

This method deletes all existing schedule jobs.

Request

This method takes no parameters.

Response

Attributes in the result:

Property	Type	Description
rev	number	Current revision number of the schedule instances

Schedule.Eval

This method evaluates a cron timespec and returns the previous and next trigger times relative to a given point in time.

Request

Parameters:

Property	Type	Description
timespec	string	Cron expression as described in the Cron Timespec section above. Required
now	number	Unix timestamp to use as current time. Optional, defaults to the device's current time if omitted

Response

Attributes in the result:

Property	Type	Description
now	number	The unix timestamp used as current time for the evaluation
next	number	Unix timestamp of the next trigger. Omitted if there is no valid next occurrence
prev	number	Unix timestamp of the previous trigger. Omitted if there is no valid previous occurrence

Examples

Schedule.Create example

Schedule.Create HTTP GET Request

http://192.168.33.1/rpc/Schedule.Create?timespec="0 0 22 * * FRI"&calls=[{"method":"Shelly.GetDeviceInfo"}]

Schedule.Create Curl Request

curl -X POST -d '{"id":1,"method":"Schedule.Create","params":{"timespec":"0 0 22 * * FRI","calls":[{"method":"Shelly.GetDeviceInfo"}]}}' http://${SHELLY}/rpc

Schedule.Create Mos Request

mos --port ${PORT} call Schedule.Create '{"timespec":"0 0 22 * * FRI","calls":[{"method":"Shelly.GetDeviceInfo"}]}'

Response

Schedule.Create HTTP GET Response

{
  "id": 3,
  "rev": 5
}

Schedule.Create Curl Response

{
  "id": 1,
  "src": "shellypro4pm-f008d1d8b8b8",
  "params": {
    "id": 3,
    "rev": 5
  }
}

Schedule.Create Mos Response

{
  "id": 3,
  "rev": 5
}

Schedule.Update example

Schedule.Update HTTP GET Request

http://192.168.33.1/rpc/Schedule.Update?id=3&enable=false

Schedule.Update Curl Request

curl -X POST -d '{"id":1,"method":"Schedule.Update","params":{"id":3,"enable":false}}' http://${SHELLY}/rpc

Schedule.Update Mos Request

mos --port ${PORT} call Schedule.Update '{"id":3,"enable":false}'

Response

Schedule.Update HTTP GET Response

{
  "rev": 11
}

Schedule.Update Curl Response

{
  "id": 1,
  "src": "shellyplus1-a8032abe54dc",
  "params": {
    "rev": 11
  }
}

Schedule.Update Mos Response

{
  "rev": 11
}

Schedule.List example

Schedule.List HTTP GET Request

http://192.168.33.1/rpc/Schedule.List

Schedule.List Curl Request

curl -X POST -d '{"id":1,"method":"Schedule.List"}' http://${SHELLY}/rpc

Schedule.List Mos Request

mos --port ${PORT} call Schedule.List

Response

Schedule.List HTTP GET Response

{
  "jobs": [
    {
      "id": 1,
      "enable": true,
      "timespec": "0 0 8 * * SUN,MON,TUE,WED,THU,FRI,SAT",
      "calls": [
        {
          "method": "Switch.Set",
          "params": {
            "id": 0,
            "on": false
          }
        }
      ]
    },
    {
      "id": 2,
      "enable": true,
      "timespec": "0 30 19 * * MON,TUE,WED,THU,FRI",
      "calls": [
        {
          "method": "Switch.Set",
          "params": {
            "id": 0,
            "on": true
          }
        }
      ]
    }
  ],
  "rev": 4
}

Schedule.List Curl Response

{
  "id": 1,
  "src": "shellypro4pm-f008d1d8b8b8",
  "params": {
    "jobs": [
      {
        "id": 1,
        "enable": true,
        "timespec": "0 0 8 * * SUN,MON,TUE,WED,THU,FRI,SAT",
        "calls": [
          {
            "method": "Switch.Set",
            "params": {
              "id": 0,
              "on": false
            }
          }
        ]
      },
      {
        "id": 2,
        "enable": true,
        "timespec": "0 30 19 * * MON,TUE,WED,THU,FRI",
        "calls": [
          {
            "method": "Switch.Set",
            "params": {
              "id": 0,
              "on": true
            }
          }
        ]
      }
    ],
    "rev": 4
  }
}

Schedule.List Mos Response

{
  "jobs": [
    {
      "id": 1,
      "enable": true,
      "timespec": "0 0 8 * * SUN,MON,TUE,WED,THU,FRI,SAT",
      "calls": [
        {
          "method": "Switch.Set",
          "params": {
            "id": 0,
            "on": false
          }
        }
      ]
    },
    {
      "id": 2,
      "enable": true,
      "timespec": "0 30 19 * * MON,TUE,WED,THU,FRI",
      "calls": [
        {
          "method": "Switch.Set",
          "params": {
            "id": 0,
            "on": true
          }
        }
      ]
    }
  ],
  "rev": 4
}

Schedule.Delete example

Schedule.Delete HTTP GET Request

http://192.168.33.1/rpc/Schedule.Delete?id=3

Schedule.Delete Curl Request

curl -X POST -d '{"id":1,"method":"Schedule.Delete","params":{"id":3}}' http://${SHELLY}/rpc

Schedule.Delete Mos Request

mos --port ${PORT} call Schedule.Delete '{"id":3}'

Response

Schedule.Delete HTTP GET Response

{
  "rev": 11
}

Schedule.Delete Curl Response

{
  "id": 1,
  "src": "shellyplus1-a8032abe54dc",
  "params": {
    "rev": 11
  }
}

Schedule.Delete Mos Response

{
  "rev": 11
}

Schedule.DeleteAll example

Schedule.DeleteAll HTTP GET Request

http://192.168.33.1/rpc/Schedule.DeleteAll

Schedule.DeleteAll Curl Request

curl -X POST -d '{"id":1,"method":"Schedule.DeleteAll"}' http://${SHELLY}/rpc

Schedule.DeleteAll Mos Request

mos --port ${PORT} call Schedule.DeleteAll

Response

Schedule.DeleteAll HTTP GET Response

{
  "rev": 11
}

Schedule.DeleteAll Curl Response

{
  "id": 1,
  "src": "shellyplus1-a8032abe54dc",
  "params": {
    "rev": 11
  }
}

Schedule.DeleteAll Mos Response

{
  "rev": 11
}

Schedule.Eval example

Schedule.Eval HTTP GET Request

http://192.168.33.1/rpc/Schedule.Eval?timespec="0 0 8 * * MON,TUE,WED,THU,FRI"&now=1704067200

Schedule.Eval Curl Request

curl -X POST -d '{"id":1,"method":"Schedule.Eval","params":{"timespec":"0 0 8 * * MON,TUE,WED,THU,FRI","now":1704067200}}' http://${SHELLY}/rpc

Schedule.Eval Mos Request

mos --port ${PORT} call Schedule.Eval '{"timespec":"0 0 8 * * MON,TUE,WED,THU,FRI","now":1704067200}'

Response

Schedule.Eval HTTP GET Response

{
  "now": 1704067200,
  "next": 1704153600,
  "prev": 1703836800
}

Schedule.Eval Curl Response

{
  "id": 1,
  "src": "shellyplus1-a8032abe54dc",
  "params": {
    "now": 1704067200,
    "next": 1704153600,
    "prev": 1703836800
  }
}

Schedule.Eval Mos Response

{
  "now": 1704067200,
  "next": 1704153600,
  "prev": 1703836800
}