Shelly BLU Assistant-Bulk Setup Tool

Bulk-Configure Your Shelly Devices in Seconds

The Shelly BLU Assistant is a compact, USB-powered device designed for quick and easy provisioning, configuration, and control of Shelly Gen2+ Devices. Powered by the Shelly Script engine and equipped with two programmable buttons, it enables a wide range of automated device management workflows, perfect for both small-scale and mass deployments. Think of it as your personal “mass‑configuration” remote for Generation‑2 (and newer) Shellys.

Heads‑up The Assistant doesn’t provision stand‑alone Shelly BLU sensors. It does, however, use BTHome to connect to them and check their readings on the fly.

Who is this for?

• Installers rolling out fleets of devices in new builds.

• Smart‑home fans fine‑tuning every detail of their setups.

• Field techs who need a reliable, laptop‑free provisioning gadget.

• Educators & makers spinning up classroom kits or workshop demos in minutes.

A Quick Look at the Hardware

The Assistant is simple by design. Here's what you're working with:

Tech Inside

• Connectivity: A built‑in Wi‑Fi radio (802.11 b/g/n @ 2.4 GHz) spins up its own configuration hotspot or joins your network, while Bluetooth 5.1 LE beams provisioning commands to nearby Shellys.

Safety First: Keep the Assistant dry, away from extreme heat, and plug it only into a standard 5 V USB port.

Getting Up and Running

Getting started is easy:

1. Power It Up: Plug the Shelly BLU Assistant into a USB-A port. Give it about 5 seconds to wake up.

2. Connect to Its Wi-Fi: On your phone or laptop, look for a Wi-Fi network called ShellyBLUAssist-xxxxxx and connect to it. You won't need a password.

3. Launch the Web Interface: Open a browser and go to http://192.168.33.1. That's it! You're in.

Optional – Add the Assistant to your LAN

In the web console, go to Settings ▸ Wi‑Fi, select your 2.4 GHz network, and enter its password. The Assistant will appear as a client device on your home network. Prefer a standalone tool on the road? Simply leave it in access‑point mode.

Your Control Panel: The Web UI

The Web UI is your mission control, organized into four sections.

• Favorites: Got devices you use often? Star them in the results list, and they'll live here. You can pin up to six favorites, give them easy-to-remember names, and even create up to four custom action buttons for each one.

• Find Shelly Devices: This is where you'll start most jobs.

  • Filters: Quickly find what you're looking for. You can filter by Model ID, search by Device Name, or set an RSSI threshold (dBm) to ignore devices that are too far away.

  • Sorting: Arrange your list by signal strength (RSSI) or alphabetically by Device Name.

  • Scan: Hit this button to start discovering nearby devices.

•  Send RPC: This is where the bulk-management happens. You can update/communicate with a few devices at the same time.

  • Just tick the boxes next to the devices you want to command.

  • Start typing your command. The interface is smart, it will auto-suggest valid commands for the type of device you've selected, so you can't go wrong.

  • If needed, add your parameters in JSON format.

  • Click Send and the Assistant connect to multiple devices at once. We can work with up to 5 devices at the same time.

• Results Pane: Each discovered device appears as a card with key stats. When you fire a command, a progress bar shows per‑device status; expand a card for success/failure details.

What Can You Do With It?

The Shelly BLU Assistant is a problem-solver. Here are a few ideas to get you started:

The Secret Sauce: Scripting

Here’s what makes the Shelly BLU Assistant great. The built‑in Shelly Script Engine (Espruino‑based) lets you automate almost anything:

You have direct access to:

• Scan for nearby devices over Bluetooth

• Configure any setting via RPC

• Store and retrieve data in flash

• React to BTN 1 / BTN 2 short, long, or double presses

All your scripts live in the Scripts tab in the Web UI. You can even create virtual buttons and text fields in the UI that your scripts can interact with, letting you build your own custom dashboards for your specific needs.

Here you can find all the specific of the Shelly scripting : link

Here you can find our repo with examples : link

Example Scripts to Get You Inspired

To get your imagination going, we've bundled a few scripts right out of the box. They are a great starting point for your own creations. You can modify them to fit your needs like scanning for all devices, not just a specific one.

Getting the Scripts on Your Device

Ready to try them out? Getting these scripts onto your Assistant is easy:

1. Connect to the Assistant and open the Web UI.

2. Head over to the Scripts section.

3. Click to create a New Script and give it a name.

4. Copy and paste the code for the script you want to add, then hit Save.

5. Run it from the UI or by pressing the physical button it's assigned to!

Part 1: Demo Scripts

These four scripts form the core demo. First you run the auto-setup, then you’ll use Wi-Fi provisioning, full config, and MQTT config against those newly created virtual fields/buttons.

Virtual Components Auto-Setup (create-demo-virtual-components.js)

What it does

This one-time setup script creates all the virtual buttons and text fields your other scripts rely on. No manual UI work-just run once and you’re ready.

How to use it

1. Open the Web UI and go to Scripts.

2. Create a new script named “Virtual Components Auto-Setup”.

3. Paste in the create-demo-virtual-components code.

4. Save and Run.

Once it finishes the script will auto stop itself and you’ll see groups and components in the Home screen like:

• Network Setup (IDs: text:200, text:201, text:202, button:200, text:211)

• Device Configuration (text:200–204, button:201, text:211)

• MQTT Configuration (text:200,205–211, button:202)

Wi-Fi Provisioning (add-to-wifi.js)

• What it does: It finds nearby Shelly devices and connects them to the Wi-Fi network you specify in the UI.

• Why it's cool: It processes devices in small, smart batches and even retries if a device doesn't connect on the first try. It’s pre-assigned to a short press of Button 1.

• How to use it: After running the virtual component setup script, just type your:

  • Wi-Fi Name (SSID) into the field associated with text:201.

  • Wi-Fi Password into the field associated with text:202.

  • Device BLE ID (e.g., 0x1800) into the field associated with text:200.

Then, press the system button (Button 1) or the virtual button linked to button:200 (Connect to WiFi)!

Full Device Configuration & Update (full-config.js)

• What it does: This script is a great example of a multi-step workflow. It finds the closest specific device, connects it to Wi-Fi, waits for it to come online, renames it, sets its timezone, and finally, checks if it needs a firmware update.

• Why it's cool: It shows how to chain commands together, some in order, some at the same time, for maximum efficiency.

• How to use it: Edit the script directly to set your desired values:

  • Target Device BLE ID (e.g., 0x1018) in FILTERED_BLE_ID associated with text:200.

  • New Device Name in DEVICE_NAME associated with text:203.

  • Wi-Fi Network SSID in WIFI_SSIDassociated with text:201.

  • Wi-Fi Password in WIFI_PASSassociated with text:202.

  • Device Timezone (e.g., Europe/Sofia) in LOCATION_TZassociated with text:204.

Then, trigger the script by pressing the system button (Button 1) or the virtual button linked to button:201(Config Device)!

MQTT Configuration (config-mqtt.js)

• What it does: This advanced script finds the closest Shelly device with that specific BLE ID and fully configures it to talk to an MQTT broker, in this case AWS, complete with the necessary security certificates.

• Why it's cool: It demonstrates the true power of the Assistant by handling a complex workflow that includes fetching files over the network and uploading them piece by piece to the target device.

• How to use it: Before running, you must host your CA bundle, client certificate, and client private key files on a web server accessible by the Shelly device running this script. Then, edit the script directly to set your custom details:

  • Target Device BLE ID (e.g., 0x1018) in FILTERED_BLE_IDassociated with text:200.

  • MQTT Server Address and Port in MQTT_SERVERassociated with text:205.

  • MQTT Client ID in MQTT_CLIENT_IDassociated with text:206.

  • MQTT Topic Prefix in MQTT_PREFIXassociated with text:207.

  • URLs to your certificate files (

    • CA_BUNDLE associated with text:208

    • CLIENT_CERT associated with text:209

    • CLIENT_KEY associated with text:210

Finally, trigger the script by pressing the system button (Button 1) or the virtual button linked to button:202(MQTT Config)!

Part 2: Additional Example Scripts

⚠️ ID Collisions:

All the scripts below assume the virtual fields/buttons from the demo are in place.If you copy/customize any example, always update the text:<ID> or button:<ID> references so two scripts don’t try to use the same UI component at once.

Factory Reset (factory-reset-device.js)

• What it does: Issues a factory reset command to all specific nearby Shelly devices you want to wipe clean.

• Why it's cool: Like the Wi-Fi script, it's robust, with built-in retry logic. It’s pre-assigned to a short press of Button 2.

• How to use it: After running the setup script, just type your:

  • Device BLE ID (e.g., 1800) into the field associated with text:200.

Then, press the system button (Button 2) or the virtual button linked to button:201 (Reset)!

Gen3 Matter Update (gen3-update-matter.js)

• What it does: This is a powerful, all-in-one script to get your Gen3 Shelly devices fully updated and ready for Matter. It automates the entire process: connecting to Wi-Fi, checking the current firmware, running an update if needed, rebooting, and finally, enabling Matter support.

• Why it's cool: It’s a true "fire-and-forget" solution. It works on multiple devices at once, smartly checks if an update is even necessary, and retries each step if something goes wrong. This is the easiest way to perform a complex, multi-step upgrade across your entire Gen3 fleet.

• How to use it: Tweak the WIFI_SSID and WIFI_PASS at the top of the script to match your network. Then, just press the button you've assigned it to. The script will find all nearby devices with a strong signal and begin the automated process,

Inventory Labels with a Network Printer (print_script.js)

• What it does: This script transforms your Shelly BLU Assistant into a mobile labeling station! It finds a nearby Shelly device, grabs its specified data, puts them in a ZPL template and sends them to a network-connected label printer to instantly create a physical sticker.

• Why it's cool: This is a game-changer for professional installers or anyone managing lots of devices. You get a perfect, scannable label for each device, making future setups and inventory management incredibly simple. It's automation you can hold in your hand.

• How to use it: First, make sure you've run the Virtual Components Auto-Setup script to create the necessary UI fields. Then, in the Web UI, enter the IP address of your ZPL-compatible printer (many Argox or Zebra models work). Edit the template with what you desire and trigger the script.

• How to use it: Run Virtual Components Auto-Setup: Ensure you've run the initial setup script to create the necessary UI input fields.

  • Enter the Target Device BLE ID (e.g., 0x1018) into the field associated with text:200.

  • Enter the HTTP/IP address of your ZPL-compatible network printer into the field associated with text:204.

  • (Optional) Customize Label: You can directly edit the zpl_template variable within the script to adjust the label's layout or content.

Finally, trigger the script by pressing the system button (Button 1) or the virtual button linked to button:202!

BLU Door/Window Sensor to Webhook Bridge (bthome-webhook.js)

• What it does: This script turns your Shelly BLU Assistant into a smart home bridge. It "listens" for your Shelly BLU Door/Window sensor to open or close and then instantly sends a command (a webhook) over your Wi-Fi to another device, like a light switch, a smart plug, or a siren.

• Why it's cool: It lets you create simple but powerful automations without needing a complex smart home hub or relying on the cloud. For example: "When the back door opens, turn on the patio light." or "If the medicine cabinet is opened, trigger a chime." All the logic runs locally and instantly on your Assistant.

• How to use it: This one is super simple to set up.

  • Find the ID of your BLU Door/Window sensor and put it in the WINDOW_SENSOR_ID field.

  • Get the webhook URLs for the device you want to control. Most Shelly devices make this easy-the URLs for turning a switch on or off are right in the device's settings.

  • Paste those URLs into the WINDOW_OPEN_WEBHOOK and WINDOW_CLOSE_WEBHOOK fields.

  • Upload the script to your Assistant, and your new automation is live!

Your new favorite time-saver

Shelly BLU Assistant cuts out the mind-numbing repeat work, so you can finish the job and move on to the tricky stuff. It configures every device in a snap and doubles as a go-anywhere command center-online or completely offline, so you stay in control no matter where the work takes you.