2N IP Intercom

Integration for 2N IP intercoms and access units (IP One, IP Verso, IP Force / IP Safety, IP Style, the Access Unit family, and similar models) over the 2N HTTP API v2. One intercom becomes one GEM device. The driver controls the unit's relays and outputs (one GEM zone each), grabs camera snapshots, receives live keypad / card / PIN / input events, keeps the 2N user directory in sync with GEM's users (PINs and RFID cards), projects GEM access-rule schedules onto the device so it enforces day/hour windows offline, and toggles the camera's privacy masking.

Communication is HTTPS to the intercom's /api/* endpoints; the unit's self-signed certificate is accepted automatically.

What this integration covers

• Relay and output control — create one GEM zone per relay or output and drive it with open / close / pulse / switch. pulse is the usual "buzz the door open" action (momentarily energizes, then releases).
• Camera snapshots — grab a JPEG still from the intercom's camera at a chosen resolution.
• Live door events — keypad presses, the call (*) button, PIN codes, RFID/NFC card reads, and digital input changes (e.g. a request-to-exit button) arrive in real time and surface as device attributes you can build triggers and access logging on.
• User and credential sync — push GEM users (name + PIN + RFID card) into the 2N directory, update existing 2N users, and pull the 2N directory back into GEM.
• Offline access schedules — GEM access-rule day/hour windows are written onto each 2N user as inline time profiles, so the intercom enforces the schedule even when GEM is unreachable.
• Camera privacy masking — turn the camera's native privacy mask on or off and read its current state.

What this integration does NOT cover

• Call audio / video (SIP). The intercom's voice and video call path runs over SIP through 2N's own apps and SIP server; GEM controls and monitors the unit but is not the call endpoint.
• General device configuration. The HTTP API v2 cannot set arbitrary single configuration keys, so GEM does not act as a config editor. The one config-backed feature wired up is privacy masking (see Camera privacy masking) — everything else is configured in the 2N web UI.
• Defining the privacy mask region. GEM toggles masking on/off; the mask area itself is drawn on the device (Hardware → Camera → Privacy Masking).

Prerequisites

• The 2N HTTP API v2 enabled on the intercom: Services → HTTP API, with an account whose privileges cover what you need — I/O Control (relays/outputs), Camera (snapshots), Phone / Call Log (events), and Directory / Access Control (user sync). Each privilege is a separate checkbox on the account.
• For user/credential sync, the account needs directory write rights.
• For privacy masking, a web-config login (typically the admin account) — this is a different account from the HTTP API account — and a privacy mask region already defined on the device.
• HTTPS reachability from the GEM controller to the intercom. The event feed (live key/card/PIN/input) needs firmware that supports the API event log — firmware 2.30 or newer.

Setup

1. In GEM, go to System → Devices → Add Device (Open Devices) and pick 2N IP Intercom as the driver.
2. Enter the intercom's 2N IP Address, API Username, and API Password (the password is stored encrypted).
3. (Optional) Adjust HTTPS Port (default 443), the Use HTTPS toggle, and HTTP API Auth Method. Set the auth method to match the device (Services → HTTP API → Account → Authentication) — newer 3.x firmware often defaults to Digest and rejects Basic on directory writes. A Base URL Override is available if the unit sits behind a non-standard path.
4. Save. The driver connects, reads the current relay/output states, records the device's identity, syncs users, and opens a live event subscription.
5. Create one zone per relay or output you want to control, bound to this device, and set its address (see Mapping relays and outputs to zones). The driver does not create these zones for you.
6. (Optional) If you will use privacy masking, set Web Config Username and Web Config Password to a web-rights login.

Subsystem placement

This driver hints intercom / access / gate / lock, but a stock GEM install seeds none of those names — it seeds Doors, Gates, Security, etc. Because the New Zone editor only pre-selects a subsystem on an exact name match, it does not pre-select one for a 2N relay. Pick the subsystem yourself: Doors for a door-strike relay, Gates for a gate, or Security for an alarm/aux output. The driver handles open/close/pulse directly and uses the per-zone Normally Closed toggle for inverted wiring, so the subsystem choice affects how the zone is grouped and presented, not whether the relay fires.

Mapping relays and outputs to zones

Create one zone per controllable point and bind it to the 2N device. The zone address selects the relay or output:

Address	Targets
1, 2, …	Relay 1, relay 2, … (a bare number is a relay)
relay_1	Relay 1 (explicit form)
output_1	Output 1 (a switched output port rather than a relay)

Set the zone's Normally Closed toggle when the relay is wired to a normally-closed contact — it inverts both the command sent and the reported state. The driver maintains a state attribute on each zone (open / closed), refreshed on every poll and whenever the device reports a switch/output change; state is cataloged, so it autocompletes in the Attribute editor and can drive attribute triggers.

Commands

Command	Args	What it does
open	address	Sets the relay/output contact open (de-energizes it).
close	address	Sets the relay/output contact closed (energizes it).
pulse	address, delay	Energizes the relay, waits delay ms (default 1000), then releases — the typical momentary door release / buzz-in.
switch	address, state	Drives a named 2N switch by id; state is on / off. (For the device's logical Switch outputs, distinct from raw relays.)
get_image / snapshot	width, height	Returns a base-64 JPEG from the camera (default 1280×960).
privacy_on	—	Turns camera privacy masking on.
privacy_off	—	Turns camera privacy masking off.
get_privacy	—	Reads the current masking state into the privacy_state attribute.
get_relay_states	—	Re-reads all relay/output states (also runs automatically on the poll).
get_io_ports	—	Lists the unit's I/O capabilities.
get_system_info	—	Refreshes the device identity attributes (model, firmware, serial, …).
get_users	—	Returns the 2N directory.
create_user	first_name, last_name, pin, rfid	Adds a user to the 2N directory with an optional PIN and RFID card.
set_credential	uuid, first_name, last_name, pin, rfid	Updates an existing 2N user's PIN / card (by 2N user uuid).
test_audio	—	Runs the intercom's built-in audio self-test.
sync_to_gem	—	Imports the 2N directory users into GEM.

open and close act on the relay contact, not on a door's lock state — for a door strike, energizing (close) usually releases the latch and de-energizing (open) re-locks it, but that depends on wiring. Use pulse for a momentary buzz-in, and the zone's Normally Closed toggle to match your contact wiring.

Live events

The driver keeps a persistent event subscription open to the intercom and reflects what happens at the door onto device attributes — these are what you build automation triggers and access logging on:

Attribute	Set when
last_key_pressed	A keypad key is pressed (cleared after ~1 second).
call_key / call_press	The call (*) button is pressed — fires the call workflow (access-log entry + snapshot for visitor capture).
pin	A PIN code is entered (cleared after ~1 second).
rfid	An RFID/NFC card is presented (cleared after ~1 second so the same card re-triggers).
input_<n>_state	A digital input changes (on / off) — e.g. a request-to-exit button or door contact.

The driver asks the device which event types it supports and subscribes to that set, re-subscribing about hourly. If the device rejects the subscription id (typically after an intercom reboot, which invalidates it), the driver drops the stale id and resubscribes on the next poll cycle, so events resume automatically; transient network errors keep the existing subscription so queued events aren't lost. If the intercom is too old to support the event log, these attributes stay idle — see Troubleshooting.

When the intercom becomes unreachable (or starts resetting connections), the poll loop backs off exponentially — 1 s, 2 s, 4 s, … capped at one probe per 60 s — instead of hammering the device, which would keep a wedged unit from ever recovering. After 5 consecutive failed poll cycles the device is marked offline (its connected attribute, feeding the standard connection monitor and offline alarms). The driver keeps probing at the capped interval and recovers automatically: the first successful cycle marks it connected again and restores the normal polling cadence. All requests ride a per-device keep-alive connection (capped at 2 sockets), so each probe reuses one TCP/TLS session rather than opening a fresh handshake.

Users, credentials, and schedules

On connect the driver syncs GEM users to the 2N directory, and you can drive it on demand:

• create_user adds a directory entry with a name, PIN, and/or RFID card.
• set_credential updates an existing 2N user (matched by their 2N uuid).
• get_users / sync_to_gem read the directory; sync_to_gem imports those users into GEM.

Only credentials that are in scope for this device are pushed — set up the user's role / access scope in Users and Access Control before bulk-syncing. GEM access rules carry day/hour windows; the driver writes those windows onto each 2N user as inline time profiles, so the intercom keeps enforcing the schedule even if GEM goes offline. Your manually-numbered Profile slots on the device are left untouched, and a user whose rules exclude every time window is disabled on the device (fail-safe deny rather than the 2N "no profile = unlimited" behavior). The first_name and last_name fields synced to the directory are cataloged for use in the Attribute editor.

Camera privacy masking

privacy_on / privacy_off / get_privacy drive the camera's native Privacy Masking feature. Because the HTTP API v2 can't set an individual configuration key, GEM does this through the intercom's web-config session instead of the API account — so it needs a web-rights login:

• Set Web Config Username / Web Config Password to an account that can log into the device web UI (often admin). These default to the API username/password if left blank, but the HTTP API account usually can not log into the web UI, so set them explicitly.
• Define the actual mask region on the device (Hardware → Camera → Privacy Masking). Turning masking on with no region configured has no visible effect.

The current state is reflected onto the privacy_state attribute (on / off).

Attribute reference

Device attributes

Name	Type	Required	Description
ip	string	yes	Intercom IP address.
username	string	yes	HTTP API account username.
password	string	yes	HTTP API account password. Stored encrypted.
port	int	no	HTTPS port (default 443).
ssl	bool	no	Use HTTPS (default true).
base_url	string	no	Full base URL override; supersedes ip/port/ssl.
auth_method	string	no	basic or digest (default basic). Match the device — 3.x firmware often needs digest.
web_username	string	no	Web-config login used by privacy masking. Defaults to username.
web_password	string	no	Web-config password. Stored encrypted. Defaults to password.

The driver also writes live device attributes as it runs: the unit's identity from its system info (model, firmware/swVersion, hwVersion, serial number, and similar — whatever the device reports), the relay_<n>_state / output_<n>_state / input_<n>_state port states, the event attributes from the table above (last_key_pressed, pin, rfid, call_key, call_press), and privacy_state.

Zone attributes

Name	Type	Description
address	string	Relay/output id — "1", "relay_1", or "output_1" (required).
normally_closed	bool	Invert the command and reported state for NC wiring (default false).
state	string	open / closed, maintained by the driver.

Troubleshooting

• Every API call returns 401 Unauthorized — the HTTP API account lacks the privilege for that operation. Grant the matching checkbox (I/O Control, Camera, Directory) under Services → HTTP API → Account. If even basic calls fail on 3.x firmware, switch HTTP API Auth Method to Digest.
• Relays work but directory/user sync fails — grant the account Access Control / directory write rights, and set the auth method to Digest (3.x firmware commonly rejects Basic on directory writes).
• Events never arrive (no card/key/PIN attributes update) — the device firmware must support the API event log (2.30+). The driver auto-narrows the event filter to what the unit advertises; if the subscription still fails, upgrade the firmware.
• Snapshot looks like the wrong camera — the snapshot always uses the intercom's primary camera source; only width and height are adjustable. There is no camera-select argument. On a two-camera unit, the secondary view isn't available through this command.
• privacy_on / privacy_off does nothing — set Web Config Username / Password to a web-rights login (the HTTP API account usually can't log into the web UI), and make sure a mask region is defined on the device. Masking with no region has no visible effect.
• The relay fires the wrong way (locks when it should release, or vice-versa) — flip the zone's Normally Closed toggle to match NC vs NO wiring, and use pulse for a momentary buzz-in rather than a steady open/close.

Related documentation

• Devices — adding and configuring the intercom device row.
• Zones — creating one zone per relay/output and binding it to the device.
• Subsystems — the Doors / Gates / Security subsystem the zones belong to.
• Commands — running these commands from the admin UI, macros, or scenes.
• Users and Access Control — the GEM users and access rules that drive credential and schedule sync.
• Access Log — where door events and call-button presses are recorded.