Search Results
Found 0 result(s) for ""
Search results are affected by your filter settings.
This page does NOT support Internet Explorer. Please use a modern browser like e.g. Google Chrome, Mozilla Firefox or Microsoft Edge.
The Home Connect APICopied link to clipboard
This API provides access to home appliances connected to Home Connect. Developers can use the Home Connect API to monitor and control these appliances. For instance, you could turn on your coffee machine and make your favorite cup of coffee. The following Quickstart guide will help you get started with exactly that.
Simulator vs. Home Connect API
"But how can I test my application?" you're asking. Of course you can use your very own Home Connect home appliance, with the actual Home Connect API, if you own one. In case you don't, we also provide a virtual environment with simulated appliances. This allows you to jump-start your development and test your applications. Please note that some of the actions you are able to perform on the simulators are not possible through the real API. One example of this is opening/closing doors. You can find the simulators here.
Using the simulator
Host
Using the real API
Host
https:/
AuthorizationCopied link to clipboard
For your application to interact with home appliances it needs to get authorized by the API. We will guide you through the steps required to complete the OAuth 2.0 Authorization Code Grant Flow process. Successful authorization will result in the API responding with a JSON Web Token.
Step 1: Get the Client ID
To get started, visit the Home Connect Developer Portal and register an account. After registration please access the application overview page. Here you can find all your applications, including a predefined one called API Web Client.
Step 2: Authorization URL and Response
Next, call the authorize endpoint. Easiest way to do this is to copy the URL into your browser.
When prompted, log in with your Home Connect Account and grant access. The API will respond with a HTTP 302 redirect to the defined redirect_uri. A request parameter in this response will contain the authorization code.
Response
https://example.com/?code=eyJ4LWVudiI6IlBSRCIsImFsZyI6IlJTMjU2IiwieC1yZWciOiJFVSIsImtpZCI6IlMxIn&grant_type=authorization_codeStep 3: Retrieve Token
Call the token endpoint including the authorization code obtained in previous step:
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id={client_id}" \
--data-urlencode "redirect_uri={redirect_uri}" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code={code}"
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id={client_id}" \
--data-urlencode "client_secret={client_secret}" \
--data-urlencode "redirect_uri={redirect_uri}" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code={code}"
Response
Expand source{
"access_token": "eyJ4LWVudiI6IlBSRCIsImFsZyI6IlJTMjU2IiwieC1yZWciOiJFVSIsImtpZCI6IlMxIn0....",
"token_type": "Bearer",
"refresh_token": "eyJ4LXJlZyI6IkVVIiwieC1lbnYiOiJQUkQiLCJ0b2tlbiI6IjU4Y2QwMDkxLWM2N...",
"expires_in": 86400,
"id_token": "eyJ4LWVudiI6IlBSRCIsImFsZyI6IlJTMjU2IiwieC1yZWciOiJFVSIsImtpZCI6IlMxIn0...."
}Conclusion
You should now have a valid access token which enables you to use the API!
For more detailed information about the authorization process visit the dedicated page.
MonitoringCopied link to clipboard
There are a few common use cases when developing an application with the Home Connect API. Displaying live status information of home appliances is one of them. Let's find out how to do that.
Step 1: Choose an Appliance to Use
To identify our home appliances, let us first request a list of all currently paired devices:
-H "Authorization: Bearer {access_token}"
-H "Authorization: Bearer {access_token}"
Every home appliance has a unique id, a haId, which we can see in the response from the API. For next calls, make sure to replace {haId} placeholders with the one of your chosen appliance.
Response
Expand source{
"data": {
"homeappliances": [
{
"name": "Washer Simulator",
"brand": "SIEMENS",
"vib": "HCS03WCH1",
"connected": true,
"type": "Washer",
"enumber": "HCS03WCH1/03",
"haId": "SIEMENS-HCS03WCH1-456227783F78"
},
{
"name": "CoffeeMaker Simulator",
"brand": "BOSCH",
"vib": "HCS06COM1",
"connected": true,
"type": "CoffeeMaker",
"enumber": "HCS06COM1/03",
"haId": "BOSCH-HCS06COM1-1AE725ADAF8A"
},
{
"name": "Dryer Simulator",
"brand": "BOSCH",
"vib": "HCS04DYR1",
"connected": true,
"type": "Dryer",
"enumber": "HCS04DYR1/03",
"haId": "BOSCH-HCS04DYR1-C80B414A484B"
},
{
"name": "Oven Simulator",
"brand": "BOSCH",
"vib": "HCS01OVN1",
"connected": true,
"type": "Oven",
"enumber": "HCS01OVN1/03",
"haId": "BOSCH-HCS01OVN1-42DAD1C2D097"
},
{
"name": "Dishwaser Simulator",
"brand": "SIEMENS",
"vib": "HCS02DWH1",
"connected": true,
"type": "Dishwasher",
"enumber": "HCS02DWH1/03",
"haId": "SIEMENS-HCS02DWH1-2A710AA487A0"
},
{
"name": "FridgeFreezer Simulator",
"brand": "SIEMENS",
"vib": "HCS05FRF1",
"connected": true,
"type": "FridgeFreezer",
"enumber": "HCS05FRF1/03",
"haId": "SIEMENS-HCS05FRF1-35EF7A5B52E2"
}
]
}
}Step 2: Retrieve the Operation State
-H "Authorization: Bearer {access_token}"
-H "Authorization: Bearer {access_token}"
As simple as that, you can retrieve the current operation state of your home appliance. You can read more about status information on the states page.
Response
{
"data": {
"key": "BSH.Common.Status.OperationState",
"value": "BSH.Common.EnumType.OperationState.Ready"
}
}ControllingCopied link to clipboard
Monitoring your home appliances is pretty neat. What's even more neat though is being able to control it. So to conclude the Quickstart, we're going to find out how to toggle our home appliances on/off and start a program.
Step 1: Turn On
The power state setting of a home appliance is what tells you whether the appliance is on or off. In general, you will be able to write this setting to toggle it. Some appliances don't have that capability. For more detailed information on which appliances do, visit the power state page.
A response of 204 - No Content is a sign the operation was successful. In that case your coffee machine should turn on and start rinsing.
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/vnd.bsh.sdk.v1+json" \
--data-raw '{
"data": {
"key": "BSH.Common.Setting.PowerState",
"value": "BSH.Common.EnumType.PowerState.On"
}
}'
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/vnd.bsh.sdk.v1+json" \
--data-raw '{
"data": {
"key": "BSH.Common.Setting.PowerState",
"value": "BSH.Common.EnumType.PowerState.On"
}
}'
Step 2: Start Program
And finally we will instruct the coffee machine to make 35ml of strong Espresso. You can find the coffee machine programs and options in detail here.
Once again, a response of 204 - No Content means it worked. Go to your coffee machine to find yourself a freshly brewed Espresso
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/vnd.bsh.sdk.v1+json" \
--data-raw '{
"data": {
"key": "ConsumerProducts.CoffeeMaker.Program.Beverage.Espresso",
"options": [
{
"key": "ConsumerProducts.CoffeeMaker.Option.BeanAmount",
"value": "ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.Strong"
},
{
"key": "ConsumerProducts.CoffeeMaker.Option.FillQuantity",
"value": 35
}
]
}
}'
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/vnd.bsh.sdk.v1+json" \
--data-raw '{
"data": {
"key": "ConsumerProducts.CoffeeMaker.Program.Beverage.Espresso",
"options": [
{
"key": "ConsumerProducts.CoffeeMaker.Option.BeanAmount",
"value": "ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.Strong"
},
{
"key": "ConsumerProducts.CoffeeMaker.Option.FillQuantity",
"value": 35
}
]
}
}'
Conclusion
Congrats on making it to the end of the Quickstart. You now know the basics of the Home Connect API and we cannot wait to see what new applications you're coming up with!