# pyelectroluxconnect
Python client package to communicate with the Electrolux Connectivity Platform (**ECP**) used by some home appliances, Electrolux owned brands, like: **Electrolux**, **AEG**, **Frigidaire**, **Husqvarna**.
Tested with AEG washer-dryer, but probably could be used with some internet connected ovens, diswashers, fridges, airconditioners.
It is general client, and all parameters (called HACL), that can be read or set, names and translations are dynamically generated, based on appliance profile file, downloaded from ECP servers.
Appliance must be registered with one of the following ECP based applications: Electrolux Care, Electrolux Kitchen, Electrolux Life, Electrolux Oven, Electrolux Home+, AEG Care, AEG Kitchen, Frigidaire 2.0
## Features
- list appliances paired with Electrolux account
- get appliance profile with translations
- get appliance state
- send command to appliance
- register/unregister Client with Electrolux MQTT cloud based broker
## Usage
#### Initiate session
To use this library, there's an account with Electrolux/AEG/Frigidaire app must be created. By default, library is using EMEA region apps credentials. If account is created in other region app, `region` parameter must be set. If created account is not supported, You can manually set `regionServer`, `customApiKey` and `customApiBrand` parameters (from sniffed traffic or extracted from mobile app).
```python
import pyelectroluxconnect
ses = pyelectroluxconnect.Session(username, password, region="emea", tokenFileName = ".electrolux-token", country = "US", language = None, deviceId = "CustomDeviceId", verifySsl = True, regionServer=None, customApiKey=None, customApiBrand=None)
```
or minimal input set:
```python
import pyelectroluxconnect
ses = pyelectroluxconnect.Session(username, password)
```
where:
`username, password` - ECP (Electrolux site) credentials
`tokenFileName` - file to store auth token (default: `~/.electrolux-token`)
`region` - account region (defalt `emea`. Tested with `emea`, `apac`, `na`, `latam`, `frigidaire`)
`country` - 2-char country code (default `US`)
`language` - 3-char language code for translations (`All` - for all delivered languages, default: `None`)
`deviceId` - custom id of client used in ECP, should be unique for every client instance (default: `CustomDeviceId`)
`verifySsl` - verify ECP servers certs (default: `True`)
`regionServer` - region server URL (default is based on selected region)
`customApiKey` - custom value of "x-ibm-client-id" and "x-api-key" HTTP headers (default is based on selected region)
`customApiBrand` - custom "brand" value (default is based on selected region)
#### Login to ECP
```python
ses.login()
```
#### Get list of appliances registered to Electrolux account
```python
appllist = ses.getAppliances()
print(appllist)
```
#### Get appliances connection state
```python
for appliance in appllist:
print(ses.getApplianceConnectionState(appliance))
```
#### Get appliance profile
List of parameters (HACL's) with allowed values, translations, etc... Note, that not all parameters can be read, or set over ECP.
Each parameter is in "module:hacl" form. Module is internal appliance module symbol, hacl is parameter hex symbol, that can be read from or set to module.
```python
print(ses.getApplianceProfile(appliance))
```
#### Get appliance latest state from ECP
Get latest appliance state from ECP. When appliance is online, current state updates are available over Internet with [MQTT](https://en.wikipedia.org/wiki/MQTT) protocol. To get credentials to connect any MQTT client to ECP MQTT broker, use `registerMQTT()` method.
to get latest state from a platform:
```python
print(ses.getApplianceState(appliance, paramName = None, rawOutput = False))
```
`paramName` - comma separated list of patrameter names (`None` (default) for all params)
`rawOutput` - get list of parameters in received form. `False` (default): parse output to more friendly form (with translations, etc)
#### Send param value to appliance
Send value to appliance (list of supported appliance destinations (`destination`) and parameters (`hacl`) with allowed values (`value`), You can get with `getApplianceProfile()` method):
```python
ses.setHacl(appliance, hacl, value, destination)
```
`hacl` - hex number of param (HACL)
`value` - value to set (it could be number or list of parameters (for container HACL type))
`destination` - destination module name, from profile path (`NIU`, `WD1`, etc...)
washer-dryer examples:
- set Wash+Dry "Cottons" program, with "Extra Dry" dryness Level:
```python
ses.setHacl(appliance, "0x1C09", [{"50":"0x0000"},{"12":"128"},{"6.32":1},{"6.33":1}], "WD1")
```
- pause program:
```python
ses.setHacl(appliance, "0x0403", 4, "WD1")
```
#### Register client to MQTT broker
```python
print(ses.registerMQTT())
```
returns parameters required to login to Electrolux MQTT broker with any MQTT client:
`Url` - Host of MQTT broker (with port number)
`OrgId` - Organization ID
`ClientID` - MQTT Client ID
`DeviceToken` - Token required to authentication (for IBM broker, use string `use-token-auth` as username, DeviceToken as password)
List of MQTT topics (QoS = 0) to subscribe:
- `iot-2/cmd/live_stream/fmt/+`
- `iot-2/cmd/feature_stream/fmt/+`
#### Unregister client from MQTT broker
```python
ses.unregisterMQTT()
```
#### Parse received MQTT message
```python
print(ses.getMqttState(mqttJsonPayload))
```
Parse message from MQTT broker, and return in getApplianceState(...) like form.
`mqttJsonPayload` - MQTT message payload in JSON form.
#### Very simple MQTT example to receive online appliance state changes from ECP MQTT broker
```python
import paho.mqtt.client as mqtt
import pyelectroluxconnect
def on_connect(client, userdata, flags, rc):
print("Connected with result code "+str(rc))
client.subscribe("iot-2/cmd/live_stream/fmt/json", 0)
def on_message(client, userdata, msg):
print(ses.getMqttState(msg.payload))
ses = pyelectroluxconnect.Session(login, passwd, language = "pol", region="emea", deviceId='MQTTHA2')
ses.login()
mqtt_params = ses.registerMQTT()
client = mqtt.Client(client_id = mqtt_params["ClientID"])
client.tls_set(ca_certs = ses.getSSLCert())
client.username_pw_set("use-token-auth", mqtt_params["DeviceToken"])
client.on_connect = on_connect
client.on_message = on_message
client.connect(mqtt_params["Url"].split(":")[0], int(mqtt_params["Url"].split(":")[1]), 60)
while True:
client.loop()
```
## Disclaimer
This library was not made by AB Electrolux. It is not official, not developed, and not supported by AB Electrolux.
Raw data
{
"_id": null,
"home_page": "https://github.com/tomeko12/pyelectroluxconnect",
"name": "pyelectroluxconnect",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "home automation electrolux aeg frigidaire husqvarna",
"author": "tomeko",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/21/f7/814d32e1b242778e3f4c5bd0dcc10d689b6cdca952a7f670278d3e9cf385/pyelectroluxconnect-0.3.19.tar.gz",
"platform": null,
"description": "# pyelectroluxconnect\r\nPython client package to communicate with the Electrolux Connectivity Platform (**ECP**) used by some home appliances, Electrolux owned brands, like: **Electrolux**, **AEG**, **Frigidaire**, **Husqvarna**.\r\nTested with AEG washer-dryer, but probably could be used with some internet connected ovens, diswashers, fridges, airconditioners. \r\nIt is general client, and all parameters (called HACL), that can be read or set, names and translations are dynamically generated, based on appliance profile file, downloaded from ECP servers. \r\nAppliance must be registered with one of the following ECP based applications: Electrolux Care, Electrolux Kitchen, Electrolux Life, Electrolux Oven, Electrolux Home+, AEG Care, AEG Kitchen, Frigidaire 2.0\r\n \r\n## Features\r\n- list appliances paired with Electrolux account\r\n- get appliance profile with translations\r\n- get appliance state\r\n- send command to appliance\r\n- register/unregister Client with Electrolux MQTT cloud based broker\r\n\r\n## Usage\r\n#### Initiate session\r\nTo use this library, there's an account with Electrolux/AEG/Frigidaire app must be created. By default, library is using EMEA region apps credentials. If account is created in other region app, `region` parameter must be set. If created account is not supported, You can manually set `regionServer`, `customApiKey` and `customApiBrand` parameters (from sniffed traffic or extracted from mobile app).\r\n\r\n \r\n```python\r\nimport pyelectroluxconnect\r\nses = pyelectroluxconnect.Session(username, password, region=\"emea\", tokenFileName = \".electrolux-token\", country = \"US\", language = None, deviceId = \"CustomDeviceId\", verifySsl = True, regionServer=None, customApiKey=None, customApiBrand=None)\r\n```\r\n\r\nor minimal input set: \r\n\r\n```python\r\nimport pyelectroluxconnect\r\nses = pyelectroluxconnect.Session(username, password)\r\n```\r\n\r\nwhere: \r\n`username, password` - ECP (Electrolux site) credentials \r\n`tokenFileName` - file to store auth token (default: `~/.electrolux-token`) \r\n`region` - account region (defalt `emea`. Tested with `emea`, `apac`, `na`, `latam`, `frigidaire`) \r\n`country` - 2-char country code (default `US`) \r\n`language` - 3-char language code for translations (`All` - for all delivered languages, default: `None`) \r\n`deviceId` - custom id of client used in ECP, should be unique for every client instance (default: `CustomDeviceId`) \r\n`verifySsl` - verify ECP servers certs (default: `True`) \r\n`regionServer` - region server URL (default is based on selected region) \r\n`customApiKey` - custom value of \"x-ibm-client-id\" and \"x-api-key\" HTTP headers (default is based on selected region) \r\n`customApiBrand` - custom \"brand\" value (default is based on selected region) \r\n\r\n\r\n\r\n#### Login to ECP\r\n\r\n\r\n```python\r\nses.login()\r\n```\r\n\r\n#### Get list of appliances registered to Electrolux account\r\n\r\n```python\r\nappllist = ses.getAppliances()\r\nprint(appllist)\r\n```\r\n\r\n\r\n#### Get appliances connection state\r\n\r\n```python\r\nfor appliance in appllist: \r\n\tprint(ses.getApplianceConnectionState(appliance))\r\n```\r\n\r\n\r\n#### Get appliance profile \r\nList of parameters (HACL's) with allowed values, translations, etc... Note, that not all parameters can be read, or set over ECP. \r\nEach parameter is in \"module:hacl\" form. Module is internal appliance module symbol, hacl is parameter hex symbol, that can be read from or set to module. \r\n \t\r\n```python\r\nprint(ses.getApplianceProfile(appliance))\r\n```\r\n\r\n \r\n#### Get appliance latest state from ECP\r\nGet latest appliance state from ECP. When appliance is online, current state updates are available over Internet with [MQTT](https://en.wikipedia.org/wiki/MQTT) protocol. To get credentials to connect any MQTT client to ECP MQTT broker, use `registerMQTT()` method.\r\n \r\n\r\nto get latest state from a platform: \r\n\r\n```python\r\nprint(ses.getApplianceState(appliance, paramName = None, rawOutput = False))\r\n```\r\n\r\n`paramName` - comma separated list of patrameter names (`None` (default) for all params) \r\n`rawOutput` - get list of parameters in received form. `False` (default): parse output to more friendly form (with translations, etc) \r\n\r\n\r\n#### Send param value to appliance\r\nSend value to appliance (list of supported appliance destinations (`destination`) and parameters (`hacl`) with allowed values (`value`), You can get with `getApplianceProfile()` method): \r\n```python\r\nses.setHacl(appliance, hacl, value, destination)\r\n```\r\n \r\n`hacl` - hex number of param (HACL) \r\n`value` - value to set (it could be number or list of parameters (for container HACL type)) \r\n`destination` - destination module name, from profile path (`NIU`, `WD1`, etc...) \r\n \r\nwasher-dryer examples:\r\n- set Wash+Dry \"Cottons\" program, with \"Extra Dry\" dryness Level:\r\n \r\n```python\r\nses.setHacl(appliance, \"0x1C09\", [{\"50\":\"0x0000\"},{\"12\":\"128\"},{\"6.32\":1},{\"6.33\":1}], \"WD1\")\r\n```\r\n\r\n- pause program:\r\n\r\n```python\r\nses.setHacl(appliance, \"0x0403\", 4, \"WD1\")\r\n```\r\n\r\n\r\n#### Register client to MQTT broker\r\n \r\n```python\r\nprint(ses.registerMQTT())\r\n```\r\n\r\nreturns parameters required to login to Electrolux MQTT broker with any MQTT client: \r\n`Url` - Host of MQTT broker (with port number) \r\n`OrgId` - Organization ID \r\n`ClientID` - MQTT Client ID \r\n`DeviceToken` - Token required to authentication (for IBM broker, use string `use-token-auth` as username, DeviceToken as password) \r\n\r\nList of MQTT topics (QoS = 0) to subscribe:\r\n- `iot-2/cmd/live_stream/fmt/+` \r\n- `iot-2/cmd/feature_stream/fmt/+` \r\n\r\n#### Unregister client from MQTT broker\r\n \r\n```python\r\nses.unregisterMQTT()\r\n```\r\n \r\n#### Parse received MQTT message\r\n\r\n```python\r\nprint(ses.getMqttState(mqttJsonPayload))\r\n```\r\n\r\nParse message from MQTT broker, and return in getApplianceState(...) like form.\r\n`mqttJsonPayload` - MQTT message payload in JSON form.\r\n\r\n#### Very simple MQTT example to receive online appliance state changes from ECP MQTT broker\r\n\r\n```python\r\nimport paho.mqtt.client as mqtt\r\nimport pyelectroluxconnect\r\n\r\ndef on_connect(client, userdata, flags, rc):\r\n print(\"Connected with result code \"+str(rc))\r\n client.subscribe(\"iot-2/cmd/live_stream/fmt/json\", 0)\r\n\r\ndef on_message(client, userdata, msg):\r\n print(ses.getMqttState(msg.payload))\r\n\r\nses = pyelectroluxconnect.Session(login, passwd, language = \"pol\", region=\"emea\", deviceId='MQTTHA2')\r\nses.login()\r\n\r\nmqtt_params = ses.registerMQTT()\r\n\r\nclient = mqtt.Client(client_id = mqtt_params[\"ClientID\"])\r\nclient.tls_set(ca_certs = ses.getSSLCert())\r\nclient.username_pw_set(\"use-token-auth\", mqtt_params[\"DeviceToken\"])\r\n \r\nclient.on_connect = on_connect\r\nclient.on_message = on_message\r\n \r\nclient.connect(mqtt_params[\"Url\"].split(\":\")[0], int(mqtt_params[\"Url\"].split(\":\")[1]), 60)\r\n \r\nwhile True:\r\n client.loop()\r\n```\r\n\r\n## Disclaimer\r\nThis library was not made by AB Electrolux. It is not official, not developed, and not supported by AB Electrolux.\r\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "Interface for Electrolux Connectivity Platform API",
"version": "0.3.19",
"project_urls": {
"Homepage": "https://github.com/tomeko12/pyelectroluxconnect"
},
"split_keywords": [
"home",
"automation",
"electrolux",
"aeg",
"frigidaire",
"husqvarna"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5d8e214914a97c315ff263d12e18b56034c0a90dd7ff264e9bd0a2d1098215bb",
"md5": "e2cec5bdd78d68ee9b8c78c802eae87e",
"sha256": "d5d155cfa9d226667aab814ad2c4c0ce44755a4ad50ef52c5c18e3ddf623f7b2"
},
"downloads": -1,
"filename": "pyelectroluxconnect-0.3.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2cec5bdd78d68ee9b8c78c802eae87e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 23118,
"upload_time": "2023-06-04T19:17:15",
"upload_time_iso_8601": "2023-06-04T19:17:15.693148Z",
"url": "https://files.pythonhosted.org/packages/5d/8e/214914a97c315ff263d12e18b56034c0a90dd7ff264e9bd0a2d1098215bb/pyelectroluxconnect-0.3.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "21f7814d32e1b242778e3f4c5bd0dcc10d689b6cdca952a7f670278d3e9cf385",
"md5": "e72cced45023feb913642398dac3d557",
"sha256": "468ae31f05e72f3b0a90741083ceb4d446b7b76f21bbf247fc028c0beba310eb"
},
"downloads": -1,
"filename": "pyelectroluxconnect-0.3.19.tar.gz",
"has_sig": false,
"md5_digest": "e72cced45023feb913642398dac3d557",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25595,
"upload_time": "2023-06-04T19:17:17",
"upload_time_iso_8601": "2023-06-04T19:17:17.437567Z",
"url": "https://files.pythonhosted.org/packages/21/f7/814d32e1b242778e3f4c5bd0dcc10d689b6cdca952a7f670278d3e9cf385/pyelectroluxconnect-0.3.19.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-04 19:17:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tomeko12",
"github_project": "pyelectroluxconnect",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyelectroluxconnect"
}
JSON
