Genie Aladdin Connect

The genie_aladdin_connect driver controls Genie / Overhead Door "Aladdin Connect" Wi-Fi garage door openers via the cloud REST API that the Aladdin Connect mobile app uses. It polls per-door status, opens and closes individual doors, and surfaces battery and Wi-Fi link state.

The driver is cloud-only — Overhead Door does not publish a LAN protocol — and uses the same endpoint as the mobile app. Overhead Door has not published an official integrator key, so the mobile app x-api-key value must be supplied by the integrator. Treat this driver as best-effort: it has been stable for years but the vendor may change endpoints or keys without notice.

Prerequisites

• Active Aladdin Connect account with at least one opener paired in the mobile app.
• The mobile-app x-api-key value. This is the same key used by the Android and iOS apps and is widely published in open-source garage-door integrations (Home Assistant genie_aladdin_connect and similar). The integrator must extract or look up this value; the driver does not ship with a default.
• Outbound HTTPS from the GEM controller to the AWS API Gateway endpoint (default https://pxdqkls7aj.execute-api.us-east-1.amazonaws.com).

Setup

1. Confirm the mobile app works. If the Aladdin Connect app cannot reach the opener, this driver cannot either.
2. Create the device under System → Devices with driver genie_aladdin_connect. Set:
   • username — account email
   • password — account password (stored encrypted)
   • api_key — the mobile app x-api-key value (stored encrypted)
3. Confirm connection. From the Script Console:

   await gem.command({device_id: <device_id>, command: 'get_doors'});

   You should see one entry per door, e.g.:

   [{ "address": "01:23:45:67:89:AB:1", "device_id": "01:23:45:67:89:AB", "door_index": 1, "name": "Main Door", "state": "closed", "battery_level": 100 }]

4. Create one zone per door under System → Zones with address set to the <device_id>:<door_index> string from get_doors. Assign the zone to the garage subsystem so the standard open / close verbs map correctly.
5. Test a command.

   await gem.command({device_id: <device_id>, command: 'open', args: {address: '01:23:45:67:89:AB:1'}});

Attributes

Device

Attribute	Required	Type	Notes
username	yes	string	Aladdin Connect account email.
password	yes	string (secure)	Aladdin Connect account password.
api_key	yes	string (secure)	Mobile-app x-api-key header value.
base_url	no	string	Override only if the vendor rotates the API endpoint. Defaults to the AWS API Gateway URL.
status_interval	no	int	Poll interval (ms). Default 30000, minimum 5000.
app_version	no	string	Reported app version in the login payload. Defaults to 5.30.
build_number	no	string	Reported build number. Defaults to 2042.

Zone

The zone address is required and follows the format <device_id>:<door_index> (e.g., 01:23:45:67:89:AB:1). The poller writes:

Attribute	Type	Source
state	string	open / closed / opening / closing / unknown, derived from door_status.
battery	int	Door sensor battery percentage if reported.

Commands

Name	Args	Description
get_devices	—	List openers (one device per gateway) on the account.
get_doors	—	List every door with its address and current state.
get_status	address	Force-refresh and return raw status for a single door. If the refresh fails, the last status the cloud reported is returned with a refresh_error field.
open	address	Send OpenDoor.
close	address	Send CloseDoor.

Door state mapping

The Aladdin Connect API reports door_status as an integer. The driver maps it to GEM zone state as follows:

door_status	GEM state
1	open
2	opening
3	open (timeout-opening surfaced as open to avoid a stuck zone)
4	closed
5	closing
6	closed (timeout-closing surfaced as closed)
0 / 7	unknown

Connection and retries

• The device shows connected once the cloud answers with door configuration or accepts a command. If the cloud refuses the login (HTTP 400, 401 or 403, meaning a wrong email, password or api_key), the device shows disconnected. The driver does not keep retrying that login. Correct the credentials and save; that reloads the device and it tries again.
• If the cloud cannot be reached at startup, or answers with an error, the driver retries after 30 seconds. The wait doubles after each failed attempt, up to 5 minutes.
• After three failed polls in a row, the poller backs off the same way, up to 5 minutes or the poll interval, whichever is longer. The first successful poll puts it back on the normal interval.
• After a refused login, background polls wait before they log in again: 30 seconds, doubling up to 5 minutes. A command you send yourself is never held back.
• An open or close is sent once. The only resend happens after the cloud rejects the request's session token (401/403). In that case the driver logs in again and sends the command once more. If that second attempt is also rejected, the error is returned and the command is not sent again. A redirect or an HTML page (for example a captive portal) comes back as an error, not as success.

Known limitations

• Cloud-only. No LAN protocol path is available.
• There is no stop operation in the cloud API — once a door starts moving it runs to completion or hits the opener's safety reverse.
• The x-api-key is not officially licensed. If Overhead Door rotates the key, the driver will return 401/403 on every request until a new key is supplied.
• Movement timing comes from the poll interval. With the default 30 s interval you may see a door transition closed → opening → open rather than catch every intermediate frame.

Troubleshooting

Symptom	Check
login http 401	Verify the email and password in the Aladdin Connect mobile app. If those work, the api_key is likely stale.
login response missing token	The endpoint may have changed. Confirm base_url and app_version against the current mobile app.
Device shows disconnected right after saving	The cloud refused the login. A 403 usually means the api_key is wrong; a 401 usually means the email or password is wrong. Correct the value and save.
Door state stuck on opening or closing	The opener hit a safety reverse, or the poll missed the transition. Run get_status to refresh, or open/close the door manually to clear.
door not found for address	Run get_doors and verify the GEM zone address matches the printed address (device_id:door_index).