search

hahn-th / homematicip-rest-api

A python wrapper for the homematicIP REST API (Access Point Based)
https://hahn-th.github.io/homematicip-rest-api/
GNU General Public License v3.0
218 stars 63 forks source link
cloud homematicip python-wrapper python3

readme

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.

PyPI download month PyPI version fury.io Discord CircleCI PyPI - Python Version

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

:book: New Documentation

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

Support me

:heart: 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:

Examples

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.