│ [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!

2

Thanks for setting this up! Hoping to use this instead of finding an exterior keypad to temporarily disable other home security features.

When I install through HACS, I am able to add the custom repository and go to add the FC SmartHome integration, but when I provide my cloud login information I get the following error:

Protocol secrets missing: place fc_secure_data.json and fc_app_privkey.b64 in the config dir or set FC_SECURE_DATA / FC_PRIVATE_KEY_B64.

1 Like
3

Hi @smith1488888 !
Thanks for your coment, please create an issue on Issues · JuanmanDev/fc-smart-home-assistant · GitHub and we can cehck together.
I will try to send a fix buit it woudl be great if I can creat versions for you and you test it.

BTW: I’m not gonna lie, the integration isnot perfect, if you dont have bluetooth you need to pres 4+# and if oyu have it it could take a bit of time also. And i test only my locker, one that have, so apologies if there is any problem.

4

I was going to go create an issue but I see that there is a new version of this app available now, and it appears to have fixed the problem! I am now able to connect my account and it has created many useful entities from the lock. I will start playing around with it and report any issues I find. I am using it with a Pineworld E202 smart lock that was already installed when we bought our home.

Thanks again!