Shelly Script Examples

This project contains example Shelly Script solutions.

Initial support for Shelly Script comes with firmware version 0.9, September 2021 for Gen2 Shellies based on ESP32.

Who is this for?

This repository is designed for:

• Home automation enthusiasts - Looking to extend Shelly device capabilities beyond the default features
• Smart home integrators - Building custom solutions with Shelly devices for clients
• Developers - Learning Shelly scripting through practical, working examples
• IoT hobbyists - Experimenting with BLE sensors, MQTT, LoRa, and other protocols
• Energy-conscious users - Implementing load shedding, power monitoring, and efficiency solutions

Prerequisites:

• Basic understanding of JavaScript
• Shelly Gen2 or Gen3 device with firmware 0.9+
• Access to the Shelly web interface or app for script deployment

Documentation

• Example Manifest - Machine-readable list of production examples, descriptions, and tags
• Changelog - See what's new
• Contributing - How to contribute to this project
• Tools - Helper utilities for uploading scripts and validation
• License - Apache License 2.0
• Shelly Script Documentation - Official Shelly scripting docs

Virtual Component Scripts

Runtime scripts that use Shelly Virtual Components should be self-contained. A user should be able to upload and start the script on a compatible device without manually creating the components first.

Use snippets/virtual-components-helper.shelly.js as the standard mechanism:

• Embed the helper as a normal code section in the standalone .shelly.js file. Do not copy the helper @title, @description, or @status metadata block into runtime scripts.
• Define one VIRTUAL_COMPONENTS manifest, or a small buildVirtualComponentsManifest() function when the script already has an ENTITIES/COMPONENTS table.
• Preserve fixed IDs when a README, dashboard, article, or companion script already documents type:id values.
• Put groups in the manifest and reference logical component keys, not raw strings such as number:200.
• Start polling, control handlers, HTTP requests, MODBUS reads, or BLE scanning only after ensureVirtualComponents(...) returns ok === true.
• Bind handles from the callback result, for example readyVc.handles.soc, instead of assuming the VC already exists.

The expected startup shape is:

ensureVirtualComponents(VIRTUAL_COMPONENTS, function(ok, readyVc) {
  if (!ok) {
    print('ERROR: Virtual component setup failed');
    return;
  }

  bindVirtualComponents(readyVc);
  startApp();
});

This makes each script create missing VCs, reuse matching VCs, repair mismatched fixed-ID VCs, restore group membership, and bind handles before normal logic starts.

Collections

• The Pill - UART peripherals and hardware integrations
• BLU Assistant - BLE device provisioning, configuration, and management scripts
• Cury - Expressive light patterns and visual feedback for Shelly Cury devices

Repository Layout

• ble/ - BLE/BLU sensors, buttons, and gateways
• howto/ - Minimal examples and tutorials
• http-integrations/ - HTTP endpoints, notifications, and external services
• lora/ - LoRa send/receive and device control examples
• modbus/ - MODBUS examples for RS485 add-ons and native MODBUS clients
• mqtt/ - MQTT and Home Assistant integrations
• networking/ - Provisioning and watchdog scripts
• power-energy/ - Load management, power thresholds, and monitoring
• scheduling/ - Scheduling, scenes, and orchestration
• switch-input/ - Input handling, switch behavior, and cover control
• weather-env/ - Weather and environmental sensor integrations