Homebridge UniFi Access

Complete HomeKit support for the UniFi Access ecosystem using Homebridge.

Table of Contents

• About
• Supported Devices
• Features
• Prerequisites
• Installation
• Configuration
• Documentation
• Contributing
• License

About

@mp-consulting/homebridge-unifi-access is a Homebridge plugin that provides HomeKit support for Ubiquiti's UniFi Access door access security platform — including doorbell, reader, lock, and controller hardware.

This plugin discovers all your supported UniFi Access devices and makes them available in HomeKit with minimal configuration. It supports all known UniFi Access controller configurations (UniFi CloudKey Gen2+, UniFi Dream Machine Pro/SE, UniFi NVR, etc.) and uses the native UniFi Access events API for realtime event capturing.

Supported Devices

| Device | Capabilities | |--------|-------------| | UA Hub | Lock, doorbell, door position sensor (DPS), terminal inputs (REL, REN, REX) | | UA Hub Door Mini | Lock, door position sensor (DPS), request to exit sensor (REX) | | UA Ultra | Lock, door position sensor (DPS), request to exit sensor (REX) | | UA Gate | Main gate (lock or garage door opener), side door (pedestrian gate) with separate lock, door position sensors for both doors | | UA Readers | Access method switches for Face, Hand Wave, Mobile, NFC, PIN, and QR |

Features

• Easy configuration - provide your controller IP address, username, and password to get started
• Full HomeKit support - locks, doorbells, door position sensors, terminal inputs, access method switches, and automation accelerators
• Automatic name sync - device and door names from UniFi Access are automatically reflected in HomeKit, including per-door names for multi-door hubs like the UA Gate
• Multiple controllers - seamlessly integrate several UniFi Access controllers into HomeKit
• Realtime device detection - automatically adds and removes devices in HomeKit as they change on your controller, without restarting Homebridge
• Customizable - feature options let you show/hide specific devices and tailor behavior via the built-in webUI
• MQTT support - publish events to an MQTT broker for further automation

Prerequisites

• Homebridge >= 1.8.0
• Node.js >= 18
• A UniFi Access controller running the latest stable firmware
• A local user account on the controller (recommended over Ubiquiti cloud credentials; 2FA is not supported)

Installation

Via Homebridge UI (recommended)

1. Open the Homebridge UI
2. Go to the Plugins tab
3. Search for @mp-consulting/homebridge-unifi-access
4. Click Install

Via CLI

npm install -g @mp-consulting/homebridge-unifi-access

Configuration

The recommended way to configure the plugin is through the Homebridge UI. For manual configuration, add the following to the platforms array in your Homebridge config.json:

{
    "platform": "UniFi Access",
    "name": "UniFi Access",
    "controllers": [
        {
            "address": "1.2.3.4",
            "username": "homebridge",
            "password": "your-password-here"
        }
    ]
}

A sample configuration file is available at config.sample.json.

Optional Settings

| Setting | Description | |---------|-------------| | controllers[].name | Custom name for the controller (used in logs) | | controllers[].mqttUrl | MQTT broker URL (e.g. mqtt://1.2.3.4) | | controllers[].mqttTopic | MQTT base topic (default: unifi/access) | | options | Array of feature options for granular control | | ringDelay | Delay in seconds between doorbell rings (default: 0) |

Documentation

• Feature Options - show/hide devices and customize behavior
• MQTT - configure MQTT event publishing
• Events - UniFi Access event types and payloads
• UniFi Access API - native API library
• Changelog - release notes and version history

Contributing

# Install dependencies
npm install

# Build
npm run build

# Run linter
npm run lint

# Run tests
npm test

# Start in dev mode with live reload
npm run watch

Event Schema Monitor

A live monitoring script is included to detect UniFi Access API changes across firmware updates. It connects to a controller, listens to real-time events, and validates each message against known schemas — reporting any new fields, missing fields, or type changes.

# Uses credentials from tests/hbConfig/config.json
npm run monitor:events

# Or point to a different Homebridge config
npm run monitor:events -- --config /path/to/config.json

# Or specify credentials directly
npm run monitor:events -- --address 192.168.1.1 --username admin --password secret

# Save raw event payloads to tmp/events/ for debugging
npm run monitor:events -- --dump

Sample output:

2026-02-28T23:02:09.004Z OK DEVICE_REMOTE_UNLOCK event_object_id=6c63f8431750
2026-02-28T23:02:09.007Z OK DEVICE_UPDATE_V2 event_object_id=3de83e52-...
2026-02-28T23:02:09.008Z MISMATCH LOCATION_UPDATE event_object_id=c87d8d81-...
  + data.new_field: unexpected_field — Type: string

When mismatches are found, update the schemas in tests/event-schemas.ts (the single source of truth) and the type definitions in src/hub/access-hub-types.ts to match the new API.

License

MIT