Secure Bluetooth Door Unlock System

Hardware Shelly 1 Gen3 (DC-powered + battery backup)
Firmware ESPHome
Companion App AndroidWearOS

Key Features

• ✅ Bluetooth Low Energy (BLE) unlocking with HMAC-SHA256 authentication
• ✅ Home Assistant integration via native ESPHome API
• ✅ Multi-lock support in companion app
• ✅ Temporal access control (expirytime windows)
• ✅ Manual device revocation
• ✅ Power outage resilient (battery backup)

System Architecture

flowchart TB
    subgraph Mobile_App
        A[QR Scanner] -- B[Key Derivation]
        B -- C[BLE Unlock]
    end
    subgraph Shelly_1_Gen3
        D[BLE Service] -- E[HMAC Verification]
        E -- F[Latch Control]
        G[HA API] -- F
    end
    subgraph Home_Assistant
        H[Event Logging]
    end

Requirements Specification

1. Access Methods

Method Authentication Notes

BLE HMAC-SHA256 Device-specific keys HA API ESPHome native Separate auth system

2. Provisioning Flow

1. Admin generates QR code containing
   • Lock BLE MAC
   • Base32-encoded secret seed
   • User-defined lock name
2. Companion app scans QR → derives unique HMAC key
3. No lock-side confirmation required

3. Companion App

• Multi-Lock Management
  • Shows all known locks (onlineoffline)
  • No hard limit on number of locks
  • Identifies locks by
    • User-defined display name
    • BLE MAC address
• Features
  • BLE unlock only
  • QR code scanning
  • Permission status display

4. Security Model

• BLE
  • Configurable expirytime windows
  • Manual revocation only
• HA API
  • Uses standard ESPHome encryption
  • No additional permission checks

5. Operational Details

Component Specification

Latch Activation Max 10 seconds (or until door opens) Hall Sensor Immediate activation override Power DC-powered + battery backup WiFi Always-on for HA reporting

Audit Capabilities

• Home Assistant
  • Receives all unlock events
  • Standard ESPHome API format
• Local Storage
  • 50-event circular buffer
  • Includes failed attempts

Installation

1. Flash ESPHome firmware to Shelly 1 Gen3
2. Configure via shelly_doorlock.yaml
3. Install companion app on AndroidWearOS device

Maintenance

• Credential Rotation Manually revokereprovision via QR
• Battery Backup Monitor charge status via HA

---

Last Updated 2025-02-20
License [Your License Here]