Akuvox Intercom

Controls Akuvox IP intercoms — R20 / R23 / R27 and E12 / E16 door stations, X912 / X915 lobby stations, and C313 / C315 / S532 indoor monitors — over the station's own HTTP interfaces.

Driver name: akuvox_intercom

Akuvox has no on-premise controller. Every station is its own GEM device, and a forty-door building is forty device rows. That is a property of the product, not of this driver.

The two HTTP surfaces

Akuvox stations answer on two different HTTP paths, and this driver uses both because each does something the other cannot.

Path	Used for	Auth	Notes
GET /fcgi/do?action=OpenDoor…	Door release	Credentials as query parameters (basic auth also sent)	The documented "Open Door by HTTP" feature. Must be enabled per relay on the station.
POST /api	Everything else	HTTP basic	JSON envelope: {"target": …, "action": …, "data": {…}} answered with {"result": {"code": 0, …}}. code 0 means success.

warning

The door-release path carries the username and password in the query string. That is the vendor's design, not a driver choice. Keep intercoms on a trusted door VLAN, or set protocol to https so the query string is inside TLS.

Prerequisites

• Akuvox firmware with the HTTP API present — 20.x or newer on R2x / E1x door stations, 220.x or newer on the X9xx range.
• An admin-level web account on the station for GEM. The factory admin account works; a dedicated account is better practice.
• Open Relay via HTTP enabled on every relay you intend to drive. This is off by default and is the single most common reason a correctly-credentialed door release fails.
• Routing from the GEM server to the station's web port. Intercoms are commonly placed on an isolated door VLAN.

Setup

1. Log into the station's web UI and open Intercom → Relay. For each relay, set Open Relay via HTTP (the exact wording moves around between firmware revisions) to Enabled, and note the relay numbers and the door-open duration. Save.
2. Under Security → Basic (or System → Account, depending on firmware) confirm the username and password GEM will use.
3. In GEM go to /admin/devices and add a device with driver akuvox_intercom. Set ip, username and password. Set protocol to https and port to 443 if the station is reachable over TLS.
4. Run get_system_info from the Script Console. A result with model and firmware confirms credentials and reachability.
5. Create one zone per relay, with zone.address set to the relay number — 1 for the primary door release.
6. Run door_release against the zone and confirm the strike fires.

Attributes

Device

Attribute	Required	Default	Purpose
ip	yes	—	LAN IP of this station.
username	yes	—	Admin-level web account on the station.
password	yes	—	Password for that account. Stored encrypted.
port	no	80	Station web port.
protocol	no	http	http or https. Self-signed station certificates are accepted.
sip_account	no	1	Which SIP account dial places calls on.
status_interval	no	300000	Health-poll interval in ms. Door stations have little pollable state, so this is deliberately slow.
request_timeout	no	8000	Per-request timeout in ms.

Zone

Zones need no attributes beyond address.

Zone address format

The relay number on the station: 1 for the primary door release, 2 for a second relay. Most door stations have one or two.

Commands

Command	Arguments	Notes
door_release	address	Releases the relay. The station owns the hold time — set the door-open duration under Intercom → Relay.
get_system_info	—	Model, firmware, MAC. Doubles as the health poll.
dial	number	Places a call to a SIP number or extension on sip_account.
hangup	—	Ends the call in progress.
set_dnd	state	Do-not-disturb on/off. Mostly relevant on indoor monitors.
reboot	—	Reboots the station.
api_request	target, action, data	Sends an arbitrary Akuvox JSON API call. data is a JSON object.
get_relay_status	—	Not implemented — see below.

About api_request

The JSON envelope (target / action / data, answered with result.code) is stable across the Akuvox range, but the individual target and action strings drift between firmware generations. The named commands above use the strings from the Akuvox HTTP API document. If one of them comes back with a non-zero code on your firmware, look the call up in the API document for that release and drive it through api_request instead:

{
  "target": "call",
  "action": "dial",
  "data": { "number": "1001", "account": "1" }
}

A non-zero code is reported as akuvox api code <n> along with the station's own response body, so you can see exactly what it objected to.

What is not supported yet

• Inbound events. Button presses, incoming calls, card swipes and tamper alarms are pushed by the station through its Action URL feature to an HTTP endpoint. GEM does not yet expose an endpoint for those, so the driver is outbound-only today. This is the most valuable follow-up.
• Relay feedback. get_relay_status returns not yet implemented. The HTTP surfaces used here do not report relay contact position — the driver reports the relay it commanded, not a confirmed state. A door-position sensor wired into GEM is the reliable way to know whether a door is open.
• Contact / user directory management. Adding and removing SIP contacts and door PINs is available through the JSON API but is not wrapped in a named command. Use api_request.
• Audio and video paths. Call audio is SIP between stations, and video is RTSP off the station. Neither goes through this driver; point a camera device at the station's RTSP URL for video.

Troubleshooting

Symptom	Check
401 / 403 on every command	The account is not admin-level, or the station has locked out after failed logins. Confirm the account under Security → Basic and reboot to clear a lockout.
get_system_info works but door_release does not	Almost always Open Relay via HTTP is still disabled for that relay. Tick it under Intercom → Relay and save.
Door releases but the zone never returns to closed	Expected. The station holds the relay for its configured duration and does not report the release; the driver reflects the commanded pulse only.
Connection timeout	Intercoms usually sit on a separate door VLAN. Confirm routing from the GEM server, and that the station's web service is not bound to a management interface only.
dial returns a non-zero code	Wrong sip_account, or the firmware uses different API strings. Check the account index first, then fall back to api_request.
Everything works from a browser but not from GEM	The browser is likely holding a logged-in session cookie. GEM authenticates on every request, so an account that only works interactively (for example one that must accept a password-change prompt) will fail here.

Related

• 2N intercoms
• Aiphone IX / IXG
• DoorBird
• Devices