https://github.com/dougrathbone/2n-doorman
Home Assistant integration for managing 2N intercom users and access codes
https://github.com/dougrathbone/2n-doorman
2n custom-integration hacs home-assistant intercom
Last synced: about 1 month ago
JSON representation
Home Assistant integration for managing 2N intercom users and access codes
- Host: GitHub
- URL: https://github.com/dougrathbone/2n-doorman
- Owner: dougrathbone
- Created: 2026-03-29T06:14:56.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T22:48:10.000Z (about 2 months ago)
- Last Synced: 2026-04-03T04:19:07.094Z (about 2 months ago)
- Topics: 2n, custom-integration, hacs, home-assistant, intercom
- Language: Python
- Size: 108 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Doorman
[](https://github.com/dougrathbone/2n-doorman/actions/workflows/ci.yml)
[](https://hacs.xyz)
[](https://github.com/dougrathbone/2n-doorman/releases)
[](LICENSE)
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](#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:
```yaml
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
```bash
# Install test dependencies
pip install -r requirements_test.txt
# Run tests
pytest tests/ -v
# Lint
ruff check custom_components/ tests/
```
---
## License
MIT