Guides

Scripting on Gen2+

Gen2+ devices can run their own JavaScript locally, without the cloud and without the app's scenes. This is for when scenes aren't enough.

Scenes in the app cover most of it. But they have a ceiling: conditional logic, custom calculations, calls to services outside Shelly's ecosystem — a scene can't do any of that. That's where scripts take over.

What a script is

Gen2+ devices (Plus, Pro, Gen3 and Gen4) can run JavaScript directly on the device. Not in the cloud, not in the app — the code lives and runs inside the switch or relay itself. According to Shelly's official documentation, scripts run on a modified, embedded-optimized version of Espruino: a JavaScript-like language, but not a full implementation of the standard.

Gen1 cannot run scripts. If you have a Shelly 1, Shelly 2.5, or another Gen1 device, this guide stops being relevant to you — see Which generation do you have? if you're not sure what you own.

Why run a script instead of a scene

The big win is that a script keeps working even if the internet or Shelly's cloud is down — the logic lives locally on the device. Beyond that, scripts can do things scenes can't:

• Custom conditions and calculations (not just "if A then B", but real logic)
• HTTP requests to other systems, and your own HTTP endpoints that other systems can call
• MQTT publishing
• Creating and controlling virtual components (virtual switches, sensors)
• Reading and parsing data from Bluetooth devices (BLU products, for example) and triggering actions from it

Where you write them

In the device's own web interface, not in the app. Go to the device's local address → Scripts in the sidebar → Create script. Write your code there, save it, and press Start to run it. If you want the script to start automatically every time the device reboots, switch that on separately in the script list.

A minimal example, just to show the shape of it:

let info = Shelly.getDeviceInfo();
console.log("Firmware:", info.ver);

Limitations worth knowing

This isn't Node.js in miniature. Per the official documentation, among other things:

• Max 5 timers, 5 event subscriptions, 5 status subscriptions and 5 RPC calls per script
• No ES6 classes, no Promise or async/await
• Strings are handled as byte sequences, not full Unicode — source code should be UTF-8, but \uHHHH escapes aren't supported
• The script shares CPU time with the rest of the firmware and must not block for long — an infinite loop can crash the device

Being honest about what this is

This chapter is enough to understand what scripts are and get started. It doesn't replace the reference documentation. If you're writing anything more than a couple of lines, go to shelly-api-docs.shelly.cloud for the full API reference and language description.

Scripting is aimed at advanced users. If you haven't written JavaScript before, or you're fine with what scenes can already do, there's rarely a reason to start here.