Homegear Scripting Tutorial =========================== Homegear is not just a communication backend for different home automation systems like Homematic or Philips Hue. It can also be used to react automatically on events or trigger other actions. For this it uses PHP as scripting language. This document shall give an overview on Homegear and how it can interact with OpenHAB. These two programs slightly overlap in functionality which might be a bit confusing in the first place. OpenHAB as well as Homegear can be scripted to execute actions on events. Using OpenHAB for triggering specific actions on events might be easier the first time. On the other hand, scripting using Homegear is very fast, as the additional communication between Homegear and OpenHAB is not needed. In this document, both ways shall be explained with help of a simple use case. ###The Use Case The idea is to have one switch "Cinema Mode", which turns on and off different lights for optimal cinema experience in the living room. It is assumed that four lights are available, where one oh these is dimmable. For optimal light conditions, lamp 1 and two shall be turned on, light three shall be dimmed to 50% and lamp 4 for shall be turned off. ### Preconditions It is assumed, that the Homematic devices are paired with Homegear. In this tutorial, the configuration is as follows: ID │ Name │ Address │ Serial Number │ Type │ Type String │ Firmware │ Config Pending │ Unreach │ Low Bat ────┼────────┼──────────┼───────────────┼──────┼───────────────────┼──────────┼────────────────┼─────────┼──────── 1 │ Lamp 1 │ 2E401D │ LTK0068462 │ 00A1 │ HM-LC-Sw1-Pl-2 │ 2.4 │ No │ No │ No 2 │ Lamp 2 │ 2F63DE │ LTK0077362 │ 00A1 │ HM-LC-Sw1-Pl-2 │ 2.4 │ No │ No │ No 3 │ Lamp 3 │ 38C158 │ MEQ0168976 │ 0068 │ HM-LC-Dim1TPBU-FM │ 2.7 │ No │ No │ No 4 │ Lamp 4 │ 3ACD16 │ MEQ0488708 │ 00AC │ HM-ES-PMSw1-Pl │ 1.6 │ No │ No │ No ────┴────────┴──────────┴───────────────┴──────┴───────────────────┴──────────┴────────────────┴─────────┴──────── The list was created using the Homegear client homegear -r > families select 0 > ls OpenHAB Approach ---------------- To control actors from OpenHAB, they have to be bound. Two common approaches are available: Homematic binding and MQTT binding. The differences and advantages are discussed in the [Openhab Binding Tutorial](OpenHAB_Binding.md). In this tutorial, the actors are bound using the Homematic binding. The items configuration is as follows: tutorial.items Switch Lamp1 "Lamp 1" { homematic="address=LTK0068462, channel=1, parameter=STATE" } Switch Lamp2 "Lamp 2" { homematic="address=LTK0077362, channel=1, parameter=STATE" } Dimmer Lamp3 "Lamp 3 [%d %%]" {homematic="address=MEQ0168976, channel=1, parameter=LEVEL"} Switch Lamp4 "Lamp 4" { homematic="address=MEQ0488708, channel=1, parameter=STATE" } Switch CinemaMode "Cinema Mode" { autoupdate=false } The line defines an internal switch which is not bound to any device. _autoupdate_ is set to false, as the state is only updated if the conditions for cinema mode are met. The sitemap for these switches is very simple: tutorial.sitemap sitemap default label="Main Menu" Switch item=CinemaMode Switch item=Lamp1 Switch item=Lamp2 Slider item=Lamp3 Switch item=Lamp4 Now, everything is set to wiring things together. One rule is needed which sets the lamps to the desired state when the virtual CinemaMode switch is turned on. Another rule is needed which sets the CinemaMode switch to off, when any state of the lamps change. tutorial.rules rule "Switch Cinema Mode ON" when Item CinemaMode received command ON then { CinemaMode.postUpdate(ON) Lamp1.sendCommand(ON) Lamp2.sendCommand(ON) Lamp3.sendCommand(33) Lamp4.sendCommand(OFF) } end rule "CinemaMode inactive" when Item Lamp1 changed to OFF or Item Lamp2 changed to OFF or Item Lamp3 changed from 33 or Item Lamp4 changed to ON then { Cinemamode.postUpdate(OFF) } end Homegear Approach ----------------- Homegear provides PHP as scripting language. Using scripts, event listener can be added so that some actions are executed on specific events. Scripts have to be stored in the script folder (normally /var/lib/homegear/scripts). The script can be executed with homegear -e rs myscript.php To get information if everything worked, print the error code. 0 means that the execution were successfull. Note, that the scripts can be arranged in subfolders. The script /var/lib/homegear/scripts/myscripts/script1.php can be executed with the following command: homegear -e rs myscripts/script1.php; echo $? > 0 Now, we can write a script which adds a new system variable and triggers action if the variable is set to true. To listen on variable changes, we have to use the event listener (https://www.homegear.eu/index.php/XML_RPC_EventDescription). /var/lib/homegear/scripts/myscripts/cinemamode.php: removeEvent("Cinema mode activate; Lamp 1"); $hg->addEvent( array( "ID" => "Cinema mode activate; Lamp 1", "TYPE" => "event", "ENABLED" => true, "PEERID" => 0, "PEERCHANNEL" => -1, "VARIABLE" => "Kinomode", "TRIGGER" => 8, "TRIGGERVALUE" => true, "EVENTMETHOD" => "setValue", "EVENTMETHODPARAMS" => array (1, 1, "STATE", true) ) ); //$hg->removeEvent("Cinema mode activate; Lamp 2"); $hg->addEvent( array( "ID" => "Cinema mode activate; Lamp 2", "TYPE" => "event", "ENABLED" => true, "PEERID" => 0, "PEERCHANNEL" => -1, "VARIABLE" => "Kinomode", "TRIGGER" => 8, "TRIGGERVALUE" => true, "EVENTMETHOD" => "setValue", "EVENTMETHODPARAMS" => array (2, 1, "STATE", true) ) ); //$hg->removeEvent("Cinema mode activate; Lamp 3"); $hg->addEvent( array( "ID" => "Cinema mode activate; Lamp 3", "TYPE" => "event", "ENABLED" => true, "PEERID" => 0, "PEERCHANNEL" => -1, "VARIABLE" => "Kinomode", "TRIGGER" => 8, "TRIGGERVALUE" => true, "EVENTMETHOD" => "setValue", "EVENTMETHODPARAMS" => array (3, 1, "LEVEL", "0.3") ) ); //$hg->removeEvent("Cinema mode activate; Lamp 4"); $hg->addEvent( array( "ID" => "Cinema mode activate; Lamp 4", "TYPE" => "event", "ENABLED" => true, "PEERID" => 0, "PEERCHANNEL" => -1, "VARIABLE" => "Kinomode", "TRIGGER" => 8, "TRIGGERVALUE" => true, "EVENTMETHOD" => "setValue", "EVENTMETHODPARAMS" => array (4, 1, "STATE", false) ) ); // Add event listeners to set cinemamode to false if any lamp changed it state //$hg->removeEvent("Cinema mode inactive; Lamp 1"); $hg->addEvent( array( "ID" => "Cinema mode inactive; Lamp 1", "TYPE" => "event", "ENABLED" => true, "PEERID" => 1, "PEERCHANNEL" => 1, "VARIABLE" => "STATE", "TRIGGER" => 9, "TRIGGERVALUE" => true, "EVENTMETHOD" => "setSystemVariable", "EVENTMETHODPARAMS" => array ("Kinomode", false) ) ); //$hg->removeEvent("Cinema mode inactive; Lamp 2"); $hg->addEvent( array( "ID" => "Cinema mode inactive; Lamp 2", "TYPE" => "event", "ENABLED" => true, "PEERID" => 2, "PEERCHANNEL" => 1, "VARIABLE" => "STATE", "TRIGGER" => 9, "TRIGGERVALUE" => true, "EVENTMETHOD" => "setSystemVariable", "EVENTMETHODPARAMS" => array ("Kinomode", false) ) ); //$hg->removeEvent("Cinema mode inactive; Lamp 3"); $hg->addEvent( array( "ID" => "Cinema mode inactive; Lamp 3", "TYPE" => "event", "ENABLED" => true, "PEERID" => 3, "PEERCHANNEL" => 1, "VARIABLE" => "LEVEL", "TRIGGER" => 9, "TRIGGERVALUE" => "0.3", "EVENTMETHOD" => "setSystemVariable", "EVENTMETHODPARAMS" => array ("Kinomode", false) ) ); //$hg->removeEvent("Cinema mode inactive; Lamp 4"); $hg->addEvent( array( "ID" => "Cinema mode inactive; Lamp 4", "TYPE" => "event", "ENABLED" => true, "PEERID" => 4, "PEERCHANNEL" => 1, "VARIABLE" => "STATE", "TRIGGER" => 9, "TRIGGERVALUE" => false, "EVENTMETHOD" => "setSystemVariable", "EVENTMETHODPARAMS" => array ("Kinomode", false) ) ); ?> Note that homegear stores even listeners into a database. This means that all event listeners are also available after a restart of homegear. However, the function addEvent() complains if an event listener with that ID already exists. So, removeEvent() has to be executed before updating the event listener with an existing ID. See https://github.com/Homegear/Homegear/issues/260 for details.