Scheduling

about

The Internet of Things (IoT) primarily involves devices connected to the Internet, enabling data exchange such as telemetry and commands. However, many applications require automation where devices can operate independently.

In line with the rest of the ESP RainMaker features, scheduling has been implemented completely on the node side in the form of a "service". The cloud backend just acts as a gateway between the node and the clients (like Phone apps).

The entire complexity of the scheduling feature is hidden beneath a simple C API and also abstracted out by the phone apps.

Use Case

ESP RainMaker’s scheduling feature enables automated control of devices based on predefined times, enhancing convenience and energy efficiency. Users can set schedules for tasks like turning lights on at 6 p.m. and off at 11 p.m. without manual intervention. This enables seamless automation in smart homes and industrial setups, optimizing power usage.

Before proceeding

If you are already familiar with the feature scheduling in ESP RainMaker, please proceed to the usage guides.

For the usage of scheduling on the firmware, click here.
On what to note for Schedules Across Nodes for phone apps, click here.

Otherwise, please continue reading.

Features of Scheduling

Perform an action at a given absolute time with configuration for:
- One time (Eg., 6:30 pm)
- Repeat on specific day(s) of the week (Eg. 6:30 pm on Mon, Tue, Sat)
- Repeat on specific date(s) of specified month(s) (Eg. 6:30 pm on 20th of Jan, Aug, Dec)
- Repeat every year (Eg. 6:30 pm of 20th Jan every year)
Perform an action after a specified period of time (Eg. 3 hours from now)
Daylight Schedules (Sunrise/Sunset): Schedule device actions based on astronomical calculations for sunrise and sunset times with configurable offsets (Eg. 30 minutes before sunset, at sunrise)
Extensible by adding custom info and flags to help apps identify and segregate different types of schedules (Eg. pre-defined schedules, default on-off schedules, etc.)
Handling of Daylight Saving Time (DST) offsets as applicable for the configured timezone; see Managing Daylight Saving Time (DST) for more information

Important

Scheduling comes hand in hand with time service. Therefore, it is mandatory to set up and configure time service. If not schedule will not trigger.

Specifications

The scheduling service consists of a single parameter which is an array of objects. Enabling the feature adds the following service in the node configuration:

JSON Payload (Toggle View)

{
    "name": "Schedule",
    "params": [{
        "bounds": {
            "max": 5
        },
        "data_type": "array",
        "name": "Schedules",
        "properties": [
            "read",
            "write"
        ],
        "type": "esp.param.schedules"
    }],
    "type": "esp.service.schedule",
    "daylight_support": "yes"
}

The schedule parameter is an empty array by default. The max bound indicates the maximum number of schedules a node can have.

The daylight_support attribute indicates if daylight (sunrise/sunset) schedules are supported. This enables client applications to discover this capability.

Add a New Schedule

A new schedule can be added by passing a value like this in setparams. This is usually sent from the client side to the cloud or directly to the node via local control.

ESP RainMaker supports three types of schedule triggers:

Time-based Schedules: Use m (minutes since midnight) with day/date patterns
Relative Schedules: Use rsec (relative seconds from now)
Daylight Schedules: Use sr (sunrise) or ss (sunset) with location data (Available from v1.7.1)

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "name": "Evening",
            "id": "8D36",
            "operation": "add",
            "triggers": [{
                "d": 31,
                "m": 1110
            }],
            "action": {
                "Light": {
                    "power": true
                }
            }
        }]
    }
}

Detailed explanation of each JSON Key within the payload

Common Fields (All Schedule Types)

name (string): A user friendly name for the schedule.
id (string): A unique ID for the schedule. (This needs to be unique only for the given user not universally unique). This should be generated by the client while adding a schedule, and then used for any further operations. A shorter ID is desirable.
operation (string): The operation to be performed. Possible values are add, remove, edit, enable and disable.
action (object): The actual action to be performed at the given time. The value of this object will be same as what you pass while setting the params. Eg. For turning on Light, it will be "Light": {"power": true}.
info (string, Optional): Additional info or description as per the clients' requirements.
flags (uint32, Optional): General purpose flags (unsigned integer value) which can be used as per the clients' requirements.
validity (object, Optional): To provide a start and end time between which the schedule should be applicable.
- start (uint32): Start time (epoch seconds) from which the schedule should be active.
- end (uint32): End time (epoch seconds) after which the schedule should be inactive.

Trigger Types

The triggers array contains objects that define when the schedule should execute. Choose one of the following trigger types:

1. Time-based Triggers (Absolute Time)

m (uint16): Minutes since midnight. Eg. 6:30pm = 18 × 60 + 30 = 1110.
d (uint8, Optional): Bitmap for days of week. LSB is Monday.
- Bit pattern: [ N/A | Sunday | Saturday | Friday | Thursday | Wednesday | Tuesday | Monday ]
- Examples: 31 (0b00011111) = weekdays, 96 (0b01100000) = weekends, 127 = every day
- Value of 0 means trigger just once
dd (uint8, Optional): Date (1-31) for specific date scheduling.
mm (uint16, Optional): Bitmap for months. LSB is January.
- Examples: 7 (0b00000111) = Jan, Feb, Mar; 4095 (0b111111111111) = all months
- Important: If mm is specified, either yy or r must be provided
yy (uint16, Optional): Specific year (e.g., 2023). Required if mm is used without r.
r (bool, Optional): Set to true for repeating every year (used with dd and optionally mm). Required if mm is used without yy.

2. Relative Triggers (Time from Now)

rsec (int32): Relative seconds starting from now. No day/date settings apply for this type.

3. Daylight Triggers (Sunrise/Sunset) Available from v1.7.1

sr (int16): Sunrise offset in minutes (positive = after, negative = before, 0 = exact sunrise).
ss (int16): Sunset offset in minutes (positive = after, negative = before, 0 = exact sunset).
lat (float): Latitude in decimal degrees (-90 to +90, positive for North).
lon (float): Longitude in decimal degrees (-180 to +180, positive for East).
loc (string, Optional): Human-readable location name for reference.
d (uint8, Optional): Day pattern bitmap (same as time-based triggers).
ts (uint32, Auto-calculated): Next trigger timestamp (automatically calculated by the system). Should not be provided by the client.

Trigger Rules

Use only one trigger type per trigger object: m, rsec, or sr/ss
For time-based triggers: Either d (days) or dd (date) should be provided with m
For date-based triggers: If mm (months) is specified, either yy (year) or r (repeat yearly) must be provided
For daylight triggers: Either sr (sunrise) or ss (sunset) should be provided, not both
Geographical coordinates (lat, lon) are mandatory for daylight triggers

Once the schedule is added successfully, a get on params will report a similar value as shown in JSON payload below:

This is an acknowledgment response sent from the node to the cloud or to the phone app.

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "name": "Evening",
            "id": "8D36",
            "enabled": true,
            "triggers": [{
                "d": 31,
                "m": 1110
            }],
            "action": {
                "Light": {
                    "power": true
                }
            }
        }]
    }
}

As you can see, the response includes an enabled key, which indicates that the schedule is now enabled.

Note

While adding or updating schedules, a single entry is sent in the schedules array. However, when queried, the node will return information of all the schedules in the array.

Other Operations

All of the following operations are done on the client side like on a phone app.

Edit

Value passed for editing the schedule will be similar to that passed for adding a new schedule.
The ID should match an existing schedule and the operation value will be edit.
You can either send the entire object or only the elements that have changed (name, trigger or action). However, the objects in these keys cannot be partial.

example

If current action is "action":{"Light": {"power": true, "brightness":90}};
And you need to change brightness to 100;
You should pass...
✓ "action":{"Light": {"power": true, "brightness":100}} not
✗ "action":{"Light": {"brightness":100}}

Remove

For removing an existing schedule, you just need to pass its ID and the operation. An example is provided below.

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "id": "8D36",
            "operation": "remove"
        }]
    }
}

Enable/Disable

The payload is very similar to that of the remove operation. This is useful when you have to temporarily disable a schedule instead of removing it. An example is provided below.

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "id": "8D36",
            "operation": "disable"
        }]
    }
}

Passing operation as enable will re-enable the schedule.

Note

A one-time schedule is automatically disabled after execution.

Schedule Examples

This section provides comprehensive examples for all three types of schedule triggers supported by ESP RainMaker.

1. Day-of-Week Schedules (d-based)

These schedules use the d parameter to specify which days of the week the schedule should trigger.

Example: Weekday Morning Alarm

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "name": "Weekday Alarm",
            "id": "WD01",
            "operation": "add",
            "triggers": [{
                "m": 420,
                "d": 31
            }],
            "action": {
                "Light": {
                    "Power": true,
                    "Brightness": 100
                },
                "Buzzer": {
                    "Power": true
                }
            }
        }]
    }
}

This schedule triggers at 7:00 AM (420 minutes) on weekdays only (d=31: Mon-Fri).

Example: Weekend Evening Lights

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "name": "Weekend Evening",
            "id": "WE01",
            "operation": "add",
            "triggers": [{
                "m": 1140,
                "d": 96
            }],
            "action": {
                "Light": {
                    "Power": true,
                    "Brightness": 60
                }
            }
        }]
    }
}

This schedule triggers at 7:00 PM (1140 minutes) on weekends only (d=96: Sat-Sun).

2. Specific Date Schedules (dd-based)

These schedules use the dd parameter for specific dates, optionally with mm (months) and yy (year) or r (repeat yearly).

Important

When using mm (month bitmap), you must also provide either yy (specific year) or r: true (repeat yearly). This combination is mandatory.

Example: Monthly Report on 1st

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "name": "Monthly Report",
            "id": "MR01",
            "operation": "add",
            "triggers": [{
                "m": 540,
                "dd": 1,
                "mm": 4095,
                "r": true
            }],
            "action": {
                "Sensor": {
                    "Report": true
                }
            }
        }]
    }
}

This schedule triggers at 9:00 AM on the 1st of every month, repeating yearly (mm=4095: all months, r=true).

Example: Quarterly Maintenance

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "name": "Quarterly Maintenance",
            "id": "QM01",
            "operation": "add",
            "triggers": [{
                "m": 600,
                "dd": 15,
                "mm": 273,
                "r": true
            }],
            "action": {
                "System": {
                    "Maintenance": true
                }
            }
        }]
    }
}

This schedule triggers at 10:00 AM on the 15th of Jan, Apr, Jul, Oct every year (mm=273: 0b100010001, r=true).

Example: Specific Year Event

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "name": "New Year 2024",
            "id": "NY24",
            "operation": "add",
            "triggers": [{
                "m": 0,
                "dd": 1,
                "mm": 1,
                "yy": 2024
            }],
            "action": {
                "Light": {
                    "Power": true,
                    "Brightness": 100,
                    "Color": "rainbow"
                }
            }
        }]
    }
}

This schedule triggers at midnight on January 1st, 2024 only (one-time event).

3. Daylight Schedules (sr/ss-based) Available from v1.7.1

These schedules use astronomical calculations for sunrise (sr) and sunset (ss) times based on geographical location.

Example: Sunrise Garden Watering

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "name": "Morning Garden Water",
            "id": "SR01",
            "operation": "add",
            "triggers": [{
                "sr": 30,
                "lat": 37.7749,
                "lon": -122.4194,
                "loc": "San Francisco",
                "d": 127
            }],
            "action": {
                "Sprinkler": {
                    "Power": true,
                    "Duration": 600
                }
            }
        }]
    }
}

This schedule starts garden watering 30 minutes after sunrise, every day, in San Francisco.

Example: Sunset Security Lights

JSON Payload (Toggle View)

{
    "Schedule": {
        "Schedules": [{
            "name": "Security Lights",
            "id": "SS01",
            "operation": "add",
            "triggers": [{
                "ss": -15,
                "lat": 51.5074,
                "lon": -0.1278,
                "loc": "London",
                "d": 31
            }],
            "action": {
                "Security_Light": {
                    "Power": true,
                    "Brightness": 80
                }
            }
        }]
    }
}

This schedule turns on security lights 15 minutes before sunset, on weekdays only, in London.

Day Pattern Reference

For quick reference, here are common day pattern values for the d parameter:

Pattern	Value	Binary	Description
Monday only	1	0b0000001
Tuesday only	2	0b0000010
Wednesday only	4	0b0000100
Thursday only	8	0b0001000
Friday only	16	0b0010000
Saturday only	32	0b0100000
Sunday only	64	0b1000000
Weekdays	31	0b0011111	Mon-Fri
Weekends	96	0b1100000	Sat-Sun
Every day	127	0b1111111	All days
One-time	0	0b0000000	Execute once

Daylight Schedule Configuration

Configuration Requirements for Daylight Schedules:

Enable Feature: Set CONFIG_ESP_SCHEDULE_ENABLE_DAYLIGHT and CONFIG_ESP_RMAKER_SCHEDULE_ENABLE_DAYLIGHT to enable daylight schedules
Flash Usage: requires approximately 15KB of flash space when enabled
Location Data: Requires geographical coordinates (latitude/longitude) for calculations
Time Service: Must have time service properly configured

Configuration Note

The daylight schedule configuration should be added to your firmware project. See the Firmware Usage Guide for detailed setup instructions.

Usage Guide

Firmware

This usage guide would mainly cover the firmware side of setup and configuration for scheduling. For instructions on how to do this, see Firmware Usage Guide.

Phone Apps

The phone applications provide a very simple user interface for various scheduling operations. Please update your phone apps, enable scheduling in the firmware, and get started.

Schedules Across Nodes
For schedules across multiple nodes, the client assigns a common schedule ID across nodes so that it can query and group them as a unified schedule. See Scheduling Usage Guide (Phone Apps) to view more information and an example.

Managing Daylight Saving Time (DST)

Normally, when daylight saving time (DST) starts, the clocks are moved forward by 1 hour and when it ends, they are moved back by 1 hour.

Take America/Los_Angeles timezone as an example

Reference: Wikipedia: In the U.S., daylight saving time starts on the second Sunday in March and ends on the first Sunday in November, with the time changes taking place at 2:00 a.m. local time. With a mnemonic word play referring to seasons, clocks "spring forward, fall back"—that is, in springtime the clocks are moved forward from 2:00 a.m. to 3:00 a.m. and in fall they are moved back from 2:00 a.m. to 1:00 a.m.

On all the days apart from the ones at which the DST switch takes place, the schedule will trigger at the correct scheduled time, since the node automatically adjusts its clock as per the DST info for the specified timezone.
However, special consideration is needed during the DST switch.
Let’s review how schedules behave during the switch:

Scheduled Time	DST Begins (spring forward from 2:00 to 3:00)	DST Ends (move back from 2:00 to 1:00)
12:59 a.m. and earlier	No change	No change
1:00 a.m. to 1:59 a.m.	No change	Triggered only once before the switch. Not triggered again the second time after the switch
2:00 a.m. to 2:59 a.m.	Delayed by 1hr. Triggered from 3:00 to 3:59 a.m. instead, on the day of switch	No change
3:00 a.m. and later	No change	No change

Use Case​

Features of Scheduling​

Specifications​

Add a New Schedule​

Common Fields (All Schedule Types)​

Trigger Types​

1. Time-based Triggers (Absolute Time)​

2. Relative Triggers (Time from Now)​

3. Daylight Triggers (Sunrise/Sunset) Available from v1.7.1​

Other Operations​

Edit​

Remove​

Enable/Disable​

Schedule Examples​

1. Day-of-Week Schedules (d-based)​

Example: Weekday Morning Alarm​

Example: Weekend Evening Lights​

2. Specific Date Schedules (dd-based)​

Example: Monthly Report on 1st​

Example: Quarterly Maintenance​

Example: Specific Year Event​

3. Daylight Schedules (sr/ss-based) Available from v1.7.1​

Example: Sunrise Garden Watering​

Example: Sunset Security Lights​

Day Pattern Reference​

Daylight Schedule Configuration​

Usage Guide​

Firmware​

Phone Apps​

Managing Daylight Saving Time (DST)​

Use Case

Features of Scheduling

Specifications

Add a New Schedule

Common Fields (All Schedule Types)

Trigger Types

1. Time-based Triggers (Absolute Time)

2. Relative Triggers (Time from Now)

3. Daylight Triggers (Sunrise/Sunset) Available from v1.7.1

Other Operations

Edit

Remove

Enable/Disable

Schedule Examples

1. Day-of-Week Schedules (d-based)

Example: Weekday Morning Alarm

Example: Weekend Evening Lights

2. Specific Date Schedules (dd-based)

Example: Monthly Report on 1st

Example: Quarterly Maintenance

Example: Specific Year Event

3. Daylight Schedules (sr/ss-based) Available from v1.7.1

Example: Sunrise Garden Watering

Example: Sunset Security Lights

Day Pattern Reference

Daylight Schedule Configuration

Usage Guide

Firmware

Phone Apps

Managing Daylight Saving Time (DST)