A Home Assistant integration for managing users and access credentials on 2N IP intercoms — directly from your Home Assistant sidebar.
- 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 persisted access events (authentications, denials, card taps); history backfills at startup without notifying
- Push-like event delivery — access events surface within ~1 s via long-polling (no extra config required)
- Doorbell notifications — optional Companion notify when a quick-dial key is pressed, with optional camera snapshot and Unlock / Answer action buttons
- Camera — still-image camera entity (JPEG snapshots from the intercom)
- Door / I/O / SIP sensors — door contact, hardware inputs, and SIP registration health
- Call ringing / active sensors —
binary_sensor.doorman_*_call_ringingand_call_activefor conditional dashboard cards - Device restart — button entity to reboot the intercom
- 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_accessHA events on every access attempt, usable in automations - Relay switches — control door relays directly as HA switch entities
- Call control — hang up, answer, or dial via services
- Configurable poll interval — adjust how often users and switches are refreshed (Settings → Integrations → Configure)
- Local only — communicates directly with the device; no cloud dependency
- Home Assistant 2024.11.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
Directoryservice 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.
- Open HACS → Integrations
- Search for Doorman (it is in the HACS default store — no custom repository needed)
- Download Doorman and restart Home Assistant
- Copy
custom_components/doorman/into your HAconfig/custom_components/directory - Restart Home Assistant
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:
- 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.
- 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.
- Go to Settings → Integrations → Add integration and search for Doorman
- Enter your 2N device's IP address, API username, and password
- Use HTTPS defaults on (recommended — directory traffic carries PINs, cards, and API passwords). Turn Verify SSL certificate off if the intercom uses a self-signed certificate
- The Doorman panel appears in the left sidebar
Enable the HTTP API on your 2N device:
-
Log in to the 2N web interface
-
Navigate to Services → HTTP API
-
Enable HTTP API
-
Create a user account and grant the HTTP API services you need:
Service Privilege Needed for Directory Monitoring + Control View / create / edit / delete users System Control Directory writes (create/edit/delete); restart button Access Log Monitoring Access Log tab and live event delivery Switch Control Relay switch entities (there is no Monitoring-only level — omit this if you do not want HA to open the door) Camera Monitoring Camera entity / doorbell snapshot Phone Monitoring SIP registration + call ringing/active sensors; Answer action I/O Monitoring Hardware input binary sensors (when the device exposes them) Minimum for the panel alone: Directory + System Control + Access Log. Other services are optional — Doorman probes them at startup and skips entities when the privilege is missing (entities do not flap unavailable).
-
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.
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. |
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. Entity IDs are device-scoped (*.doorman_<serial_slug>_…, falling back to an entry-id slug) so multiple intercoms do not collide.
- Settings → Devices & Services → Doorman → delete each config entry
- Remove the integration in HACS (or delete
custom_components/doorman/for a manual install) - Restart Home Assistant
Stored links, notification settings, and access-log history under .storage/doorman* can be deleted manually if you want a clean slate.
The Doorman panel has four 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) |
| Notifications | Configure access and doorbell notify targets, iOS sounds, and Android channels. Doorbell notifies can attach a camera snapshot, Unlock / Answer Companion actions, optional time-sensitive delivery, and optional Call-ringing notifies (outgoing ringing uses doorbell wording; a Call ringing within a few seconds of a doorbell press is suppressed so you are not double-chimed). Snapshot fetches are coalesced for a couple of seconds (including brief failure cooldown) so several phones ringing at once do not stampede the intercom camera. Incoming Call-ringing Answer buttons pin the call session id — Answer is omitted if the event has no session; Answer is intercom-side, not a phone softphone. Set the doorbell key code (default %1 for the Verso quick-dial / call button; use %2, %3, … for other buttons). Leave the doorbell key empty to disable doorbell notifications on that device |
| Device | View device information and trigger immediate access |
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
All services are admin-gated: calls from a signed-in non-admin user are rejected. Automations and scripts (no user context) still run — that is Home Assistant's admin-service contract. Each service accepts an optional device field (config entry ID) when multiple devices 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.answer_call |
— | Answer an incoming call |
doorman.dial |
number |
Place an outgoing call |
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 |
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:
- Go to Developer Tools → Events and subscribe to
doorman_access - Present a card or enter a PIN on the intercom
- The event should appear within a second
The doorman_access event fires on every access attempt and on doorbell presses:
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"trigger:
- platform: event
event_type: doorman_access
event_data:
event_type: DoorbellPressed
action:
- service: notify.mobile_app_phone
data:
message: "Someone is at the door"Available event_type values include UserAuthenticated, UserRejected, CodeEntered, CardEntered, FingerEntered, MobKeyEntered, and the synthetic DoorbellPressed (when a matching doorbell key is configured).
When the visitor starts a call, binary_sensor.doorman_<serial>_call_ringing turns on. Use a conditional card so Answer / Unlock only appear while ringing (replace the slug and optional user_uuid):
type: conditional
conditions:
- condition: state
entity: binary_sensor.doorman_YOURSLUG_call_ringing
state: "on"
card:
type: vertical-stack
cards:
- type: picture-entity
entity: camera.doorman_YOURSLUG_camera
show_state: false
- type: horizontal-stack
cards:
- type: button
name: Answer
icon: mdi:phone
tap_action:
action: call-service
service: doorman.answer_call
- type: button
name: Unlock
icon: mdi:door-open
tap_action:
action: call-service
service: doorman.grant_access
data:
access_point_id: 1
- type: button
name: Hang up
icon: mdi:phone-hangup
tap_action:
action: call-service
service: doorman.hangup_callsdoorman.answer_call answers on the intercom (not softphone audio in the browser). The camera entity is still JPEG only.
# Install test dependencies (current HA pin)
pip install -r requirements_test.txt
# Unit tests (skip Docker/Podman integration suite)
pytest tests/ --ignore=tests/integration -v
# Lint
ruff check custom_components/ tests/MIT