HomematicIP REST API

A Python 3 wrapper for the homematicIP REST API (Access Point Based) Since there is no official documentation about this API everything was done via reverse engineering. Use at your own risk.

Any help from the community through e.g. pull requests would be highly appreciated.

Using Home Assistant?

Home Assistant's Homematic IP Cloud integration is built on this library. If your question is about entities, devices or automations inside Home Assistant, start with the integration documentation. This README is about the library itself and its command line tools.

A device has to be supported here before Home Assistant can expose it, so if your device is missing entirely, see New devices and config dump.

Get Help / Discord

If you want to get in contact with me or need help with the library, you can get in touch with me via discord. There is a discord server and my discord tag is agonist#6159

📖 Documentation

The documentation is at https://hahn-th.github.io/homematicip-rest-api and is generated from the docs/ folder of this repository. It covers getting started, the API reference and the changelog.

Support me

❤️ If you want to say thank you or want to support me, you can do that via PayPal. https://paypal.me/thomas08154711

Thanks

Kudos and a big thank you to @coreGreenberet, who created this library.

Installation

To install the package, run:

pip install -U homematicip

Usage

Generate a token

If you are about to connect to a HomematicIP HCU1 you have to press the button on top of the device, before running the script. From now, you have 5 Minutes to complete the registration process.

After that, run hmip_generate_auth_token (from the command line) to get an auth token for your access point. It will generate a config.ini in your current directory.

Use the CLI

You can send commands to homematicIP using the hmip_cli script. To get an overview, use -h or --help param. To address devices, use the argument -d in combination with the 24-digit ID (301400000000000000000000) from --list-devices.

A few examples:

hmip_cli --help to get help
hmip_cli --list-devices to get a list of your devices.
hmip_cli -d <id-from-device-list> --toggle-garage-door to toggle the garage door with HmIP-WGC.
hmip_cli --list-events to listen to events and changes in your homematicIP system
hmip_cli -d <id> --set-lock-state LOCKED --pin 1234 to lock a door with HmIP-DLD
hmip_cli --dump-configuration --anonymize to dump the current config and anonymize it.

Examples

All examples assume a config.ini created by hmip_generate_auth_token, see Paths for config.ini for where it is looked up.

Connect and list your devices:

import homematicip
from homematicip.home import Home

config = homematicip.find_and_load_config_file()

home = Home()
home.init(config.access_point, config.auth_token)
home.get_current_state()

for device in home.devices:
    print(f"{device.id}  {device.label}  ({device.modelType})")

Read a value. Devices are containers; the readings live on their functional channels, and which channel carries what depends on the device:

device = home.search_device_by_id("3014F711A000000000000001")

for channel in device.functionalChannels:
    print(channel.index, channel.functionalChannelType)

# on a wall thermostat, channel 1 is the WALL_MOUNTED_THERMOSTAT_PRO_CHANNEL
print(device.functionalChannels[1].actualTemperature)

Switch something on. The write methods live on the device and on the channel:

device = home.search_device_by_id("3014F711A000000000000001")
device.turn_on()

The library is async underneath. Every method has an _async counterpart, and Home wraps those for synchronous use. In an async application use AsyncHome directly:

import asyncio

import homematicip
from homematicip.async_home import AsyncHome


async def main():
    config = homematicip.find_and_load_config_file()

    home = AsyncHome()
    await home.init_async(config.access_point, config.auth_token)
    await home.get_current_state_async()

    for device in home.devices:
        print(device.label)


asyncio.run(main())

Events

It is also possible to receive push notifications over a websocket connection. Events are only delivered while the connection is open, so this has to run inside an event loop:

import asyncio

import homematicip
from homematicip.async_home import AsyncHome


def print_events(event_list):
    for event in event_list:
        print(f"EventType: {event['eventType']} Data: {event['data']}")


async def main():
    config = homematicip.find_and_load_config_file()

    home = AsyncHome()
    await home.init_async(config.access_point, config.auth_token)
    await home.get_current_state_async()

    home.onEvent += print_events
    await home.enable_events()

    try:
        while True:
            await asyncio.sleep(1)
    finally:
        await home.disable_events_async()


asyncio.run(main())

Paths for config.ini

The scripts will look for a config.ini in 3 different locations depending on your OS. Copy the file to one of these locations so that it will be accessible for the scripts.

General
- current working directory
Windows
- %APPDATA%\homematicip-rest-api
- %PROGRAMDATA%\homematicip-rest-api
Linux
- ~/.homematicip-rest-api/
- /etc/homematicip-rest-api/
MAC OS
- ~/Library/Preferences/homematicip-rest-api/
- /Library/Application Support/homematicip-rest-api/

New devices and config dump

If your device is missing from the list below, or is listed but does not do what you need, open an issue with a configuration dump attached. A dump is what makes a device implementable without owning the hardware.

From Home Assistant, which is the shortest path if you use it: open Settings > Devices & services > Homematic IP Cloud, use the three-dot menu next to your access point and choose Download diagnostics. The result is already redacted and contains everything needed.

From this library, if you have it set up:

hmip_cli --dump-configuration --anonymize

--anonymize replaces the identifying values with placeholders: every GUID, every SGTIN serial number, the refresh token, and your city and coordinates. It does not touch the names you gave your devices and groups, so check the output before posting it publicly.

Please include:

the model number as printed on the device, for example HmIP-WGRC
what the device should do that the library cannot do yet
the dump itself, as a gist if it is long

Device support

A checked box means the model is mapped to a device class here, so its readings and commands are available. An unchecked box means the model is known but not implemented, usually because nobody has sent a dump for it yet, see New devices and config dump.

Radio and wired devices are in one list; wired models carry the HMIPW prefix. Entries marked *powered by HmIP are third-party devices speaking the Homematic IP protocol.

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
homematicip_demo		homematicip_demo
scripts		scripts
src/homematicip		src/homematicip
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE.txt		LICENSE.txt
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
codecov.yml		codecov.yml
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
readthedocs.yaml		readthedocs.yaml
requirements.txt		requirements.txt
requirements_dev.txt		requirements_dev.txt
requirements_docs.txt		requirements_docs.txt
review.md		review.md
run.py		run.py
setup.cfg		setup.cfg
setup.py		setup.py
test.py		test.py
test_aio.py		test_aio.py

Navigation Menu

Repository files navigation

HomematicIP REST API

Using Home Assistant?

Get Help / Discord

📖 Documentation

Support me

Thanks

Installation

Usage

Generate a token

Use the CLI

Examples

Events

Paths for config.ini

New devices and config dump

Device support

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

HomematicIP REST API

Using Home Assistant?

Get Help / Discord

📖 Documentation

Support me

Thanks

Installation

Usage

Generate a token

Use the CLI

Examples

Events

Paths for config.ini

New devices and config dump

Device support

About

Topics

Resources

Code of conduct

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages