search

dlarrick / hass-kumo

Home Assistant module interfacing with Mitsubishi mini-split units
MIT License
99 stars 23 forks source link
climate custom-component home-assistant homeassistant kumo kumocloud mini-split mitsubishi python

readme

Mitsubishi Kumo Cloud

Type hacs_badge

Mitubishi Kumo Cloud (Kumo for short) is a custom component for Home Assistant that allows you to control Mitsubishi mini-split units that are connected to the Mitsubishi KumoCloud service.

Installation

Note: Kumo is not included in Home Assistant as an official integration. Instead, the recommended way to install it is through the Home Assistant Community Store (HACS) add-in.

You can install Kumo in one of two ways.

We recommend using the HACS installation method, which makes future updates to Kumo easy to track and install. Click the HACS badge above for details on installing and using HACS.

Configuration

Configure Kumo using the Home Assistant user interface.

  1. In Home Assistant, go to Settings ➤ Devices & Services ➤ Integrations, and click ➕ Add Integration.
  2. Search for "Kumo" and select the Kumo item.
  3. When prompted, enter your KumoCloud username (email address) and password.
  4. You can also enable the prefer_cache setting in this dialog. See details below.
  5. Click Submit to enable the integration and begin device discovery.
  6. Once discovery is complete:
    • You'll be prompted to assign a room (Area in Home Assistant terminology) for all discovered devices.
    • You might be prompted to assign IP addresses for devices where Kumo didn’t receive an IP address from the KumoCloud service. See details below.

Once the Kumo integration is added, you'll have a card for it on the Integrations page. (Integrations are sorted by name, and the name of this integration is "Kumo".) The Kumo integration card includes a "Configure" link. The configuration panel lets you change the default timeout values for device connections, or update IP addresses for configured units. Important: New values don't take effect until you restart Home Assistant.

IP Addresses

Kumo accesses your indoor units directly on the local LAN using their IP address, discovered at setup time (or at Home Assistant startup, if prefer_cache is False) from the Kumo Cloud web service. It is strongly recommended that you set a fixed IP address for your indoor unit(s), using something like a DHCP reservation.

In some cases, Kumo is unable to retrieve the indoor units' addresses from the Kumo Cloud web service. If this happens, you will be prompted to supply the address(es) as part of setup. It's also possible to edit the IP address of existing units through the UI using the Configure link on Kumo's tile in the Integrations section of Settings.

If you continue to have connection issues with your units, try using the Kumo Cloud app to force a refresh of your devices with KumoCloud. Quoting @rhasselbaum's Gist:

So back into Installer Settings. I clicked on the unit there, and under Advanced, there is a Refresh Settings option. Bingo! This resynchronizes the state of the device with Kumo Cloud, apparently. Clicked that, restarted HA again, and finally, it shows up!

Troubleshooting

WiFi

The most common cause of flaky behavior is weak WiFi signal at the indoor unit. Try measuring WiFi strength (2.4 GHz only) with a phone app. Also try repositioning the Mitsubishi WiFi adapter within the unit, positioning it close to the plastic exterior rather than metal interior components.

API errors

In early 2023 Mitsubishi appears to have made some change that makes the WiFi adapter less reliable. My educated guess is that it has a memory leak. See Issue 105 in the hass-kumo repository for discussion.

As a result of this issue, if you are seeing serializer_error or (especially) __no_memory errors consistently in your HA logs, it's likely that your indoor unit needs power-cycling. Unfortunately the easiest way is probably at the circuit breaker for the entire mini-split system.

Home Assistant Entities and Control

Each indoor unit appears as a separate climate entity in Home Assistant. Entity names are derived from the name you created for the unit in KumoCloud. For example, climate.bedroom or climate.living_room.

Entity attributes can tell you more about the current state of the indoor unit, as well as the unit's capabilities. Attributes can include the following:

Home Assistant Services and Control

Use the standard climate service calls to control or automate each unit. Available services can include:

Specific support and behavior can vary, depending on the capabilities of your indoor unit.

Home Assistant Sensors

Useful information from indoor units is provided as attributes on the associated climate entity. This data can be turned into sensors in one of two ways: sensors provided by the integration, or template sensors from the main entity's attributes.

Sensors

By default a sensor for current temperature is enabled. It's possible to enable sensors for a few other values, if available:

To enable these optional sensors, click on the Kumo tile in Settings -> Devices and Services, go into the Devices section, click on the indoor unit (or Kumo Station) and enable them under Sensors.

Note that you will need to restart HmomeAssistant after enabling a new sensor type, due to Issue 120.

Template Sensors

For additional attributes not covered above, or if you require more customization, you can convert attributes to sensors using templates. For example, here's a simple sensor for the target temperature.

# Get attribute of climate state in form of sensor
- platform: template
  sensors:
    thermostat_target_temperature_bedroom:
      friendly_name: "Target Temperature"
      unit_of_measurement: '°F'
      value_template: "{{ state_attr('climate.bedroom', 'temperature') }}"

Here's a more complex template that sets additional entity attributes and takes certain error conditions into consideration:

- platform: template
  sensors:
    temperature_bedroom_current:
      friendly_name: "Bedroom Temperature"
      device_class: temperature
      unit_of_measurement: "°F"
      value_template: >-
        {%- if state_attr('climate.bedroom', 'current_temperature') != None %}
          {{state_attr('climate.bedroom','current_temperature') | float }}
        {%- endif %}
      availability_template: >-
        {%- if not is_state('climate.bedroom', 'unavailable') %}
          true
        {%- endif %}

This template was suggested in the community thread (see Support, below). It can be especially useful if, for example, you're experiencing connection issues with the integration due to problems with your wireless network.

Support

For support, see the Kumo integration thread on the Home Assistant community. (To skip early development discussions, start with the official availability announcement in that thread.)

For bugs or feature improvements, feel free to create a GitHub issue or pull request.

Implementation Notes

TODO

Status

License

MIT