API Documentation¶

OAuth2 Authentication¶

class homepluscontrol.authentication.AbstractHomePlusOAuth2Async(subscription_key, oauth_client=None)¶

abstract async async_get_access_token() → str¶: Return a valid access token.

async get_request(url, **kwargs)¶

Makes an authenticated async HTTP GET request.

Shortcut method that relies on request() call and simply hardcodes the ‘get’ HTTP method

Parameters

url (str) – Endpoint of the HTTP request
**kwargs (dict) – Keyword arguments that will be forwarded to the aiohttp request handler

Returns

aiohttp response object

Return type

ClientResponse

Raises

ClientError raised by aiohttp if it encounters an exceptional –
situation in the request –

async post_request(url, data, **kwargs)¶

Makes an authenticated async HTTP POST request.

Shortcut method that relies on request() call and simply hardcodes the ‘post’ HTTP method

Parameters

url (str) – Endpoint of the HTTP request
data (dict) – Dictionary containing the parameters to be passed in the POST request body
**kwargs (dict) – Keyword arguments that will be forwarded to the aiohttp request handler

Returns

aiohttp response object

Return type

ClientResponse

Raises

ClientError raised by aiohttp if it encounters an exceptional –
situation in the request –

async request(method, url, **kwargs)¶

Makes an authenticated async HTTP request.

This method wraps around the aiohttp request method and adds the mandatory subscription key header that is required by the Home + Control API calls.

Parameters

method (str) – HTTP method to be used in the request (get, post, put, delete)
url (str) – Endpoint of the HTTP request
**kwargs (dict) – Keyword arguments that will be forwarded to the aiohttp request handler

Returns

aiohttp response object

Return type

ClientResponse

Raises

ClientError raised by aiohttp if it encounters an exceptional –
situation in the request –

class homepluscontrol.authentication.HomePlusOAuth2Async(client_id, client_secret, subscription_key, token=None, redirect_uri=None, token_updater=None, oauth_client=None)¶

Handles authentication with OAuth2 - Uses aiohttp for asynchronous requests.

This class is an implementation of the base class AbstractHomePlusOAuth2Async and so provides additional functions to request and manage the OAuth2 authentication flow and refresh access tokens when required.

client_id¶

Client identifier assigned by the API provider when registering an app

Type: str

client_secret¶

Client secret assigned by the API provider when registering an app

Type: str

subscription_key¶

Subscription key obtained from the API provider

Type: str

token¶

oauth2 token used by this authentication instance

Type: dict

redirect_uri¶

URL for the redirection from the authentication provider

Type: str

token_update¶

function that is called when a new token is obtained from the authentication provider

Type: function

oauth_client¶

aiohttp ClientSession object that handles HTTP async requests

Type: ClientSession

async async_ensure_token_valid() → str¶

Ensures that the access token is valid.

Deprecated - Use async_get_access_token() instead.

Returns

String containing the new access token. The object attribute: that holds the token is also updated.

Return type

str

async async_fetch_initial_token(redirect_url: Any) → dict¶

Fetches the initial access and refresh tokens once the authorization step was completed.

This method relies on the redirect URL that was provided by the API once authorization was approved.

Parameters

redirect_url (str) – The redirect URL that was provided by the API after authorizing.

Returns

Dictionary of the new token. The object attribute that: holds the token is also updated.

Return type

dict

async async_get_access_token() → str¶

Return a valid access token.

If the current token is no longer valid, then a new one is requested and the object attribute updated. If the current token is still valid, then do nothing.

Returns

String containing the new access token. The object attribute: that holds the token is also updated.

Return type

str

generate_authorize_url() → str¶

Generate the URL for the user to authorize the app.

Returns: The URL that is used for the authorization step.
Return type: str

property logger: logging.Logger¶: Logger of authentication module.

property valid_token: bool¶

Current validity of the Oauth token (i.e. it has not expired).

Returns: True if the token is valid, False otherwise

Home+ Plant (Home) Class¶

class homepluscontrol.homeplusplant.HomePlusPlant(id, name, country, oauth_client: homepluscontrol.authentication.AbstractHomePlusOAuth2Async)¶

Class representing a “plant”, i.e a Home or Environment containing Home+ devices

id¶

Unique identifier of the plant.

Type: str

name¶

Name of the plant.

Type: str

country¶

Two-letter country code where the plant is located.

Type: str

oauth_client¶

Authentication client to make requests to the REST API.

Type: AbstractHomePlusOAuth2Async

modules¶

Dictionary containing the information of all modules in the plant.

Type: dict

topology¶

JSON representation of the plant’s topology as returned by the API

Type: dict

module_status¶

JSON representation of the plant modules’ status as returned by the API

Type: dict

property logger¶: Return logger of the plant.

async refresh_module_status()¶

Makes a call to the API to refresh the status of all modules in the plant into attribute module_status. The module status provides information about the modules current status, eg. reachability, on/off, battery, consumption.

TODO: Handle consumptions

async refresh_topology()¶

Makes a call to the API to refresh the topology information of the plant into attribute topology. The topology provides information about the plants ambients/rooms and the modules within them.

At this time, the plant topology is only used to extract the module data. TODO: Handle ambients/rooms

async update_module_status()¶

Convenience method that first refreshes the information of the modules’ status through an API call and then parses the status information into the modules of the object’s inner map.

This method call on its own will not refresh the module topology of the plant so modules that are no longer present in the plant will remain with their last known status, while new modules that may have been added to the topology will not be reflected in it just yet.

async update_topology()¶

Convenience method that first refreshes the plant’s topology information through an API call and then parses the modules contained in that topology into the object’s inner map.

This method call on its own will not refresh the status of the modules.

async update_topology_and_modules()¶

Convenience method that first refreshes the plant’s topology information and then refreshes the status of all modules in that topology.

This implies 2 API calls and will produce an up-to-date view of the plant in the inner map of modules.

homepluscontrol.homeplusplant.PLANT_TOPOLOGY_BASE_URL = 'https://api.developer.legrand.com/hc/api/v1.0/plants/'¶: API endpoint for the Home+ plant information.

homepluscontrol.homeplusplant.PLANT_TOPOLOGY_RESOURCE = '/topology'¶: Path to the Home+ plant topology information.

Home+ Module Base Class¶

class homepluscontrol.homeplusmodule.HomePlusModule(plant, id, name, hw_type, device, fw='', type='', reachable=False)¶

Base Class representing a “module”, i.e a Home+ device such as a plug, a light or a remote.

plant¶

Plant that holds this module

Type: HomePlusPlant

id¶

Unique identifier of the module

Type: str

name¶

Name of the module

Type: str

hw_type¶

Hardware type(?) of the module (NLP, NLT, NLF)

Type: str

device¶

Type of the device (plug, light, remote)

Type: str

fw¶

Firware(?) of the module. Defaults to an empty string.

Type: str, optional

type¶

Additional type information of the module. Defaults to an empty string.

Type: str, optional

reachable¶

True if the module is reachable and False if it is not. Defaults to False.

Type: bool, optional

statusUrl¶

URL of the API endpoint that returns the status of the module

Type: str

build_status_url(base_url)¶

Build the full API URL that provides the status of the module. The URL is updated into the statusUrl attribute

Parameters: base_url (str) – Leftmost part of the URL to which Plant and Module Identifiers are concatenated

async get_status_update()¶

Get the current status of the module by calling the corresponding API method located at the URL in the statusUrl attributes.

Returns: JSON representation of the module’s status.
Return type: dict

property logger¶: Return logger of the Home+ Control Module

update_state(module_data)¶

Update the internal state of the module from the input JSON data.

Parameters: module_data (json) – JSON data of the module state

Home+ Interactive Module Base Class¶

class homepluscontrol.homeplusinteractivemodule.HomePlusInteractiveModule(plant, id, name, hw_type, device, fw='', type='', reachable=False)¶

Base Class for Home+ modules that are interactive, i.e a Home+ device that accepts commands to update its status, such as a plug or a light

This class extends the HomePlusModule base class.

status¶

The module can have status = ‘on’ or status = ‘off’

Type: str

power¶

The module power consumption in watts (as an integer value)

Type: int

MODULE_BASE_URL = 'https://api.developer.legrand.com/hc/api/v1.0/dummy'¶: Dummy endpoint for this module’s status - has to be set by the inheriting classes.

STATUS_OFF = {'status': 'off'}¶: Data that is to be sent to the API to set the device to an ‘on’ state.

STATUS_ON = {'status': 'on'}¶: Data that is to be sent to the API to set the device to an ‘on’ state.

async post_status_update(desired_end_status)¶

Call the API method to act on the module’s status.

Parameters: desired_end_status (dict) – One of the two class attributes (STATUS_ON and STATUS_OFF) that are defined to set the status ON or OFF.
Returns: True if the API update request was successful; False otherwise.
Return type: bool

async toggle_status()¶: Toggle the state of this interactive module, i.e. if the module is on, the method call turns it off. If the module is off, the method call turns it on.

async turn_off()¶: Turn off this interactive module

async turn_on()¶: Turn on this interactive module

update_state(module_data)¶

Update the internal state of the module from the input JSON data.

Parameters: module_data (json) – JSON data of the module state

Home+ Plug (Outlet)¶

class homepluscontrol.homeplusplug.HomePlusPlug(plant, id, name, hw_type, device, fw='', type='', reachable=False)¶

Class that represents a Home+ Plug Module, i.e. electrical socket.

This class extends the HomePlusInteractiveModule base class.

MODULE_BASE_URL = 'https://api.developer.legrand.com/hc/api/v1.0/plug/energy/addressLocation/plants/'¶: API endpoint for the Home+ Plug status

Home+ Light¶

class homepluscontrol.homepluslight.HomePlusLight(plant, id, name, hw_type, device, fw='', type='', reachable=False)¶

Class that represents a Home+ Light Module.

This class extends the HomePlusInteractiveModule base class.

MODULE_BASE_URL = 'https://api.developer.legrand.com/hc/api/v1.0/light/lighting/addressLocation/plants/'¶: API endpoint for the Home+ Light status

Home+ Remote (Wireless Switch)¶

class homepluscontrol.homeplusremote.HomePlusRemote(plant, id, name, hw_type, device, fw='', type='', reachable=False)¶

Class that represents a Home+ Remote Module, i.e. a switch that is wireless and configured to control specific modules in the plant

This class extends the HomePlusModule base class. The remote is not an interactive module.

battery¶: level of charge of the module’s battery.

MODULE_BASE_URL = 'https://api.developer.legrand.com/hc/api/v1.0/remote/remote/addressLocation/plants/'¶: API endpoint for the Home+ Remote status

update_state(module_data)¶

Update the internal state of the module from the input JSON data.

Parameters: module_data (json) – JSON data of the module state

Home+ Automation (Shutter Control)¶

class homepluscontrol.homeplusautomation.HomePlusAutomation(plant, id, name, hw_type, device, fw='', type='', reachable=False)¶

Class that represents a Home+ Automation Module.

This class extends the HomePlusModule base class.

level¶

The automation’s position level (as an integer value from 0 to 100).

Type: int

CLOSED_FULL = 0¶: Level value that represents a fully closed cover.

MODULE_BASE_URL = 'https://api.developer.legrand.com/hc/api/v1.0/automation/automation/addressLocation/plants/'¶: API endpoint for the Home+ Automation status

OPEN_FULL = 100¶: Level value that represents a fully open cover.

STOP_MOTION = -1¶: Level value to send to the API to make the automation stop.

async close()¶

Close the automation module.

This method will indicate the automation to go to the fully closed position.

async open()¶

Open the automation module.

This method will indicate the automation to go to the fully open position.

async post_status_update(desired_level)¶

Call the API method to act on the module’s status.

Parameters: desired_level (int) – Level value to be set on the automation.
Returns: True if the API update request was successful; False otherwise.
Return type: bool

async set_level(desired_level)¶: Set the level of the automation module.

async stop()¶: Stop the motion of the automation module.

update_state(module_data)¶

Update the internal state of the module from the input JSON data.

Parameters: module_data (json) – JSON data of the module state

Home+ API¶

class homepluscontrol.homeplusapi.HomePlusControlAPI(subscription_key, oauth_client=None, update_intervals={'module_status_update_interval': 300, 'plant_topology_update_interval': 3600, 'plant_update_interval': 7200})¶

Presents a unique API to the Home+ Control platform.

This class is an implementation of the base class AbstractHomePlusOAuth2Async and is intended for the integration into Home Assistant.

This class presents a unified view of the interactive modules that are available in the Home+ Control platform through the method async_get_modules() and it handles the refresh of the different elements of the plant, topology and module status through the provided update intervals.

This class is still in an abstract form because it does not implement the method async_get_access_token(). That is provided through the Home Assistant integration.

subscription_key¶

Subscription key obtained from the API provider

Type: str

oauth_client¶

aiohttp ClientSession object that handles HTTP async requests

Type: ClientSession

_plants¶

Dictionary containing the information of all plants.

Type: dict

_modules¶

Dictionary containing the information of all modules in the plants.

Type: dict

_modules_to_remove¶

Dictionary containing the information of modules that are no longer in the plants’ topology.

Type: dict

_refresh_intervals¶

Dictionary of the configured update intervals for plant, topology and module status information.

Type: dict

async async_get_modules()¶

Retrieve the module information.

Returns: Dictionary of modules across all of the plants keyed by the unique platform identifier.
Return type: dict

async async_handle_module_status()¶

Recover the topology information for the plants defined in this object.

By requesting the topology of the plant, the system learns about the modules that exist. The topology indicates identifiers, type and other device information, but it contains no information about the state of the module.

This method returns the list of modules that will be registered in HomeAssistant. At this time the modules that are discovered through this API call are flattened into a single data structure.

Returns: Dictionary of modules across all of the plants.
Return type: dict

async async_handle_plant_data()¶

Recover the plant data for this particular user.

This will populate the “private” array of plants of this object and will return it. It is expected that in most cases, there will only be one plant.

Returns

Dictionary of plants for this user - Keyed by the plant ID. Can be empty if no: plants are retrieved.

Return type

dict

property logger¶: Return logger of the API.

exception homepluscontrol.homeplusapi.HomePlusControlApiError¶: General HomePlusControlApi error occurred.

API Documentation¶

OAuth2 Authentication¶

Home+ Plant (Home) Class¶

Home+ Module Base Class¶

Home+ Interactive Module Base Class¶

Home+ Plug (Outlet)¶

Home+ Light¶

Home+ Remote (Wireless Switch)¶

Home+ Automation (Shutter Control)¶

Home+ API¶

Home + Control

Navigation

Related Topics