Skip to main content
Documentation Hub

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 allows seamless automation for 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.

Else, please read on.

Features of Scheduling​

  • Perform an action at a given absolute time with configuration for:
    • One time (Eg. 6:30pm)
    • Repeat on specific day(s) of the week (Eg. 6:30pm on Mon, Tue, Sat)
    • Repeat on specific date(s) of specified month(s) (Eg. 6:30pm 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)
  • 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 Day Light Savings (DST) offsets as applicable for the configured timezone. Check Managing Daylight Saving Time (DST) section 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 (Click to view)
{
    "name": "Schedule",
    "params": [{
        "bounds": {
            "max": 5
        },
        "data_type": "array",
        "name": "Schedules",
        "properties": [
            "read",
            "write"
        ],
        "type": "esp.param.schedules"
    }],
    "type": "esp.service.schedule"
}

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

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.

JSON Payload (Click to 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

  • 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.
  • triggers (array of objects): The time at which the schedule should trigger. Either "m" or "rsec" should be provided.
    • m (uint16): Minutes since midnight. Eg. 6:30pm = 18 * 60 + 30 = 1110. Either "d" or "dd" should be provided.
      • d (uint8): Bitmap for days. LSB is Monday. [ N/A | Sunday | Saturday | Friday | Tuesday | Wednesday | Tuesday | Monday ]. Eg. 0b00011111 (31) means all weekdays. A value of zero means trigger just once.
      • dd (uint8): Date (1-31).
      • mm (uint16, Optional) : Bitmap for months. LSB is January. Eg.0b00000111 (7) means Jan, Feb, Mar.
        • yy (uint16, Optional) : Year. Eg. 2023.
        • r (bool, Optional): true for repeating every year.
  • rsec (int32): Relative seconds starting from now. There is no day/date setting for this. Either "m" or "rsec" should be provided.
  • 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.

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 (Click to 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.

To 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 (Click to view)
{
    "Schedule": {
        "Schedules": [{
            "id": "8D36",
            "operation": "remove"
        }]
    }
}

Enable/Disable​

  • The payload is very similar to 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 (Click to view)
{
    "Schedule": {
        "Schedules": [{
            "id": "8D36",
            "operation": "disable"
        }]
    }
}

Passing operation as "enable" will re-enable the schedule.

Note

A one-time schedule automatically gets disabled after it has executed.

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, click here.

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. Click here 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.

Let us 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, what happens during the DST switch is something to be considered.
  • Let's now see what happens to schedules during the switch:
Scheduled TimeDST Begins
(spring forward from 2:00 to 3:00)		DST Ends
(move back from 2:00 to 1:00)
12:59 a.m. and earlierNo changeNo change
1:00 a.m. to 1:59 a.m.No changeTriggered 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 switchNo change
3:00 a.m. and laterNo changeNo change

On this page