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

---

Updating

A Doorman update needs a Home Assistant restart. This is not a workaround — there is no other way.

Home Assistant imports every custom integration once, when it starts. Python cannot replace a module that is already loaded, and Home Assistant has no mechanism to unload one: the entities, event listeners and services that are already running hold references to the old classes. So when HACS downloads a new version of Doorman it writes the new files to disk, but the code Home Assistant is running is still the code it imported at boot. Reloading the integration entry (Settings → Devices & Services → Doorman → Reload) re-runs the old code — it does not pick up the new files.

After updating Doorman in HACS:

1. Restart Home Assistant. HACS raises a repair issue in Settings → System ("Restart required") right after the download, and it can perform the restart for you — click through that and you are done. Otherwise use Settings → System → Restart Home Assistant.
2. Reload the browser tab once Home Assistant is back. The panel is a JavaScript module that your browser has already loaded; restarting Home Assistant from the UI does not reload the page, so the tab keeps running the previous version's frontend code. Doorman detects this and shows a "Doorman was updated to X — reload this page to finish updating" banner at the top of the panel; a single page refresh (or Ctrl/Cmd-Shift-R) clears it.

Nothing is lost by waiting to restart: the new version simply is not active until you do.

---

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. The log is stored by Home Assistant, so it survives restarts, and events recorded by the intercom while HA was down are pulled in at startup (silently — historical events never trigger notifications)
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
doorman.hangup_calls	—	Hang up all active call sessions
doorman.resync_log_history	—	Re-read the device's on-box access log history and merge anything missing into Doorman's log (no duplicates, no notifications). The number of events added is written to the Home Assistant log

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