📛 Shelly i4 Button Controller by LTek ... with Single Button Dim & Multi-Press Functions

[Ltek]

Shelly i4 Button Controller with scenes and single-button dimming and scenes

Version 2026.03.01.07c

• Improved overall code efficiency and tweaked the Dim capabilities

• added Dim configuration guide and optimized defaults for high latency lights.

• fixed bug where Dimming would not work if the Button Up or Down was populated.

  Features:
  - Set any HA Action for Button presses (Single, Double, Triple, Down, Up, Long)
  - Single Button Dim any or all buttons (optional)
  - Dim Direction Start Boundary sets dim direction at start of dim; upward if below, downward if above
  - Dim Fine Tuning - Dim Percent per Step, Step Interval (time delay between steps), Transition Duration
  - Debug notifications show trigger and action, with timestamps

  Dim Configuration Guide"
  NOTE… Dimming starts 1 second after the initial press-hold. (native Shelly device detection period for long_press)
  Default values balance dim speed, system latency, and smoothness control for Zigbee lights.

  - When Dim Function is Enabled, Basic Actions for Button Up and Long Press are disabled
    - if the Light is OFF, Long press turns on the Light then Dims
  These three settings work together to control dimming feel:
  - Dim Step Percent — brightness change per cycle. Smaller = finer steps but slower
    to traverse the full range. Larger = faster but more visible jumps.
    Default: 14%  
  - Dim Interval — time between each step. This is the primary speed control.
    Shorter = faster dimming. 
    Default: 0.2s
  - Transition Duration — the lights own transition between the current and new brightness.
    Must be LESS than Dim Interval or steps will overlap and stutter.
    Default: 0.0s
    
  ⚠️ High-latency lights (Zigbee, Z-Wave): if dimming feels slow despite short intervals,
    set Transition Duration to 0.0 — the light's own fade response is adding delay to
    each loop cycle. The step frequency itself creates perceived smoothness.
  

[xky1980]

Thanks, for sharing your project. Works fine with multiple click usage too.

[t3chguy (Michael Telatynski)]

You have impeccable timing. Just installed my i4 + wall plate after weeks of putting it off and this made it far easier to set up than even Shelly’s own solution for controlling shelly lights from an i4. Thanks

[diegoms (Diego)]

Hi @Ltek I’ll describe my issue or what I want to see if it can be achieved.

See the image:

I will have several push buttons (normal) connected to a zigbee relay. The relay is also connected to the power supply.

We will have several zigbee lights creating a group and connected to the power suply all time so they are always on zigbee mesh.

What I want is to use the push buttons to toggle the status of the lights and if HA is down been able to switch the lights. I would also be able to toggle lights from HA. Ideally it would be great to change dimming from push buttons but not mandatory. what I want is a fallback in case HA fails, and for my wife and kids for been able to use push buttons.

Thanks!

[Ltek]

this blueprint has been tested with Shelly i4 (both DC and gen3) which do not control a load directly, aka ‘detached’. Since Shelly uses the same base code / command set, this BP should work fine for all normal Shelly relays (zigbee, wifi, bluetooth) which have a switch input (I think they all do). I do not have any other Shelly relays to test with so cant verify it.

[diegoms (Diego)]

But this communicates directly with HA, what happens is HA is down @Ltek

I’ve redone the image

If not this blueprint, do you know how can i accomplish this?

[Ltek]

as I explained, you need to use a normal Shelly relay, the blueprint will handle syncing with HA, and a normal relay has physical switch inputs. You literally have a diagram that shows exactly that. If your puck lights themselves are ONLY Zigbee, not connected directly to a switch (which is what a relay is) then of course you cant control them when zigbee is not running.

[ps-jay (Phil)]

This is very nice, and one small improvement would be the addition of transition time on dimming
e.g.

variables:
...
  button4_dim_transition: !input button4_dim_transition
...
                      data: 
                        brightness_step: "{{ button4_dim_direction }}{{ brightness_step_value }}"
                        transition: "{{ button4_dim_transition }}"

---

Question: should there be 4 x dimming_active variables? So that multiple inputs can be held at once?
e.g. a button1_dimming_active, button2_dimming_active, etc.

I haven’t tested what happens when multiple inputs are long held yet!

(also commented on the gist directly: Home Assistant Blueprint : Shelly i4 Button Controller by Ltek · GitHub)

[Ltek]

Hi @ps-jay, not sure what adding a transition variable would accomplish. Shelly i4 devices are not dimmers themselves, thus do not natively support Transition Time. Using the variables Dim % per Step and Step Interval together will control how much light change occurs, over what period of time… thus it somewhat mimics transition time. If you want a button press (not a hold) to do dimming then you can create that in the Action however you want.

I dont know if the i4 is designed to detect simultaneous presses or holds (meaning two or more buttons pressed at exactly the same time can trigger a different events in the device (and be sent to HA). I have not seen mention in the documentation of “simultaneous-press detection” as a separate event.

I can see if anyone on the dedicated Shelly forums/groups know. LMK if you modify the code and get it working.

hope that helps

[ps-jay (Phil)]

Hi @Ltek,

Agreed - i4 doesn’t dim by itself - I’d be sending the transition time command to the light bulb (Lifx brand in my case), along with the brightness %

I’ll fork the code, test, and report back

[Ltek]

That has nothing to do with the blueprint.
Transition Time is set directly on the Light Entity. Add the Entity to the ‘Basic Actions’ on any button then set the entity properties/values as you’d like…

[Sven.2410]

Nice work! I have a request. Could you elaborate a bit? If I don’t want to use buttons 3 and 4, it won’t work. I’ve modified your blueprint to only show buttons 1 and 2, but could you also add a toggle switch so I can choose which buttons to use? And finally, is there a way to have the lights turn off when I press a single button while the lights are on?

[Ltek]

The blueprint works fine no matter how many buttons you want, or not want, to use. For example, you can use Buttons 2,3,4 but not Button 1.

Light Toggle does exactly what you describe…

[ps-jay (Phil)]

I did a couple of modifications, and this has been good for me since November: shelly-i4-blueprint · GitHub

[Ltek]

POSTED… Version 2026.03.01.07c

• Improved overall code efficiency and tweaked the Dim capabilities
• added Dim configuration guide and optimized defaults for high latency lights.
• fixed bug where Dimming would not work if the Button Up or Down was populated.

[Ferr8 (Mike)]

Hi, thank you so much for sharing this blueprint! I’ve set it up using an i4 Button as dimmer for a shelly dimmer gen4. It works great apart from when I dim down all the way, the light dimms to 0% and then switches off. I’m new at this, but the trace shows it as registering a btn_up. Is this something you’ve seen before? I haven’t changed anything I the blueprint apart from enabling button 3 dimmer function. I’ve only just added these to home assistant and don’t have any other automations set for them. I ran through a long troubleshooting session with perplexity, but it ran out of ideas.

[Ltek]

What action Home Assistant registers (btn_up, etc) is what the Shelly device sends it and the blueprint cannot change that – the blueprint only knows what HA tells it.

btn_up is how the blueprint knows when you want to stopped the dim loop/cycle

The blueprint does not send an off command when there is a 0% brightness value. Some lights may turn off automatically at 0%, I dont know what Shelly does. But, with the blueprint, the dimming loop continues running even though no visible change is happening at 0%, until you release the button.

[Ferr8 (Mike)]

Thanks. I’ll keep testing and see if I can figure it out.

[timw99]

For some reason button 1 and button 4 execute the same action on my end. The correct buttons are being shown when I check them under the device sensors, so I definitely wired the buttons correctly. Anyone else had this issue?

alias: Shelly buttons
description: ""
use_blueprint:
  path: gist.githubusercontent.com/shelly-i4-button-controller-ltek.yaml
  input:
    shelly_device: ec4e24c5ace9f5a505f22c62bba1235b
    button1_single:
      - action: light.toggle
        metadata: {}
        data: {}
        target:
          entity_id:
            - light.standing_lamp_1
            - light.lounge_lamps
    button2_single:
      - action: light.toggle
        metadata: {}
        data: {}
        target:
          entity_id: light.dinner_table_lamp_light
    button3_single:
      - action: light.toggle
        metadata: {}
        data: {}
        target:
          area_id: keuken
    button4_single:
      - action: light.toggle
        metadata: {}
        data: {}
        target:
          area_id: backyard

[Ltek]

I have not seen any issue, and I use mine several times a day, all 4 buttons (I have different actions for each)

If you post the downloaded trace file I can take a look