Package: econnect-python
E-connect Python APIeconnect-pythonis an API adapter used to control programmatically an Elmo-like alarm system.
Through a generic configuration, the client allows:Retrieving access tokens to make API callsObtaining/releasing the systemLock()to have exclusive control of the systemArm/disarm all the alarms registered in the systemQuery the system and get the status of your sectors and inputsRequirementsPython 3.8+requestsSupported SystemsThis package targets Elmo-like alarm systems. The following systems are known to work:Elmo e-ConnectIESS MetronetGetting StartedThis package is available on PyPI:$pipinstalleconnect-pythonUsagefromelmoimportqueryfromelmo.api.clientimportElmoClient# 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()withclient.lock("secret-code")asc:c.arm()# Arm all alarmsc.disarm()# Disarm all alarmsc.arm(sectors=[3,4])# Arm only sectors 3 and 4c.disarm(sectors=[3])# Disarm only sector 3# Query the systemsectors=client.query(query.SECTORS)inputs=client.query(query.INPUTS)The access token is valid for 10 minutes, after which, you need to authenticate again to
refresh the token. Obtaining the lock viaclient.lock("secret-code")is mandatory to arm or
disarm the system, otherwise the API returns403.secret-codeis 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.Connecting to SystemsBy default, theElmoClientconstructor will automatically connect to the Elmo e-Connect
system. However, if you need to connect to a different system, thesystemsmodule provides
a list of available alarm systems for you to choose from.Here's how you can use it:fromelmo.api.clientimportElmoClientfromelmo.systemsimportELMO_E_CONNECT,IESS_METRONET# Connect to the default Elmo e-Connect systemclient=ElmoClient()# Explicitly connect to the Elmo e-Connect systemclient=ElmoClient(base_url=ELMO_E_CONNECT)# Connect to the IESS Metronet systemclient=ElmoClient(base_url=IESS_METRONET)Note: The default constructor (with no parameters) remains unchanged to ensure backward compatibility and performs identically to the explicit call withELMO_E_CONNECT.Custom URLsIfhttps://connect.elmospa.comorhttps://metronet.iessonline.comare your authentication pages, no configuration
is needed and you can skip this section.On the other hand, if your authentication page is something similar tohttps://connect3.elmospa.com/nwd, you must configure your client as follows:fromelmo.api.clientimportElmoClient# Override the default URL and domainclient=ElmoClient(base_url="https://connect3.elmospa.com",domain="nwd")client.auth("username","password")If yourbase_urlordomainare not properly set, your credentials will not work
and you will get a403 Client Erroras your username and password are not correct.ContributingWe 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 ourContributor Guidelinesfirst,
and ask for help in ourDiscord channelif you have questions.DevelopmentWe welcome external contributions, even though the project was initially intended for personal use. If you think some
parts could be exposed with a more generic interface, please open aGitHub issueto discuss your suggestion.Dev EnvironmentTo create a virtual environment and install the project and its dependencies, execute the following commands in your
terminal:# Create and activate a new virtual environmentpython3-mvenvvenvsourcevenv/bin/activate# Upgrade pip and install all projects and their dependenciespipinstall--upgradepip
pipinstall-e'.[all]'# Install pre-commit hookspre-commitinstallCoding GuidelinesTo maintain a consistent codebase, we utilizeflake8andblack. Consistency is crucial as it
helps readability, reduces errors, and facilitates collaboration among developers.To ensure that every commit adheres to our coding standards, we've integratedpre-commit hooks.
These hooks automatically runflake8andblackbefore each commit, ensuring that all code changes
are automatically checked and formatted.For details on how to set up your development environment to make use of these hooks, please refer to theDevelopmentsection of our documentation.TestingEnsuring the robustness and reliability of our code is paramount. Therefore, all contributions must include
at least one test to verify the intended behavior.To run tests locally, execute the test suite usingpytestwith the following command:pytesttests/--cov--cov-branch-vvFor a comprehensive test that mirrors the Continuous Integration (CI) environment across all supported Python
versions, usetox:toxNote: To usetoxeffectively, ensure you have all the necessary Python versions installed. If any
versions are missing,toxwill provide relevant warnings.