py-ccm15

Python Library to access a Midea CCM15 data converter

This package provides an asynchronous interface to communicate with Midea CCM15 data converter modules. It allows you to control and monitor air conditioning units via the CCM15 gateway using Python.

The CCM15 — officially the Midea CCM-15 Central Controller — is a data converter that bridges Midea's RS-485 VRF bus to TCP/IP, exposing a small HTTP interface for monitoring and control of up to 64 indoor units.

Features

• Read and set temperature
• Control fan mode and AC mode
• Async support for non-blocking operations
• Communicate with CCM15 over HTTP

Installation

pip install py-ccm15

Usage

import asyncio
from ccm15 import CCM15Device

async def main():
    # host and port of the CCM15 gateway (default HTTP port is 80).
    # Optionally pass password="123456" for firmwares that require it.
    device = CCM15Device("192.168.1.100", 80)

    # Read the state of every AC slave, keyed by its slot index.
    state = await device.get_status_async()
    for index, ac in state.devices.items():
        print(index, ac.ac_mode, ac.fan_mode, ac.temperature, ac.temperature_setpoint)

    # Change a slave: mutate its decoded state and write it back.
    ac = state.devices[0]
    ac.ac_mode = 0                 # mode code (0 = cool — see PROTOCOL.md)
    ac.fan_mode = 0                # fan code (0 = auto)
    ac.temperature_setpoint = 24
    await device.async_set_state(0, ac)

asyncio.run(main())

The importable package is ccm15 (the PyPI distribution is py-ccm15). The CCM15 uses no token; the only optional auth is a password= for firmwares that require it. See PROTOCOL.md for the mode/fan codes.

Requirements

• Python 3.7+
• httpx>=0.24.1
• xmltodict>=0.13.0

Documentation

For full API reference and advanced usage, visit the GitHub repository.

Protocol

The CCM15's HTTP interface (status.xml / ctrl.xml) and the per-slave status byte layout are documented in detail in PROTOCOL.md — a bit-level reverse-engineering reference for the wire format, including the ac0/ac1 slave mask, mode/fan codes, and the optional pwd/sw/ht parameters.

References

• Midea CCM-15 Central Controller — official product page
• Home Assistant ccm15 integration — consumes this library
• Where to buy: the CCM15 / CCM-15 data converter is often available cheaply on AliExpress (search "Midea CCM15")

Contributing

Pull requests are welcome. If you find a bug or have a feature request, feel free to open an issue.

Acknowledgements

The CCM15 wire protocol implemented here — the status.xml byte decoding and the HVAC/fan mode command mappings — was originally derived from the houselabs/home-assistant-mideaccm Home Assistant custom component (originally authored by Chao Shen). This library re-implements that protocol as a standalone, async package. Thanks to the original authors for reverse-engineering the controller protocol.

Thanks also to daxingplay/home-assistant-midea-ccm15, an independent CCM15 Home Assistant component whose status.xml decoding and ctrl.xml command handling were a valuable second reference for validating this library's wire protocol.

Special thanks to Alexa (@Alexa-RR), who captured the controller's own midea.js from a live device and traced the protocol to document the swing (sw, status byte 4 bit 1) and electric-heater (ht, status byte 4 bit 0) parameters and their control-URL semantics. That work is the basis for the opt-in swing/heater support and much of PROTOCOL.md.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Made by Oscar Calvo