Shelly QuickApps for Zooz Z-Box

Local control and monitoring of Shelly Wi-Fi devices from a Zooz Z-Box controller — no cloud, no MQTT, no third-party services required.

Each QuickApp in this repository targets a specific Shelly device type. All communication is local over your home network using the Shelly HTTP API.

---

Supported Devices

QuickApp	Shelly Device	Z-Box Type	Notes
ShellyEM	Shelly EM Gen1 (SHEM)	electricMeter	Dual-channel energy monitor
ShellyEMGen3	Shelly EM Gen3	electricMeter	Dual-channel energy monitor
ShellyPMMini	Shelly PM Mini Gen3	electricMeter	Single-channel power monitor
ShellyI4	Shelly i4 / i4 DC	remoteController	4-input button device
ShellyRelays	Shelly Plug US Gen4, Plug S/E Gen3, compatible Gen3/Gen4 relays - such as the Shelly 1, 1PM, 1 Mini, 1PM Mini	binarySwitch	On/off control + optional power & light sensor

---

Network Requirements

Before you begin, your Shelly device must be reachable by IP address on your local network.

• Assign a static IP address to each Shelly device. You can do this in your router's DHCP reservation settings (preferred) or in the Shelly app under Network → Wi-Fi → Static IP.
• The Z-Box and the Shelly device must be on the same local network (or the same VLAN with inter-VLAN routing enabled).
• These QuickApps communicate over HTTP only. HTTPS (SSL/TLS) connectivity is not currently supported. Do not expose your Shelly devices to the public internet.

---

Security Notes

• These scripts support both password-protected and open Shelly devices.
• If your Shelly device has no password set, leave shellyPassword as PASSWORD_PLACEHOLDER — the scripts detect this and send unauthenticated requests.
• If a password is set, enter it in the shellyPassword variable. Gen1 devices use HTTP Basic Auth; Gen2/Gen3/Gen4 devices use HTTP Digest Auth (SHA-256).
• HTTPS is not yet supported. Credentials are transmitted in plaintext or via Digest hash over HTTP. Use on a trusted local network only.

---

Installation

There are two ways to install a QuickApp. The Simple Install is recommended for most users.

Simple Install — Upload a .fqa file

A pre-packaged .fqa file contains the QuickApp and all its settings ready to import. This is the fastest way to get started.

1. Download the .fqa file for your Shelly device from the Releases page.
2. In your Z-Box web interface, go to Devices → Add Device → Other Device → QuickApp.
3. Click Upload and select the .fqa file.
4. Once imported, open the device's Variables tab and update the required variables (see Configuration below).
5. Click Save, then restart the QuickApp.

Advanced Install — Paste the Lua source

Use this method if you want to customise the code or track updates from source.

1. In your Z-Box web interface, go to Devices → Add Device → Other Device → QuickApp.
2. Set the device type to match the QuickApp you are installing (see the Supported Devices table above).
3. Open the Code tab, select all existing code, and replace it by pasting the contents of the .lua file.
4. Click Save.
5. Open the Variables tab and set the required variables (see Configuration below).
6. Restart the QuickApp.

---

Configuration

After installing any QuickApp, set these variables in the device's Variables tab before use.

Variables common to all QuickApps

Variable	Required	Default	Description
shellyIP	✅	192.168.1.100	Local IP address of your Shelly device. Must be a static IP.
shellyUsername		admin	Shelly device username. Default is admin.
shellyPassword		PASSWORD_PLACEHOLDER	Shelly device password. Leave as PASSWORD_PLACEHOLDER if no password is set.
pollInterval		10	How often (in seconds) to poll the device for status updates.

Additional variables — ShellyRelays only

Variable	Required	Default	Description
shelly0ID		0	Shelly switch component ID. Use 0 for single-switch devices.
powerReport		true	Set to false to disable the Power Meter child device.
luxReport		true	Set to false to disable the Illuminance child device. Only applies to devices with a built-in light sensor.

Additional variables — ShellyI4 only

Variable	Required	Default	Description
checkSecs		30	Heartbeat interval in seconds for online/offline detection.
zboxIP	✅	(empty)	Local IP address of your Z-Box hub. Required for the bridge script to call back.
zboxUser		admin	Z-Box local API username.
zboxPass	✅	PASSWORD_PLACEHOLDER	Z-Box local API password. Required for the bridge script.
eventGlobalName		(auto)	Optional custom name for the Z-Box global variable. Defaults to shelly_i4_<QuickAppID>_event.

---

ShellyI4 — Additional Setup

The i4 QuickApp works differently from the others. Instead of polling, it deploys a small JavaScript bridge script directly onto the Shelly i4 that fires button events back to Z-Box in real time.

Before starting the QuickApp, you must manually create a global variable in Z-Box:

1. Go to Variables in the Z-Box interface and create a new global variable.
2. Name it: shelly_i4_<QuickAppID>_event (replace <QuickAppID> with this QuickApp's device ID).
3. Set the initial value to: idle

Once running, Block Scenes can trigger when the variable changes to values like:

input1_single_push    input2_single_push    input3_single_push    input4_single_push
input1_double_push    input2_double_push    input3_double_push    input4_double_push
input1_triple_push    input3_triple_push    input3_triple_push    input4_triple_push
input1_long_push      input2_long_push      input3_long_push      input4_long_push

If you have multiple Shelly i4 devices, each QuickApp uses its own uniquely-named global variable so they do not conflict.

---

Child Devices

Several QuickApps automatically create child devices inside Z-Box to expose additional data cleanly.

• ShellyEM / ShellyEMGen3 create two electricMeter child devices — one per channel (CH-A and CH-B). The parent device shows combined total power.
• ShellyRelays optionally creates an electricMeter child (power/energy) and a lightSensor child (illuminance). Each can be independently enabled or disabled via the powerReport and luxReport variables.

Child devices are created automatically on first run and persist across restarts. To remove a child device, set its variable to false and restart the QuickApp.

---

Changelog

See CHANGELOG.md for a full version history.

---

License

MIT — see LICENSE for details.

---

About

Created by SaveThePanel / Darren Crane.
Repository: github.com/SaveThePanel/zbox-shelly-quickapp

Contributions, bug reports, and feature requests are welcome — please open an issue or pull request.

---

Disclosure: Some links in this README are affiliate links. If you purchase through them, SaveThePanel may earn a small commission at no extra cost to you. This helps support continued development of free tools like this one.