Doorman

A Home Assistant integration for managing users and access credentials on 2N IP intercoms — directly from your Home Assistant sidebar.

---

Features

• Sidebar panel — dedicated Doorman view pinned to the HA left navigation
• User management — create, edit, and delete directory users on your 2N device
• Credential control — set and update PINs, RFID cards, and switch codes per user
• Enable / disable users — toggle access without deleting the user
• Validity windows — configure time-limited access (valid from / valid to)
• Access log — browse the most recent access events (authentications, denials, card taps)
• Push-like event delivery — access events surface within ~1 s via long-polling (no extra config required)
• Multi-device support — manage multiple 2N intercoms from a single HA instance
• Multiple access points — grant access to any access point, not just the first one
• HA user linking — associate 2N directory users with Home Assistant accounts for presence automations
• Access notifications — send a notification to any HA notify service when a linked user authenticates
• Access events — fires doorman_access HA events on every access attempt, usable in automations
• Relay switches — control door relays directly as HA switch entities
• Configurable poll interval — adjust how often users and switches are refreshed (Settings → Integrations → Configure)
• Local only — communicates directly with the device; no cloud dependency

---

Requirements

• Home Assistant 2024.1.0 or later
• A 2N IP intercom with the HTTP API enabled (Services → HTTP API)
• An API user on the device with Directory permission

Firmware note: Directory write access (create/edit/delete users) requires a 2N firmware version that exposes the Directory service to HTTP API users. Older firmware (e.g. 2.45.x) does not include this service, so write operations will fail even with all other permissions enabled. If Doorman reports that directory write is unavailable, check Administration → Firmware in the 2N web interface for an update. Read access (viewing users and the access log) works on all supported firmware versions.

---

Installation

Via HACS (recommended)

1. Open HACS → Integrations → ⋮ → Custom repositories
2. Add https://github.com/dougrathbone/2n-doorman with category Integration
3. Install Doorman and restart Home Assistant

Manual

1. Copy custom_components/doorman/ into your HA config/custom_components/ directory
2. Restart Home Assistant

---

Configuration

1. Go to Settings → Integrations → Add integration and search for Doorman
2. Enter your 2N device's IP address, API username, and password
3. The Doorman panel appears in the left sidebar

2N device setup

Enable the HTTP API on your 2N device:

1. Log in to the 2N web interface
2. Navigate to Services → HTTP API
3. Enable HTTP API
4. Create a user account with the following permissions:
   • Directory — read + write (required for user management)
   • System with Control access — required for create/edit/delete operations
   • Access Log — required for the Access Log tab and event delivery
5. Note the username and password for HA setup

If the Directory permission option is not visible, your device firmware is too old to support directory write via the HTTP API. See the firmware note in Requirements.

Changing integration options

After setup, go to Settings → Integrations → Doorman → Configure to adjust:

Option	Default	Description
Poll interval	30 s	How often users and relay switch states are refreshed. Access events are delivered via long-polling regardless of this setting.

Multiple devices

Add a separate integration entry for each 2N device (Settings → Integrations → Add integration → Doorman). The sidebar panel shows a device selector in the header when more than one device is configured. Services accept an optional device field (the config entry ID) to target a specific device; without it, calls are routed automatically when only one device is configured.

---

Usage

Sidebar panel

The Doorman panel has three tabs:

Tab	Description
Users	View all directory entries; add, edit, or delete users and their credentials
Access Log	Browse recent access events from the device
Device	View device information and trigger immediate access

Linking 2N users to HA accounts

In the Users tab, open any user and use the Link to HA User dropdown to associate them with a Home Assistant account. Once linked:

• The HA user's name appears alongside their 2N entry
• Access events include the linked HA user ID, enabling presence automations

Services

All services accept an optional device field (config entry ID) to target a specific device when multiple are configured.

Service	Key fields	Description
doorman.create_user	name, pin, card, code, enabled, valid_from, valid_to	Add a new user to the 2N directory
doorman.update_user	uuid (required) + any field above	Update an existing user's credentials
doorman.delete_user	uuid	Remove a user from the 2N directory
doorman.grant_access	access_point_id (default 1), user_uuid	Open an access point immediately

Push-like event delivery

Access events (card swipes, PIN entries, authentications) are delivered within ~1 second — no polling delay. Doorman holds a long-poll HTTP connection open to the 2N device (GET /api/log/pull?timeout=20); the device responds as soon as an event occurs.

No configuration is required. To verify it's working:

1. Go to Developer Tools → Events and subscribe to doorman_access
2. Present a card or enter a PIN on the intercom
3. The event should appear within a second

Automations

The doorman_access event fires on every access attempt:

trigger:
  - platform: event
    event_type: doorman_access
    event_data:
      event_type: UserAuthenticated
action:
  - service: notify.mobile_app_phone
    data:
      message: "{{ trigger.event.data.params.user.name }} entered"

Available event_type values: UserAuthenticated, UserRejected, CodeEntered, CardEntered, FingerEntered, MobKeyEntered.

---

Development

# Install test dependencies
pip install -r requirements_test.txt

# Run tests
pytest tests/ -v

# Lint
ruff check custom_components/ tests/

---

License

MIT