Metadata-Version: 2.1
Name: homepluscontrol
Version: 0.0.4
Summary: Python-based API to interact with the Legrand Home + Control interface
Home-page: https://github.com/chemaaa/homepluscontrol
Author: chemaaa
Author-email: chemaaar@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: aiohttp (==3.7.1)
Requires-Dist: aioresponses (>=0.7.1)
Requires-Dist: alabaster (>=0.7.12)
Requires-Dist: async-timeout (>=3.0.1)
Requires-Dist: attrs (==19.3.0)
Requires-Dist: Babel (>=2.9.0)
Requires-Dist: certifi (>=2020.11.8)
Requires-Dist: cffi (>=1.14.3)
Requires-Dist: chardet (>=3.0.4)
Requires-Dist: coverage (>=5.3)
Requires-Dist: cryptography (==3.2)
Requires-Dist: docutils (>=0.16)
Requires-Dist: idna (>=2.10)
Requires-Dist: imagesize (>=1.2.0)
Requires-Dist: iniconfig (>=1.1.1)
Requires-Dist: Jinja2 (>=2.11.2)
Requires-Dist: MarkupSafe (>=1.1.1)
Requires-Dist: multidict (>=5.0.2)
Requires-Dist: oauthlib (>=3.1.0)
Requires-Dist: packaging (>=20.4)
Requires-Dist: pip-autoremove (>=0.9.1)
Requires-Dist: pluggy (>=0.13.1)
Requires-Dist: py (>=1.9.0)
Requires-Dist: pycparser (>=2.20)
Requires-Dist: Pygments (>=2.7.2)
Requires-Dist: PyJWT (==1.7.1)
Requires-Dist: pyparsing (>=2.4.7)
Requires-Dist: pytest (>=6.1.2)
Requires-Dist: pytest-cov (>=2.10.1)
Requires-Dist: pytz (>=2020.4)
Requires-Dist: requests (>=2.25.0)
Requires-Dist: requests-oauthlib (>=1.3.0)
Requires-Dist: six (>=1.15.0)
Requires-Dist: snowballstemmer (>=2.0.0)
Requires-Dist: Sphinx (>=3.3.1)
Requires-Dist: sphinxcontrib-applehelp (>=1.0.2)
Requires-Dist: sphinxcontrib-devhelp (>=1.0.2)
Requires-Dist: sphinxcontrib-htmlhelp (>=1.0.3)
Requires-Dist: sphinxcontrib-jsmath (>=1.0.1)
Requires-Dist: sphinxcontrib-qthelp (>=1.0.3)
Requires-Dist: sphinxcontrib-serializinghtml (>=1.1.4)
Requires-Dist: toml (>=0.10.2)
Requires-Dist: typing-extensions (>=3.7.4.3)
Requires-Dist: urllib3 (>=1.26.2)
Requires-Dist: yarl (==1.4.2)

# Home + Control
This is a basic Python library that interacts with the *Legrand Home + Control* API. It is 
primarily intended for integration into Smart Home platforms such as Home Assistant.

More information of the API can be found here: https://developer.legrand.com/

The library currently supports 3 types of Legrand modules:

1) Plugs (power outlets)
2) Lights (connected switches)
3) Remotes (wireless switches)

The first two - plugs and lights - are modeled as basic switches that can be interacted with to set their status to *on* or *off*.
Remotes are presented as passive modules that only have a battery level attribute.

A 'home' is represented by a *plant* which presents all of its corresponding modules in a topology. A *plant* is basically a 
Legrand Home+ Control gateway.

The status of each module in the *plant* can be accessed through a single *status* call to the *plant* or through individual *status* 
calls to each module.

## Authentication
The *Legrand Home + Control* API uses Oauth2 authentication, so you must first register an account at https://developer.legrand.com/. 

Once registered, you will then need to create a subscription to the *Starter Kit* (currently the only subscription available) and this will
generate your SUBSCRIPTION_KEY.

As a final step, you will have to register an Application, where you will have to define a name, a redirect URL and the scopes of your application
(for simplicity you can mark all scopes). 

Once the Application is confirmed, you should receive an email containing the CLIENT_IDENTIFIER and
the CLIENT_SECRET which you will be using to set up the authentication flows.

### Authentication Flow
Communication with the API, first requires Oauth2 authentication to obtain an access and a refresh token. Subsequent requests to the API, require the use of the SUBSCRIPTION_KEY in addition to the access token.

Information about the Oauth2 exchange is provided here: https://developer.legrand.com/tutorials/0auth2-end-point-url/

## Quickstart
Install `homepluscontrol` using `pip`: 

    $ pip install homepluscontrol

### Usage Example
The following script is a simple example of how this Python library can be used::

```python
from homepluscontrol import authentication, homeplusplant
import asyncio

client_id = 'YOUR_CLIENT_IDENTIFIER'
client_secret = 'YOUR_CLIENT_SECRET'
subscription_key = 'YOUR_SUBSCRIPTION_KEY'
redirect_uri = 'https://www.example.com'

dummy_token = 
    {"refresh_token": 
        "dummy-refresh-token", 
        "access_token": "dummy-access-token", 
        "expires_at": -1, 
        "expires_on": -1}
api_plant_url = 'https://api.developer.legrand.com/hc/api/v1.0/plants'

# Create the asynchronous client to handle the authentication 
# process and the authenitcated requests
client = authentication.HomePlusOAuth2Async(client_id, 
                                            client_secret, 
                                            subscription_key, 
                                            token=dummy_token, 
                                            redirect_uri=redirect_uri)

# The URL returned by this method launches the Oauth2 flow and 
# allows a user to confirm the process.
# Doing so redirects the user's browser/client to the redirect URI
# and includes the code and the state for the next step.
authorization_url = client.generate_authorize_url()
print(authorization_url)

# Here is where you can enter the complete redirect URL
return_url = input('Redirect URL received:')

# This function will now handle the asynchronous calls to the API
async def interact_with_api():
    token = await client.async_fetch_initial_token(return_url)
    print(token)
    # The client now has a valid token and can be used 
    # to interact with the API.

    # First get the plant information
    result = await client.request('get', api_plant_url)
    plant_info = await result.json()
    print(plant_info)
    plant_array = []
    for p in plant_info['plants']:
        plant_array.append(
            homeplusplant.HomePlusPlant(p['id'], 
                                        p['name'], 
                                        p['country'], 
                                        client)
        )
    plant = plant_array[0]
    print(plant)

    # Next read the module information for the plant
    await plant.update_topology_and_modules()
    for mod_id in plant.modules.keys():
            print(plant.modules[mod_id])
    # Close the client session
    await client.oauth_client.close()

loop = asyncio.get_event_loop()
loop.run_until_complete(interact_with_api())
```

## Testing
`homepluscontrol` tests are based on `pytest`. To run, change to the root directory of `homepluscontrol` and use the command: 

    $ pytest 

