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, camera	Returns a base-64 JPEG from the camera (default 1280×960). camera selects internal (default) or external on two-camera units. Models with no camera return an error rather than an image — see Snapshots on cameraless models.
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 — the keypad call key (*) on keypad models, or a quick-dial button (reported as %1, %2, …) on button units like the IP One. 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.
call_session_state / call_session_originator	The intercom's call session changes state (initialized, terminated, …). The originator says who started it — button for a doorbell press versus an incoming SIP call — so triggers can follow the call lifecycle (ringing panels, missed-call logic) without touching the call_press doorbell path.

The driver asks the device which event types it supports and subscribes to that set, re-subscribing about hourly. On units whose event vocabulary lacks the native CardEntered event, the driver falls back to the unified UserAuthenticated/UserRejected events instead: it resolves the reported directory user to the linked GEM user (via the mapping the user sync maintains) and replays that user's stored RFID credential through the normal access path, so access rules and logging behave the same. A device-side rejection is logged and still evaluated against GEM's own rules — GEM stays the authority, exactly as with a native card event the device marked invalid. Credentials the device doesn't recognize at all can't be matched this way (these firmwares omit the raw card UID from the event), so enroll cards in the 2N directory or sync users for the fallback to see them. 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.

Snapshots on cameraless models

Not every unit in the 2N range has a camera. The Access Unit family (Access Unit M, Access Unit 2.0, and similar reader-only models) is card/PIN only, and answers api/camera/snapshot with an API error — code 1, function is not supported — rather than an image.

GEM captures a snapshot for every access-log entry, so on a cameraless unit that call fails on every card swipe or PIN entry. The driver reports the error instead of returning it as an image, and the access-log row is simply left without a snapshot; the failure is logged as 2n http snapshot is not an image.

To get a picture of who is at a cameraless reader, point the access device at a real camera:

1. Add the camera as its own GEM device (any driver that supports a snapshot command — ONVIF, AXIS, a 2N intercom on the same door, and so on).
2. On the access-unit device, set the camera_zone_id attribute to the camera's zone. The attribute editor opens a zone picker, so you choose the camera by name; GEM reads both the camera device and the camera selector off the zone, because a camera zone's address is the selector (an ONVIF media profile token, an ACS videoSource id, an NVR channel).
3. If the camera has no zone, set camera_device_id to that camera device's id instead, plus camera_address to pick a specific camera/channel on a multi-camera device — it is passed through as the snapshot command's camera argument.

camera_zone_id wins when both are set, and falls back to the explicit pair if the zone or its device is unavailable. Either way GEM takes the snapshot from the camera instead of the reader, and never calls the reader's camera API.

See Readers with no camera for the full list of drivers that can serve as the camera.

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

The identity attributes are a fixed set — variant, serialNumber, hwVersion, swVersion, buildType and deviceName. Any other field the intercom returns from its system info is ignored rather than written through, so a device cannot name attributes on its own GEM record. If a firmware release adds an identity field you need, it has to be added to the driver.

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 — on a two-camera unit, pass camera as internal (the default) or external in the snapshot command args.
• Access-log entries have no picture — the unit has no camera, so the error document it returns is rejected rather than stored as an unrenderable image. The log records access log snapshot unavailable with the device's own reason. Set camera_zone_id on this device to the camera zone covering the door and badge-read captures photograph through that zone's camera instead — see Snapshots on cameraless models. (Rows written by older builds may still hold a broken image; those are historical and are not rewritten.)
• 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 Activity — reporting and investigating door events and call-button presses.