Tutorial: Integrating VC with DomoticZ

[Nodo]

Good day,

In this integration tutorial between VC and the awesome free and open source home automation tool "DomoticZ" I will try to start from basic use to more advanced options.
We are going to assume that your DomoticZ setup is working flawlessly and that all you need is to integrate your existing DomoticZ setup with VC.

First off, the documentation references we should consult are:
1- DomoticZ API https://www.domoticz.com/wiki/Domoticz_API/JSON_URL's

[Will add more references once the tutorial is complete]

This tutorial will be divided into three parts:
Part One: Preparing all the information we will later need.
Part Two: Sending commands to DomoticZ.
Part Three: Getting information from DomoticZ.

Part One - Preparing Info

In this part we will be preparing all the information we need for sending/receiving commands to/from DomoticZ.

1- DomoticZ server`s IP address: if DomoticZ is on the same machine as VC you can safely use the IP mentioned below. Else, if DomoticZ is on a different machine, you would need the IP of that machine on your LAN.

Code: [Select]

DomoticZ IP = 127.0.0.1
2- DomoticZ webserver`s port: By default, the port is "8080".

3- (Optional) DomoticZ username and password: If you already specified username and password for DomoticZ.

4- Specific Switch IDx: Each switch in DomoticZ has its own unique ID, to get this unique ID:

• Open your browser and go to http://127.0.0.1:8080
• Enter username and password, if prompted.
• Click Setup -> Devices
• In the Devices table, identify the "Name" and "idx" columns as identified in the image below.

Now, we know that the switch "testSwitch" has an idx of 15.

Part Two - Sending Commands to DomoticZ

The most basic feature is to be able to send commands to DomoticZ to turn a switch on/off.

To test this out on the testSwitch we dealt with earlier to turn that switch "on", we need to open our browser and type:

Code: [Select]

http://127.0.0.1:8080/json.htm?type=command&param=switchlight&idx=15&switchcmd=On
The format for this command is as follows:

Code: [Select]

http://(IP Address):(Port)/json.htm?type=command&param=switchlight&idx=(Switch ID)&switchcmd=On
Okay, what if we have setup a username and password for DomoticZ server ?

In this case we change the format to:

Code: [Select]

http://username:password@127.0.0.1:8080/json.htm?type=command&param=switchlight&idx=15&switchcmd=On
If you noticed at the end of this url after the idx part, we have a

Code: [Select]

switchcmd=On
All we need to do to turn this switch off is to replace "On" by "off" as follows:

Code: [Select]

http://127.0.0.1:8080/json.htm?type=command&param=switchlight&idx=15&switchcmd=Off
Now that we`ve verified that we can communicate with DomoticZ, it is time to finalize this part integrating what we have learnt with VC.


All we need to do in VC is a "scrape" action in a command group with the phrase of our choice, in the following code snippet, the phrase used is "Turn On Test Switch" to turn on the switch and "Turn Off Test Switch" to turn it off.

Code: [Select]

<?xml version="1.0" encoding="utf-16"?>
<!--VoxCommando 2.2.0.9-->
<commandGroup open="True" name="DomoticZ" enabled="True" prefix="" priority="0" requiredProcess="" description="">
  <command id="261" name="Turn Switch On" enabled="true" alwaysOn="False" confirm="False" requiredConfidence="0" loop="False" loopDelay="0" loopMax="0" description="">
    <action>
      <cmdType>Scrape</cmdType>
      <params>
        <param>http://127.0.0.1:8080/json.htm?type=command&param=switchlight&idx=15&switchcmd=On</param>
      </params>
      <cmdRepeat>1</cmdRepeat>
    </action>
    <phrase>Turn On test Switch</phrase>
  </command>
  <command id="278" name="Turn Switch Off" enabled="true" alwaysOn="False" confirm="False" requiredConfidence="0" loop="False" loopDelay="0" loopMax="0" description="">
    <action>
      <cmdType>Scrape</cmdType>
      <params>
        <param>http://127.0.0.1:8080/json.htm?type=command&param=switchlight&idx=15&switchcmd=Off</param>
      </params>
      <cmdRepeat>1</cmdRepeat>
    </action>
    <phrase>Turn off test Switch</phrase>
  </command>
</commandGroup>
 
All you need to change in that code is the "idx" of the switch you want to turn on/off and of course the phrase needed.

Simply clone these commands to add more switches and change "idx" and the phrase to trigger the different commands.

In the next part we will go through more advanced topics about automating the process of getting device IDs and getting information from DomoticZ in a way that VC understands.

Hope this tutorial was easy to follow and stay tuned for the final part .

[Nodo]

Reserved

[jitterjames]

Thanks Nodo. The first part of your tutorial looks splendid and I look forward to seeing the rest, whenever it is ready. 

[sainf]

great tutorial looking forward to next as well.

[Pastis]

thank you ! A domoticz plugin would be wonderful...

[nime5ter]

A plugin is not needed,  as Domoticz works quite well with VC out of the box.
One needs to become familiarized with VC a little, but not much.

Send notifications from Domoticz to VC by generating VC events:
http://voxcommando.com/forum/index.php?topic=2522

Example commands, including how to generate payload xml for device names:

http://voxcommando.com/forum/index.php?topic=2514.0