Skip to content

Commit

Permalink
[mybmw] Upgrade to new BMW API (openhab#14452)
Browse files Browse the repository at this point in the history 
* [mybmw] fix not working binding due to API update

to make it work the code has been refactored and due to API changes some
improvements could be made. These include:
- (improvement) fingerprint generation: You can
  take a look at the README how to create a
  fingerprint more conveniently.
- (change) changed channel: charge-info has been
  renamed to charge-remaining
- (improvement) added channels:
  estimated-fuel-l-100km and estimated-fuel-mpg
  which calculates the estimated fuel consumption
  based on the range and remaining fuel liters
  - unfortunately such a calculation is not available
  for EVs as there is no information about the capacity of the battery.
- (improvement) added channel last-fetched:
  the last-updated timestamp is showing by when
  the last update of the vehicle happened. As right
  now you can not see from the channels if a thing
  is offline due to connection issues, you can check
  now if last-fetched is more than 5 minutes ago to identify an issue
- (fixed) remote command typos fixed

Fixes openhab#14065

Also-by: Mark Herwege <[email protected]>
Signed-off-by: Martin Grassl <[email protected]>
Signed-off-by: Jørgen Austvik <[email protected]>
  • Loading branch information
@martingrassl @austvik
martingrassl authored and austvik committed Mar 27, 2024
1 parent 86fd59d commit 245825d
Show file tree
Hide file tree
Showing 223 changed files with 12,384 additions and 14,633 deletions.
2 changes: 1 addition & 1 deletion CODEOWNERS
View file
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -226,7 +226,7 @@
/bundles/org.openhab.binding.mqtt.homie/ @ccutrer
/bundles/org.openhab.binding.mqtt.ruuvigateway/ @ssalonen
/bundles/org.openhab.binding.mycroft/ @dalgwen
/bundles/org.openhab.binding.mybmw/ @weymann @ntruchsess
/bundles/org.openhab.binding.mybmw/ @ntruchsess @mherwege @martingrassl
/bundles/org.openhab.binding.mynice/ @clinique
/bundles/org.openhab.binding.mystrom/ @pail23
/bundles/org.openhab.binding.nanoleaf/ @stefan-hoehn
Expand Down
71 changes: 39 additions & 32 deletions bundles/org.openhab.binding.mybmw/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -163,9 +163,9 @@ Reflects overall status of the vehicle.
| Check Control | check-control | String | Presence of active warning messages | X | X | X | X |
| Plug Connection Status | plug-connection | String | Plug is _Connected_ or _Not connected_ | | X | X | X |
| Charging Status | charge | String | Current charging status | | X | X | X |
| Charging Information | charge-info | String | Information regarding current charging session | | X | X | X |
| Motion Status | motion | Switch | Driving state - depends on vehicle hardware | X | X | X | X |
| Remaining Charging Time | charge-remaining | Number:Time | Remaining time for current charging session | | X | X | X |
| Last Status Timestamp | last-update | DateTime | Date and time of last status update | X | X | X | X |
| Last Fetched Timestamp | last-fetched | DateTime | Date and time of last time status fetched | X | X | X | X |

Overall Door Status values

Expand Down Expand Up @@ -239,17 +239,19 @@ See description [Range vs Range Radius](#range-vs-range-radius) to get more info
- Availability according to table
- Read-only values

| Channel Label | Channel ID | Type | conv | phev | bev_rex | bev |
|---------------------------|-------------------------|----------------------|------|------|---------|-----|
| Mileage | mileage | Number:Length | X | X | X | X |
| Fuel Range | range-fuel | Number:Length | X | X | X | |
| Electric Range | range-electric | Number:Length | | X | X | X |
| Hybrid Range | range-hybrid | Number:Length | | X | X | |
| Battery Charge Level | soc | Number:Dimensionless | | X | X | X |
| Remaining Fuel | remaining-fuel | Number:Volume | X | X | X | |
| Fuel Range Radius | range-radius-fuel | Number:Length | X | X | X | |
| Electric Range Radius | range-radius-electric | Number:Length | | X | X | X |
| Hybrid Range Radius | range-radius-hybrid | Number:Length | | X | X | |
| Channel Label | Channel ID | Type | conv | phev | bev_rex | bev |
|------------------------------------|----------------------------|----------------------|------|------|---------|-----|
| Mileage | mileage | Number:Length | X | X | X | X |
| Fuel Range | range-fuel | Number:Length | X | X | X | |
| Electric Range | range-electric | Number:Length | | X | X | X |
| Hybrid Range | range-hybrid | Number:Length | | X | X | |
| Battery Charge Level | soc | Number:Dimensionless | | X | X | X |
| Remaining Fuel | remaining-fuel | Number:Volume | X | X | X | |
| Estimated Fuel Consumption l/100km | estimated-fuel-l-100km | Number | X | X | X | |
| Estimated Fuel Consumption mpg | estimated-fuel-mpg | Number | X | X | X | |
| Fuel Range Radius | range-radius-fuel | Number:Length | X | X | X | |
| Electric Range Radius | range-radius-electric | Number:Length | | X | X | X |
| Hybrid Range Radius | range-radius-hybrid | Number:Length | | X | X | |

#### Doors Details

Expand Down Expand Up @@ -359,6 +361,7 @@ The channel _command_ provides options
- _horn-blow_
- _climate-now-start_
- _climate-now-stop_
- _charge-now_

The channel _state_ shows the progress of the command execution in the following order

Expand Down Expand Up @@ -471,10 +474,11 @@ Image representation of the vehicle.

Possible view ports:

- _VehicleStatus_ Front Side View
- _VehicleInfo_ Front View
- _ChargingHistory_ Side View
- _Default_ Front Side View
- _VehicleStatus_ Front Left Side View
- _FrontView_ Front View
- _FrontLeft_ Front Left Side View
- _FrontRight_ Front Right Side View
- _RearView_ Rear View

## Further Descriptions

Expand All @@ -491,7 +495,8 @@ There are 3 occurrences of dynamic data delivered
The channel id _name_ shows the first element as default.
All other possibilities are attached as options.
The picture on the right shows the _Session Title_ item and 3 possible options.
Select the desired service and the corresponding Charge Session with _Energy Charged_, _Session Status_ and _Session Issues_ will be shown.
Select the desired service and the corresponding Charge Session with _Energy Charged_, _Session Status_ and
_Session Issues_ will be shown.

### TroubleShooting

Expand All @@ -507,32 +512,34 @@ If these preconditions are fulfilled proceed with the fingerprint generation.

#### Generate Debug Fingerprint

<img align="right" src="./doc/DiscoveryScan.png" width="400" height="350"/>
Login to the openHAB console and use the `mybmw fingerprint` command.

First [enable debug logging](https://www.openhab.org/docs/administration/logging.html#defining-what-to-log) for the binding.
Fingerprint information on your account and vehicle(s) will show in the console and can be copiedfrom there.
A zip file with fingerprint information for your vehicle(s) will also be generated and put into the `mybmw` folder in the userdata folder.
This fingerprint information is valuable for the developers to better support your vehicle.

```shell
log:set DEBUG org.openhab.binding.mybmw
```
You can restrict the accounts and vehicles for the fingerprint generation.
Full syntax is available through the `mybmw help` console command.

The debug fingerprint is generated every time the discovery is executed.
To force a new fingerprint perform a _Scan_ for MyBMW things.
Personal data is eliminated from the log entries so it should be possible to share them in public.
Personal data is eliminated from fingerprints so it should be possible to share them in public.
Data like

- Vehicle Identification Number (VIN)
- Location data

are anonymized.
You'll find the fingerprint in the logs with the command
are anonymized in the JSON response and URL's.

```shell
grep "Discovery Fingerprint Data" openhab.log
```
After the corresponding fingerprint is generated please [follow the instructions to raise an issue](https://community.openhab.org/t/how-to-file-an-issue/68464) and attach the fingerprint!

After the corresponding fingerprint is generated please [follow the instructions to raise an issue](https://community.openhab.org/t/how-to-file-an-issue/68464) and attach the fingerprint data!
Your feedback is highly appreciated!

#### Debug Logging

You can [enable debug logging](https://www.openhab.org/docs/administration/logging.html#defining-what-to-log) to get more information on the behaviour of the binding.
The package.subpackage in this case would be "org.openhab.binding.mybmw".

As with fingerprint data, personal data is eliminated from logs.

### Range vs Range Radius

<img align="right" src="./doc/range-radius.png" width="400" height="350"/>
Expand Down
167 changes: 167 additions & 0 deletions bundles/org.openhab.binding.mybmw/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,171 @@

<name>openHAB Add-ons :: Bundles :: MyBMW Binding</name>

<profiles>
<profile>
<id>test-coverage</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<systemPropertyVariables>
<jacoco-agent.destfile>target/jacoco.exec</jacoco-agent.destfile>
</systemPropertyVariables>
</configuration>
</plugin>
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.8</version>
<executions>
<execution>
<id>default-instrument</id>
<goals>
<goal>instrument</goal>
</goals>
</execution>
<execution>
<id>default-restore-instrumented-classes</id>
<phase>test</phase>
<goals>
<goal>restore-instrumented-classes</goal>
</goals>
</execution>
<execution>
<id>default-report</id>
<phase>test</phase>
<goals>
<goal>report</goal>
</goals>
</execution>
<execution>
<id>default-check</id>
<goals>
<goal>check</goal>
</goals>
<configuration>
<rules>
<rule>
<element>BUNDLE</element>
<limits>
<limit>
<counter>INSTRUCTION</counter>
<value>COVEREDRATIO</value>
<minimum>0.20</minimum>
</limit>
<limit>
<counter>BRANCH</counter>
<value>COVEREDRATIO</value>
<minimum>0.20</minimum>
</limit>
</limits>
</rule>
</rules>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>

<dependencies>
<dependency>
<!-- must be on the classpath -->
<groupId>org.jacoco</groupId>
<artifactId>org.jacoco.agent</artifactId>
<classifier>runtime</classifier>
<version>0.8.8</version>
<scope>test</scope>
</dependency>
</dependencies>
</profile>
<profile>
<!--
If you activate this profile, the MyBmwProxyIT is executed which means real
backend requests. The test is only successful if you provide CONNECTED_USER and
CONNECTED_PASSWORD as environment variable of the Maven command.
-->
<id>integration-tests</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>3.0.0-M7</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
<profile>
<!--
This profile generates a jar file <regular-jar-file-name>-testenv.jar in the target folder. This
testenv jar contains the regular classes and in addition all responses from
src/test/resources. If you copy this jar file to your addons folder, you can simulate all
accounts which are available as fingerprints in the responses folder. This can be done like
this:
1. start openhab with the environment variable "ENVIRONMENT=test"
2. configure the connected account with username "testuser"
3. configure as connected password the folder which you want to test, e.g. "BEV", "BEV2", "PHEV", "ICE", "ICE2",
"MILD_HYBRID"
after that you should get the vehicles loaded properly so you can check if the channels are populated with data properly.
-->
<id>test-jar</id>
<build>
<plugins>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.3.0</version>
<executions>
<execution>
<id>copy-resources</id>
<!-- here the phase you need -->
<phase>package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${basedir}/target/classes</outputDirectory>
<resources>
<resource>
<directory>src/test/resources</directory>
<filtering>true</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.3.0</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<classifier>testenv</classifier>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>
5 changes: 3 additions & 2 deletions ...ng/mybmw/internal/MyBMWConfiguration.java → ...mw/internal/MyBMWBridgeConfiguration.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,13 @@
import org.openhab.binding.mybmw.internal.utils.Constants;

/**
* The {@link MyBMWConfiguration} class contains fields mapping thing configuration parameters.
* The {@link MyBMWBridgeConfiguration} class contains fields mapping thing configuration parameters.
*
* @author Bernd Weymann - Initial contribution
* @author Martin Grassl - renamed
*/
@NonNullByDefault
public class MyBMWConfiguration {
public class MyBMWBridgeConfiguration {

/**
* Depending on the location the correct server needs to be called
Expand Down
Loading

0 comments on commit 245825d

Please sign in to comment.