Alarm.com Python Library

Author: Justin Wong

Overview

A Python library to asynchronously interface with Alarm.com. Forked from Daren Lord's pyalarmdotcom. Mainly built for use with Home Assistant.

BREAKING CHANGES

v0.2 of pyalarmdotcomajax breaks just about all features available in v0.1. Be careful when updating.

Installation / Usage

To install use pip:

pip install pyalarmdotcomajax

Or clone the repo:

git clone https://github.com/uvjustin/pyalarmdotcomajax.git
python setup.py install

Usage

See examples/basic_sensor_data.py for a basic usage example.

Device Support

• As of v0.2, multiples of all devices are supported.
• All devices include the attributes: name, id_, state, battery_low, battery_critical, malfunctioning, parent_ids, and a few others.

Device Type	Notable Attributes	Actions
System	unit_id	(none)
Partition	uncleared_issues, desired_state	arm away, arm stay, arm night, disarm
Sensors	device_subtype	(none)
Locks	desired_state	lock, unlock
Garage Door	(none)	open, close

Known Sensor deviceTypes

This list identifies deviceTypes used in the alarm.com API and is incomplete. Please help by submitting missing values.

deviceType	Description
1	Contact Sensor
5	Smoke Detector
6	CO Detector
9	Panic Button
19	Glass Break Detector

Command Line Interface

The CLI is available by running adc from anywhere in your terminal.

usage: adc [-h] -u USERNAME -p PASSWORD [-c COOKIE] [-v] [-d] [-ver]

Basic command line debug interface for Alarm.com via pyalarmdotcomajax. Shows device states in various formats.

optional arguments:
  -h, --help            show this help message and exit
  -u USERNAME, --username USERNAME
                        alarm.com username
  -p PASSWORD, --password PASSWORD
                        alarm.com password
  -c COOKIE, --cookie COOKIE
                        two-factor authentication cookie
  -v, --verbose         show verbose output. -v returns server response for all devices except systems. -vv returns server response for all devices.
  -d, --debug           show pyalarmdotcomajax's debug output.
  -ver, --version       show program's version number and exit

Development

VS Code Support Structures

This repository includes a full development environment for VS Code:

1. VS Code dev container. Automatically installs extensions and Python dependencies and registers Git pre-commit scripts.
2. Configuration files for type checking (mypy), linting (flake8, isort, and black), code security (Bandit), etc.
3. Pre-commit checks run all of the above when committing to Git and on demand via VS Code tasks.

References

1. Some API definitions are available in the node-alarm-dot-com repository.

Open Items

Features

1. Support additional components (lights, irrigation, etc.).
2. Support more sensor types (see list above in this README).
3. Add debug_info property to ADCController that returns aggregate of raw JSON from all endpoints. This will allow users to export the entity model of unsupported devices to help maintainers implement support in this library.
4. Similar to above, proactively populate unsupported_devices property for ADCBaseElement to show users device id, device name, and device type for available but unsupported devices.
5. More granular exception handling when logging in. Should report discrete error types for authentication failures due to wrong credentials, connection issues, or other.

Housekeeping

1. Testing framework
2. Auto-build and publish to pypi w/ GitHub release.