Comelit ViP / HSrv

Comelit ViP intercom controllers and HSrv home servers (Mini Handsfree 6741W, Planux Manager, HSrv 6741W) over the local icon-based HTTP API. GEM uses this to drive door / gate strikes, bus-attached lighting and shutter actuators, and to surface intercom call state. The cloud-mediated path is not used — everything goes direct on-LAN.

Prerequisites

• HSrv firmware that exposes the local icon_desc.json / icon_status.cgi / user.cgi endpoints. Most HSrv 6741W, Planux Manager, and Mini Handsfree units on firmware 2.x do.
• The HSrv on a reserved LAN IP (router DHCP reservation, or set statically on the unit itself).
• The 4-digit installer or user code that signs into the local web UI at http://<hsrv-ip>/.

Setup steps

1. Confirm http://<hsrv-ip>/ shows the Comelit ViP login screen and that the 4-digit code grants access.
2. Create a Device using driver comelit_vip. Fill in ip and paste the 4-digit code into password (it is stored encrypted; the field is marked secure).
3. Run the get_devices command on the device. The response is a flat list of icons, each with id, name, sub_type, and type. Door / gate releases typically appear with a name containing "Apri" or "Cancello".
4. Create one GEM Zone per icon you want to control. Set zone.address to the numeric icon id from step 3.
5. Set the zone's subsystem so verb dispatch maps correctly:
   • gate / door — open / close actuate the strike.
   • lights — on / off toggle the relay.
   • shade — open / close / stop drive the shutter.
6. (Optional) For dry-contact door strikes that need a momentary pulse, the pulse command is an alias for open and is the preferred verb in macros — it makes the intent obvious in the macro log.

Attribute reference

Required

Attribute	Type	Description
ip	string	HSrv LAN IP. No scheme — driver builds http://<ip>:<port> internally.
password	string	4-digit installer/user code. Stored encrypted (the name password triggers auto-encryption).

Optional

Attribute	Type	Default	Description
port	int	80	Override HTTP port if the HSrv runs behind a port-mapped NAT.
status_interval	int	5000	Per-icon poll interval in ms. 1000–60000. A blank, zero, negative or unparseable value uses 5000.

Zone address format

zone.address is the numeric icon id returned by get_devices. The address is sent as given, with surrounding spaces trimmed — keep it numeric to avoid confusion. A blank address, or an unfilled placeholder such as [address], is refused with address required and nothing is sent. Zones with no address are not polled.

Commands

Command	Args	Notes
open / pulse	address	Sends action 1 to the icon. Use pulse in macros for door strikes.
close	address	Sends action 0.
stop	address	Shutter stop (action 2). Leaves the zone state alone until the next poll reports where the shutter stopped.
on / off	address	Same as open / close — exposed so light-subsystem verbs route cleanly.
get_devices		Enumerates all DOM icons.
get_status	address	Reads one icon's status JSON.
logout		Forgets the session cookie. Status loop re-logs in automatically.

If the HSrv answers a command with an HTTP error page (anything outside 2xx, after one re-login on 401/403), the command returns {error: "http <status>"} rather than success, and the zone state is not changed.

Connection and polling behaviour

• If the HSrv is unreachable or refuses the code when the device connects, the driver retries the login after 30 seconds, doubling the wait up to 15 minutes, and starts polling once it gets in. You do not need to reload the device after the HSrv comes back.
• When the HSrv rejects the code (HTTP 4xx, or a login reply saying it is not logged in), the driver stops sending the code for 30 seconds, doubling up to 15 minutes. Commands sent during that time return not authenticated. Changing the password attribute or reloading the device lets the driver try again straight away.
• If a poll cannot reach the HSrv, the next poll waits twice as long, up to 5 minutes. Polling returns to status_interval as soon as the HSrv answers.

Known limitations

• The HSrv API is the only path supported. The Comelit cloud (vipmobile) flow is not implemented and not planned — it is unreliable and rate-limited compared to the LAN endpoint.
• SIP audio / video preview of the intercom stream is out of scope. GEM surfaces "is the doorstation ringing?" via zone state but does not pipe audio.
• Some HSrv firmware revisions emit a different icon-id space when accessed through the cloud-mediated bridge. This driver only reads the on-LAN icon ids; do not mix the two address sources.
• Lighting dim levels are not yet implemented — only on/off through the icon action=0/1 path. If the bus actuator is a dimmer, the dim slider stays a no-op until that is wired.

Troubleshooting

• Login keeps failing (driver logs "login failed" or "login refused"): verify the 4-digit code by signing in to http://<hsrv-ip>/ from a browser on the same LAN. The HSrv intentionally rate-limits repeated bad codes, so the driver holds off between attempts (see above); correcting the password attribute makes it try again immediately.
• get_devices returns an empty list: confirm the user code has admin privileges. Read-only codes can sometimes log in but see no icons.
• State updates lag by tens of seconds: lower status_interval (default 5000 ms). Going below 1000 ms is rarely worth it; the HSrv tends to drop session cookies under heavy polling.
• 401 in driver logs every few minutes: expected — the driver transparently re-logs in. If the cycle is constant, the HSrv has another active session (browser open elsewhere) bumping us off. Close the other session.