Alarm.com (Cloud Security)

GEM integrates with an Alarm.com-monitored security system through Alarm.com's cloud — the same service the homeowner's Alarm.com app uses. One GEM device represents one Alarm.com account/system; once linked, GEM can arm and disarm the panel and shows the live open/closed state of every sensor (doors, windows, motion, smoke, glass-break) as zones.

This is a cloud integration: there is no LAN/local path to the panel. The GEM server needs outbound internet access to reach alarm.com. The link is established once, through Alarm.com's two-factor (SMS or email) verification, after which GEM keeps itself signed in automatically — there is nothing to re-enter on a server restart unless Alarm.com revokes the trust.

Licensing

Alarm.com is a premium integration. Adding an Alarm.com device requires the security product in your license. Existing devices keep running if a license later changes.

What you get

• Arm / Disarm the panel: arm away, arm home (stay), arm night, and disarm — issued from GEM as device commands, which you can place on a UI button or fire from a macro/trigger.
• Live sensor zones. Every sensor on the account is pulled in automatically and created as a zone under the Security subsystem, with its real-time state (for example closed, open, idle, activated) mirrored onto the zone.
• System state feedback. The panel's overall armed/disarmed state is published back onto the device so macros and triggers can react to it.
• Near-real-time updates. GEM holds an event connection open to Alarm.com, so a door opening or the panel arming is reflected within seconds, backed up by a periodic full refresh.

Prerequisites

• An Alarm.com account (username and password) for the monitored system. This is the same login the homeowner uses for the Alarm.com app — there is no separate "integration" account.
• During setup, access to the phone or email on the account, to receive the one-time verification code.
• Outbound HTTPS (port 443) from the GEM server to alarm.com, plus an outbound secure WebSocket on port 8443 to webskt.alarm.com for live events.
• The Security subsystem must exist (it ships by default). Sensor zones are auto-created under it; if it is missing, zone creation is skipped.

Setup

1. Add the device

1. Open Devices and add a new device with the driver set to Alarm.com.
2. Fill in the authentication fields:
   • Username — the Alarm.com account login (often an email address).
   • Password — the account password. Stored encrypted.
   • System ID — leave blank for a normal single-system account; GEM discovers and fills it in on first sign-in. Only set it by hand if the login owns multiple Alarm.com systems and you need to pin GEM to a specific one.
3. Save and enable the device.

2. Complete two-factor verification (one time)

Alarm.com requires a trusted-device handshake before it will let GEM stay signed in. You do this once, from GEM:

1. Run the authenticate command against the device — from the device's command list or the Commands screen.
2. GEM signs in and asks Alarm.com to send a verification code. It prefers SMS if the account has it enabled, otherwise email. A dialog appears in GEM: "Enter the verification code sent via sms" (or email).
3. Enter the code that arrives on the phone/email. GEM verifies it, registers itself as a trusted device ("GEM Controller"), and stores the resulting trust token in the device's encrypted Two-Factor Trust Token attribute.

You have about two minutes to enter the code before the prompt times out — if you miss it, just run authenticate again. After this succeeds, GEM reconnects on its own using the stored trust token; you do not re-run authenticate on reboots or reloads.

tip

If the device was already trusted, authenticate returns "device is already trusted" and there is nothing more to do. Re-run it only if you cleared the Two-Factor Trust Token attribute, or if Alarm.com dropped the trust (for example after a password change).

3. Let the sensors populate

You do not create sensor zones by hand. On the first successful sign-in GEM reads the account's sensor list and, for each sensor, creates a zone under the Security subsystem:

• the zone label is the sensor's Alarm.com description (e.g. Front Door),
• the zone address is the Alarm.com sensor id (filled in automatically),
• the zone state tracks the sensor's live status.

Open Zones and filter to the Security subsystem to confirm they appeared. New sensors added in Alarm.com later are picked up on the next refresh. If a sensor never shows up, check the device log for unmapped alarm.com sensor — that means GEM saw the sensor but could not create a zone (almost always because the Security subsystem is missing).

Arming and disarming

Arming is done with device commands, not zone commands. The driver exposes:

Command	What it does
arm_away	Arms the system in Away mode (perimeter + interior).
arm_home	Arms in Home / Stay mode (perimeter only).
arm_stay	Same as arm_home — an alias for Stay arming.
arm_night	Arms in Night mode (stay arming with night settings).
disarm	Disarms the system.

You can fire these three ways:

• For testing — run the command directly from the device's command list or the Commands screen and watch the result.
• From a UI — wire a button or a Security control to the command so the homeowner can arm and disarm from a touch panel (see Known limitations for one caveat about the built-in Security control's status banner).
• From automation — call the command in a macro or trigger (for example, "arm Night when the house goes to Sleep mode"). See Macros and Triggers.

The panel's current state is published to the device's system_state attribute as one of disarmed, armed_home, armed_away, armed_night, or unknown — a macro condition or trigger can read it to avoid, say, re-arming an already-armed system.

Single-partition systems

The arm/disarm commands target the account's single security partition automatically, which covers virtually all residential installs. The commands do not expose a partition selector, so systems split into multiple partitions cannot currently target a specific partition from GEM.

Attribute reference

Device attributes

Attribute	Required	Type	Notes
username	yes	string	Alarm.com account login.
password	yes	string (secure)	Account password.
system_id	auto	string	Leave blank for single-system accounts — GEM fills it in on first sign-in. Set it only for multi-system logins.
two_factor_token	auto	string (secure)	Trust token written automatically by authenticate. Don't clear it unless you intend to re-verify.
system_state	auto	string (read-only)	Live panel state: disarmed / armed_home / armed_away / armed_night / unknown.
otp_code	auto	string	Transient holder for the verification code during authenticate; GEM clears it after use. You do not set this directly — the authenticate dialog writes it for you.
connected	auto	boolean (read-only)	Online flag — true while GEM holds a live Alarm.com session and event connection.
update_interval	no	integer (ms)	How often GEM does a full sensor refresh. Defaults to 300000 (5 minutes). Live changes still arrive instantly over the event connection; this is the safety-net poll. Add this attribute only if you want to change the cadence.

Zone attributes

Attribute	Required	Type	Notes
address	yes	string	Alarm.com sensor id. Filled in automatically when the zone is auto-created.
state	auto	string (read-only)	Live sensor state straight from Alarm.com (lower-cased), e.g. closed, open, idle, activated.

Diagnostic commands

These return raw Alarm.com data and are mainly useful for commissioning and support — they do not change anything on the panel.

Command	Args	Notes
get_system_state	system_id (optional)	Returns the account's full current state — partitions and every sensor. Handy for confirming what GEM can see. Defaults to the device's own system if no id is passed.
get_components	url, ids	Low-level passthrough that fetches specific Alarm.com objects by URL and id. Advanced/support use.

How it works

Live events. After signing in, GEM opens a secure WebSocket to Alarm.com (webskt.alarm.com:8443). When a sensor changes or the panel arms/disarms, Alarm.com pushes an event and GEM immediately refreshes just that sensor — so the matching zone updates within seconds without waiting for a poll.

Backstop polling. Independently, GEM does a full sensor sweep every update_interval (5 minutes by default) to catch anything the event stream missed and to keep the panel's system_state current.

Staying signed in. Alarm.com rotates session cookies and the WebSocket auth token aggressively. GEM handles this transparently: if a command comes back unauthorized, it re-signs-in with the stored credentials and trust token and retries, and the WebSocket reconnects on its own if it drops. Occasional reconnect lines in the device log are normal and self-heal — they do not need intervention.

Known limitations

• Cloud only. There is no local/LAN control path. If the GEM server loses internet, or Alarm.com is unreachable, arm/disarm and sensor updates stop until connectivity returns.
• Home-panel Security control status banner. GEM's built-in homeowner Security control shows a large armed/disarmed status banner that it reads from an arm_state value. This driver publishes the panel's state under system_state instead, so that banner can read UNKNOWN and the arm buttons may not highlight even though arming and disarming work correctly. Trigger arm/disarm from a macro-backed UI button, and surface the live state from the device's system_state attribute, if you need an on-screen indicator that follows the panel. (This is a driver/UI mismatch, noted here for accuracy.)
• Zone bypass is not supported. The Alarm.com driver does not implement a bypass command, so the Security control's per-zone Bypass and Bypass Faulted actions have no effect on an Alarm.com system. Bypass a zone from the physical panel or the Alarm.com app instead.
• Sensor state only — no rich sensor metadata. Zones reflect each sensor's reported state; battery level, tamper, and signal-strength detail are not surfaced as attributes.
• Trust can expire. A password change, or Alarm.com clearing trusted devices, invalidates the stored trust token; re-run authenticate to re-establish it.

Troubleshooting

Symptom	Check
alarm.com missing username or password in the device log	Set both the Username and Password attributes on the device, then reload it.
The verification-code dialog never appears, or authenticate errors immediately	The username/password is wrong, or the account has no SMS/email two-factor method enabled. Confirm the login works in the Alarm.com app, then retry.
Prompted for a 2FA code on every reconnect	authenticate did not finish (the code wasn't entered in time, or trust failed). Run authenticate again and enter the code promptly; success stores the Two-Factor Trust Token automatically.
Sensors don't appear as zones	Look for unmapped alarm.com sensor in the device log — the Security subsystem must exist for auto-create to succeed. Confirm it under Subsystems.
Device shows Disconnected / WebSocket reconnects every few minutes	Alarm.com rotates the event-connection token periodically, so brief reconnects are expected and self-heal. Persistent disconnection points to an internet/DNS problem reaching alarm.com or webskt.alarm.com, or revoked credentials.
Arming "succeeds" but the panel doesn't arm	A sensor is faulted (open door/window) or the system has a trouble condition; Alarm.com refuses the arm. Clear the fault, or bypass it from the panel/app, then retry.

Related documentation

• Devices — where the Alarm.com account device is added and authenticate is run.
• Zones — sensor zones auto-created under the Security subsystem.
• Subsystems — the Security subsystem that holds the sensor zones.
• Commands — where arm_away, arm_home, arm_night, and disarm are dispatched and wired into automation.
• Macros and Triggers — arm/disarm on a schedule or in response to other events, and react to system_state.