| Name | andersen-ev JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | |
| Summary | Python package for controlling the Andersen A2 EV charger |
| upload_time | 2023-01-11 09:30:28 |
| maintainer | |
| docs_url | None |
| author | James Brown |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Andersen-EV
Python package to enable control of the Andersen A2 EV charger. The library routes commands to the charger via Andersen's cloud API. So whilst the A2 cannot be controlled directly, this library could be used to replicate, or even replace the Konnect+ app.
## Installation
```
pip install andersen-ev
```
Alternatively, install directly from this Github repo:
```
pip install git+https://github.com/strobejb/andersen-ev
```
## Authentication
Register your mobile phone with the Andersen Konnect+ app as normal. The email address and password used to register with Andersen are also needed by the python client to authenticate with the cloud API. User credentials should be protected and never hard-coded into scripts or source-control:
```python
from andersen_ev import AndersenA2
a2 = AndersenA2()
a2.authenticate(email=EMAIL, password=PASSWORD)
```
Device confirmation is not implemented yet, but will be soon. When this feature arrives, it will be possible to authenticate with an access token, meaning the password does not need to be persisted.
## Basic Usage
Now that the python client is authenticated, the Andersen APIs be accessed. Andersen's API is based on GraphQL and returns JSON structures for all queries. This python library acts as a simple wrapper that performs the necessary GraphQL queries, and converts all return values into python dictionaries.
### Retrieve device ID
This is the first step needed after authentication. Most functions exposed by this library will require the 'device ID' of your Andersen charger. This ID can be found using the `get_current_user_devices` function:
```python
devices = a2.get_current_user_devices()
deviceId = devices[0]['id']
```
The example above retrieves the ID of the first device (charger) registered with your account.
If you have more than one EV charger, then you will need to search by the name or ID of the device, or just use the `device_id_from_name` helper function:
```python
deviceId = a2.device_id_from_name('Charger Name Here')
```
### Enable scheduled charging
Scheduled charging can be resumed by enabling a specific schedule. The 'slot number' (an integer in the range 0-4) identifies the schedule as it appears in the Konnect app:
```python
a2.enable_schedule(deviceId, 0)
```
If the charger is locked, you might also want to unlock it at the same time to allow the schedule to take affect.
### Disable scheduled charging
The charger will most likely be running off an overnight schedule. The Konnect+ app lets you cancel the schedules, allowing any connected vehicle to start charging:
```python
a2.set_all_schedules_disabled(deviceId)
```
The command above disables all schedules and puts the charger into 'ready' (unlocked) state.
### Define a new schedule
A new schedule can be created by providing the schedule data (start & end time, and days applicable to). The slot number (0-4) needs to be specified separately as the 2nd parameter to the function:
```python
schedule = {
'startHour': 0,
'startMinute': 30,
'endHour': 4,
'endMinute': 30,
'enabled': True,
"dayMap": {
"monday": True,
"tuesday": True,
"wednesday": True,
"thursday": True,
"friday": True,
"saturday": True,
"sunday": True
}
}
a2.create_schedule(deviceId, 0, schedule)
```
### Lock the charger
Andersen chargers can be 'user locked' so that connected vehicles will not charge, and any scheduled charge events will also prevent the vehicle to charge.
```python
a2.user_lock(deviceId)
```
### Unlock the charger
The charger can also be unlocked, which will put it in the 'ready' state. Charging will commence if a vehicle is connected.
```python
a2.user_unlock(deviceId)
```
### Receive device status updates
It is possible to subscribe to device status updates sent by the cloud service, providing near-realtime information about what the charger is doing (what state it is in), and how much power is being used for charging connected vehicles.
```python
import json
for result in a2.subscribe_device_updates(deviceId):
j = json.dumps(result, indent=2)
print(j)
```
The results of these notifications contain slightly more information than just querying (polling) the API directly. Specifically, the result includes the current charging status (power level, etc) and can be used to replicate what the Konnect+ app displays. There are lots of values available- just run the `examples/konnect-status.py` sample to see it in action.
Useful fields seem to be:
|Field|Description|
|---|---|
|`sysSchEnabled`|True when a schedule is enabled|
|`sysSchLocked`|True when the device is locked due to a schedule|
|`sysUserLock`|True then the device is user-locked (False when unlocked)|
|`chargePower`|The current charge level|
|`evseState`|device status / locked / charging |
Values for `evseState` are defined below. These appear to be the same values as
defined by the OpenEVSE specification.
|EVSE State|Description|
|---|---|
|1| Ready (disconnected) |
|2| Connected |
|3| Charging |
|4| Error |
|254| Sleeping |
|255| Disabled (locked by user, or schedule) |
There doesn't seem to be a reliable way to determine if a charger is physically connected, but not drawing power because of another reason. For example, if the charger is disabled because of a timed schedule, or locked by the user, the EVSE state always appears as 255 (disabled) even when a vehicle is connected. Only when the device is unlocked and there is no schedule enabled, will `evseState` reflect the connected/charging status.
I've also never observed the Andersen charger reporting the EVSE state as 254 (sleeping) which could be inferred as 'disabled due to a schedule'. These limitations are potentially a bug which could be rectified by future firmware update by Andersen.
### Example device status
```python
{
"deviceStatusUpdated": {
"id": "....",
"evseState": 255, # 1=ready, 2=connected, 3=charging, 255=locked
"online": true, # Connected to cloud
"sysRssi": -69, # Wifi signal strength
"sysSSID": "SSID HERE", # SSID
"sysSchEnabled": True, # True when a schedule is active
"sysUserLock": False, # Is device Locked
"sysScheduleLock": True, # True when schedule is active
"sysSolarPower": null,
"sysGridPower": null,
"solarMaxGridChargePercent": 100,
"solarChargeAlways": true,
"solarOverride": false,
"cfgCTConfig": 1,
"chargeStatus": {
"start": "2023-01-05T00:30:00Z",
"chargeEnergyTotal": 9.128312,
"chargePower": 0, # current charge level
"duration": 8472
},
"scheduleSlotsArray": [ # array of schedule slots
],
"sysSchDSORandom": null
}
```
## Examples
There are two examples that demonstate some of the functionality of the API:
* `examples/konnect-query.py` demonstrates how to lock & unlock, and enable charging schedules.
* `examples/konnect-status.py` is a basic example to demonstrate how to subscribe to device status events.
Both examples need your credentials to run. These can be provided by creating a file called `examples/config.cfg`, and speciying your email and password in as follows:
```ini
[KONNECT]
email=user@example.com
password=...
```
Raw data
{
"_id": null,
"home_page": "",
"name": "andersen-ev",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "James Brown",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/82/02/ef62be6f7e891736523519610ae2eddb84b866ef9071940d08cc47fdb32a/andersen_ev-0.1.4.tar.gz",
"platform": null,
"description": "# Andersen-EV \n\nPython package to enable control of the Andersen A2 EV charger. The library routes commands to the charger via Andersen's cloud API. So whilst the A2 cannot be controlled directly, this library could be used to replicate, or even replace the Konnect+ app.\n\n\n## Installation\n\n```\npip install andersen-ev\n```\n\nAlternatively, install directly from this Github repo:\n\n```\npip install git+https://github.com/strobejb/andersen-ev\n```\n\n## Authentication\n\nRegister your mobile phone with the Andersen Konnect+ app as normal. The email address and password used to register with Andersen are also needed by the python client to authenticate with the cloud API. User credentials should be protected and never hard-coded into scripts or source-control:\n\n```python\nfrom andersen_ev import AndersenA2\n\na2 = AndersenA2()\na2.authenticate(email=EMAIL, password=PASSWORD)\n```\n\nDevice confirmation is not implemented yet, but will be soon. When this feature arrives, it will be possible to authenticate with an access token, meaning the password does not need to be persisted. \n\n## Basic Usage\n\nNow that the python client is authenticated, the Andersen APIs be accessed. Andersen's API is based on GraphQL and returns JSON structures for all queries. This python library acts as a simple wrapper that performs the necessary GraphQL queries, and converts all return values into python dictionaries.\n\n### Retrieve device ID \n\nThis is the first step needed after authentication. Most functions exposed by this library will require the 'device ID' of your Andersen charger. This ID can be found using the `get_current_user_devices` function:\n\n```python\ndevices = a2.get_current_user_devices()\ndeviceId = devices[0]['id']\n```\n\nThe example above retrieves the ID of the first device (charger) registered with your account.\nIf you have more than one EV charger, then you will need to search by the name or ID of the device, or just use the `device_id_from_name` helper function:\n\n```python\ndeviceId = a2.device_id_from_name('Charger Name Here')\n```\n\n### Enable scheduled charging\n\nScheduled charging can be resumed by enabling a specific schedule. The 'slot number' (an integer in the range 0-4) identifies the schedule as it appears in the Konnect app:\n\n```python\na2.enable_schedule(deviceId, 0)\n```\nIf the charger is locked, you might also want to unlock it at the same time to allow the schedule to take affect.\n\n### Disable scheduled charging\n\nThe charger will most likely be running off an overnight schedule. The Konnect+ app lets you cancel the schedules, allowing any connected vehicle to start charging:\n\n```python\na2.set_all_schedules_disabled(deviceId)\n```\nThe command above disables all schedules and puts the charger into 'ready' (unlocked) state.\n\n### Define a new schedule\n\nA new schedule can be created by providing the schedule data (start & end time, and days applicable to). The slot number (0-4) needs to be specified separately as the 2nd parameter to the function:\n\n```python\nschedule = {\n 'startHour': 0,\n 'startMinute': 30,\n 'endHour': 4,\n 'endMinute': 30,\n 'enabled': True,\n \"dayMap\": {\n \"monday\": True,\n \"tuesday\": True,\n \"wednesday\": True,\n \"thursday\": True,\n \"friday\": True,\n \"saturday\": True,\n \"sunday\": True\n }\n}\na2.create_schedule(deviceId, 0, schedule)\n```\n\n### Lock the charger\n\nAndersen chargers can be 'user locked' so that connected vehicles will not charge, and any scheduled charge events will also prevent the vehicle to charge.\n\n```python\na2.user_lock(deviceId)\n```\n\n### Unlock the charger\n\nThe charger can also be unlocked, which will put it in the 'ready' state. Charging will commence if a vehicle is connected.\n\n```python\na2.user_unlock(deviceId)\n```\n\n### Receive device status updates\n\nIt is possible to subscribe to device status updates sent by the cloud service, providing near-realtime information about what the charger is doing (what state it is in), and how much power is being used for charging connected vehicles. \n\n```python\nimport json\n\nfor result in a2.subscribe_device_updates(deviceId):\n j = json.dumps(result, indent=2)\n print(j)\n``` \n\nThe results of these notifications contain slightly more information than just querying (polling) the API directly. Specifically, the result includes the current charging status (power level, etc) and can be used to replicate what the Konnect+ app displays. There are lots of values available- just run the `examples/konnect-status.py` sample to see it in action.\n\nUseful fields seem to be:\n\n|Field|Description|\n|---|---|\n|`sysSchEnabled`|True when a schedule is enabled|\n|`sysSchLocked`|True when the device is locked due to a schedule|\n|`sysUserLock`|True then the device is user-locked (False when unlocked)|\n|`chargePower`|The current charge level|\n|`evseState`|device status / locked / charging |\n\nValues for `evseState` are defined below. These appear to be the same values as\ndefined by the OpenEVSE specification.\n\n|EVSE State|Description|\n|---|---|\n|1| Ready (disconnected) |\n|2| Connected |\n|3| Charging |\n|4| Error |\n|254| Sleeping |\n|255| Disabled (locked by user, or schedule) |\n\nThere doesn't seem to be a reliable way to determine if a charger is physically connected, but not drawing power because of another reason. For example, if the charger is disabled because of a timed schedule, or locked by the user, the EVSE state always appears as 255 (disabled) even when a vehicle is connected. Only when the device is unlocked and there is no schedule enabled, will `evseState` reflect the connected/charging status.\n\nI've also never observed the Andersen charger reporting the EVSE state as 254 (sleeping) which could be inferred as 'disabled due to a schedule'. These limitations are potentially a bug which could be rectified by future firmware update by Andersen.\n\n### Example device status \n\n```python\n{\n \"deviceStatusUpdated\": {\n \"id\": \"....\",\n \"evseState\": 255, # 1=ready, 2=connected, 3=charging, 255=locked\n \"online\": true, # Connected to cloud\n \"sysRssi\": -69, # Wifi signal strength\n \"sysSSID\": \"SSID HERE\", # SSID \n \"sysSchEnabled\": True, # True when a schedule is active\n \"sysUserLock\": False, # Is device Locked\n \"sysScheduleLock\": True, # True when schedule is active\n \"sysSolarPower\": null,\n \"sysGridPower\": null,\n \"solarMaxGridChargePercent\": 100,\n \"solarChargeAlways\": true,\n \"solarOverride\": false,\n \"cfgCTConfig\": 1,\n \"chargeStatus\": {\n \"start\": \"2023-01-05T00:30:00Z\",\n \"chargeEnergyTotal\": 9.128312,\n \"chargePower\": 0, # current charge level\n \"duration\": 8472\n },\n \"scheduleSlotsArray\": [ # array of schedule slots\n ],\n \"sysSchDSORandom\": null \n}\n\n```\n\n## Examples\n\nThere are two examples that demonstate some of the functionality of the API:\n* `examples/konnect-query.py` demonstrates how to lock & unlock, and enable charging schedules.\n* `examples/konnect-status.py` is a basic example to demonstrate how to subscribe to device status events. \n\nBoth examples need your credentials to run. These can be provided by creating a file called `examples/config.cfg`, and speciying your email and password in as follows:\n\n```ini\n[KONNECT]\nemail=user@example.com\npassword=...\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python package for controlling the Andersen A2 EV charger",
"version": "0.1.4",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "42fbf1c202430996c7b2985b2d842bf90fb92678b9f9a78adc17016f32184382",
"md5": "525e82f4e3c61b9c6e0938bf1c00554a",
"sha256": "ef54e6d17734d5194b63ee069c2d828644af700bca3aaf0229de3e2252a09498"
},
"downloads": -1,
"filename": "andersen_ev-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "525e82f4e3c61b9c6e0938bf1c00554a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 11540,
"upload_time": "2023-01-11T09:30:26",
"upload_time_iso_8601": "2023-01-11T09:30:26.568745Z",
"url": "https://files.pythonhosted.org/packages/42/fb/f1c202430996c7b2985b2d842bf90fb92678b9f9a78adc17016f32184382/andersen_ev-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8202ef62be6f7e891736523519610ae2eddb84b866ef9071940d08cc47fdb32a",
"md5": "7ff8a143f04bd45f2b827565c029bc92",
"sha256": "7918fbc0c363e70d86a74ed1a2a2b83fe17fa6e1f81157f4039136e9c24a6b27"
},
"downloads": -1,
"filename": "andersen_ev-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "7ff8a143f04bd45f2b827565c029bc92",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 13007,
"upload_time": "2023-01-11T09:30:28",
"upload_time_iso_8601": "2023-01-11T09:30:28.299631Z",
"url": "https://files.pythonhosted.org/packages/82/02/ef62be6f7e891736523519610ae2eddb84b866ef9071940d08cc47fdb32a/andersen_ev-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-11 09:30:28",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "andersen-ev"
}
