Looking for an easy enough way to call and consume the Home Connect API from OH, I created a proxy application running in docker, and allowing to call the APIs without need to take care for auth headers and access token refresh.
Whilst it needs to be used with caution (e.g. in isolated sub-net etc.), it also makes it quite easy to automate stuff in openHAB.
The proxy also features MQTT publishing of Home Connect SSE event stream which is very useful to monitor appliance status changes, updates etc.
Source code with instructions to build and basic documentation is available at https://github.com/ananchev/homeconnect-proxy
One of my OH implementations is for managing my kitchen hood defined as generic MQTT thing with channels for power control, fan speed and work light.
Commands
Commands to the linked items are processed in rules, where the necessary API calls to the proxy are executed. The proxy on its turn handles the authentication and makes the requests to the Home Connect API.
Here example of such a rule written in ruby:
rule 'Toggle operation state' do
received_command Hood_Power, commands: ["ON","OFF"]
run do |event|
logger.info("Hood received command: #{event.command}" )
uri = "http://<proxy_uri:port>/homeappliances/<appliance_id>/programs/active"
# turn on the device
if event.command == ON
payload = {
data: {
key: "Cooking.Common.Program.Hood.Venting",
options: [
{
key: "Cooking.Common.Option.Hood.VentingLevel",
value: "Cooking.Hood.EnumType.Stage.FanStage02"
}
]
}
}
response = REST.put(uri, JSON.generate(payload), 'Accept' => '*/*', 'Content-Type' => 'application/json')
# turn off the device
else
response = REST.delete(uri, 'Accept' => '*/*', 'Content-Type' => 'application/json')
end
end
end
Status updates
For item status updates, the proxy MQTT publishing is used, which basically publishes all SSE events streamed by Home Connect.
This way the respective items are updated both when commands to the appliance are executed from OH, and from outside - e.g. on the appliance itself, or via the Home Connect mobile application.
Publishing is to by default to topic hc-proxy/<appliance_id>/<sse_event>, where <appliance_id> is the is the primary access key of the device (see API Documentation | Home Connect Developer Program), and <sse_event> the event type (see https://api-docs.home-connect.com/events). All events for all linked to the Home Connect account appliances are published by the proxy to the broker, but obviously we can selectively configure the OH thing channels with the ones we are interested into.
Back to the hood power ON/OFF example, the mqtt state topic configured in the channel is hc-proxy/<appliance_id>/NOTIFY.
The payload for power ON status is
{
"items":[
{
"timestamp":1644622286,
"handling":"none",
"uri":"/api/homeappliances/<appliance_id>/status/BSH.Common.Status.OperationState",
"key":"BSH.Common.Status.OperationState",
"value":"BSH.Common.EnumType.OperationState.Run",
"level":"hint"
}
],
"haId":"<appliance_id>"
}
and for power OFF
{
"items":[
{
"timestamp":1644622310,
"handling":"none",
"uri":"/api/homeappliances/<appliance_id>/settings/BSH.Common.Setting.PowerState",
"key":"BSH.Common.Setting.PowerState",
"value":"BSH.Common.EnumType.PowerState.Off",
"level":"hint"
}
],
"haId":"<appliance_id>"
}
Using JSONPATH incoming value transformation at channel level as JSONPATH:$.items[0].value with custom ON (BSH.Common.EnumType.OperationState.Run) and OFF (BSH.Common.EnumType.PowerState.Off) values appliance status updates can then be mapped back to the item state.
This is probably a too simple example, but using the API interactive portal at https://apiclient.home-connect.com, and the documentation https://api-docs.home-connect.com quite more can be achieved with relatively minor effort.