| 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.
1. Go to [Mercedes Developer Page](https://developer.mercedes-benz.com/). Login with your Mercedes Me credentials.
2. Create a project in the [console tab](https://developer.mercedes-benz.com/console)
- _Project Name:_ unique name e.g. **openHAB Mercedes Me binding** plus **Your bridge ID**
- _Purpose URL:_ use link towards [this binding description](https://www.openhab.org/addons/bindings/mercedesme/)
- _Business Purpose:_ e.g. **Private usage in openHAB Smarthome system**
3. After project is created subscribe [to these Mercedes Benz APIs](https://developer.mercedes-benz.com/products?vt=cars&vt=vans&vt=smart&p=BYOCAR) with _Add Products_ button
4. For all Products perform the same steps
- Select product
- Choose _Get For Free_
- Choose _BYOCAR_ (Build Your Own Car)
- Button _Confirm_
5. Select the following products
- Vehicle Status
- Vehicle Lock Status
- Pay as you drive insurance
- Electric Vehicle Status
- Fuel Status
6. 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.
7. Press _Subscribe_ button. Your project should have [these product subscriptions](#mb-product-subscriptions)
8. Generate the [project credentials](#mb-credentials)
9. Open in new browser tab your openHAB page. Add a new Thing _Mercedes Me Account_
10. Copy paste _Client ID_ , _Client Secret_ and _API Key_ from the Mercedes tab into the openHAB configuration
11. Check if the registered Mercedes products _excluding Vehicle Images_ are matching exactly with the openHab configuration switches
12. Create Thing!
13. The fresh created [account has one property](#openhab-configuration) `callbackUrl`. Copy it and paste it in a new browser tab
14. A [simple HTML page is shown including a link towards the Authorization flow](#callback-page) - **don't click yet**. If page isn't shown please adapt IP and port in openHAB configuration with Advanced Options activated
15. The copied URL needs to be added in your [Mercedes project credentials](#mb-credentials) from 8
16. Now click onto the link from 14. You'll be asked one time if you [grant access](#mb-access-request) towards the API. Click OK and authorization is done!
| image-view | text | Vehicle image viewpoint | X |
| clear-cache | Switch | Remove all stored images | X |
**If** the `imageApiKey` in [Bridge Configuration Parameters](#bridge-configuration-parameters) is set the vehicle thing will try to get images.
Pay attention to the [Advanced Image Configuration Properties](#thing-configuration) 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
1. change the [Advanced Image Configuration Properties](#thing-configuration)
2. Switch `clear-cache` channel item to `ON` to clear all images
3. 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_
| `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](#bridge-configuration-parameters)
* _mercedesme_%VEHICLE_VIN%.json_ - images are stored per vehicle. File name contains `vin` configured by [vehicle Thing Configuration](#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](https://community.openhab.org/t/docs-on-how-to-backup-openhab/100182) 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
