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.

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

📖 New Documentation

There is a new documentation site unter https://hahn-th.github.io/homematicip-rest-api which is still under construction.

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

Just run pip install -U homematicip to get the package

"Nightly" Builds

Each push on the master branch will trigger a build. That way you can test the latest version of the library with your systems. Just run pip install -U homematicip --pre to get the package.

New devices and config dump

If you missing a device which is not implemented yet, open an issue and append a dump of your configuration to it using https://gist.github.com. To create a dump use the CLI: python hmip_cli.py --dump-configuration --anonymize. See Usage for more instructions.

Usage

Generate Token

First run python hmip_generate_auth_token.py (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.py 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:

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

Examples

hmip_cli.py for listing devices, groups, securityJournal; setting labels, turning switches on/off
Sample Projects are under ./homematicip-samples

Implemented Stuff

Homematic IP Devices:

Homematic IP Wired Devices (no radio signal):

Events

It’s also possible to use push notifications based on a websocket connection:

    # Example function to display incoming events.
    def print_events(event_list):
        for event in event_list:
            print("EventType: {} Data: {}".format(event["eventType"], event["data"]))


    # Initialise the API.
    config = homematicip.find_and_load_config_file()
    home = Home()
    home.set_auth_token(config.auth_token)
    home.init(config.access_point)

    # Add function to handle events and start the connection.
    home.onEvent += print_events
    home.enable_events()

    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        print("Interrupt.")

Pathes 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/