[evnotify] Initial contribution: New binding for evnotify online service #11537
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| This content is produced and maintained by the openHAB project. | ||
|
|
||
| * Project home: https://www.openhab.org | ||
|
|
||
| == Declared Project Licenses | ||
|
|
||
| This program and the accompanying materials are made available under the terms | ||
| of the Eclipse Public License 2.0 which is available at | ||
| https://www.eclipse.org/legal/epl-2.0/. | ||
|
|
||
| == Source Code | ||
|
|
||
| https://github.com/openhab/openhab-addons |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| # EVNotify Binding | ||
|
|
||
| This binding can be used to read data for a given electric vehicle from the EVNotify online service (account). Please see [EVNotify](https://evnotify.de/). | ||
|
|
||
| It allows you to monitor different data from your electric vehicle (e.g. state of charge, state of health, etc.). | ||
|
|
||
| The binding was tested with a Hyundai Ioniq electric. | ||
|
|
||
| ## Supported Things | ||
|
|
||
| | Thing Type | Description | | ||
| | ---------- | ----------- | | ||
| | `vehicle` | The vehicle represents a connection to the [EVNotify](https://evnotify.de/) online service (account) | | ||
|
|
||
| ## Discovery | ||
|
|
||
| There is no discovery implemented. You have to create your things manually and specify the `AKey` and the `Token` of your [EVNotify](https://evnotify.de/) online service (account). | ||
|
|
||
| ## Binding Configuration | ||
|
|
||
| The binding has no configuration options, all configuration is done at `vehicle` level. | ||
|
|
||
| ## Thing Configuration | ||
|
|
||
| ### Vehicle Thing Configuration | ||
|
|
||
| | Parameter | Description | Required | Default | | ||
| | ----------------- | ----------- | :------: | :-----: | | ||
| | `AKey` | AKey used for EVNotify API access | yes | - | | ||
| | `Token` | Token used for EVNotify API access. It is like a password. Do not share this with people you do not trust! | yes | - | | ||
| | `refreshInterval` | Refresh interval for reading data from EVNotify online service (in seconds) | no | 120 | | ||
|
|
||
| ## Channels | ||
|
|
||
| ### Channels for Vehicle Thing | ||
|
|
||
| | Channel ID | Item Type | Description | | ||
| | ------------------------------ | --------- | ---------------------------------------------- | | ||
| | `soc_display` | Number | State of Charge (Display) | | ||
| | `soc_bms` | Number | State of Charge (BMS) | | ||
| | `last_soc` | String | Timestamp of the latest state of charge export | | ||
| | `soh` | Number | State of Health | | ||
| | `charging` | Switch | ON if charging | | ||
| | `rapid_charge_port` | Switch | ON if connected to a rapid charging port | | ||
| | `normal_charge_port` | Switch | ON if connected to a normal charging port | | ||
| | `slow_charge_port` | Switch | ON if connected to a slow charging port | | ||
|
Comment on lines
+44
to
+46
There was a problem hiding this comment. Suggestion (not a request for change): you could have defined one unique channel for the type of charging port (rapid, normal, slow). There was a problem hiding this comment.
You are right, but I just reused the terminology, of the ev notify service. |
||
| | `aux_battery_voltage` | Number | Voltage of the aux battery | | ||
| | `dc_battery_voltage` | Number | Voltage of the DC battery | | ||
| | `dc_battery_current` | Number | Current of the DC battery | | ||
| | `dc_battery_power` | Number | Power of the DC battery | | ||
| | `cumulative_energy_charged` | Number | Amount of energy that has been charged | | ||
| | `cumulative_energy_discharged` | Number | Amount of energy that has been discharged | | ||
| | `battery_min_temperature` | Number | The minimum temperature of the battery | | ||
| | `battery_max_temperature` | Number | The maximum temperature of the battery | | ||
| | `battery_inlet_temperature` | Number | The inlet temperature of the battery | | ||
| | `external_temperature` | Number | External temperature | | ||
|
Comment on lines
+47
to
+56
There was a problem hiding this comment. You could certainly rather used Number with the appropriate dimension in order to let the user define the unit he would like. |
||
| | `last_extended` | String | Timestamp of the latest export | | | ||
|
There was a problem hiding this comment. The channel name is a little strange and if the channel is a timestamps, the item type is not the good one. There was a problem hiding this comment. Same as above: Just reused terminology of the ev notify service. |
||
|
|
||
| ## Full Example | ||
|
|
||
| ### evnotify.things | ||
|
|
||
| ``` | ||
| # Thing evnotify:vehicle:YOUR_VEHICLE_ID "YOUR_VEHICLE_LABEL" @ "YOUR_VEHICLE_LOCATION" [akey="YOUR_AKEY",token="YOUR_TOKEN",refreshInterval=120] | ||
| Thing evnotify:vehicle:ioniq "Ioniq" @ "Carport" [akey="YOUR_AKEY",token="YOUR_TOKEN",refreshInterval=120] | ||
| ``` | ||
|
|
||
|  | ||
|
There was a problem hiding this comment. I am not sure this picture add any value... |
||
|
|
||
| ### evnotify.items | ||
|
|
||
| ``` | ||
| // Equipment representing thing: | ||
| // evnotify:vehicle:ioniq | ||
| // (Ioniq) | ||
|
Comment on lines
+73
to
+75
There was a problem hiding this comment. Probably something not useful. There was a problem hiding this comment. That are the comments openHAB is exporting, for the example thing. So for the added example image in my opinion it could be useful for the users. |
||
|
|
||
| Group Ioniq "Ioniq" ["Car"] | ||
|
|
||
| // Points: | ||
|
|
||
| Number Ioniq_StateofChargeDisplay "State of Charge (Display)" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:soc_display" } | ||
| Number Ioniq_StateofChargeBMS "State of Charge (BMS)" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:soc_bms" } | ||
| String Ioniq_Lateststateofcharge "Latest state of charge" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:last_soc" } | ||
| Number Ioniq_StateofHealth "State of Health" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:soh" } | ||
| Switch Ioniq_Charging "Charging" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:charging" } | ||
| Switch Ioniq_RapidChargingPort "Rapid Charging Port" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:rapid_charge_port" } | ||
| Switch Ioniq_NormalChargingPort "Normal Charging Port" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:normal_charge_port" } | ||
| Switch Ioniq_SlowChargingPort "Slow Charging Port" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:slow_charge_port" } | ||
| Number:ElectricPotential Ioniq_AUXBatteryVoltage "AUX Battery Voltage" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:aux_battery_voltage" } | ||
| Number:ElectricPotential Ioniq_DCBatteryVoltage "DC Battery Voltage" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:dc_battery_voltage" } | ||
| Number:ElectricCurrent Ioniq_DCBatteryCurrent "DC Battery Current" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:dc_battery_current" } | ||
| Number:Power Ioniq_DCBatteryPower "DC Battery Power" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:dc_battery_power" } | ||
| Number:Energy Ioniq_CumulativeEnergyCharged "Cumulative Energy Charged" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:cumulative_energy_charged" } | ||
| Number:Energy Ioniq_CumulativeEnergyDischarged "Cumulative Energy Discharged" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:cumulative_energy_discharged" } | ||
| Number:Temperature Ioniq_BatteryMinTemperature "Battery Min Temperature" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:battery_min_temperature" } | ||
| Number:Temperature Ioniq_BatteryMaxTemperature "Battery Max Temperature" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:battery_max_temperature" } | ||
| Number:Temperature Ioniq_BatteryInletTemperature "Battery Inlet Temperature" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:battery_inlet_temperature" } | ||
| Number:Temperature Ioniq_ExternalTemperature "External Temperature" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:external_temperature" } | ||
| String Ioniq_Latestexport "Latest export" (Ioniq) ["Point"] { channel="evnotify:vehicle:ioniq:last_extended" } | ||
| ``` | ||
|
|
||
|  | ||
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,17 @@ | ||||||
| <?xml version="1.0" encoding="UTF-8"?> | ||||||
| <project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0" | ||||||
| xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> | ||||||
|
There was a problem hiding this comment.
Suggested change
See #11833 |
||||||
|
|
||||||
| <modelVersion>4.0.0</modelVersion> | ||||||
|
|
||||||
| <parent> | ||||||
| <groupId>org.openhab.addons.bundles</groupId> | ||||||
| <artifactId>org.openhab.addons.reactor.bundles</artifactId> | ||||||
| <version>3.3.0-SNAPSHOT</version> | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| </parent> | ||||||
|
|
||||||
| <artifactId>org.openhab.binding.evnotify</artifactId> | ||||||
|
|
||||||
| <name>openHAB Add-ons :: Bundles :: EVNotify Binding</name> | ||||||
|
|
||||||
| </project> | ||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <features name="org.openhab.binding.evnotify-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0"> | ||
| <repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository> | ||
|
|
||
| <feature name="openhab-binding-evnotify" description="EVNotify Binding" version="${project.version}"> | ||
| <feature>openhab-runtime-base</feature> | ||
| <bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.evnotify/${project.version}</bundle> | ||
| </feature> | ||
| </features> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| /** | ||
| * Copyright (c) 2010-2022 Contributors to the openHAB project | ||
| * | ||
| * See the NOTICE file(s) distributed with this work for additional | ||
| * information. | ||
| * | ||
| * This program and the accompanying materials are made available under the | ||
| * terms of the Eclipse Public License 2.0 which is available at | ||
| * http://www.eclipse.org/legal/epl-2.0 | ||
| * | ||
| * SPDX-License-Identifier: EPL-2.0 | ||
| */ | ||
| package org.openhab.binding.evnotify.api; | ||
|
|
||
| import org.eclipse.jdt.annotation.NonNullByDefault; | ||
|
|
||
| /** | ||
| * Class for API error. | ||
| * | ||
| * @author Michael Schmidt - Initial contribution | ||
| */ | ||
| @NonNullByDefault | ||
| public class ApiException extends Exception { | ||
|
There was a problem hiding this comment. Please add |
||
|
|
||
| public ApiException(String message) { | ||
| super(message); | ||
| } | ||
|
|
||
| public ApiException(String message, Throwable cause) { | ||
| super(message, cause); | ||
| } | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| /** | ||
| * Copyright (c) 2010-2022 Contributors to the openHAB project | ||
| * | ||
| * See the NOTICE file(s) distributed with this work for additional | ||
| * information. | ||
| * | ||
| * This program and the accompanying materials are made available under the | ||
| * terms of the Eclipse Public License 2.0 which is available at | ||
| * http://www.eclipse.org/legal/epl-2.0 | ||
| * | ||
| * SPDX-License-Identifier: EPL-2.0 | ||
| */ | ||
| package org.openhab.binding.evnotify.api; | ||
|
|
||
| import org.eclipse.jdt.annotation.NonNullByDefault; | ||
| import org.eclipse.jdt.annotation.Nullable; | ||
|
|
||
| /** | ||
| * Represents version for the API of the evnotify online service. | ||
| * | ||
| * @author Michael Schmidt - Initial contribution | ||
| */ | ||
| @NonNullByDefault | ||
| public enum ApiVersion { | ||
|
|
||
| V2, | ||
| V3; | ||
|
|
||
| public static ApiVersion getApiVersion(@Nullable String searchVersion) { | ||
|
|
||
| for (ApiVersion version : ApiVersion.values()) { | ||
| if (version.name().equals(searchVersion)) { | ||
| return version; | ||
| } | ||
| } | ||
|
|
||
| throw new IllegalArgumentException(String.format("'%s' is not a valid version", searchVersion)); | ||
|
There was a problem hiding this comment. NullPointerException if searchVersion is null There was a problem hiding this comment. Give String.format("'%s' is not a valid version", null) a try |
||
| } | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| /** | ||
| * Copyright (c) 2010-2022 Contributors to the openHAB project | ||
| * | ||
| * See the NOTICE file(s) distributed with this work for additional | ||
| * information. | ||
| * | ||
| * This program and the accompanying materials are made available under the | ||
| * terms of the Eclipse Public License 2.0 which is available at | ||
| * http://www.eclipse.org/legal/epl-2.0 | ||
| * | ||
| * SPDX-License-Identifier: EPL-2.0 | ||
| */ | ||
| package org.openhab.binding.evnotify.api; | ||
|
|
||
| import java.time.OffsetDateTime; | ||
|
|
||
| import org.eclipse.jdt.annotation.NonNullByDefault; | ||
|
|
||
| /** | ||
| * Interface for the data from the API of the evnotify online service. | ||
| * | ||
| * @author Michael Schmidt - Initial contribution | ||
| */ | ||
| @NonNullByDefault | ||
| public interface ChargingData { | ||
|
There was a problem hiding this comment. Please add |
||
|
|
||
| Float getStateOfChargeDisplay(); | ||
|
|
||
| Float getStateOfChargeBms(); | ||
|
|
||
| OffsetDateTime getLastStateOfCharge(); | ||
|
|
||
| Boolean isCharging(); | ||
|
|
||
| Boolean isRapidChargePort(); | ||
|
|
||
| Boolean isNormalChargePort(); | ||
|
|
||
| Boolean isSlowChargePort(); | ||
|
|
||
| Float getStateOfHealth(); | ||
|
|
||
| Float getAuxBatteryVoltage(); | ||
|
|
||
| Float getDcBatteryVoltage(); | ||
|
|
||
| Float getDcBatteryCurrent(); | ||
|
|
||
| Float getDcBatteryPower(); | ||
|
|
||
| Float getCumulativeEnergyCharged(); | ||
|
|
||
| Float getCumulativeEnergyDischarged(); | ||
|
|
||
| Float getBatteryMinTemperature(); | ||
|
|
||
| Float getBatteryMaxTemperature(); | ||
|
|
||
| Float getBatteryInletTemperature(); | ||
|
|
||
| Float getExternalTemperature(); | ||
|
|
||
| OffsetDateTime getLastExtended(); | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| /** | ||
| * Copyright (c) 2010-2022 Contributors to the openHAB project | ||
| * | ||
| * See the NOTICE file(s) distributed with this work for additional | ||
| * information. | ||
| * | ||
| * This program and the accompanying materials are made available under the | ||
| * terms of the Eclipse Public License 2.0 which is available at | ||
| * http://www.eclipse.org/legal/epl-2.0 | ||
| * | ||
| * SPDX-License-Identifier: EPL-2.0 | ||
| */ | ||
| package org.openhab.binding.evnotify.api; | ||
|
|
||
| import java.io.IOException; | ||
|
|
||
| import org.eclipse.jdt.annotation.NonNullByDefault; | ||
|
|
||
| /** | ||
| * Interface for the client to get data from the API of the evnotify online service. | ||
| * | ||
| * @author Michael Schmidt - Initial contribution | ||
| */ | ||
| @NonNullByDefault | ||
| public interface EVNotifyClient { | ||
|
There was a problem hiding this comment. Please add |
||
|
|
||
| /** | ||
| * returns a {@link ChargingData} | ||
| * | ||
| * @return state of a car | ||
| */ | ||
| ChargingData getCarChargingData() throws IOException, InterruptedException, ApiException; | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| /** | ||
| * Copyright (c) 2010-2022 Contributors to the openHAB project | ||
| * | ||
| * See the NOTICE file(s) distributed with this work for additional | ||
| * information. | ||
| * | ||
| * This program and the accompanying materials are made available under the | ||
| * terms of the Eclipse Public License 2.0 which is available at | ||
| * http://www.eclipse.org/legal/epl-2.0 | ||
| * | ||
| * SPDX-License-Identifier: EPL-2.0 | ||
| */ | ||
| package org.openhab.binding.evnotify.api.v2; | ||
|
|
||
| import java.time.Instant; | ||
| import java.time.OffsetDateTime; | ||
| import java.time.ZoneId; | ||
|
|
||
| import com.google.gson.annotations.SerializedName; | ||
|
|
||
| /** | ||
| * Represents the basic data that is returned by evnotify v2 API. | ||
| * | ||
| * e.g. | ||
| * | ||
| * { | ||
| * "soc_display": 93, | ||
| * "soc_bms": 88.5, | ||
| * "last_soc": 1631220014 | ||
| * } | ||
| * | ||
| * @author Michael Schmidt - Initial contribution | ||
| */ | ||
| public class BasicChargingDataDTO { | ||
|
There was a problem hiding this comment. Please add |
||
|
|
||
| @SerializedName("soc_display") | ||
| public Float stateOfChargeDisplay; | ||
|
|
||
| @SerializedName("soc_bms") | ||
| public Float stateOfChargeBms; | ||
|
|
||
| @SerializedName("last_soc") | ||
| public Integer lastStateOfCharge; | ||
|
|
||
| public Float getStateOfChargeDisplay() { | ||
| return stateOfChargeDisplay; | ||
| } | ||
|
|
||
| public Float getStateOfChargeBms() { | ||
| return stateOfChargeBms; | ||
| } | ||
|
|
||
| public OffsetDateTime getLastStateOfCharge() { | ||
| return lastStateOfCharge == null ? null | ||
| : OffsetDateTime.from(Instant.ofEpochSecond(lastStateOfCharge).atZone(ZoneId.systemDefault())); | ||
| } | ||
| } | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If the channel is a timestamps, the item type is not the good one.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same as above: Just reused terminology of the ev notify service.