Package: homepluscontrol
Home + ControlThis is a basic Python library that interacts with theLegrand Home + ControlAPI. 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 4 types of Legrand modules:Plugs (power outlets)Lights (connected switches)Remotes (wireless switches)Automations (shutters/covers)The first two - plugs and lights - are modeled as basic switches that can be interacted with to set their status toonoroff.
Remotes are presented as passive modules that only have a battery level attribute.
Automations can be issued commands to open or close to their full positions and to be stopped during the motion.A 'home' is represented by aplantwhich presents all of its corresponding modules in a topology. Aplantis basically a
Legrand Home+ Control gateway.The status of each module in theplantcan be accessed through a singlestatuscall to theplantor through individualstatuscalls to each module.AuthenticationTheLegrand Home + ControlAPI uses Oauth2 authentication, so you must first register an account athttps://developer.legrand.com/.Once registered, you will then need to create a subscription to theStarter 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 FlowCommunication 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/QuickstartInstallhomepluscontrolusingpip:$ pip install homepluscontrolUsage ExampleThe following script is a simple example of how this Python library can be used::fromhomepluscontrolimportauthentication,homeplusplantimportasyncioclient_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 requestsclient=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 URLreturn_url=input('Redirect URL received:')# This function will now handle the asynchronous calls to the APIasyncdefinteract_with_api():token=awaitclient.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 informationresult=awaitclient.request('get',api_plant_url)plant_info=awaitresult.json()print(plant_info)plant_array=[]forpinplant_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 plantawaitplant.update_topology_and_modules()formod_idinplant.modules.keys():print(plant.modules[mod_id])# Close the client sessionawaitclient.oauth_client.close()loop=asyncio.get_event_loop()loop.run_until_complete(interact_with_api())Testinghomepluscontroltests are based onpytest. To run, change to the root directory ofhomepluscontroland use the command:$ pip install -r requirements.txt
$ pip install -r requirements_test.txt
$ pytest