Skip to content

About

Home Assistant integration for managing 2N intercom users and access codes

Topics

Resources

Contributing

Security policy

Stars

5 stars

Watchers

1 watching

Forks

Repository files navigation

Doorman

CI HACS Default GitHub release License: MIT

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

Doorman logo


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 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_ringing and _call_active for 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_access HA 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

Requirements

  • 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 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
  2. Search for Doorman (it is in the HACS default store — no custom repository needed)
  3. Download 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. 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
  4. 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 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).

  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. Entity IDs are device-scoped (*.doorman_<serial_slug>_…, falling back to an entry-id slug) so multiple intercoms do not collide.

Removing Doorman

  1. Settings → Devices & Services → Doorman → delete each config entry
  2. Remove the integration in HACS (or delete custom_components/doorman/ for a manual install)
  3. Restart Home Assistant

Stored links, notification settings, and access-log history under .storage/doorman* can be deleted manually if you want a clean slate.


Usage

Sidebar panel

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

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 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

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 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).

Dashboard card — answer while ringing

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_calls

doorman.answer_call answers on the intercom (not softphone audio in the browser). The camera entity is still JPEG only.


Development

# 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/

License

MIT

About

Home Assistant integration for managing 2N intercom users and access codes

Topics

Resources

Contributing

Security policy

Stars

5 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages