This page is part of archived documentation for openHAB 4.0. Go to the current stable version
# MercedesMe Binding
This binding provides similar access to your Mercedes Benz vehicle like the Smartphone App Mercedes Me. For this you need a Mercedes developer account to get data from your vehicles. Setup requires some, time so follow the steps of bridge configuration.
If you face some problems during setup or runtime please have a look into the Troubleshooting section
# Supported Things
Type | ID | Description |
---|---|---|
Bridge | account | Connect your Mercedes Me account |
Thing | combustion | Conventional fuel vehicle |
Thing | hybrid | Fuel vehicle with supporting electric engine |
Thing | bev | Battery electric vehicle |
# Bridge Configuration
Bridge needs configuration in order to connect properly to your Mercedes Me Account.
# Pre-Conditions
- each bridge shall have its own Mercedes Benz Client ID!
Don't create several
account
bridges with the same client id! If this is not the case the tokens won't be stored properly and the authorization is jeopardized! - each bridge shall have its own port.
It's absolutely necessary to assign a different port for each
account
bridge. If this is not the case the tokens won't be stored properly and the authorization is jeopardized!
# Bridge Setup
Perform the following steps to obtain the configuration data and perform the authorization flow.
- Go to Mercedes Developer Page (opens new window). Login with your Mercedes Me credentials.
- Create a project in the console tab (opens new window)
- Project Name: unique name e.g. openHAB Mercedes Me binding plus Your bridge ID
- Purpose URL: use link towards this binding description (opens new window)
- Business Purpose: e.g. Private usage in openHAB Smarthome system
- After project is created subscribe to these Mercedes Benz APIs (opens new window) with Add Products button
- For all Products perform the same steps
- Select product
- Choose Get For Free
- Choose BYOCAR (Build Your Own Car)
- Button Confirm
- Select the following products
- Vehicle Status
- Vehicle Lock Status
- Pay as you drive insurance
- Electric Vehicle Status
- Fuel Status
- Optional: Subscribe also to Vehicle images. Select the Basic Trial version. The images will be stored so the API is used just a few times.
- Press Subscribe button. Your project should have these product subscriptions
- Generate the project credentials
- Open in new browser tab your openHAB page. Add a new Thing Mercedes Me Account
- Copy paste Client ID , Client Secret and API Key from the Mercedes tab into the openHAB configuration
- Check if the registered Mercedes products excluding Vehicle Images are matching exactly with the openHab configuration switches
- Create Thing!
- The fresh created account has one property
callbackUrl
. Copy it and paste it in a new browser tab - A simple HTML page is shown including a link towards the Authorization flow - don't click yet. If page isn't shown please adapt IP and port in openHAB configuration with Advanced Options activated
- The copied URL needs to be added in your Mercedes project credentials from 8
- Now click onto the link from 14. You'll be asked one time if you grant access towards the API. Click OK and authorization is done!
Some supporting screenshots for the setup
# MB Credentials
# MB Product Subscriptions
# openHAB Configuration
# MB Access Request
# Callback page
# Bridge Configuration Parameters
Name | Type | Description | Default | Required | Advanced |
---|---|---|---|---|---|
clientId | text | Mercedes Benz Developer Client ID | N/A | yes | no |
clientSecret | text | Mercedes Benz Developer Client Secret | N/A | yes | no |
imageApiKey | text | Mercedes Benz Developer Image API Key | N/A | no | no |
odoScope | boolean | PayAsYourDrive Insurance | true | yes | no |
vehicleScope | boolean | Vehicle Status | true | yes | no |
lockScope | boolean | Lock status of doors and trunk | true | yes | no |
fuelScope | boolean | Fuel Status | true | yes | no |
evScope | boolean | Electric Vehicle Status | true | yes | no |
callbackIP | text | IP address of your openHAB server | auto detect | no | yes |
callbackPort | integer | Unique port number | auto detect | no | yes |
The callbackPort
needs to be unique for all created Mercedes Me account things. Otherwise token exchange will be corrupted.
Set the advanced options by yourself if you know your IP and Port, otherwise give auto detect a try.
# Thing Configuration
For vehicle images Mercedes Benz Developer offers only a trial version with limited calls.
Check in beforehand if your vehicle has some restrictions or even if it's supported at all.
Visit Vehicle Image Details (opens new window) in order to check your vehicle capabilities.
Visit Image Settings (opens new window) to get more information about
For example the EQA doesn't provide night
images with background
.
If your configuration is set this way the API calls are wasted!
See also image channel section for further advise.
Name | Type | Description | Default | Required | Advanced |
---|---|---|---|---|---|
vin | text | Vehicle identification number | N/A | yes | no |
refreshInterval | integer | Refresh interval in minutes | 5 | yes | no |
background | boolean | Vehicle images provided with or without background | false | no | yes |
night | boolean | Vehicle images in night conditions | false | no | yes |
cropped | boolean | Vehicle images in 4:3 instead of 16:9 | false | no | yes |
roofOpen | boolean | Vehicle images with open roof (only Cabriolet) | false | no | yes |
format | text | Vehicle images format (webp or png) | webp | no | yes |
For all vehicles you're free to give the tank / battery capacity. Giving these values in configuration the open fuel / charge capacities are reported in the range channels.
Name | Type | Description | Default | Required | Advanced | combustion | bev | hybrid |
---|---|---|---|---|---|---|---|---|
batteryCapacity | decimal | Battery Capacity | N/A | no | no | X | X | |
fuelCapacity | decimal | Fuel Capacity | N/A | no | no | X | X |
# Channels
Channels are separated in groups:
Channel Group ID | Description |
---|---|
range | Provides mileage, range and charge / fuel levels |
doors | Details of all doors |
windows | Current position of windows |
lights | Interior lights and main light switch |
lock | Overall lock state of vehicle |
location | Heading of the vehicle |
image | Images of your vehicle |
# Range
Group name: range
All channels read-only
Channel | Type | Description | bev | hybrid | combustion |
---|---|---|---|---|---|
mileage | Number:Length | Total mileage | X | X | X |
soc | Number:Dimensionless | Battery state of charge | X | X | |
charged | Number:Energy | Charged Battery Energy | X | X | |
uncharged | Number:Energy | Uncharged Battery Energy | X | X | |
soc | Number:Dimensionless | Battery state of charge | X | X | |
range-electric | Number:Length | Electric range | X | X | |
radius-electric | Number:Length | Electric radius for map | X | X | |
fuel-level | Number:Dimensionless | Fuel level in percent | X | X | |
fuel-remain | Number:Volume | Reamaining Fuel | X | X | |
fuel-open | Number:Volume | Open Fuel Capacity | X | X | |
range-fuel | Number:Length | Fuel range | X | X | |
radius-fuel | Number:Length | Fuel radius for map | X | X | |
range-hybrid | Number:Length | Hybrid range | X | ||
radius-hybrid | Number:Length | Hybrid radius for map | X | ||
last-update | DateTime | Last range update | X | X | X |
Channels with radius
are just giving a guess which radius can be reached in a map display.
# Doors
Group name: doors
All channels read-only
Channel | Type | Description |
---|---|---|
driver-front | Contact | Driver door |
driver-rear | Contact | Driver door reat |
passenger-front | Contact | Passenger door |
passenger-rear | Contact | Passenger door rear |
deck-lid | Contact | Deck lid |
sunroof | Number | Sun roof (only Cabriolet) |
rooftop | Number | Roof top |
last-update | DateTime | Last doors update |
Mapping table sunroof
Number | Mapping |
---|---|
0 | Closed |
1 | Open |
2 | Open Lifting |
3 | Running |
4 | Closing |
5 | Opening |
6 | Closing |
Mapping table rootop
Number | Mapping |
---|---|
0 | Unlocked |
1 | Open and locked |
2 | Closed and locked |
# Windows
Group name: windows
All channels readonly
Channel | Type | Description |
---|---|---|
driver-front | Number | Driver window |
driver-rear | Number | Driver window rear |
passenger-front | Number | Passenger window |
passenger-rear | Number | Passenger window rear |
last-update | DateTime | Last windows update |
Mapping table for all windows
Number | Mapping |
---|---|
0 | Intermediate |
1 | Open |
2 | Closed |
3 | Airing |
4 | Intermediate |
5 | Running |
# Lights
Group name: lights
All channels read-only
Channel | Type | Description |
---|---|---|
interior-front | Switch | Interior light front |
interior-rear | Switch | Interior light rear |
reading-left | Switch | Reading light left |
reading-right | Switch | Reading light right |
light-switch | Number | Main light switch |
last-update | DateTime | Last lights update |
Mapping table light-switch
Number | Mapping |
---|---|
0 | Auto |
1 | Headlight |
2 | Sidelight Left |
3 | Sidelight Right |
4 | Parking Light |
# Lock
Group name: lock
All channels read-only
Channel | Type | Description |
---|---|---|
doors | Number | Lock status all doors |
deck-lid | Switch | Deck lid lock |
flap | Switch | Flap lock |
last-update | DateTime | Last lock update |
Mapping table doors
Number | Mapping |
---|---|
0 | Unlocked |
1 | Locked Internal |
2 | Locked External |
3 | Unlocked Selective |
# Location
Group name: location
All channels readonly
Channel | Type | Description |
---|---|---|
heading | Number:Angle | Vehicle heading |
last-update | DateTime | Last location update |
# Image
Provides exterior and interior images for your specific vehicle.
Group name: image
Channel | Type | Description | Write |
---|---|---|---|
image-data | Raw | Vehicle image | |
image-view | text | Vehicle image viewpoint | X |
clear-cache | Switch | Remove all stored images | X |
If the imageApiKey
in Bridge Configuration Parameters is set the vehicle thing will try to get images.
Pay attention to the Advanced Image Configuration Properties before requesting new images.
Sending commands towards the image-view
channel will change the image.
The image-view
is providing options to select the available images for your specific vehicle.
Images are stored in jsondb
so if you requested all images the Mercedes Benz Image API will not be called anymore which is good because you have a restricted amount of calls!
If you're not satisfied e.g. you want a background you need to
- change the Advanced Image Configuration Properties
- Switch
clear-cache
channel item toON
to clear all images - request them via
image-view
# Image View Options
You can access the options either in a rule via YOUR_IMAGE_VIEW_ITEM.getStateDescription().getOptions()
or in UI in widget configuration as Action: Command options and as Action Item: YOUR_IMAGE_VIEW_ITEM
# Troubleshooting
# Authorization fails
The configuration of openHAB account thing and the Mercedes Developer project need an extract match regarding
- MB project credentials vs.
clientId
clientSecret
andcallbackUrl
- MB project subscription of products vs.
scope
If you follow the bridge configuration steps both will match.
Otherwise you'll receive some error message when clicking the link after opening the callbackUrl
in your browser
Most common errors:
- redirect URL doesn't match: Double check if
callbackUrl
is really saved correctly in your Mercedes Benz Developer project - scope failure: the requested scope doesn't match with the subscribed products.
- Check openHab configuration switches
- apply changes if necessary and don't forget to save
- after these steps refresh the
callbackUrl
in your browser to apply these changes - try a new authorization clicking the link
# Receive no data
Especially after setting the frist Mercedes Benz Developer Project you'll receive no data. It seems that the API isn't filled yet.
# Pre-Condition
- The Mercedes Me bridge is online = authorization is fine
- The Mercedes Me thing is online = API calls are fine
# Solution
- Reduce
refreshInterval
to 1 minute - Go to your vehicle, open doors and windows, turn on lights, drive a bit ...
- wait until values are providing the right states
# Images
Testing the whole image settings is hard due to the restricted call number towards the Image API.
My personal experience during limited testing
Test | Tested | OK | Not OK | Comment |
---|---|---|---|---|
format webp | Yes | X | ||
format png | Yes | X | Internal Server Error 500 on Mercedes Server side | |
format jpeg | No | Not tested due to missing transparency in jpeg format | ||
all options off | Yes | X | ||
background | Yes | X | ||
night | No | Not support by my vehicle | ||
roofOpen | No | Not support by my vehicle | ||
cropped | No | Not desired from my side |
# Storage
Data is stored in directory %USER_DATA%/jsondb
for handling tokens and vehicle images.
- StorageHandler.For.OAuthClientService.json - token is stored with key
clientId
which is provided byaccount
Brige Configuration Parameters - mercedesme%VEHICLE_VIN%.json_ - images are stored per vehicle. File name contains
vin
configured by vehicle Thing Configuration
With this data the binding is able to operate without new authorization towards Mercedes each startup and reduces the restricted calls towards image API.
Also these files are properly stored in your backup (opens new window) e.g. if you perform openhab-cli backup
# Full example
The example is based on a battery electric vehicle. Exchange configuration parameters in the Things section
Bridge
- 4711 - your desired bridge id
- YOUR_CLIENT_ID - Client ID of the Mercedes Developer project
- YOUR_CLIENT_SECRET - Client Secret of the Mercedes Developer project
- YOUR_API_KEY - Image API Key of the Mercedes Developer project
- YOUR_OPENHAB_SERVER_IP - IP address of your openHAB server
- 8090 - a unique port number - each bridge in your openHAB installation needs to have different port number!
Thing
- eqa - your desired vehicle thing id
- VEHICLE_VIN - your Vehicle Identification Number
# Things file
Bridge mercedesme:account:4711 "MercedesMe John Doe" [ clientId="YOUR_CLIENT_ID", clientSecret="YOUR_CLIENT_SECRET", imageApiKey="YOUR_API_KEY", callbackIP="YOUR_OPENHAB_SERVER_IP", callbackPort=8092, odoScope=true, vehicleScope=true, lockScope=true, fuelScope=true, evScope=true] {
Thing bev eqa "Mercedes EQA" [ vin="VEHICLE_VIN", refreshInterval=5, background=false, night=false, cropped=false, roofOpen=false, format="webp"]
}
# Items file
Number:Length EQA_Mileage "Odometer [%d %unit%]" {channel="mercedesme:bev:4711:eqa:range#mileage" }
Number:Length EQA_Range "Range [%d %unit%]" {channel="mercedesme:bev:4711:eqa:range#range-electric"}
Number:Length EQA_RangeRadius "Range Radius [%d %unit%]" {channel="mercedesme:bev:4711:eqa:range#radius-electric"}
Number:Dimensionless EQA_BatterySoc "Battery Charge [%.1f %%]" {channel="mercedesme:bev:4711:eqa:range#soc"}
Contact EQA_DriverDoor "Driver Door [%s]" {channel="mercedesme:bev:4711:eqa:doors#driver-front" }
Contact EQA_DriverDoorRear "Driver Door Rear [%s]" {channel="mercedesme:bev:4711:eqa:doors#driver-rear" }
Contact EQA_PassengerDoor "Passenger Door [%s]" {channel="mercedesme:bev:4711:eqa:doors#passenger-front" }
Contact EQA_PassengerDoorRear "Passenger Door Rear [%s]" {channel="mercedesme:bev:4711:eqa:doors#passenger-rear" }
Number EQA_Trunk "Trunk [%s]" {channel="mercedesme:bev:4711:eqa:doors#deck-lid" }
Number EQA_Rooftop "Rooftop [%s]" {channel="mercedesme:bev:4711:eqa:doors#rooftop" }
Number EQA_Sunroof "Sunroof [%s]" {channel="mercedesme:bev:4711:eqa:doors#sunroof" }
Number EQA_DoorLock "Door Lock [%s]" {channel="mercedesme:bev:4711:eqa:lock#doors" }
Switch EQA_TrunkLock "Trunk Lock [%s]" {channel="mercedesme:bev:4711:eqa:lock#deck-lid" }
Switch EQA_FlapLock "Charge Flap Lock [%s]" {channel="mercedesme:bev:4711:eqa:lock#flap" }
Number EQA_DriverWindow "Driver Window [%s]" {channel="mercedesme:bev:4711:eqa:windows#driver-front" }
Number EQA_DriverWindowRear "Driver Window Rear [%s]" {channel="mercedesme:bev:4711:eqa:windows#driver-rear" }
Number EQA_PassengerWindow "Passenger Window [%s]" {channel="mercedesme:bev:4711:eqa:windows#passenger-front" }
Number EQA_PassengerWindowRear "Passenger Window Rear [%s]" {channel="mercedesme:bev:4711:eqa:windows#passenger-rear" }
Number:Angle EQA_Heading "Heading [%.1f %unit%]" {channel="mercedesme:bev:4711:eqa:location#heading" }
Image EQA_Image "Image" {channel="mercedesme:bev:4711:eqa:image#image-data" }
String EQA_ImageViewport "Image Viewport [%s]" {channel="mercedesme:bev:4711:eqa:image#image-view" }
Switch EQA_ClearCache "Clear Cache [%s]" {channel="mercedesme:bev:4711:eqa:image#clear-cache" }
Switch EQA_InteriorFront "Interior Front Light [%s]" {channel="mercedesme:bev:4711:eqa:lights#interior-front" }
Switch EQA_InteriorRear "Interior Rear Light [%s]" {channel="mercedesme:bev:4711:eqa:lights#interior-rear" }
Switch EQA_ReadingLeft "Reading Light Left [%s]" {channel="mercedesme:bev:4711:eqa:lights#reading-left" }
Switch EQA_ReadingRight "Reading Light Right [%s]" {channel="mercedesme:bev:4711:eqa:lights#reading-right" }
Number EQA_LightSwitch "Main Light Switch [%s]" {channel="mercedesme:bev:4711:eqa:lights#light-switch" }
# Sitemap
sitemap MB label="Mercedes Benz EQA" {
Frame label="EQA Image" {
Image item=EQA_Image
}
Frame label="Range" {
Text item=EQA_Mileage
Text item=EQA_Range
Text item=EQA_RangeRadius
Text item=EQA_BatterySoc
}
Frame label="Door Details" {
Text item=EQA_DriverDoor
Text item=EQA_DriverDoorRear
Text item=EQA_PassengerDoor
Text item=EQA_PassengerDoorRear
Text item=EQA_Trunk
Text item=EQA_Rooftop
Text item=EQA_Sunroof
Text item=EQA_DoorLock
Text item=EQA_TrunkLock
Text item=EQA_FlapLock
}
Frame label="Windows" {
Text item=EQA_DriverWindow
Text item=EQA_DriverWindowRear
Text item=EQA_PassengerWindow
Text item=EQA_PassengerWindowRear
}
Frame label="Location" {
Text item=EQA_Heading
}
Frame label="Lights" {
Text item=EQA_InteriorFront
Text item=EQA_InteriorRear
Text item=EQA_ReadingLeft
Text item=EQA_ReadingRight
Text item=EQA_LightSwitch
}
Frame label="Image Properties" {
Selection item=EQA_ImageViewport
Switch item=EQA_ClearCache
}
}
# Mercedes Benz Developer
Visit Mercedes Benz Developer (opens new window) to gain more deep information.
← MELCloud Meteo Alerte →