A Home Assistant custom integration for locally controlling Akuvox intercoms and access control devices. All communication happens over your local network — no cloud services required.
- Lock Entities — One lock entity per relay on your device. Unlock doors and gates directly from Home Assistant.
- Webhook Events — Receive real-time notifications when relays trigger, codes are entered, or inputs change state.
- User & Schedule Management — Full CRUD services for managing access codes, user PINs, card codes, and time-based schedules.
- Local Polling — Device state updates every 30 seconds via direct HTTP communication.
- Flexible Authentication — Supports no-auth (IP allowlist), HTTP Basic, and HTTP Digest authentication.
- SSL Support — Optional HTTPS with configurable certificate verification.
- Home Assistant 2026.2.0 or later
- An Akuvox intercom or access control device with HTTP API access (e.g., E21V, R29, or similar models)
- Network connectivity between Home Assistant and the device
- Open HACS in Home Assistant.
- Go to Integrations → click the three-dot menu → Custom repositories.
- Add
https://github.com/tykeal/homeassistant-local-akuvoxwith category Integration. - Search for "Local Akuvox" and install it.
- Restart Home Assistant.
- Download the latest release from the releases page.
- Copy the
custom_components/local_akuvoxdirectory into your Home Assistantconfig/custom_components/directory. - Restart Home Assistant.
- Go to Settings → Devices & Services → Add Integration.
- Search for Local Akuvox.
- Follow the setup wizard:
| Step | Description |
|---|---|
| Device Connection | Enter the IP/hostname and whether to use SSL. |
| SSL Options | Choose whether to verify the SSL certificate. |
| Authentication | Select: None / AllowList, Basic, or Digest. |
| Credentials | Enter username and password (if required). |
| Webhook Events | Optionally enable webhook event delivery. |
Go to Settings → Devices & Services → Local Akuvox → Configure to update connection settings, authentication, or webhook configuration at any time.
One lock entity is created for each relay on the device (e.g., Relay
A, Relay B). Each lock entity supports:
| Action | Description |
|---|---|
| Unlock | Triggers the relay for the configured hold duration. |
| Lock | Not supported — relay closure depends on device config. |
Entity names are derived from the device configuration. If a relay has a custom name configured on the device, that name is used.
When webhooks are enabled, the integration configures your Akuvox device
to send event notifications to Home Assistant. Events are fired on the
Home Assistant event bus as local_akuvox_webhook_received.
Use Developer Tools → Events → Listen to events and enter
local_akuvox_webhook_received to monitor incoming webhooks.
You can also use these events in automations:
automation:
- alias: "Notify on door unlock"
trigger:
- platform: event
event_type: local_akuvox_webhook_received
event_data:
event_type: relay_a_triggered
action:
- service: notify.mobile_app
data:
message: "Front door was unlocked!"| Event Type | Description |
|---|---|
relay_a_triggered |
Relay A was activated (door opened). |
relay_a_closed |
Relay A returned to closed state. |
relay_b_triggered |
Relay B was activated. |
relay_b_closed |
Relay B returned to closed state. |
input_a_triggered |
Input A was triggered. |
input_a_closed |
Input A returned to closed state. |
input_b_triggered |
Input B was triggered. |
input_b_closed |
Input B returned to closed state. |
valid_code_entered |
A valid PIN or card code was entered. |
invalid_code_entered |
An invalid PIN or card code was entered. |
Unrecognized events from the device are emitted as
unknown_<normalized_name> with sanitized query parameters (sensitive
fields such as code are redacted) as the payload.
{
"device_id": "ha_device_registry_id",
"config_entry_id": "ha_config_entry_id",
"event_type": "relay_a_triggered",
"payload": {
"event": "relay_a_triggered",
"status": "1",
"device_user_id": "42",
"user_id": "john.doe",
"username": "John Doe"
}
}| Field | Description |
|---|---|
device_id |
HA device registry ID (may be null). |
config_entry_id |
Home Assistant config entry ID. |
event_type |
Normalized event type string. |
payload.event |
Event name from webhook query param. |
payload.status |
Relay status (null for code events). |
payload.device_user_id |
Device-internal user ID (code events). |
payload.user_id |
External user identifier (code events). |
payload.username |
Display name of the user (code events). |
Note: User identity fields (
device_user_id,user_id,username) are populated from a local cache and may benullon first use. The cache refreshes automatically.Security: Raw PIN codes are never included in event payloads. Only the resolved user identity is emitted.
All services target lock entities belonging to this integration. Call them via Developer Tools → Services or from automations and scripts.
| Service | Description |
|---|---|
local_akuvox.list_schedules |
Retrieve all access schedules. |
local_akuvox.add_schedule |
Create a new access schedule. |
local_akuvox.modify_schedule |
Update an existing schedule. |
local_akuvox.delete_schedule |
Remove a schedule. |
Schedule types (schedule_type must be a string):
"0"— Date Range (specific start/end dates)"1"— Weekly (selected days of the week)"2"— Daily (every day)
| Service | Description |
|---|---|
local_akuvox.list_users |
Retrieve all user codes. |
local_akuvox.add_user |
Create a user (PIN/card). |
local_akuvox.modify_user |
Update an existing user. |
local_akuvox.delete_user |
Remove a user. |
local_akuvox.add_user_schedule_relay |
Assign schedule-relay. |
local_akuvox.remove_user_schedule_relay |
Remove schedule-relay. |
service: local_akuvox.add_user
target:
entity_id: lock.local_akuvox_front_gate
data:
name: "Jane Doe"
schedules: "10, 20"
lift_floor_num: "3"
private_pin: "5678"- Verify the device IP address is correct and reachable from your Home Assistant host.
- Check that the HTTP API is enabled on the device.
- If using authentication, confirm the credentials are correct.
- If using SSL, try disabling certificate verification to rule out certificate issues.
- Ensure your Home Assistant instance is accessible from the device's network.
- Check that webhooks are enabled in the integration options.
- Verify the device's action URL configuration points to the correct Home Assistant webhook URL.
- Use HTTPS/TLS for webhook URLs.
valid_code_enteredwebhooks include the entered PIN in the query string; using HTTP transmits it in plaintext. Only use HTTP on a trusted network for testing.
- The device may not have responded to the initial status poll. Wait for the next polling interval (30 seconds).
- Check Home Assistant logs for connection errors.
Users and schedules provisioned via Akuvox cloud services cannot be modified or deleted through this integration. The integration will return a clear error message when this is attempted.
This project is licensed under the Apache License 2.0. See the LICENSE file for details. This project follows the REUSE specification for license compliance.