Reason for new integration

[mundschenk-at]

The problem

Hi, I assume you know about https://github.com/HomeAssistant-Mods/home-assistant-miele? I've been using it for a while and would like to improve the state of the Miele@home integration into HA overall. It looks like your integration has a more modern codebase, but lacks a lot of device types at the moment (and the wide user base). Is there a particular reason you chose to start from scratch?

Anyway, as I said, I'd like help get things moving, either by improving the "old" integration or making yours gain feature parity. Are you interested in joining efforts? I'm not yet well-versed in HA's API, but that should not be a handicap in the long run.

Version of hass_template integration having the issue?

master

Version of Home Assistant Core having the issue?

2021.12.10

Anything in the logs that might be useful for us?

No response

Additional information

No response

[astrandb]

Hi @mundschenk-at,
The reason that I started from scratch was that I have done a few similar intergrations recently and my view was that there was a lot of refactoring needed in the "original" integration if it should use all bells and wistles in the latest versions of HA.

The main things I wanted (for my personal use):

• Organize entities in HA devices
• Use HA's OAuth2 implementation
• Support push updates from Miele cloud for doors and alarms etc

I have only got a refridgerator and a freezer from Miele so I have not been able to verify functionality in other appliances. I have a couple of washers and tumble dryers also but they are not "smart", 12-15 years old and they never break ;-) .

I am absolutely interested in help with adding more appliance types.
A good way to start is to enable debug logging for custom_components/miele with your account. (If you have access to more smart devices than I have.) The data downloaded from Miele cloud when HA starts is printed in the debug log and can then be used as template when adding more sensors and controls. The Miele API is pretty well documented but I have bumped ito a few issues to interpret the docs.

[mundschenk-at]

Yeah, after trying to retrofit devices onto the old integration, I have to agree that starting fresh sounds like the more sensible option. I've got a new washer-dryer and newish dishwasher (6xxx series, so probably no ecoFeedback via the API). The problem with the API is that it does not always deliver what the docs say it does (i.e. for me, ecoFeedback always reports 0 for both water and electricity for my washer-dryer, where as the key points to a null value for the dishwasher).

I'll enable logging, but I also know how to use the Swagger UI, so I can directly report things from the API if there is anything specific we need to do.

What might also be of interest to you (though not for this integration) is this thread I stumbled upon yesterday about accessing the devices locally instead of using the cloud API. It is in German unfortunately, but it should be readable via Google Translate (and the code examples probably speak for themselves). There's some participation by Miele engineers and someone even did a (proof-of-concept) JS implementation of the gateway protocol.

[astrandb]

Please send me the output from Swagger for the endpoint /devices. I can then setup a first version of sensors and other relevant entitors.

[mundschenk-at]

Sure, here's the data (slightly anonymized of course). The dishwasher is running at the moment. As it's a 6xxx series device, Miele does not export the ecoFeedback data to the API for it, even though it does have that information on the device (not in the app at the moment, because the app is FUBAR). The following keys, as far as I have seen, never actually contain meaningful data on the dishwasher:

• targetTemperature
• temperature
• spinningSpeed
• dryingStep
• ventilationStep
• plateStep
• batteryLevel

I'm not sure about the *light keys, I'd have to check when the door is open and the light on.

Definitely of interest (in addition to the default entitites already created):

• ProgramID (both the raw value and the localized text)
• programType (both the raw value and the localized text, but it would probably be OK to have those in the extra state attributes)
• programPhase (both the raw value and the localized text)
• remainingTime
• startTime
• elapsedTime
• signalDoor

I'll get you state information for when the washer-dryer is running tomorrow.

{
  "<fabNumber1>": {
    "ident": {
      "type": {
        "key_localized": "Device type",
        "value_raw": 7,
        "value_localized": "Dishwasher"
      },
      "deviceName": "",
      "protocolVersion": 2,
      "deviceIdentLabel": {
        "fabNumber": "<fabNumber1>",
        "fabIndex": "64",
        "techType": "G6865-W",
        "matNumber": "<matNumber1>",
        "swids": [
		"<swid1>",
		"<swid2>",
		"<swid3>",
		"<...>",
        ]
      },
      "xkmIdentLabel": {
        "techType": "EK039W",
        "releaseVersion": "02.72"
      }
    },
    "state": {
      "ProgramID": {
        "value_raw": 38,
        "value_localized": "QuickPowerWash",
        "key_localized": "Program name"
      },
      "status": {
        "value_raw": 5,
        "value_localized": "In use",
        "key_localized": "status"
      },
      "programType": {
        "value_raw": 2,
        "value_localized": "Automatic programme",
        "key_localized": "Program type"
      },
      "programPhase": {
        "value_raw": 1799,
        "value_localized": "Drying",
        "key_localized": "Program phase"
      },
      "remainingTime": [
        0,
        15
      ],
      "startTime": [
        0,
        0
      ],
      "targetTemperature": [
        {
          "value_raw": -32768,
          "value_localized": null,
          "unit": "Celsius"
        }
      ],
      "temperature": [
        {
          "value_raw": -32768,
          "value_localized": null,
          "unit": "Celsius"
        },
        {
          "value_raw": -32768,
          "value_localized": null,
          "unit": "Celsius"
        },
        {
          "value_raw": -32768,
          "value_localized": null,
          "unit": "Celsius"
        }
      ],
      "signalInfo": false,
      "signalFailure": false,
      "signalDoor": false,
      "remoteEnable": {
        "fullRemoteControl": true,
        "smartGrid": false,
        "mobileStart": false
      },
      "ambientLight": null,
      "light": null,
      "elapsedTime": [
        0,
        59
      ],
      "spinningSpeed": {
        "unit": "rpm",
        "value_raw": null,
        "value_localized": null,
        "key_localized": "Spin speed"
      },
      "dryingStep": {
        "value_raw": null,
        "value_localized": "",
        "key_localized": "Drying level"
      },
      "ventilationStep": {
        "value_raw": null,
        "value_localized": "",
        "key_localized": "Fan level"
      },
      "plateStep": [],
      "ecoFeedback": null,
      "batteryLevel": null
    }
  },
  "<fabNumber2>": {
    "ident": {
      "type": {
        "key_localized": "Device type",
        "value_raw": 24,
        "value_localized": "Washer dryer"
      },
      "deviceName": "",
      "protocolVersion": 4,
      "deviceIdentLabel": {
        "fabNumber": "<fabNumber2>",
        "fabIndex": "32",
        "techType": "WTR870",
        "matNumber": "<matNumber2>",
        "swids": [
		"<swid1>",
		"<swid2>",
		"<swid3>",
		"<...>",        ]
      },
      "xkmIdentLabel": {
        "techType": "EK037",
        "releaseVersion": "03.88"
      }
    },
    "state": {
      "ProgramID": {
        "value_raw": 3,
        "value_localized": "Minimum iron",
        "key_localized": "Program name"
      },
      "status": {
        "value_raw": 1,
        "value_localized": "Off",
        "key_localized": "status"
      },
      "programType": {
        "value_raw": 1,
        "value_localized": "Own programme",
        "key_localized": "Program type"
      },
      "programPhase": {
        "value_raw": 256,
        "value_localized": "",
        "key_localized": "Program phase"
      },
      "remainingTime": [
        1,
        59
      ],
      "startTime": [
        0,
        0
      ],
      "targetTemperature": [
        {
          "value_raw": 3000,
          "value_localized": 30,
          "unit": "Celsius"
        },
        {
          "value_raw": -32768,
          "value_localized": null,
          "unit": "Celsius"
        },
        {
          "value_raw": -32768,
          "value_localized": null,
          "unit": "Celsius"
        }
      ],
      "temperature": [
        {
          "value_raw": -32768,
          "value_localized": null,
          "unit": "Celsius"
        },
        {
          "value_raw": -32768,
          "value_localized": null,
          "unit": "Celsius"
        },
        {
          "value_raw": -32768,
          "value_localized": null,
          "unit": "Celsius"
        }
      ],
      "signalInfo": false,
      "signalFailure": false,
      "signalDoor": true,
      "remoteEnable": {
        "fullRemoteControl": true,
        "smartGrid": false,
        "mobileStart": false
      },
      "ambientLight": null,
      "light": null,
      "elapsedTime": [
        0,
        0
      ],
      "spinningSpeed": {
        "unit": "rpm",
        "value_raw": 1000,
        "value_localized": "1000",
        "key_localized": "Spin speed"
      },
      "dryingStep": {
        "value_raw": 0,
        "value_localized": "",
        "key_localized": "Drying level"
      },
      "ventilationStep": {
        "value_raw": null,
        "value_localized": "",
        "key_localized": "Fan level"
      },
      "plateStep": [],
      "ecoFeedback": null,
      "batteryLevel": null
    }
  }
}

[mundschenk-at]

Some additional thoughts:

• I'd suggest adding the information from xkmIdentLabel to the device information (techType as hw_version, releaseVersion as sw_version).
• While it should be theoretically possible to translate all program types, phases and IDs from their raw values (and thus enable translation within HA), it is a lot of work and so it would probably be useful to be able to set the API language for string localization.
• It might be useful to provide a full set of state attributes somewhere (i.e. to add a kind of automatic basic support for all device types, similar to what the old integration does with the sensor.<device>_status entity).

[astrandb]

Comments below:

The following keys, as far as I have seen, never actually contain meaningful data on the dishwasher:

• targetTemperature
• temperature
• spinningSpeed
• dryingStep
• ventilationStep
• plateStep
• batteryLevel

The official device capabilities are documented here: Capabilities matrix. None or -32768 means not supported
I haven't checked the details of your devices but they seem to be in accordance.

Definitely of interest (in addition to the default entitites already created):

• ProgramID (both the raw value and the localized text)
• programType (both the raw value and the localized text, but it would probably be OK to have those in the extra state attributes)
• programPhase (both the raw value and the localized text)
• remainingTime
• startTime
• elapsedTime
• signalDoor

Agree!

• I'd suggest adding the information from xkmIdentLabel to the device information (techType as hw_version, releaseVersion as sw_version).

Possible, but xkmIdentLabel just refers to communications module. Perhaps better as extra_attributes in a diagnostic sensor.

• While it should be theoretically possible to translate all program types, phases and IDs from their raw values (and thus enable translation within HA), it is a lot of work and so it would probably be useful to be able to set the API language for string localization.

I thought about this when I started this project. I decided to use HA translation for couple of reasons

• Miele only support a limitied selection of languages. Especially important is the lack of Swedish ;-).
• When you change language in HA everything will change language except this integration - perhaps confusing for some...
• My general idea was to align this integration with HA standards as much as possible

I suggest that the translation issue is put on hold for the time beeing.

• It might be useful to provide a full set of state attributes somewhere (i.e. to add a kind of automatic basic support for all device types, similar to what the old integration does with the sensor.<device>_status entity).

This will be handled in HomeAssistant 2022.2. I will try to add the necessary code as soon as 2022.2 is released.

[mundschenk-at]

The official device capabilities are documented here: Capabilities matrix. None or -32768 means not supported I haven't checked the details of your devices but they seem to be in accordance.

Yes, but those only indicate maximum capabilities of a device type. A specific model might only support some of the capabilities listed.

• I'd suggest adding the information from xkmIdentLabel to the device information (techType as hw_version, releaseVersion as sw_version).

Possible, but xkmIdentLabel just refers to communications module. Perhaps better as extra_attributes in a diagnostic sensor.

Fine by me (although I think we will never know more than the comm module about the hard-/software of the devices, so for practical purposes, that is the hw_version and sw_version).

• While it should be theoretically possible to translate all program types, phases and IDs from their raw values (and thus enable translation within HA), it is a lot of work and so it would probably be useful to be able to set the API language for string localization.

I thought about this when I started this project. I decided to use HA translation for couple of reasons

• Miele only support a limitied selection of languages. Especially important is the lack of Swedish ;-).
• When you change language in HA everything will change language except this integration - perhaps confusing for some...
• My general idea was to align this integration with HA standards as much as possible

All good reasons. Does that mean you intend to use the Miele en localization as the baseline, or do you intend for the integration to provide all the strings itself (mapping from the raw values)?

• It might be useful to provide a full set of state attributes somewhere (i.e. to add a kind of automatic basic support for all device types, similar to what the old integration does with the sensor.<device>_status entity).

This will be handled in HomeAssistant 2022.2. I will try to add the necessary code as soon as 2022.2 is released.

Interesting. Can you tell me were I can read up on this new feature (and other things coming in 2022.2)?

[astrandb]

@mundschenk-at Please send me the Swagger output for /devices/{device_id}/programs for your devices

[mundschenk-at]

Unfortunately, the call only returns an empty array for both devices (i.e. it looks like the API is broken at the moment). Changing the device ID (i.e. removing a digit) results in a 404 response, so the empty response is not because of an incorrect device ID.

[astrandb]

OK, let us wait and see if the API recovers.

The Home Assistant way is to start with english translation and then let the community create translation files to other languages. See `translations/en.json'. That is for custom components. Official integrations are handled on lokalise.com

There is no coordinated release plan for new features but you can follow the development from this page https://developers.home-assistant.io/

Github core repo and Discord chats are good places to monitor.

2022.2beta will be released on jan 26. A draft changelog is usually published on https://rc.home-assistant.io

[mundschenk-at]

The Home Assistant way is to start with english translation and then let the community create translation files to other languages. See `translations/en.json'. That is for custom components. Official integrations are handled on lokalise.com

Yes, what I meant is whether you intend to use the localized_value and localized_key for en from the Miele API or do the mapping from value_raw to user visible strings entirely in the integration.

2022.2beta will be released on jan 26. A draft changelog is usually published on https://rc.home-assistant.io

Thanks, I didn't know about that subsite and I'll be sure to monitor it in the future. Unfortunately, there is no draft changelog at athe moment. However, since you seem to have a specific feature in mind, could you point me to the GitHub issue or PR? (I do casually read the core repository, but it is huge and very busy.)

[mundschenk-at]

OK, let us wait and see if the API recovers.

I've done some more research, it appears the endpoint has never been working for most devices. (It was relatively recently introduced in version 1.0.5 of the API.) I don't think we should wait for Miele to fix this, but rather integrate support when and if they add more device types to this endpoint.

Here are some mappings from programm phases to names from other projects:

• MQTT-Miele
• ioBroker adapter

[mundschenk-at]

So here's the output when the washer-dryer is running (a combined program):

{
  "ident": {
    "type": {
      "key_localized": "Device type",
      "value_raw": 24,
      "value_localized": "Washer dryer"
    },
    "deviceName": "",
    "protocolVersion": 4,
    "deviceIdentLabel": {
      "fabNumber": "<fabNumber>",
      "fabIndex": "32",
      "techType": "WTR870",
      "matNumber": "<matNumber>",
      "swids": [
        "<swid1>",
        "<swid2>",
        "<swid3>",
        "<...>"
      ]
    },
    "xkmIdentLabel": {
      "techType": "EK037",
      "releaseVersion": "03.88"
    }
  },
  "state": {
    "ProgramID": {
      "value_raw": 1,
      "value_localized": "Cottons",
      "key_localized": "Program name"
    },
    "status": {
      "value_raw": 5,
      "value_localized": "In use",
      "key_localized": "status"
    },
    "programType": {
      "value_raw": 1,
      "value_localized": "Own programme",
      "key_localized": "Program type"
    },
    "programPhase": {
      "value_raw": 260,
      "value_localized": "Main wash",
      "key_localized": "Program phase"
    },
    "remainingTime": [
      4,
      51
    ],
    "startTime": [
      0,
      0
    ],
    "targetTemperature": [
      {
        "value_raw": 4000,
        "value_localized": 40,
        "unit": "Celsius"
      },
      {
        "value_raw": -32768,
        "value_localized": null,
        "unit": "Celsius"
      },
      {
        "value_raw": -32768,
        "value_localized": null,
        "unit": "Celsius"
      }
    ],
    "temperature": [
      {
        "value_raw": -32768,
        "value_localized": null,
        "unit": "Celsius"
      },
      {
        "value_raw": -32768,
        "value_localized": null,
        "unit": "Celsius"
      },
      {
        "value_raw": -32768,
        "value_localized": null,
        "unit": "Celsius"
      }
    ],
    "signalInfo": false,
    "signalFailure": false,
    "signalDoor": false,
    "remoteEnable": {
      "fullRemoteControl": true,
      "smartGrid": false,
      "mobileStart": false
    },
    "ambientLight": null,
    "light": null,
    "elapsedTime": [
      0,
      1
    ],
    "spinningSpeed": {
      "unit": "rpm",
      "value_raw": 1200,
      "value_localized": "1200",
      "key_localized": "Spin speed"
    },
    "dryingStep": {
      "value_raw": 0,
      "value_localized": "",
      "key_localized": "Drying level"
    },
    "ventilationStep": {
      "value_raw": null,
      "value_localized": "",
      "key_localized": "Fan level"
    },
    "plateStep": [],
    "ecoFeedback": {
      "currentWaterConsumption": {
        "unit": "l",
        "value": 0
      },
      "currentEnergyConsumption": {
        "unit": "kWh",
        "value": 0
      },
      "waterForecast": 0,
      "energyForecast": 0
    },
    "batteryLevel": null
  }
}

[astrandb]

Re translation: I think I will use english localized strings as the base.
Can you please try /devices/{device_id}/actions It will return the actions that are allowed at the moment. I e different responses depending on the current operating mode of the machine.

[mundschenk-at]

Washer-dryer (running):

{
  "processAction": [
    2,
    3
  ],
  "light": [],
  "ambientLight": [],
  "startTime": [],
  "ventilationStep": [],
  "programId": [],
  "targetTemperature": [],
  "deviceName": true,
  "powerOn": false,
  "powerOff": true,
  "colors": [],
  "modes": []
}

Dishwasher (not running, but switched on):

{
  "processAction": [],
  "light": [],
  "ambientLight": [],
  "startTime": [],
  "ventilationStep": [],
  "programId": [],
  "targetTemperature": [],
  "deviceName": true,
  "powerOn": false,
  "powerOff": false,
  "colors": [],
  "modes": []
}

IIRC, the dishwasher supports the same actions as the washer-dryer when running, i.e. you can pause or cancel the current program. All a bit underwhelming, really.

[astrandb]

Suggested ToDo

Next steps

• Setup a test system where I can inject static data from your devices in the live data from my devices. Then it should be fairly easy to build and verify the new specific sensors.
• Prepare for translation of states, program names etc.

Later

• Add services, switches and/or select boxes to control the appliances

[mundschenk-at]

To make the code easier to maintain, I'd also suggest adding constants for at least the various device types and status values (maybe also for program IDs, phases etc.). Can I help with coding anything in particular? My python is a bit rusty, but then again it's a very readable language.

[astrandb]

Good idea with constants. I started to make an attempt in devcap.py but then I was too eager to get something up and running. Planned to get back and fix the constants on a rainy day sometime in the future.
I appreciate if you would start with relevant constant definitions. They should reside in const.py. Preferrably as a PR but it is OK as plain text also. Then a german translation file could be a good execise. I just have to fix the base files strings.json and en.json first. And sensor specific translation files also. It is a bit tricky to get them working when you start from scratch so I must look in another project how we did it there.

[mundschenk-at]

I've created #13 for the German translation. I'll have a look at the constants when I'm less tired. We'll need to add more states/programs for washing machines.

[astrandb]

Please see PR #11 where I have started with the values that are known to me.

[astrandb]

One more step...

[mundschenk-at]

I would not classify the "status" entity as diagnostic in nature. What the washing machine is doing at the moment (off, running ...) is what I'm interested in, after all.

[astrandb]

OK, I have moved it to sensors. I placed in diagnostics without much thought when my fridge and freezer showed "Running" and never changed.

[mundschenk-at]

Haha, yeah those wouldn't change much, would they? (Though I could imagine the freezer having some indication when it's in superfreeze or whatever Miele calls that.)

[mundschenk-at]

OK, I have moved it to sensors. I placed in diagnostics without much thought when my fridge and freezer showed "Running" and never changed.

Is there an easy way to refresh HA's device information, short of removing and re-adding the integration? My status sensor is still in Diagnostics (because the entity was first created with the previous release).

[astrandb]

I noted the same problem. No workaround that I know of.