Python service that listens to HomeConnect event and logs them.
Project description
homeconnect-watcher
Python service that listens to HomeConnect event and logs them.
Usage
Before you start, create a developer account at https://developer.home-connect.com/ and
register an application with the "Authorization Code Grant Flow" as OAuth Flow
and http://localhost:8000/code/
as redirect URL.
Next, set the following environment variables with the values of your application:
HOMECONNECT_CLIENT_ID
HOMECONNECT_CLIENT_SECRET
HOMECONNECT_REDIRECT_URI
Authorization
The watcher requires a token, which will be automatically refreshed once obtained. To obtain the first token run
homeconnect-watcher authorize
and follow the instructions.
If the watcher is used regularly, this only needs to be done once.
Watching
Next up, run
homeconnect-watcher watch
Exposing Metrics to Prometheus
The watcher can expose its metrics to Prometheus. This requires the prometheus-client
to be installed;
pip install "homeconnect-watcher[prometheus]"
Then, when starting the watcher, pass the port you want to expose the metrics to. For example:
homeconnect-watcher watch --metrics-port 8000
Events
Events are received as multi-line byte-strings, and always end with a double newline (\n\n
). They (may) contain the
following keys:
- event: Event type. One of the types listed below.
- data: Contains a JSON dictionary. For Keep-Alive events, this field is present, but empty.
- id: Contains the appliance id. For Keep-Alive events, this field is missing.
Events come in the following flavours:
Keep-Alive
Periodic keep-alive message (interval: every 55 seconds)
event:KEEP-ALIVE
data:
Status
Status changes (e.g. "DoorState")
event:STATUS
data:{"haId":"SIEMENS-WM14T6H9NL-AB1234567890","items":[{"handling":"none","key":"BSH.Common.Status.LocalControlActive","level":"hint","timestamp":1676897835,"uri":"/api/homeappliances/SIEMENS-WM14T6H9NL-AB1234567890/status/BSH.Common.Status.LocalControlActive","value":true},{"handling":"none","key":"BSH.Common.Status.RemoteControlActive","level":"hint","timestamp":1676897835,"uri":"/api/homeappliances/SIEMENS-WM14T6H9NL-AB1234567890/status/BSH.Common.Status.RemoteControlActive","value":false}]}
id:SIEMENS-WM14T6H9NL-AB1234567890
Event
Event (e.g. "Preheat finished")
event:EVENT
data:{"items":[{"timestamp":1642001123,"handling":"none","key":"BSH.Common.Event.ProgramFinished","value":"BSH.Common.EnumType.EventPresentState.Present","level":"hint"}],"haId":"SIEMENS-WM14T6H9NL-AB1234567890"}
id:SIEMENS-WM14T6H9NL-AB1234567890
Notify
Value changes
event:NOTIFY
data:{"haId":"SIEMENS-WM14T6H9NL-AB1234567890","items":[{"handling":"none","key":"BSH.Common.Root.SelectedProgram","level":"hint","timestamp":1676897836,"uri":"/api/homeappliances/SIEMENS-WM14T6H9NL-AB1234567890/programs/selected","value":"LaundryCare.Washer.Program.DelicatesSilk"}]}
id:SIEMENS-WM14T6H9NL-AB1234567890
Connected
Connection to home appliance re-established
event:CONNECTED
data:{"haId":"SIEMENS-WT8HXM90NL-AB1234567890","handling":"none","key":"BSH.Common.Appliance.Connected","level":"hint","timestamp":1676897865,"value":true}
id:SIEMENS-WT8HXM90NL-AB1234567890
Disconnected
Connection to home appliance lost or not possible
event:DISCONNECTED
data:{"haId":"SIEMENS-WM14T6H9NL-AB1234567890","handling":"none","key":"BSH.Common.Appliance.Disconnected","level":"hint","timestamp":1676897981,"value":true}
id:SIEMENS-WM14T6H9NL-AB1234567890
Paired
New home appliance was added to HC account, this appliance can be directly monitored with an open event stream
TODO: add example
Depaired
Existing home appliance was removed, monitoring of this appliance is no longer possible
TODO: add example
Requests
We can make three kinds of requests to an appliance. These return a payload with one of the following keys:
- "data", containing a dictionary with the result, or
- "error", in case something went wrong.
Status
Status information
{
"data": {
"status": [
{
"key": "BSH.Common.Status.RemoteControlActive",
"value": true
},
{
"key": "BSH.Common.Status.RemoteControlStartAllowed",
"value": false
},
{
"key": "BSH.Common.Status.OperationState",
"value": "BSH.Common.EnumType.OperationState.Run"
},
{
"key": "BSH.Common.Status.DoorState",
"value": "BSH.Common.EnumType.DoorState.Closed"
}
]
}
}
Settings
Settings information
{
"data": {
"settings": [
{
"key": "BSH.Common.Setting.PowerState",
"value": "BSH.Common.EnumType.PowerState.On"
}
]
}
}
Programs Active
{
"data": {
"key": "LaundryCare.Dryer.Program.Cotton",
"options": [
{
"key": "LaundryCare.Dryer.Option.DryingTarget",
"value": "LaundryCare.Dryer.EnumType.DryingTarget.CupboardDry",
"unit": "enum"
},
{
"key": "BSH.Common.Option.ProgramProgress",
"value": 3,
"unit": "%"
},
{
"key": "BSH.Common.Option.RemainingProgramTime",
"value": 348,
"unit": "seconds"
},
{
"key": "BSH.Common.Option.ElapsedProgramTime",
"value": 12,
"unit": "seconds"
},
{
"key": "BSH.Common.Option.Duration",
"value": 360,
"unit": "seconds"
}
]
}
}
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for homeconnect_watcher-0.0.12.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8e72a5ee6afe143fce0b0a4a5ea790c68b1af37e617ba0bd8280d4d433bdf966 |
|
MD5 | e9800a15191cbac65c94d308c99e9487 |
|
BLAKE2b-256 | 257aeacc2940abbc967cd92f3cc0011836b3d1eecc8949931ed9765eae8345a6 |
Hashes for homeconnect_watcher-0.0.12-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bd526d0ed4429d2a067e88e50b3dd0de9a928b4de7396842fe9ac680ce8ca0d5 |
|
MD5 | e4efab8fd42a6b3063c412017f148c77 |
|
BLAKE2b-256 | 9eda2b6ff43d4b3dc6243d07e0cf7eba0cec362214e1237a1e44589050986a9b |