Create Scene

The scene represents some action that the user sets. Scenes are used for home automation. We can create a scene in two ways:

• Template Scene - using JavaScript code
• Manual Scene - using the UI

Creating

Script Scene

First we add a name for the scene. We can create out own name or use a template.

Examples:

• Air condition heating
• Auto power save
• Smart curtain controller
• Motion Light

and many others

Every template has a short description about the processes it executes.

Scene parts:

Scenes are allowed to be executed in specific intervals:

• Day(s) of the week (Monday - Sunday)
• Time interval
  • Start time - (00:00 - 23:59)
  • End time - (00:00 - 23:59)

⚠️ CAUTION At least 1 day must be selected. Time interval must be at least 1 minute long.

If all of the previos steps are completed, script is generated.

const params = {
  // add parameters here
};

function init() {
  // initialization
}

function when() {
  // check if parameters meet a condition
}

function doBlock() {
  // trigger action when a condition is met
}

Functions

init() - Initialization of the scene. Happens once.

when() - Defines the condition under which the automation should run.

doBlock() - Triggers the action if when() is true.

Manual Scene

We start with adding a condition (rule that must be true to run an action)

There are several conditions between which the user can choose:

We can add conditions and combine them with AND/OR.

Then we add actions:

Scenes are allowed to be executed in specific intervals:

• Day(s) of the week (Monday - Sunday)
• Time interval
  • Start time - (00:00 - 23:59)
  • End time - (00:00 - 23:59)

⚠️ CAUTION At least 1 day must be selected. Time interval must be at least 1 minute long.

More options:

• Enable scene - if a scene is disabled it can be enabled only manually
• Execute the scene on save or edit - used for testing

Select a room (“folder” that groups devices by their physical location)

Details:

• Scene name
• Select picture - from your device or a default picture

Script Structure

What is a script

The script represents a JavaScript program that runs on the Shelly device (or in your Shelly environment) to create custom automation.

With scripts you can do things like:

• React to events (button press, power change, sensor value)
• Make logic like if/else, timers

The program contains 3 functions:

• init()
• when()
• doBlock()

Functions

init()

This is the script’s startup function. When the script is started, init() is called first to:

• Read your parameters/constants
• Set initial state/variables
• Register event handlers (button/input, power change, etc.)
• Start timers/intervals (periodic checks)

when()

Returns true when the parameters meet a given condition/event.

doBlock()

Runs if the when() block returned true. doBlock() triggers a defined action when the condition(s) is met.

Parameters and variables

You can have params block. This is where the scene/script stores user-editable settings in one place.

const params = {
  maxTemp: 25,
  minTemp: 22,
};

The script then reads these values in when() and doBlock().

Variables are used to store and reuse values.

Why they matter:

• Readability - meaningful names make code easier to understand
• Reuse - avoid repeating the same value/device ID many times
• State - keep memory (last temp, armed status, last run time)
• Flexibility - change one variable and the whole logic updates.

Creating a Script

You can create a script in 3 different ways. For the first 2 ways - “Create with your own name” and “Use a template” you press the JS button is the navigation menu.

1. Create with your own name

In the modal you enter a name for the script.

You start a blank script where you write/paste your code. Best for custom logic and advanced automations.

2. Use a template

In the modal you pick a ready-made example.

After you picked a template, you need to choose a room and devices to use.

Then you choose a time interval where the script is active

Then your example is ready and you can adjust the values or keep it as it is. This is the fastest way to get a working baseline.

3. Convert a Scene to a script

The app generates a script from an existing scene, so you can extend it with more complex logic (variables, loops, extra conditions).

First, you select the scene you want to convert. Second, on the right menu you press this button <>. A button for converting appears.

When you press it an alert for confirmation is displayed at the top of the screen.

Script Templates

We use templates to create a script because they give a working starting point

Main benefits:

• Faster setup - no need to write everything from scratch.
• Fewer mistakes - structure, events, and timers are already correct.
• Best practices included - common patterns (overheat protection, delays, retries).
• Easy to customize - you usually only change a few values (device ID, temperature/power limits, timeouts).

When you press the JS button in the All Scenes screen a modal pops up.

Templates

Air condition heating - turns AC on/off based on room temperature.

Auto power saver - turns off house lights and AC when the main door is closed.

Smart curtain controller - opens or closes the curtains based on light levels.

Humidy regulator - turns the humidifier on when the air is too dry and off when humidity rises above the ideal range.

Motion light - turns the light on when motion is detected.

Mourning routine starter - turns on the kitchen light and coffee machine at 7:00 AM on weekdays.

Night power saver - turns off the TV and AC during late-night hours when no motion is detected.

Window alert - sends a phone notification whenever the window is opened.

Smart AC controller - turns on the AC when it’s hot, but only if the window is closed, and turns if off when the temperature drops.

Auto power saver with motion - turns TV, lights and AC off when there is no motion in living room and bedroom for 15 minutes. If motion is detected again after 18:00, the lights turn on.

Window aware heating - turns heating on when temperature is below threshold and all windows are closed.

Weekday morning starter - turns on the kitchen light and coffee machine at 7:00 AM on weekdays. If it’s dark and someone is at home - both turn on; if it is bright - only the coffee machine turns on.

Night motion control - turns off lights and AC between 00:00 and 05:00 if there is no motion. If motion is detected during this period, only the hallway light turns on, while AC stays off.

Smart bathroom heating - controls bathroom heating based on temperature and motion. If temperature falls below 20°C and motion is detected - heating turns on.

Smart entry control - controls hallway light and TV based on door opening time and room motion.

Smart hallway lighting - turns on hallway light when motion is detected and it is dark. The light stays on for 5 minutes, then turns off if no further motion is detected.

Smart pool heating - controls pool heating based on water temperature and pump status.

Garage motion light - controls garage light based on two motion sensors. If either motion sensor detects movement - light turns on.

Button door control - controls doors based on button presses. If any button is pressed twice - front door closes. If any button is pressed three times - garage door opens.

Car charge status - sends notifications based on car charging status using power meter.

AC window control - controls AC based on window status and temperature. If AC is on and the window opens - AC turns off and a notification is send.

Morning temp control - controls kitchen heating based on morning temperature.

Motion aware living room - turns on living room light based on motion and light.

Evening heating control - controls evening heating based on temperature and window status.

Night auto-off and coridor light - turns off TV and AC if there is no motion at night for at least 15 minutes. Turns on corridor light if motion is detected.

Script Page Buttons

On this page you have 2 buttons:

• Add - creates a new script entry on the device, so you can name it and start editing/importing code
• Save - saves the current script (or any edits you made) so it’s stored on the device/app

You can add one of the following entries:

• Device - first select a room where you want the device to be and then select the device. The selection for both is made via a drop-down list.This creates a variable with an id that corresponds to the selected device.
• Nested scene - this allows us to use scenes in the code. A variable for the scene is created.
• Alarm - allows creating an alarm variable. To use an alarm, you must have created it.
• Group - adds a group (multiple devices combined together) variable. The difference between the group variable and the other variables is that the group id is an integer, while the others are a string.
• Condition - the condition type accepts two values ​​- device or time
• Action - creates an automation action that runs when a condition is met
• Active time - sets a time window when an action is allowed to run. Outside the window, the action wont’t execute
• Global variable - creates a named value which is used to store state or reuse value
• Solar condition - adds a condition that can be used to decide when an action should run. Example - only when there is solar surplus / production is high (run boiler/heater only on surplus)

Device

Devices are added as variables and can be used anywhere in the script

Nested scene

Nested scenes are added as variables and can be used anywhere in the script

Alarm

Alarms are added as variables and can be used anywhere in the script

Group

Groups are added as variables and can be used anywhere in the script

Condition

Device types

Then a comparator (comparison operator) is used to check whether the condition meets a specified value (in %).

The property is watched as a trigger or a condition

Property as a Trigger

Trigger is the event that starts an automation running. You can choose one of the following trigger cases:

• Condition (check)
• DeviceTrigger on any change (check)
• DeviceTrigger once with value (check)
• DeviceTrigger once with hold off (check, holdOff)
• Repeated DeviceTrigger (check)

The trigger is initialized in the init() function. when() checks whether the condition is met and returns true/false

Property as a Condition

Checks a specific device parameter and triggers an action only if it matches a rule

Action

Has 3 condition types

Actions are added to the doBlock() function.

Device actions set values to parameters:

fridge.on = {
  value: true,
  timeout: { wait: 45, unit: "seconds" },
  delay: { wait: 5, unit: "seconds" },
};

Only relays have timeout

While scene actions and notification actions call functions with 1 or more parameters passed to the function:

Scene action:

myTestScene.runDo();

Notification action:

sceneUtils.logActivity(message);

Active time

You set an interval in which an action can be performed. First select a day(s) of the week using a checkbox.

⚠️ At least 1 day must be selected.

Then a start and end time interval is selected.

⚠️ The interval must be at least 1 minute

Active time is initialized in the init() function

Global variable

Global variables are persistent values that the script can save and reuse (even after reboot). These variables can have 1 of the 2 types:

The variable has a name and is added to a block.

If the type is Get it can be used in:

• When
• Do
• Else

If the type is Set you add a value to the variable. If no value is entered, the variable is undefined

Variables with type Set can be used in:

• Init
• When
• Do
• Else

When a variable is first defined, by default it is initialized in the init block

Solar condition

This is a sun event-based trigger using your location.

Fields

• Event - what solar moment triggers it (sunrise or sunset)
• Direction - wheter it is before or after a given position of the sun
• Time - an offset from the event

This event is added to the init block with its parameters

Scene examples

Here are some examples of scenes created using templates. Templates are easy to use and they give a working starting point.

First example

Automatically turns on the kitchen light and coffee machine at 7:00 AM on weekdays.

// Generated Parameters
const params = {};

var kitchenLight = deviceFactory.getDevice("use_id_here"); // Light
var coffeeMachine = deviceFactory.getDevice("use_id_here"); // Coffee

function init() {
  sceneUtils.setActiveTime({
    start: "00:00",
    duration: "1439",
    days: [1, 2, 3, 4, 5, 6, 7],
  });
}

function when() {
  return sceneUtils.checkSchedule("07:00", [1, 2, 3, 4, 5]);
}

function doBlock() {
  kitchenLight.on = true;
  coffeeMachine.on = true;
}

Summary

Every Monday–Friday at 07:00 AM, it turns Kitchen Light = ON and Coffee Machine = ON.

How it works

• deviceFactory.getDevice() - creates references to your two target devices (you must replace with real IDs).
• init() - sets the automation Active time to the whole day - 1439 minutes (00:00 - 23:59) and all days (Monday - Sunday).
• when() - returns true when the schedule matches 07:00 AM on workdays (Monday-Friday).
• doBlock() - runs if when() is true; turns ON both devices.

Second example

Automatically turns the light on when motion is detected in low light conditions and turns it off when no motion is detected.

// Generated Parameters
const params = {
  illuminanceValue: 50,
};

var light = deviceFactory.getDevice("use_id_here"); // Color Light
var motionSensor = deviceFactory.getDevice("use_id_here"); // Motion Sensor

function init() {
  motionSensor.setTriggerOnAnyChange("motion");
  motionSensor.setRepeatedTrigger("illuminance < " + params.illuminanceValue);
  sceneUtils.setActiveTime({
    start: "18:00",
    duration: "720",
    days: [1, 2, 3, 4, 5, 6, 7],
  });
}

function when() {
  return (
    motionSensor.motion && motionSensor.illuminance < params.illuminanceValue
  );
}

function doBlock() {
  if (light.off) {
    light.on = true;
  } else if (motionSensor.noMotion) {
    light.off = true;
  }
}

Summary

The script is active between 18:00 and 06:00 (720 min), every day. If motion is detected and illuminance < 50 → turns the light ON. When the sensor reports noMotion → turns the light OFF.

How it works

• params.illuminanceValue sets the darkness threshold (50).
• init():
  • setTriggerOnAnyChange(“motion”) reacts to motion state changes
  • setRepeatedTrigger(“illuminance < 50”) keeps triggering while it’s dark
  • setActiveTime limits execution to 18:00–06:00 daily
• when() - returns the result from:
  • motion == true AND illuminance < 50
• doBlock() - turns ON if currently off; otherwise, if noMotion, turns OFF.

Third example

Turns off house lights and AC automatically when the main door is closed.

// Generated Parameters
const params = {};

var mainDoor = deviceFactory.getDevice("use_id_here"); // Stove
var houseLights = deviceFactory.getDevice("use_id_here"); // Color Light
var ac = deviceFactory.getDevice("use_id_here"); // Air conditioner

function init() {
  mainDoor.setTriggerOnce("closed");
  sceneUtils.setActiveTime({
    start: "00:00",
    duration: "1439",
    days: [1, 2, 3, 4, 5, 6, 7],
  });
}

function when() {
  return houseLights.on || ac.on;
}

function doBlock() {
  houseLights.off = true;
  ac.off = true;
}

Summary

A trigger is set when the door is closed. This turns OFF the house lights and the ac. The script is active from 00:00 to 23:59, Monday-Sunday

How it works

• init():
  • setTriggerOnce(“closed”) - runs the automation once each time the door reports “closed”
  • setActiveTime - enables it 00:00–23:59 (1439 minutes), Monday-Sunday
• when() - only proceeds if either lights or ac are currently ON (avoids pointless actions).
• doBlock() - forces both devices to OFF.

Fourth example

Automatically turns AC on/off based on room temperature.

// Generated Parameters
const params = {
  maxTemp: 25,
  minTemp: 22,
};

var ac = deviceFactory.getDevice("use_id_here"); // Air conditioner
var tempSensor = deviceFactory.getDevice("use_id_here"); //Livingroom Temperature

function init() {
  sceneUtils.setActiveTime({
    start: "00:00",
    duration: "1439",
    days: [1, 2, 3, 4, 5, 6, 7],
  });
  tempSensor.setRepeatedTrigger("temperature < " + params.minTemp);
  tempSensor.setRepeatedTrigger("temperature > " + params.maxTemp);
}

function when() {
  return (
    tempSensor.temperature < params.minTemp ||
    tempSensor.temperature > params.maxTemp
  );
}

function doBlock() {
  if (tempSensor.temperature < params.minTemp) {
    ac.on = true;
  } else if (tempSensor.temperature > params.maxTemp) {
    ac.on = false;
  }
}

Summary

Works from 00:00 to 23:59, all days.

• If room temperature < 22°C → sets AC ON.
• If room temperature > 25°C → sets AC OFF.

How it works

• params - defines thresholds:
  • minTemp=22
  • maxTemp=25
• init() - enables Active time and sets repeated triggers whenever temperature goes below/above the limits, so the automation re-evaluates automatically.
• when() - returns true if temp is outside the limits (below min OR above max).
• doBlock() - applies the action depending on which limit was crossed.