Timer

The Timer API provides scheduling capabilities for delayed and periodic code execution in Shelly scripts.

Overview

The Timer global object allows you to:

• Execute code after a delay (one-shot timers)
• Execute code periodically (repeating timers)
• Cancel scheduled timers
• Query timer information

API Reference

Timer.set()

Creates and starts a timer.

Syntax:

Timer.set(period, repeat, callback[, userdata]) -> timer_handle

Property	Type	Description
period	number	Timer period in milliseconds
repeat	boolean	If true, timer fires periodically; if false, fires only once
callback	function	Function to invoke when timer fires Property Type Description userdata any The passed userdata value
userdata	any	Optional data to pass to callback

Returns: Timer handle for use with Timer.clear() and Timer.getInfo()

Example:

// One-shot timer - executes once after 5 seconds
let oneShot = Timer.set(5000, false, function() {
    console.log("This runs once after 5 seconds");
});

// Repeating timer - executes every 2 seconds
let repeating = Timer.set(2000, true, function(ud) {
    console.log("Tick! User data:", ud);
}, "my_data");

Timer.clear()

Stops and removes a timer.

Syntax:

Timer.clear(timer_handle) -> boolean or undefined

Property	Type	Description
timer_handle	handle	Handle returned by Timer.set()

Returns:

• true if timer was active and cleared
• false if timer didn't exist
• undefined if handle was invalid

Example:

let timer = Timer.set(1000, true, function() {
    console.log("Tick");
});

// Stop the timer after 5 seconds
Timer.set(5000, false, function() {
    if (Timer.clear(timer)) {
        console.log("Timer stopped");
    }
});

Timer.getInfo()

Gets information about an active timer.

Syntax:

Timer.getInfo(timer_handle) -> object or undefined

Property	Type	Description
timer_handle	handle	Handle returned by Timer.set()

Returns: Object with timer information or undefined if invalid

Return object properties:

Property	Type	Description
interval	number	Timer interval in ms (0 if non-repeating)
next	number	Next invocation time in ms uptime

Example:

let timer = Timer.set(10000, true, function() {
    console.log("Tick");
});

let info = Timer.getInfo(timer);
console.log("Interval:", info.interval, "ms");
console.log("Next fire:", info.next, "ms uptime");
console.log("Time until next:", info.next - Shelly.getUptimeMs(), "ms");

Common Patterns

Delayed Execution

// Execute code after 3 seconds
Timer.set(3000, false, function() {
    console.log("3 seconds have passed");
    Shelly.call("Switch.Set", {id: 0, on: false});
});

Periodic Monitoring

// Check temperature every minute
Timer.set(60000, true, function() {
    let status = Shelly.getComponentStatus("temperature", 0);
    if (status && status.tC > 30) {
        console.log("Temperature alert:", status.tC, "°C");
    }
});

Timeout Pattern

let timeout = null;

function startTimeout() {
    // Cancel existing timeout if any
    if (timeout) Timer.clear(timeout);
    
    // Start new 10-second timeout
    timeout = Timer.set(10000, false, function() {
        console.log("Timeout reached!");
        timeout = null;
    });
}

// Reset timeout on activity
Shelly.addEventHandler(function(event) {
    if (event.component === "input:0") {
        startTimeout();
    }
});

Debouncing

let debounceTimer = null;

function debounce(func, delay) {
    return function() {
        if (debounceTimer) Timer.clear(debounceTimer);
        debounceTimer = Timer.set(delay, false, func);
    };
}

// Debounced function - only executes 500ms after last call
let debouncedSave = debounce(function() {
    console.log("Saving data...");
    Script.storage.setItem("data", JSON.stringify(data));
}, 500);

Self-Canceling Timer

let count = 0;
let timer = Timer.set(1000, true, function() {
    count++;
    console.log("Count:", count);
    
    if (count >= 10) {
        Timer.clear(timer);
        console.log("Timer self-canceled after 10 iterations");
    }
});

Resource Limits

• Maximum 5 timers per script
• Minimum practical interval: ~10ms (shorter intervals may impact performance)
• Timers are cleared when script stops
• Timer IDs are not preserved across reboots