│ [Custom Integration] FC SmartHome (Fingerchip / Fingercrystal / Yi-Lock / eApartment) — Full Reverse Engineering & HACS Release

Share your Projects! Custom Integrations
, , ,
1

Hey everyone! :waving_hand:

I’m excited to share a project that solves a long-standing closed-ecosystem problem: FC SmartHome for Home Assistant.

:open_book: The Problem

Smart locks powered by Shenzhen Fingerchip / Fingercrystal (sold globally under brands using the FC SmartHome, Yi-Lock, eApartment, and K3 apps) are widely available and well-built hardware, but

they are completely locked down. There is no public API, no HomeKit, no Matter, and no local integration. Until now, the only way to control them was through the official Chinese mobile app.

:microscope: What We Reverse-Engineered

Over the past weeks, we completely reverse-engineered the communication stack (static APK decompilation, live packet capture on an OpenWrt gateway, and runtime mobile tracing):

  1. Local Bluetooth Low Energy (BLE):

    • Decoded the proprietary framing protocol (0xFC … 0xFE).
    • Transport encryption: AES-128-ECB NoPadding with per-device bluetoothKey.
    • Fully integrates with Home Assistant’s native Bluetooth stack and ESPHome Bluetooth proxies for reliable local unlatching.

  2. The WiFi / Remote Channel (Port 4067):

    • The lock does not use HTTP, HTTPS, or MQTT for remote actions.
    • When woken up, it opens a raw TCP connection to port 4067 and communicates using the exact same framing as the Bluetooth protocol!
    • We captured and decrypted the live remote-unlock command (cat=0x02, cmd=0x0e, data=[0x01]).

  3. 100% Local Options (Zero Cloud):

    • Documented how an OpenWrt firewall NAT redirect rule (iptables) or DNS rewrite lets Home Assistant intercept port 4067 directly, allowing 100% offline local WiFi control with <50ms unlock latency.

:high_voltage: Feature: Concurrent Dual-Channel Unlock (Race BLE & WiFi)

Battery-operated locks sleep aggressively to preserve battery.
Entering 4 + # on the keypad wakes the lock for ~60 seconds.

This integration features Concurrent Dual-Channel Unlock:
When you tap Unlock in Home Assistant, it races Bluetooth (BLE via ESP32 proxies) and the WiFi/Cloud connection at the exact same moment. Whichever channel connects first unlatches the door
and cancels the other!
* If you are in Bluetooth range: BLE unlocks in ~1.5 seconds.
* If a visitor pressed 4 + #: WiFi/Cloud catches the wake session immediately without waiting for Bluetooth timeouts.

:control_knobs: Provided Entities & Features

Platform Entity / Feature Description
Lock lock.* Lock, Unlock, and Latch-open (lock.open)
Binary Sensor binary_sensor.*_door Real-time door position (Open / Closed)
Binary Sensor binary_sensor.*_tamper Tamper and brute-force alarms
Binary Sensor binary_sensor.*_door_open_long Alert when door is left open too long
Binary Sensor binary_sensor.*_bell_ringing Doorbell press event
Sensor sensor.*_battery Battery percentage with native low-battery warnings
Sensor sensor.*_last_event Who unlocked and how (PIN, fingerprint, card, app, remote)
Sensor sensor.*_doorbell_last_ring Timestamp of the last doorbell chime
Events event.* & fc_smarthome_event Full access history fired directly onto the HA event bus
Services fc_smarthome.* Add/delete PIN users, enroll fingerprints, manage RFID cards, and fetch history

:package: Installation via HACS

  1. Open HACS in your Home Assistant instance.
    2. Click the three dots in the top right $\rightarrow$ Custom repositories.
    3. Enter:

    • Repository: https://github.com/JuanmanDev/fc-smart-home-assistant
    • Category: Integration

  2. Click Add, then find FC SmartHome and click Download.

  3. Restart Home Assistant.

  4. Go to Settings > Devices & Services > Add Integration, search for FC SmartHome, and enter your credentials.

:handshake: Feedback & Support

Note: AI used on 99% on this project

Happy automating!