API adapter used to control programmatically an Elmo alarm system.
Project description
E-connect Python API
econnect-python
is an API adapter used to control programmatically an Elmo alarm system.
Through a generic configuration, the client allows:
- Retrieving access tokens to make API calls
- Obtaining/releasing the system
Lock()
to have exclusive control of the system - Arm/disarm all the alarms registered in the system
- Query the system and get the status of your sectors and inputs
Requirements
- Python 3.6+
requests
Getting Started
This package is available on PyPI:
$ pip install econnect-python
Usage
from elmo import query
from elmo.api.client import ElmoClient
# Initialize a new client to authenticate your connection
# and retrieve an access token used for the entire session.
client = ElmoClient()
client.auth("username", "password")
# To arm/disarm the system you must gain the exclusive Lock()
with client.lock("secret-code") as c:
c.arm() # Arm all alarms
c.disarm() # Disarm all alarms
c.arm(sectors=[3, 4]) # Arm only sectors 3 and 4
c.disarm(sectors=[3]) # Disarm only sector 3
# Query the system
sectors_armed, sectors_disarmed = client.query(query.SECTORS)
inputs_alerted, inputs_wait = client.query(query.INPUTS)
# Or use the shortcut
status = client.check()
# Returns:
# {
# "sectors_armed": [{"id": 0, "name": "Entryway", "element": 1, "index": 0}, ...],
# "sectors_disarmed": [{"id": 1, "name": "Kitchen", "element": 2, "index": 1}, ...],
# "inputs_alerted": [{"id": 0, "name": "Door", "element": 3, "index": 0}, ...],
# "inputs_wait": [{"id": 1, "name": "Window", "element": 4, "index": 1}, ...],
# }
The access token is valid for 10 minutes, after which, you need to authenticate again to
refresh the token. Obtaining the lock via client.lock("secret-code")
is mandatory to arm or
disarm the system, otherwise the API returns 403
. secret-code
is the numeric code you
use to arm/disarm the system from the alarm panel.
Once the lock is obtained, other clients cannot connect to the alarm system and only a manual override on the terminal is allowed. Outside the context manager, the lock is automatically released.
Client Configuration
If https://connect.elmospa.com
is your authentication page, no configuration is needed
and you can skip this section.
On the other hand, if your authentication page is something similar to
https://connect3.elmospa.com/nwd
, you must configure your client as follows:
# Override the default URL and domain
client = ElmoClient(base_url="https://connect3.elmospa.com", domain="nwd")
client.auth("username", "password")
If your base_url
or domain
are not properly set, your credentials will not work
and you will get a 403 Client Error
as your username and password are wrong.
Contributing
We are very open to the community's contributions - be it a quick fix of a typo, or a completely new feature! You don't need to be a Python expert to provide meaningful improvements. To learn how to get started, check out our Contributor Guidelines first, and ask for help in our Discord channel if you have questions.
Development
We accept external contributions even though the project is mostly designed for personal needs. If you think some parts can be exposed with a more generic interface, feel free to open a GitHub issue and to discuss your suggestion.
Coding Guidelines
We use flake8 as a style guide enforcement. That said, we also use black to reformat our code, keeping a well defined style even for quotes, multi-lines blocks and other.
Before submitting your code, be sure to launch black
to reformat your PR.
Testing
tox
is used to execute the following test matrix:
lint
: launchesflake8
andblack --check
to be sure the code honors our style guidelinepy{35,36,37,38}
: launchespy.test
to execute all tests under Python 3.5, 3.6, 3.7 and 3.8.
To launch the full test matrix, just:
$ tox
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.