Getting Started
Installation
Just run pip3 install -U homematicip in the command line to get the package. This will install (and update) the library and all required packages
Getting the AUTH-TOKEN
Before you can start using the library you will need an auth-token. Otherwise the HMIP Cloud will not trust you.
You will need:
Access to an active Access Point (it must glow blue)
the SGTIN of the Access Point
[optional] the PIN
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.
To get an auth-token you have to run the script hmip_generate_auth_token which is installed with the library.
`sh
hmip_generate_auth_token
`
It will generate a config.ini in your current working directory. The scripts which are using this library are looking for this file to load the auth-token and SGTIN of the Access Point. You can either place it in the working directory when you are running the scripts or depending on your OS in different “global” folders:
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/
Using 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.
Get Information about devices and groups
Commands are bound to the channel type. To get a list of all allowed actions for a device you can write hmip_cli -d {deviceid} –print-allowed-commands or hmip_cli -d {deviceid} -ac.
To get infos for a device and its channels use the –print-infos argument in combination with -d for a device or -g for a group.
Examples
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 toogle 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.
Batch Testing of applicable commands
HomematicIP devices can have different channels and each channel can have different commands. To test which commands are applicable for a channel, you can use the hmip_batch script.
This script will try to execute commands for a device and print the result. It will also print the commands which are not applicable for the device.
The script takes the device ID and the channel index as arguments. Required is the json-batch file which contains the commands.
> Please pay close attention to the parameters used for each command. Incorrect or inappropriate parameters may lead to unexpected behavior or even malfunction of your HomematicIP devices. Executing commands is at your own risk. Always double-check the documentation and ensure you understand the effects of each command before using it in your environment.
Following steps are required: - Install this library with pip pip install -U homematicip - Get an access token as described above - Get your device ID and channel index from the device list using hmip_cli –list-devices or hmip_cli –dump-configuration - Download JSON Batch File from https://github.com/hahn-th/homematicip-rest-api/blob/master/homematicip_demo/hmip_batch.json - Edit the JSON Batch File to choose which commands you want to test. You can enable or disable commands by setting the “active” flag to true or false.
With the “active” flag you can enable or disable commands.
To run the batch test, use the following command:
`sh
hmip_batch -d <device-id> -i <channel-index> <path-to-json-batch-file>
`