Skip to main content
Version: 1.0

Shelly Scripts Overview

Shelly devices run JavaScript directly on-device for local automation and integrations—no cloud or external servers required. Scripts execute on a modified version of Espruino, providing a JavaScript environment that's close to the standard while optimized for embedded systems.

What Can Scripts Do?​

Scripts on Shelly devices can:

  • Automate device behavior - Create complex logic that responds to device events
  • Create HTTP endpoints - Turn your Shelly into a mini web server
  • Integrate with external services - Send HTTP requests, publish MQTT messages
  • Control virtual components - Create and manage virtual switches, sensors, and more
  • Process sensor data - Read from Bluetooth devices, parse data, trigger actions
  • Schedule actions - Use timers for delayed or periodic tasks

Quick Start: Your First Script​

Prerequisites​

  • A Shelly Gen2+ device (Plus or Pro series)
  • Device connected to your network
  • Device IP address (find it in your router or device's local web interface)

Step 1: Create a Script Slot​

http://192.168.33.1/rpc/Script.Create?name="my_first_script"

Response

{
  "id": 1
}

Step 2: Upload Your Code​

http://192.168.33.1/rpc/Script.PutCode?id=1&code="console.log('Hello Shelly!');\nlet temp = Shelly.getComponentStatus('temperature', 0);\nif (temp && temp.tC > 25) {\n  console.log('Temperature is', temp.tC, '°C - Too hot!');\n}"

Step 3: Start the Script​

http://192.168.33.1/rpc/Script.Start?id=1

Step 4: Enable Auto-Start (Optional)​

To make the script run automatically when the device boots:

http://192.168.33.1/rpc/Script.SetConfig?id=1&config={"enable":true}

Script Management​

For complete script management operations including:

  • Listing all scripts
  • Checking script status and errors
  • Downloading script code
  • Stopping and deleting scripts

See the Script Component documentation for all available RPC methods.

Common Script Patterns​

Respond to Button Press​

Shelly.addEventHandler(function(event) {
  if (event.component === "input:0" && event.info.event === "single_push") {
    Shelly.call("Switch.Toggle", {id: 0});
    console.log("Button pressed - toggling switch");
  }
});

Temperature-Based Automation​

// Check temperature every minute
Timer.set(60000, true, function() {
  let status = Shelly.getComponentStatus("temperature", 0);
  if (status && status.tC > 28) {
    // Turn on cooling fan
    Shelly.call("Switch.Set", {id: 0, on: true});
  } else if (status && status.tC < 25) {
    // Turn off cooling fan  
    Shelly.call("Switch.Set", {id: 0, on: false});
  }
});

Send HTTP Notifications​

function sendAlert(message) {
  Shelly.call("HTTP.Request", {
    method: "POST",
    url: "https://your-webhook.com/alert",
    body: JSON.stringify({
      device: Shelly.getDeviceInfo().id,
      message: message,
      timestamp: Date.now()
    }),
    headers: {"Content-Type": "application/json"}
  });
}

// Use it in event handlers
Shelly.addEventHandler(function(event) {
  if (event.component === "input:0" && event.info.state === true) {
    sendAlert("Motion detected!");
  }
});

Debugging​

Enable debug logs to see script output:

http://192.168.33.1/rpc/Sys.SetConfig?config={"debug":{"websocket":{"enable":true}}}

Then connect to see logs:

wscat --connect ws://YOUR_SHELLY_IP/debug/log

Community Script Examples​

The shelly-script-examples repository contains example scripts for common use cases. Here are some highlights:

BLE and Shelly BLU Integration​

ScriptDescription
ble-shelly-blu.jsUniversal BLU device scanner that decodes BTHome data and emits events for other scripts to handle
ble-events-handler.jsCompanion script that handles BLU events with configurable automations
ble-shelly-btn-gateway.jsUse Gen2 device as gateway between BLU Button and other Shelly devices

Power and Energy Management​

ScriptDescription
load-shedding.jsAutomatic load shedding based on power thresholds with Pro4PM/Pro3EM
consume-limited-power.jsStop output after consuming a set amount of energy
failure-monitor.jsAlert when load power drops to zero while switch is on

MQTT and Home Assistant​

ScriptDescription
mqtt-discovery.jsMQTT Auto Discovery for Home Assistant integration
mqtt-announce.jsGen1 MQTT format compatibility for mixed device networks

Advanced Patterns​

ScriptDescription
scene.jsScene player with sequential actions, delays, and conditions
remoterpc.jsRemote Shelly abstraction for calling RPC methods on other devices
telegram-interaction.jsTelegram bot framework with command parsing and parameter validation
router-watchdog.jsMonitor connectivity and auto-restart router on failure

LoRa Communication (Gen3+)​

ScriptDescription
lora-send-encrypted-msg.jsSend AES-encrypted messages over LoRa with checksum verification
lora-covercontrol-sender.jsRemote cover control over LoRa for long-range automation
tip

Many scripts in the repository are designed to work together. For example, ble-shelly-blu.js emits events that ble-events-handler.js can process, allowing you to separate BLE scanning from automation logic.

Getting Help​

  • Check Script.GetStatus for error information
  • Enable debug logs to see script output and errors
  • Scripts causing crashes are automatically disabled on reboot
  • Browse the full community examples repository for more scripts