DOCSEARCHbyAlgolia
Submit Docs

ECHONETLite Home Assistant Custom Component

repository·master·Indexed 42 days ago

https://github.com/scottyphillips/echonetlite_homeassistant

A Home Assistant custom component for controlling and monitoring ECHONET Lite compatible devices, primarily Japanese IoT hardware such as air conditioners, water heaters, refrigerators, and solar power systems. It utilizes the pychonet library and supports a wide range of manufacturers including Mitsubishi Electric, Fujitsu General, Sharp, Panasonic, Daikin, Rinnai, Noritz, OMRON, and KDK. Features include hybrid communication via push notifications and polling, manufacturer-specific device quirks, and support for climate, fan, sensor, select, and switch platforms.

Tokens
5.4K
Snippets
6
Records
25
Agent score
53%

What's inside ECHONETLite

  1. Overview of ECHONETLite Platform for Home Assistant

    master

    ECHONETLite is a Home Assistant custom component designed to integrate any device that implements the ECHONET Lite protocol. It uses the pychonet Python library to communicate with hardware such as air conditioners, water heaters, refrigerators, and solar power systems.

    Key features include:

    • Broad Support: Works with any ECHONET Lite compatible device, even those not explicitly listed in the Machine Readable Appendix (MRA).
    • Hybrid Communication: Uses push notifications for responsive updates and polling for specific EPCs (Extended Property Codes).
    • Network Flexibility: Can operate on segmented or managed networks using the always_poll option to bypass multicast dependencies.
    • Device Quirks: Includes manufacturer-specific overrides for devices that deviate from the standard specification.
    • Compound Sensors: Supports sensors that combine multiple EPCs (e.g., scaling energy readings by a coefficient).

  3. Investigate and implement device quirks for non-standard EPCs

    master

    If a manufacturer uses non-standard EPCs (values above 240/0xF0), you can identify and implement them using quirks.

    1. Identify the quirk

    1. Enable debug logging on the ECHONETLite integration screen and restart Home Assistant.
    2. Once startup is complete, disable debug logging and download the logs.
    3. Search the logs for your device's IP address and inspect the getmap and setmap data for values above 240.

    Example log entry:

    {'eojcc': 130, 'eojci': 1, 'eojgc': 2, 'getmap': [128, 224, 129, 241, 130, 131, 147, 243, 244, 245, 246, 247, 136, 248, 249, 138, 250, 251, 252, 157, 253, 158, 254, 159, 255], 'host': '192.168.0.49', 'manufacturer': 'Rinnai', ...}

    2. Create a quirks file

    Create a Python file in your quirks directory (e.g., quirks/Manufacturer/model/filename.py) to map the custom EPCs. Use the CONF_NAME constant from homeassistant.const.

    Example quirks file structure:

    from homeassistant.const import CONF_NAME

def _hex(edt):
    return edt.hex()

QUIRKS = {
    0xFA: {
        "EPC_FUNCTION": _hex,
        "ENL_OP_CODE": {CONF_NAME: "FA"},
    },
    0xFD: {
        "EPC_FUNCTION": _hex,
        "ENL_OP_CODE": {CONF_NAME: "FD"},
    },
}

    3. Verify

    Restart Home Assistant. New entities for the custom EPCs should appear. Observe if their values change during device operation to confirm the mapping is correct.

  5. Enable the ECHONET Protocol on Mitsubishi Adapters

    master

    This component was originally designed for the Mitsubishi MAC-568IF-E WiFi adapter. For many devices, you must explicitly enable the ECHONETlite protocol.

    Using the official Mitsubishi AU/NZ Wifi app, navigate to the "edit unit" settings and enable the ECHONETlite protocol.

    Note: Adapters released in Japan (such as HM-W002-AC, HM-W002-ACB, etc.) may not require this manual step. The developer cannot assist with enabling ECHONET Lite on non-Mitsubishi vendor products.

  6. Install the ECHONETLite integration

    master

    To install the ECHONETLite custom component in Home Assistant:

    1. Install the component files into your custom_components directory.
    2. Reload Home Assistant.
    3. Verify that the echonetlite platform has been added to your custom_components directory.
    4. (Optional) Clear your browser cache.
    5. In the Home Assistant UI, navigate to Configuration -> Integrations -> ADD INTEGRATION.
    6. Select the echonetlite integration.
    7. Enter the device's IP address in the host field and provide a name for the platform.

    Upon successful configuration, the integration will automatically set up climate entities and, depending on your hardware, sensor and select entities.

  7. Enable ECHONET Protocol on Mitsubishi Devices

    master

    To use Mitsubishi MAC-568IF-E WiFi Adaptors with this component, you must manually enable the ECHONET Lite protocol:

    1. Open the official Mitsubishi AU/NZ WiFi App.
    2. Navigate to the 'edit unit' settings.
    3. Enable the 'ECHONET lite' protocol.

    Note on Temperature: While proprietary Mitsubishi apps (MELCloud/MELView/Kumo Cloud) may support single °F or half °C increments, ECHONET operates using whole °C.

    Network Requirement: Ensure that UDP port 3610 is unblocked in your firewall to allow ECHONET Lite communication.

  8. Configure Fan and Swing Mode Options for Air Conditioners

    master

    Once the integration is added, you can fine-tune the settings for supported air conditioners and air purifiers:

    1. Go to Settings -> Devices & Services.
    2. Find the ECHONETLite integration and click Configure.
    3. Adjust the required Fan and Swing Mode settings.

    Note: Because ECHONETLite does not provide a way to return allowed values for these settings, selecting the correct options may require a process of "trial and error." Changes take effect immediately after saving.

  9. Install ECHONETLite Platform via HACS

    master

    The recommended method for installing the integration is via the Home Assistant Community Store (HACS).

    1. Open HACS in your Home Assistant instance.
    2. Search for 'ECHONETLite Platform'.
    3. Click Download, then confirm by clicking Download again.
    4. Restart Home Assistant.
    # No CLI command required; use HACS UI

  10. Set up the ECHONET Lite integration

    master

    Once the files are installed, follow these steps to add your device:

    1. Navigate to Settings → Devices & Services → ADD INTEGRATION.
    2. Select ECHONET Lite.
    3. Enter the IP address of your ECHONET Lite device.
    4. The integration will automatically create supported platforms such as climate, sensor, switch, fan, and select based on the device capabilities.
    5. Repeat the process for each additional device on your network.

  11. Migrate from versions prior to 3.0.1

    master

    If you are upgrading from a version of this component older than 3.0.1, you must perform these cleanup steps to avoid conflicts:

    1. Delete the mitsubishi folder from your custom_components directory.
    2. Remove any existing references to mitsubishi from your configuration.yaml file.

  12. Configure and Enable the ECHONETLite Integration

    master

    After installing the files, follow these steps to activate the integration:

    1. Restart Home Assistant and clear your browser cache.
    2. Navigate to Settings -> Devices & Services -> Add Integration.
    3. Select the echonetlite integration.
    4. Enter the IP address of your device in the Host field and provide a name for the platform.
    5. The integration will automatically configure supported platforms: climate, sensor, switch, fan, and select.
    6. To add additional devices, repeat the process for each IP address.