Help request: Disconnect BLE when API client not connected

[user45876]

Dear digaus,

thank you so much for this. I was using a Zero 2 with several keyble for years and while it is great, this is looking to be more reliable and easier in the end. This has so much less moving parts than a zero with Node on it ;)

However, I am having two questiong and want to ask for help:

• it seems to stay connected forever despite me removing the 4 minute timer from the example. While this makes it instand, could you say what would need to be set to have it disconnect after some time?
• more importantly, you are having a condition, that it must be connected to wifi to start BLE scanning. How would I need to set it up to have it only scan when an API connection is established to HA? There is a condition api.connected (https://esphome.io/components/api) - but could you maybe put this into the example?

Thank you so much for your efforts, very much appreciated!
Corwin

[user45876]

After reading and trying to think in this bedlam I came up with this. Should this work? Is it enough or too much?
Desired behaviour is that it disconnects from the lock when the API is disconnected for whatever reason so the app can be used.
(editing around...)

api:
  encryption:
    key: "..."

  on_client_disconnected:
    - while:
        condition:
          - not: api.connected
        then:
          - esp32_ble_tracker.stop_scan:
          - eqiva_key_ble.disconnect:

However, this does not seem to be working as intended. When the API is disconnected (e.g. temporarily shutting the HA switchport), the lock does not become available in the app.

[dlbogdan]

Yes, this is quite important in order to have redundancy of opening the door.
example. HA crashes or wifi or whatever, you should be able to use the Eqiva App in your phone to open the door.
If the ESP32 is constantly connected to the lock, you can't.

Help!

[balgerion]

My version behaves like a phone or any other smart device — no need to spam BLE, which helps preserve battery life. Plus, it works seamlessly with Ekey Uno!

  name: faplab-lock
  friendly_name: fapLab-lock

esp32:
  board: esp32dev
  framework:
    type: esp-idf
    sdkconfig_options:
      CONFIG_BOOTLOADER_WDT_TIME_MS: "60000"

  
# Enable logging
logger:
  
# Enable Home Assistant API
api:
  encryption:
    key: z3I07eTnpy8hYIHpIGoJu0FgHu/i3uySyUIWg0YvJjY=
    
ota:
  platform: esphome
  password: 
  
web_server:
  include_internal: true
  local: false
  port: 80

wifi:
  ssid: 
  password: 
  manual_ip:
        static_ip: 192.168.1.45
        gateway: 192.168.1.1
        subnet: 255.255.255.0
        dns1: 192.168.1.1
        
  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Esphome-Web-Eqiva-Lock"
    password: "12345678"
  # Activate scan only after wifi connect, see https://github.com/esphome/issues/issues/2941#issuecomment-1842369092
  on_connect:
    - esp32_ble_tracker.start_scan:
       continuous: true
    - eqiva_key_ble.connect:
       mac_address: !lambda 'return id(mac_address).state;' 
       user_id: !lambda 'return id(user_id).state;'
       user_key: !lambda 'return id(user_key).state;'
  on_disconnect:
    - esp32_ble_tracker.stop_scan:

      

#button, number and text input for pairing and setting mac/user_id/user-key via UI
button:
  - platform: template
    id: ble_settings
    name: BLE Settings _Save_
    icon: "mdi:content-save"
    on_press:
      - eqiva_key_ble.connect:
          mac_address: !lambda 'return id(mac_address).state;' 
          user_id: !lambda 'return id(user_id).state;'
          user_key: !lambda 'return id(user_key).state;'
  
  - platform: template
    id: ble_disconnect
    name: BLE Disconnect
    icon: "mdi:clear"
    on_press:
      - eqiva_key_ble.disconnect:

  - platform: template
    id: ble_connect
    name: BLE Connect
    icon: "mdi:clear"
    on_press:
      - eqiva_key_ble.connect:
          mac_address: !lambda 'return id(mac_address).state;' 
          user_id: !lambda 'return id(user_id).state;'
          user_key: !lambda 'return id(user_key).state;'

  - platform: template
    id: ble_pair
    name: BLE Pair _Start_
    icon: "mdi:check-underline"
    on_press:
      - eqiva_key_ble.pair:
          card_key: !lambda 'return id(card_key).state;' 

  - platform: template
    id: lock_settings
    name: Lock Settings _Apply_
    icon: "mdi:check-underline"
    on_press:
      - eqiva_key_ble.settings:
          turn_left: !lambda 'return id(direction).state == "Left";' 
          key_horizontal: !lambda 'return id(position).state == "Horizontal";'
          lock_turns: !lambda 'return atoi(id(turns).state.c_str());'
          
number:
  - platform: template
    mode: box
    name: BLE Settings User ID
    id: user_id
    max_value: 7
    min_value: 0
    step: 1
    optimistic: true
    restore_value: true

text:
  - platform: template
    mode: text
    name: BLE Settings Mac Address
    id: mac_address
    optimistic: true
    restore_value: true
  - platform: template
    mode: text
    name: BLE Settings User Key
    id: user_key
    optimistic: true
    restore_value: true
  - platform: template
    mode: text
    name: BLE Pair Card Key
    id: card_key
    optimistic: true

select:
  - platform: template
    name: Lock Settings Close Direction
    id: direction
    options:
     - "Left"
     - "Right"
    optimistic: true
  - platform: template
    name: Lock Settings Key Position
    id: position
    options:
     - "Vertical"
     - "Horizontal"
    optimistic: true
  - platform: template
    name: Lock Settings Turns
    id: turns
    options:
     - "1"
     - "2"
     - "3"
     - "4"
    optimistic: true




captive_portal:
    
external_components:
  source: github://digaus/esphome-components-eqiva
  # use refresh when you do not get latest version
  # refresh: 0s

esp32_ble_tracker:
   scan_parameters:
    window: 300ms
    # Activate scan only after wifi connect, see https://github.com/esphome/issues/issues/2941#issuecomment-1842369092
    continuous: false

eqiva_ble:

eqiva_key_ble:
  id: key_ble

text_sensor: 
  - platform: eqiva_key_ble
    mac_address: 
      name: "Mac Address"
    lock_status: 
      name: "Lock Status"
      id: lock_status
    low_battery:
      name: "Low Battery"
    lock_ble_state:
      name: "Lock BLE State"
    user_id:
      name: "User ID"
    user_key:
      name: "User Key"
    # on_raw_value:
            # then:   Do stuff on state change (!lambda "return x") 

          
# Lock component for HA, can also create two locks and use connect service to connect/control two different locks
# One ESP per lock is still recommended
lock:
  - platform: template
    name: "Lock 1"
    lambda: |-
      if (id(lock_status).state == "LOCKED") {
        return LOCK_STATE_LOCKED;
      } else if (id(lock_status).state == "UNLOCKED" || id(lock_status).state == "OPENED") {
        return LOCK_STATE_UNLOCKED;
      } else if(id(lock_status).state == "MOVING") {
        return {};
      } else if (id(lock_status).state == "UNKNOWN") {
        return LOCK_STATE_JAMMED;
      } 
      return LOCK_STATE_LOCKED;
    lock_action:
      - eqiva_key_ble.connect:
          mac_address: !lambda 'return id(mac_address).state;'
          user_id: !lambda 'return id(user_id).state;'
          user_key: !lambda 'return id(user_key).state;'
      - delay: 1s
      - eqiva_key_ble.lock:
      - delay: 15s
      - eqiva_key_ble.disconnect:
    unlock_action:
      - eqiva_key_ble.connect:
          mac_address: !lambda 'return id(mac_address).state;'
          user_id: !lambda 'return id(user_id).state;'
          user_key: !lambda 'return id(user_key).state;'
      - delay: 1s
      - eqiva_key_ble.unlock:
      - delay: 15s
      - eqiva_key_ble.disconnect:
    open_action:    
      - eqiva_key_ble.open:

[atlab95]

My version behaves like a phone or any other smart device — no need to spam BLE, which helps preserve battery life. Plus, it works seamlessly with Ekey Uno!

  name: faplab-lock
  friendly_name: fapLab-lock

esp32:
  board: esp32dev
  framework:
    type: esp-idf
    sdkconfig_options:
      CONFIG_BOOTLOADER_WDT_TIME_MS: "60000"

  
# Enable logging
logger:
  
# Enable Home Assistant API
api:
  encryption:
    key: z3I07eTnpy8hYIHpIGoJu0FgHu/i3uySyUIWg0YvJjY=
    
ota:
  platform: esphome
  password: 
  
web_server:
  include_internal: true
  local: false
  port: 80

wifi:
  ssid: 
  password: 
  manual_ip:
        static_ip: 192.168.1.45
        gateway: 192.168.1.1
        subnet: 255.255.255.0
        dns1: 192.168.1.1
        
  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Esphome-Web-Eqiva-Lock"
    password: "12345678"
  # Activate scan only after wifi connect, see https://github.com/esphome/issues/issues/2941#issuecomment-1842369092
  on_connect:
    - esp32_ble_tracker.start_scan:
       continuous: true
    - eqiva_key_ble.connect:
       mac_address: !lambda 'return id(mac_address).state;' 
       user_id: !lambda 'return id(user_id).state;'
       user_key: !lambda 'return id(user_key).state;'
  on_disconnect:
    - esp32_ble_tracker.stop_scan:

      

#button, number and text input for pairing and setting mac/user_id/user-key via UI
button:
  - platform: template
    id: ble_settings
    name: BLE Settings _Save_
    icon: "mdi:content-save"
    on_press:
      - eqiva_key_ble.connect:
          mac_address: !lambda 'return id(mac_address).state;' 
          user_id: !lambda 'return id(user_id).state;'
          user_key: !lambda 'return id(user_key).state;'
  
  - platform: template
    id: ble_disconnect
    name: BLE Disconnect
    icon: "mdi:clear"
    on_press:
      - eqiva_key_ble.disconnect:

  - platform: template
    id: ble_connect
    name: BLE Connect
    icon: "mdi:clear"
    on_press:
      - eqiva_key_ble.connect:
          mac_address: !lambda 'return id(mac_address).state;' 
          user_id: !lambda 'return id(user_id).state;'
          user_key: !lambda 'return id(user_key).state;'

  - platform: template
    id: ble_pair
    name: BLE Pair _Start_
    icon: "mdi:check-underline"
    on_press:
      - eqiva_key_ble.pair:
          card_key: !lambda 'return id(card_key).state;' 

  - platform: template
    id: lock_settings
    name: Lock Settings _Apply_
    icon: "mdi:check-underline"
    on_press:
      - eqiva_key_ble.settings:
          turn_left: !lambda 'return id(direction).state == "Left";' 
          key_horizontal: !lambda 'return id(position).state == "Horizontal";'
          lock_turns: !lambda 'return atoi(id(turns).state.c_str());'
          
number:
  - platform: template
    mode: box
    name: BLE Settings User ID
    id: user_id
    max_value: 7
    min_value: 0
    step: 1
    optimistic: true
    restore_value: true

text:
  - platform: template
    mode: text
    name: BLE Settings Mac Address
    id: mac_address
    optimistic: true
    restore_value: true
  - platform: template
    mode: text
    name: BLE Settings User Key
    id: user_key
    optimistic: true
    restore_value: true
  - platform: template
    mode: text
    name: BLE Pair Card Key
    id: card_key
    optimistic: true

select:
  - platform: template
    name: Lock Settings Close Direction
    id: direction
    options:
     - "Left"
     - "Right"
    optimistic: true
  - platform: template
    name: Lock Settings Key Position
    id: position
    options:
     - "Vertical"
     - "Horizontal"
    optimistic: true
  - platform: template
    name: Lock Settings Turns
    id: turns
    options:
     - "1"
     - "2"
     - "3"
     - "4"
    optimistic: true




captive_portal:
    
external_components:
  source: github://digaus/esphome-components-eqiva
  # use refresh when you do not get latest version
  # refresh: 0s

esp32_ble_tracker:
   scan_parameters:
    window: 300ms
    # Activate scan only after wifi connect, see https://github.com/esphome/issues/issues/2941#issuecomment-1842369092
    continuous: false

eqiva_ble:

eqiva_key_ble:
  id: key_ble

text_sensor: 
  - platform: eqiva_key_ble
    mac_address: 
      name: "Mac Address"
    lock_status: 
      name: "Lock Status"
      id: lock_status
    low_battery:
      name: "Low Battery"
    lock_ble_state:
      name: "Lock BLE State"
    user_id:
      name: "User ID"
    user_key:
      name: "User Key"
    # on_raw_value:
            # then:   Do stuff on state change (!lambda "return x") 

          
# Lock component for HA, can also create two locks and use connect service to connect/control two different locks
# One ESP per lock is still recommended
lock:
  - platform: template
    name: "Lock 1"
    lambda: |-
      if (id(lock_status).state == "LOCKED") {
        return LOCK_STATE_LOCKED;
      } else if (id(lock_status).state == "UNLOCKED" || id(lock_status).state == "OPENED") {
        return LOCK_STATE_UNLOCKED;
      } else if(id(lock_status).state == "MOVING") {
        return {};
      } else if (id(lock_status).state == "UNKNOWN") {
        return LOCK_STATE_JAMMED;
      } 
      return LOCK_STATE_LOCKED;
    lock_action:
      - eqiva_key_ble.connect:
          mac_address: !lambda 'return id(mac_address).state;'
          user_id: !lambda 'return id(user_id).state;'
          user_key: !lambda 'return id(user_key).state;'
      - delay: 1s
      - eqiva_key_ble.lock:
      - delay: 15s
      - eqiva_key_ble.disconnect:
    unlock_action:
      - eqiva_key_ble.connect:
          mac_address: !lambda 'return id(mac_address).state;'
          user_id: !lambda 'return id(user_id).state;'
          user_key: !lambda 'return id(user_key).state;'
      - delay: 1s
      - eqiva_key_ble.unlock:
      - delay: 15s
      - eqiva_key_ble.disconnect:
    open_action:    
      - eqiva_key_ble.open:

Tried your code but it randomly work then get stuck on connecting...
Is there a proper way to disconnect the esp from the lock after an action?

[balgerion]

im trigering simple script every 30 minutes as a "heartbeat"

its working without issue since i post it. Home assistant + ekey uno.

[atlab95]

I'm using this approach with esphome Version: 2025.9.3 and the new code. Before with esphome 2024 and the old code, it took about 12 seconds from idle to established, now it ranges from 20 to 30 sec and sometimes hangs up. Any clue @digaus?
I'm using ESP32-C3 4MB flash

[digaus]

I'm using this approach with esphome Version: 2025.9.3 and the new code. Before with esphome 2024 and the old code, it took about 12 seconds from idle to established, now it ranges from 20 to 30 sec and sometimes hangs up. Any clue @digaus? I'm using ESP32-C3 4MB flash

Might be because the ble client changed something in auto connect implementation.

Previously I think we needed to call connect in the ble client and maybe that was faster because auto connect waits for discovery and then connects.

Might have a look at the source code.

[dlbogdan]

Hello? Anyone managed to get this working with some form of redundancy included? I can’t shake the anxiety that something may happen to a server or a network switch or something and I can’t get in my own house.