search

KiboOst / php-devoloDHC

php API providing control over Devolo Home Control
MIT License
11 stars 0 forks source link
automation devolo domotic home home-control php php-api zwave

readme

php-devoloDHC

php API for Devolo Home Control

This php API allows you to control your Devolo Home Control devices. The following devices are currently supported:

Changing settings will appear in Devolo web interface / Apps daily diary with your account as usual.

Feel free to submit an issue or pull request to add more.

Need a python version of this API ? python-devoloDHC

This isn't an official API | USE AT YOUR OWN RISK!
Anyway this API use exact same commands as your Devolo Home Control, which is based on ProSyst mBS SDK. When you ask bad stuff to the central, this one doesn't burn but just answer this isn't possible or allowed.
This API is reverse-engineered, provided for research and development for interoperability.

:exclamation: WARNING :exclamation:

I'm sorry to say that I have switch to Jeedom and do not use anymore Devolo Home Control solution. This API has work flawlessly since it's creation here, but in case of coming problems I won't be able to fix or extend it anymore.

If someone want to continue further development of this API, contact me.

Requirements
How-to
Connection
Reading datas
Changing datas
Consumption
Unsupported device
Version history

Requirements

⇑

How-to

Connection

require($_SERVER['DOCUMENT_ROOT'].'/path/to/phpDevoloAPI.php');
$DHC = new DevoloDHC($login, $password);
if (isset($DHC->error)) echo $DHC->error;

If you have several Central Units, or keep the demo central on your mydevolo page, you can choose which to connect to:

//(login | password | connect or not, default true | which central, default 0)
$DHC = new DevoloDHC($login, $password, true, 1);
if (isset($DHC->error)) echo $DHC->error;

Let the fun begin:

//get some infos on your Devolo Home Control box:
echo "__infos__<br>";
$infos = $DHC->getInfos();
echo "<pre>".json_encode($infos['result'], JSON_PRETTY_PRINT)."</pre><br>";

⇑

READING OPERATIONS

Change devices names by yours!

//get all devices in a zone:
$zone = $DHC->getDevicesByZone('living room');
echo "<pre>zone:<br>".json_encode($zone, JSON_PRETTY_PRINT)."</pre><br>";

//get rule or timer state:
$state = $DHC->isRuleActive('MyRule');
echo "Rule state:".$state['result']."<br>";
$state = $DHC->isTimerActive('MyTimer');
echo "Timer state:".$state['result']."<br>";

//Check if a device is on (0=off, 1=on)
$state = $DHC->isDeviceOn('My Wall Plug');
echo "Device state:".$state['result']."<br>";

//Check for devices with 2 relays (eg. Qubino Flush 2 Relay ZMNHBD1) is on (0=off, 1=on)
//contact 1
$state = $DHC->isDeviceOn('myRelay', 1);
echo "Device state:".$state['result']."<br>";
//contact 2
$state = $DHC->isDeviceOn('myRelay', 2);
echo "Device state:".$state['result']."<br>";
//all contacts
$state = $DHC->isDeviceOn('myRelay', 'all');
echo "Device state:".$state['result']."<br>";

//check a device battery level:
$batteryLevel = $DHC->getDeviceBattery('My Motion Sensor');
echo "BatteryLevel:".$batteryLevel['result']."<br>";

//get all batteries level under 20% (ommit argument to have all batteries levels):
$BatLevels = $DHC->getAllBatteries(20);
echo "<pre>Batteries Levels:<br>".json_encode($BatLevels['result'], JSON_PRETTY_PRINT)."</pre><br>";

//get daily diary, last number of events:
$diary = $DHC->getDailyDiary(10);
echo "<pre>diary:<br>".json_encode($diary['result'], JSON_PRETTY_PRINT)."</pre><br>";

//get daily device stat:
//0:today, 1:yesterday, 2:day before yesterday
$stats = $DHC->getDailyStat('My MotionSensor', 0)

//get weather report:
$weather = $DHC->getWeather()
echo "<pre>weather:<br>".json_encode($weather, JSON_PRETTY_PRINT)."</pre><br>";

//Get one device states (all sensors):
$states = $DHC->getDeviceStates('My Motion Sensor');
echo "<pre>States: My Siren:".json_encode($states, JSON_PRETTY_PRINT)."</pre><br>";

//Get one sensor data for any device, like light from a Motion Sensor or energy from a Wall Plug:
$data = $DHC->getDeviceData('My Motion Sensor', 'light');
echo "MyMotionSensor luminosity: ".$data['result']['value']."<br>";
$data = $_DHC->getDeviceData('Radiator', 'temperature');
echo $data['result']['value'];

//You can first ask without data, it will return all available sensors datas for this device:
$data = $DHC->getDeviceData('My Wall Plug');
echo "<pre>MyWallPlug available states:<br>".json_encode($data, JSON_PRETTY_PRINT)."</pre><br>";

//get url from http device:
$url = $DHC->getDeviceURL('myhttp device');

//get message data:
$url = $DHC->getMessageData('MyAlert');

⇑

CHANGING OPERATIONS

Change devices names by yours!

//TURN DEVICE ON(1) or OFF(0):
//supported: all on/off devices and http devices
$DHC->turnDeviceOnOff("My Room wallPlug", 1);

//for devices with 2 relays as Qubino Flush 2 Relay ZMNHBD1 (device name, state, contact):
//contact 1 on
$DHC->turnDeviceOnOff('myRelay', 1, 1);
//contact 2 on
$DHC->turnDeviceOnOff('myRelay', 1, 2);
//all contacts on
$DHC->turnDeviceOnOff('myRelay', 1, 'All');

//TURN GROUP ON(1) or OFF(0):
$DHC->turnGroupOnOff('My Plugs Group', 1);

//RUN HTTP DEVICE:
$DHC->turnDeviceOnOff('My http device', 1); //, 0 won't do anything of course.

//START SCENE:
$DHC->startScene('We go out');

//SEND MESSAGE:
$DHC->sendMessage('Alert');

//CHANGE THERMOSTAT/VALVE VALUE:
$targetValue = $DHC->setDeviceValue('My radiator', 21);
echo "<pre>".json_encode($targetValue['result'], JSON_PRETTY_PRINT)."</pre><br>";
$_DHC->setDeviceValue('my thermostat', 19);
//press thermostat button:
$_DHC->pressDeviceKey('my thermostat', 1);

//TURN SIREN ON: (last number is the indice of the tone in the interface list. For example, 1 is alarm and won't stop! 0 will!)
$DHC->setDeviceValue('My Devolo Siren', 5);

//SET SHUTTER OPENING:
$DHC->setDeviceValue('qubShutter', 50);

//SET DIMMER VALUE:
$DHC->setDeviceValue('qubDimmer', 50);

//PRESS REMOTE SWITCH KEY OR KEY FOB KEY:
$DHC->pressDeviceKey('MySwitch', 3);

//TURN RULE ACTIVE (1 or 0)
$DHC->turnRuleOnOff('MyRule', 1);

//TURN TIMER ACTIVE (1 or 0)
$DHC->turnTimerOnOff('MyTimer', 1);

//TURN OFF DAILY DIARY REPORT (true/false):
$DHC->setDeviceDiary('movekitchen', false);

⇑

Consumption

Some people would like to have more than 3days consumption log for devices like Wall Plugs. Here are two functions to log consumptions, and read them between two dates of choice. So you can make a cron task to call this function everyday, it will log the yesterday total consumption of each Wall Plugs:

$DHC->logConsumption('log.json');

If you don't provide a file path, or it can't write to, the api will return an error, but also provide the result (so you can write your own custom functions).
Then, to read the log and know consumption for a month, or along summer/winter etc:

$stats = $DHC->getLogConsumption('log.json', '01.03.2017', '31.03.2017');
echo "<pre>".json_encode($stats, JSON_PRETTY_PRINT)."</pre><br>";

Of course, it needs a valid previously saved log file by the api. You can provide no dates (full log), or only one (set first as null if needed). Just respect day.month.year (php 'd.m.Y').

For visual logs feedback, have a look here

⇑

Unsupported device

If you have unsupported device, you can call special function with this device and post the return in a new issue.

Request for unsupported device

$help = $DHC->debugDevice('MyStrangeDevice');

⇑

Version history

v 2.80 (2017-09-23)

v 2.72 (2017-06-02)

qubino/devolo 1 relay and dimmer should works also

v 2.6 (2017-04-05)

v 2.55 (2017-03-30)

v 2.5 (2017-03-29)

v 2.3 (2017-03-27)

v 2.2 (2017-03-22)

v 2.0 (2017-03-18)

v 1.2 (2017-03-14)

v 1.1 (2017-03-13)

v 1.0 (2017-03-12)

⇑

License

The MIT License (MIT)

Copyright (c) 2017 KiboOst

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.