This page is part of archived documentation for openHAB 4.1. 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 to ON 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 and callbackUrl
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 by account 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.

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← MELCloud Meteo Alerte →