ISEO Argo BLE Lock Integration

A Home Assistant custom component and command-line utility for controlling ISEO smart locks via Bluetooth Low Energy (BLE).

This integration makes Home Assistant behave as a native ISEO ARGO Gateway, providing a professional-grade implementation with specialized commands and real-time monitoring.

[!IMPORTANT]

This project is not affiliated with ISEO, Argo, or Home Assistant and is not an official product. This is an independent implementation for interoperability with the Argo lock system. Use at your own risk. All trademarks and rights reserved to their respective owners.

✨ Features

• 🚀 Native Performance: Uses specialized Gateway commands for fast response times and improved reliability.
• 🤫 Silent Operation: Access-log reads use specialized unread-log commands that do not trigger the lock's audible "beep."
• 👤 User Attribution: Attributes remote operations to the specific Home Assistant user. Audit logs will show "Opened by [HA User] via Home Assistant."
• 🔓 Lock Control: Remotely unlock your ISEO smart lock with real-time feedback.
• 📊 Full Audit Logs: Access every log entry found on the lock, with automatic mapping to Home Assistant users.
• 🔐 Secure Authentication: Uses EC cryptography (SECP224R1) for secure session establishment.
• 📡 Local Control: Direct Bluetooth communication without any cloud dependencies or bridge hardware.

📡 State Updates (Passive, No Polling)

This integration is push-based. Door status, battery level, and lock modes are read from the lock's passive BLE advertisements, so Home Assistant does not connect to the lock on a timer. The lock is only actively connected to on demand: when you open it, and once per physical door-open to read the access log and attribute the event to a user.

[!WARNING] Do not re-introduce polling on recent ISEO firmware. On the latest ISEO firmware, repeatedly connecting to the lock over BLE on a timer triggers a firmware fault. After a few weeks the lock crashes and stops responding entirely — Bluetooth included — and the only way to recover it is a full power cycle by removing and reinserting the batteries.

This is not specific to aggressive intervals: in testing, even a 10-minute periodic connection (a background sync of the lock's user list) was enough to eventually crash the lock. An earlier 30-second door-state poll almost certainly failed faster, but the interval is not the point — any repeated timed connection is unsafe. For this reason the integration now does no periodic polling of any kind: state comes from passive advertisements, the user list is read once at setup and only on demand (a user toggle or the options "refresh users" step), and the access log is read only when a door-open is detected.

The crash was observed on the following firmware (ISEO X1R Smart). If your lock reports these versions or newer, keep polling disabled:

(Internal plate firmware not reported.) You can find these values in the Argo app under the lock's device information.

🚀 Quick Start

Prerequisites

• Home Assistant with Bluetooth support.
• ISEO Smart lock (X1R Smart, Smart Series, etc.).
• Physical Master Card for the lock (required for setup).

Installation via HACS (Recommended)

1. Click the button above, or open HACS → Integrations → ⋮ → Custom repositories and add https://github.com/FezVrasta/iseo-argo-ble with category Integration.
2. Find "ISEO Argo BLE Lock" in HACS and install it.
3. Restart Home Assistant.

🔧 Configuration

The integration uses a streamlined "Direct Master Registration" flow.

1. Add Integration: Go to Settings > Devices & Services > Add Integration and search for "ISEO Argo BLE Lock".
2. Discovery: Select your lock from the discovered Bluetooth devices.
3. Register Gateway: When prompted, click Submit, then scan your physical Master Card on the lock within 30 seconds. The lock will blink green once the card is read successfully.
4. Fetch Users: Click Submit again and scan the Master Card one more time within 30 seconds to download the lock's whitelist.
5. Map Users: Link your physical credentials (RFID tags, PINs, phones) to your Home Assistant user accounts.

👥 User Mapping

Once configured, you can use the Configure button on the integration page to refresh the user mapping. This allows you to:

• Link an RFID tag or PIN to a specific person in Home Assistant.
• See exactly who opened the door in the Home Assistant Logbook.
• Attribute remote openings via the Home Assistant UI to the specific HA user who clicked the button.

Entity Information

Lock Entity

• Domain: lock
• State: locked / unlocked
• Attributes:
  • door_state: Open/closed status (requires hardware sensor)
  • battery_level: Battery percentage
  • last_event: The last recorded action (e.g., "Opened by Marco")

⚠️ Troubleshooting

"No backend with an available connection slot"

• The lock only supports one active connection. Ensure the Argo app is closed on your phone and no other device is connected to the lock.

"Auth failed" during Master Card scan

• Ensure you click Submit in Home Assistant before scanning the card. The lock must be expecting the command when the card is scanned.

Lock has become completely unresponsive (no Bluetooth, no app, no HA)

• On recent ISEO firmware this is the polling-induced firmware crash described above, typically after a few weeks of continuous polling by older versions of this integration. Recover it with a full power cycle: remove the batteries, wait a few seconds, then reinsert them. Update to the latest version of this integration (which no longer polls) to prevent it recurring.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• ISEO and Argo for creating the smart lock system.
• The Home Assistant community for the excellent integration platform.
• Contributors to the protocol documentation and implementation.

⚖️ Legal

This project is for educational and personal use only. The developers are not responsible for any damage or malfunction of your smart lock. Always ensure you have alternative access methods to your property.

European Interoperability Rights

Under European Union law, particularly Article 6 of the EU Software Directive (2009/24/EC), the development of interoperable software solutions may be permitted when necessary to achieve interoperability with independently created programs. This project aims to provide interoperability with existing smart lock systems for legitimate use cases.

Important: This information is provided for general awareness only and does not constitute legal advice. Laws vary by jurisdiction and specific circumstances. Users should consult with qualified legal counsel regarding the applicability of interoperability provisions in their specific situation and jurisdiction.