Shelly LoRa Add-on

What it is for

Two buildings on the same property, a gate at the end of a long drive, a pump house across a field. Anywhere a relay needs to follow a switch and there is no network between them.

The LoRa Add-on clips onto a Gen3 or Gen4 device and carries small amounts of data over long distances — hundreds of metres in built-up areas, kilometres with line of sight. No Wi-Fi, no internet, no gateway and no subscription.

The trade-off is bandwidth. LoRa carries a few bytes at a time, so this sends “ON”, “OFF”, a temperature reading or a heartbeat — not video, not a dashboard, not device status in any richness.

It works through scripting. There is no LoRa page in the app: a script on each device sends and receives. That is what the rest of this page is about.

Supported devices

The Add-on requires a Gen3 or Gen4 device with a matching form factor — it clips onto the device, so the shape has to fit.

Correct as of January 2026 — check the current list before ordering for a job, as devices are added.

Both ends need one. A LoRa Add-on talks to another LoRa Add-on; there is no bridge from LoRa to Wi-Fi built into any of this.

The four script pairs

Every solution is two scripts: one on the sending device, one on the receiving device. They are separate files, and putting the wrong one on the wrong device is the most common setup mistake.

Relay follows relay

The plain case. When the sender’s relay switches, the receiver’s relay does the same.

• lora-relay-sender.js — on the device with the switch
• lora-relay-receiver.js — on the device with the load

Feedback

The relay pair sends and hopes. This pair adds confirmation that the command actually arrived and was carried out.

The direction is inverted, and this catches everyone: the feedback sender goes on the device that receives the relay command, and the feedback receiver goes on the device that sends it. The confirmation travels back the other way.

• lora-feedback-sender.js — add to the receiving device
• lora-feedback-receiver.js — add to the sending device

The result appears in the script console, and in two virtual components on the sending device: a Boolean (id 200) showing true or false, and a Text (id 200) with the detail.

Temperature and humidity

Sends a reading once a minute — a summer house, a greenhouse, a pump house.

• lora-th-sender.js — reads a paired BLU H&T
• lora-th-receiver.js — writes humidity to virtual number 200 and temperature to 201

The sender needs a BLU H&T paired directly to it over Bluetooth — see BTHome components.

Alive signal

A heartbeat. The sender transmits at an interval; the receiver switches a relay if nothing arrives within a timeout.

• lora-alive-sender.js — sends every minute by default
• lora-alive-receiver.js — acts after two minutes of silence

The receiver also writes to a Text and a Boolean virtual component, both id 200, so the state is visible in the app.

Encryption

Every pair encrypts what it sends with AES-128, so only the two devices holding the key can read it. LoRa is a radio; anything nearby with a receiver can hear the transmission.

The key sits at the top of each script:

// AES-128 key in base64 (16 bytes) - CHANGE THIS, and use the same key in both scripts
const aesKey = "Q0hBTkdFLVRISVMtS0VZIQ==";

Use a different key for each installation. Reusing one across customers means a device from one site can be commanded from another.

Installing a pair

Same procedure for all four. See how to add a script.

1. Fit the Add-on to both devices, and confirm each one recognises it
2. Install the sender script on the sending device, and the receiver on the receiving one
3. Change aesKey in both — the same value in each
4. Adjust the settings at the top of the script: interval, timeout, relay id, component ids
5. Save, start, and enable run on startup on both
6. Test at the real distance, not on the bench

Step six matters more here than anywhere else. LoRa range depends on what is between the two devices, and a pair that works across a workshop may not work across the property. Walk the receiver out to where it will live before mounting anything.

Tips & best practices

• Height beats power. Getting the antenna above what is in the way does more for range than anything in the configuration.
• Add the feedback pair on anything that matters. A gate that did not open is worth knowing about; a relay pair alone cannot tell you.
• Note which script is on which device. The sender and receiver look similar in the script list, and the feedback pair is deliberately the other way round.
• One key per installation, written down somewhere other than the device.
• Check the console after the first day. The receivers count packet errors, and a link that works but drops a third of its messages will show it there long before it fails outright.

Video

An introduction to the LoRa Add-on and what it can do.

Loads YouTube when you press play. Watch on YouTube

By ShellyGuide on YouTube

Related guides