General

Homegear::configureGateway

Signatures

void configureGateway(string $host, int $port, $caCert, $gatewayCert, $gatewayKey, $password)

Description

This method remotely sets the certificates on an unconfigured Homegear Gateway. To find gateways and to check if a gateway is configured, you can use Homegear::ssdpSearch("urn:schemas-upnp-org:device:basic:1", 5000). The response contains the field HG-Gateway-Configured which is set to 0 if the gateway is unconfigured. The certificates can be generated using Homegear Management.

Parameters

192.168.178.104

2017

aJn10ymAkloiq28nKlOlf4QjsN

Return Value

Exceptions

Homegear::download

Signatures

bool download(string $hostname, int $port, string $path, string $filename, string $caFile, bool $verifyCertificate)

Description

This method downloads a file from a web server. It was implemented so you can download files (SSL encrypted) on embedded systems when OpenSSL certificate verification is not working. You should not use it to download large files because the download is fully saved to the memory before it is written to the disk.

Parameters

www.example.com

443

/path/to/file.dat

/local/path/to/file.dat

/path/to/my/ca-certificates.pem

true

Return Value

Homegear::getHttpContents

Signatures

string getHttpContents(string $hostname, int $port, string $path, string $caFile, bool $verifyCertificate)

Description

This method returns the source of a web page as a string. It was implemented to add the possibility of accessing web pages in an SSL-encrypted manner on embedded systems when OpenSSL certificate verification is not working.

Parameters

www.example.com

443

/path/to/file.html

/path/to/my/ca-certificates.pem

true

Return Value

Homegear::getScriptId

Signatures

string getScriptId()

Description

Homegear assigns a unique ID to each script. This ID is used to identify the script in different threads. Additionally, a password token is generated, which means that any given script cannot accidently register as a different script. getScriptId() returns the ID and the token for the current script. The string that is returned can then be used to register new threads using "registerThread()". getScriptId() returns valid data only if this method is called in the main thread or after "registerThread()" has been called.

Parameters

This method has no parameters.

Return Value

Example Output

Homegear::getScriptId()

4241

Homegear::listRpcClients

Signatures

array listRpcClients()

Description

This method returns information about all registered RPC event servers (all servers that have called init()).

Parameters

This method has no parameters.

Return Value

Exceptions

Example Output

var_dump($hg->listRpcClients())

array(1) {
  [0]=>
  array(13) {
    ["BINARY_RPC"]=>
    bool(true)
    ["CLIENT_ID"]=>
    int(0)
    ["INIT_BINARY_MODE"]=>
    bool(true)
    ["INIT_INTERFACE_ID"]=>
    string(30) "HomegearLib.192.168.0.137:9877"
    ["INIT_JSON_MODE"]=>
    bool(false)
    ["INIT_KEEP_ALIVE"]=>
    bool(true)
    ["INIT_NEW_FORMAT"]=>
    bool(true)
    ["INIT_SUBSCRIBE_PEERS"]=>
    bool(false)
    ["INIT_URL"]=>
    string(27) "binary://192.168.0.137:9877"
    ["IP_ADDRESS"]=>
    string(13) "192.168.0.137"
    ["JSON_RPC"]=>
    bool(false)
    ["WEBSOCKET"]=>
    bool(false)
    ["XML_RPC"]=>
    bool(false)
  }
}

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->listRpcClients());'

Homegear::log

Signatures

bool log(int $logLevel, string $message)

Description

This method writes a message to the script engine log and (if there are errors) to the error log file (/var/log/homegear/homegear-scriptengine.log and /var/log/homegear/homegear-scriptengine.err by default). To write to the main log file (homegear.log and homegear.err), use the RPC method writeLog().

Parameters

4

My message

Return Value

Errors

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->log(3, "Hello Homegear!"));'

Homegear::mqttPublish

Signatures

void mqttPublish(string $topic, string $payload)

Description

This method publishes to a MQTT topic. For this to work, make sure, MQTT is enabled in "mqtt.conf".

Parameters

MyTopic

{"value": 5}

Exceptions

Homegear::peerExists

Signatures

bool peerExists(int peerId)

Description

This method checks if a peer is known to Homegear.

Parameters

43

Return Value

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->peerExists(12));'

Homegear::pollEvent

Signatures

array pollEvent([int $timeout = -1])

Description

This method blocks until an event from Homegear is received. General events and events that concern all devices are always returned. Device value and configuration changes are returned only if the script has called subscribePeer() for the device. See the RPC reference for "event", "newDevices", "deleteDevices", and "updateDevice" for more information about the returned values. If you are calling pollEvent() from a thread that is not the main thread, you need to call registerThread() first. When Homegear shuts down, pollEvent() returns

array(
	"TYPE" => "event",
	"PEERID" => 0,
	"CHANNEL" => -1,
	"VARIABLE" => "DISPOSING",
	"VALUE" => true
)

Parameters

5000

Return Value

Errors

Example

<?php
/**
 * Class to share data between the main script and the event thread.
 */
class SharedData extends Threaded
{
    public function __construct($scriptId)
    {
        $this->scriptId = $scriptId;
        $this->resetData();
    }

    public function resetData()
    {
        $this->peerId = 0;
        $this->variable = '';
        $this->value = 0;
    }

    public function setData($peerId, $variable, $value)
    {
        $this->peerId = $peerId;
        $this->variable = $variable;
        $this->value = $value;
    }

    public function getPeerId()
    {
        return $this->peerId;
    }

    public function getVariable()
    {
        return $this->variable;
    }

    public function getValue()
    {
        return $this->value;
    }

    public function run() {}
}

/**
 * Class to process events received from Homegear
 */
class EventThread extends Thread
{
    private $sharedData;
    public function __construct($sharedData)
    {
        $this->sharedData = $sharedData;
    }
    
    public function run()
    {
        $hg = new \Homegear\Homegear();
        // Make the new thread known to Homegear. Without this, pollEvent() is not working.
        if($hg->registerThread($this->sharedData->scriptId) === false)
        {
            $hg->log(2, "Could not register thread.");
            return;
        }

        // Get all devices
        $devices = $hg->listDevices(false, array("ID"));
        foreach($devices as $device)
        {
            // Subscribe to device to receive events.
            $hg->subscribePeer($device["ID"]);
        }
        
        // Run the thread until Homegear shuts down.
        while(!$hg->shuttingDown())
        {
            // Wait for event.
            $result = $hg->pollEvent();
            if($result !== false && $result["TYPE"] == "event")
            {
                // Pass result to main thread
                $this->sharedData->setData($result["PEERID"], $result["VARIABLE"], $result["VALUE"]);
                
                // Wake up main thread
                $this->synchronized(function($thread){ $thread->notify(); }, $this);
            }
        }
    }
}

$hg = new \Homegear\Homegear();

// Get script id and password token.
$scriptId = $hg->getScriptId();

// Create new object for sharing data between main and event thread.
$sharedData = new SharedData($scriptId);

// Create and start new event thread.
$thread = new EventThread($sharedData);
$thread->start();

// Run main thread until Homegear shuts down.
while(!$hg->shuttingDown())
{
    // Wait to be notified by event thread with a timeout of 5 seconds.
    $thread->synchronized(function($thread){ $thread->wait(5000000); }, $thread);
    
    // Check if new data is available was set.
    if($sharedData->getVariable())
    {
        // Print variable name and value of last event to log.
        $hg->log(4, "Got event: Peer: ".$sharedData->getPeerId().", variable: ".$sharedData->getVariable().", value: ".$sharedData->getValue());
        // Reset data.
        $sharedData->resetData();
    }
}

// Wait for event thread to finish.
$thread->join();
?>

Homegear::raiseDeleteDevice

Signatures

void raiseDeleteDevice(array $serialNumbers)

Description

This method sends deleteDevices() to all RPC event servers that are registered with Homegear. This is done to force the deletion of a device.

Parameters

array("JEQ1827519")

Homegear::registerThread

Signatures

bool registerThread(string $scriptId)

Description

This method makes a new thread known to Homegear. It is required so that the system can receive events.

Parameters

3,MTIzNDU2Nzg5MDEyMzQ1Ng==

Return Value

Example Output

registerThread("3,MTIzNDU2Nzg5MDEyMzQ1Ng==")

true

Homegear::setScriptLogLevel

Signatures

void setScriptLogLevel(int $logLevel)

Description

This method sets the log level for the current script overwriting the global settings. It must be called from the main thread to work for all script threads. If called from a child thread it only sets the log level for this thread.

Parameters

4

Return Value

Errors

Homegear::shuttingDown

Signatures

bool shuttingDown()

Description

This method checks whether Homegear is shutting down. If it returns "true", the script should exit.

Parameters

This method has no parameters.

Return Value

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->shuttingDown());'

Homegear::ssdpSearch

Signatures

bool ssdpSearch(string $stHeader, int $timeout)

Description

This method searches for SSDP devices on the network. It sends a M-SEARCH packet and waits for devices to respond. The header field ST of the response must match $stHeader.

Parameters

urn:schemas-upnp-org:device:ZonePlayer:1

5000

Return Value

Errors

Example Output

ssdpSearch("ssdp:all", 5000)

(Array length=1)
{
  (Struct length=5)
  {
    [additionalFields]
    {
      (Struct length=5)
      {
        [cache-control]
        {
          (String) max-age=1800
        }
        [location]
        {
          (String) http://192.168.0.107:49000/fboxdesc.xml
        }
        [server]
        {
          (String) Fonbox UPnP/1.0 AVM FRITZ!Box Fon WLAN 7390 84.06.83
        }
        [st]
        {
          (String) upnp:rootdevice
        }
        [usn]
        {
          (String) uuid:123402409-bccb-40e7-8e6c-24651156553F::upnp:rootdevice
        }
      }
    }
    [additionalInfo]
    {
      (Struct length=12)
      {
        [UDN]
        {
          (String) uuid:123402409-bccb-40e7-8e6c-24651156553F
        }
        [deviceType]
        {
          (String) urn:schemas-upnp-org:device:fritzbox:1
        }
        [friendlyName]
        {
          (String) Fonbox
        }
        [iconList]
        {
          (Struct length=1)
          {
            [icon]
            {
              (Struct length=5)
              {
                [depth]
                {
                  (String) 8
                }
                [height]
                {
                  (String) 119
                }
                [mimetype]
                {
                  (String) image/gif
                }
                [url]
                {
                  (String) /ligd.gif
                }
                [width]
                {
                  (String) 118
                }
              }
            }
          }
        }
        [manufacturer]
        {
          (String) AVM Berlin
        }
        [manufacturerURL]
        {
          (String) http://www.avm.de
        }
        [modelDescription]
        {
          (String) FRITZ!Box Fon WLAN 7390
        }
        [modelName]
        {
          (String) FRITZ!Box Fon WLAN 7390
        }
        [modelNumber]
        {
          (String) avm
        }
        [modelURL]
        {
          (String) http://www.avm.de
        }
        [presentationURL]
        {
          (String) http://192.168.0.107
        }
        [serviceList]
        {
          (Struct length=1)
          {
            [service]
            {
              (Struct length=5)
              {
                [SCPDURL]
                {
                  (String) /fboxSCPD.xml
                }
                [controlURL]
                {
                  (String) /upnp/control/fritzbox
                }
                [eventSubURL]
                {
                  (String) /upnp/control/fritzbox
                }
                [serviceId]
                {
                  (String) urn:any-com:serviceId:fritzbox
                }
                [serviceType]
                {
                  (String) urn:schemas-any-com:service:fritzbox:1
                }
              }
            }
          }
        }
      }
    }
    [ip]
    {
      (String) 192.168.0.107
    }
    [location]
    {
      (String) http://192.168.0.107:49000/fboxdesc.xml
    }
    [port]
    {
      (Integer64) 49000
    }
  }
}

Homegear::subscribePeer

Signatures

(1) void subscribePeer(int $peerId)
(2) void subscribePeer(int $peerId, int $channel, string $variableName)

Description

This method enables the reception of events for a device. You need to call subscribePeer() for pollEvent() to return events for a device. If you are calling subscribePeer() from a thread that is not the main thread, you need to call registerThread() first.
(1) subscribes to all events of a peer, (2) subscribes to the events of a single variable. (2) can be called to subscribe to multiple variables.

Parameters

32

2

2

Exceptions

Homegear::unsubscribePeer

Signatures

(1) void unsubscribePeer(int $peerId)
(2) void unsubscribePeer(int $peerId, int $channel, string $variableName)

Description

This method disables the reception of events for a device that was previously enabled via the call of subscribePeer(). If you call unsubscribePeer() from a thread that is not the main thread, you need to call registerThread() first.
(1) unsubscribes from all events of that peer, (2) unsubscribes from the event of a single variable. (2) can only be used when the variable to unsubscribe from was explicetly subscribed.

Parameters

32

2

2

Exceptions

lifetick

bool lifetick()

print_v($hg->lifetick());

print_v

Signatures

string print_v(mixed $variable [, bool $return = false])

Description

This method prints human-readable information about a Homegear variable returned by one of the RPC functions.

Parameters

true

Return Value

GPIO Operations

HomegearGpio::close

Signatures

void close(int $index)

Description

This method closes a GPIO that was previously opened with HomegearGpio::open().

Parameters

18

HomegearGpio::export

Signatures

void export(int $index)

Description

This method exports a GPIO. Make sure you have sufficient permissions to do that. If this is not the case, you can set "exportGpios" in /etc/homegear/main.conf. This setting tells Homegear to export the GPIOs when it starts up and before it drops its root privileges.

Parameters

18

HomegearGpio::get

Signatures

bool get(int $index)

Description

This method gets the current state of a GPIO. Before this method is called, the GPIO needs to be opened with HomegearGpio::open().

Parameters

18

Return Value

HomegearGpio::open

Signatures

void open(int $index)

Description

This method opens a GPIO. Make sure you have sufficient authorization to export GPIOs. If this is not the case, you can set "exportGpios" in /etc/homegear/main.conf. This setting tells Homegear to export the GPIOs when it starts up and before it drops its root privileges.

Parameters

18

HomegearGpio::poll

Signatures

int poll(int $index, int $timeout [, bool $debounce = false])

Description

This method waits for a GPIO state change to occur. Before it is called, the GPIO needs to be opened by calling HomegearGpio::open(). This method blocks until the configured edge is detected on the GPIO (see setEdge()). It works only if the GPIO is configured as input. If no state change occurs, this method requires almost no system resources.

Parameters

18

true

Return Value

Errors

Example Output

poll(17, 5000)

1

Example

<?php
/*
 * This example waits for a change on GPIO 22 and mirrors the new state of GPIO 22 to GPIO 24.
 */

use Homegear\HomegearGpio as HomegearGpio;
 
// Create Homegear object.
$hg = new Homegear\Homegear();

// Create GPIO object.
$gpio = new HomegearGpio();

// Open GPIO.
$gpio->open(22);

// Set direction to input.
$gpio->setDirection(22, HomegearGpio::DIRECTION_IN);

// Set edge to both.
$gpio->setEdge(22, HomegearGpio::EDGE_BOTH);

// We just opened the GPIO, so poll to discard the occured change.
$result = $gpio->poll(22, 1);

$result = -2;
while($result == -2) // Stay in loop if poll times out.
{
        // Wait for state change.
        $result = $gpio->poll(22, 5000, true);
}

if($result == -1) die("Error reading GPIO");

$hg->log(4, "Value of GPIO 22: ".$result);

// Close GPIO.
$gpio->close(22);

// Open output GPIO
$gpio->open(24);

// Set direction to output.
$gpio->setDirection(24, HomegearGpio::DIRECTION_OUT);

// Set state of GPIO 24 to state of GPIO 22.
$gpio->set(24, $result);

// Close GPIO 24
$gpio->close(24);
?>

HomegearGpio::set

Signatures

void set(int $index, bool $value)

Description

This method sets the state of a GPIO. Before this method is called, the GPIO needs to be opened with HomegearGpio::open().

Parameters

18

true

HomegearGpio::setDirection

Signatures

void setDirection(int $index, int $direction)

Description

This method sets the direction of a GPIO. Before this method is called, the GPIO needs to be opened with HomegearGpio::open().

Parameters

18

HomegearGpio::DIRECTION_OUT

HomegearGpio::setEdge

Signatures

void setEdge(int $index, int $edge)

Description

This method sets the edge of a GPIO for which you want to generate interrupts. Before this method is called, the GPIO needs to be opened with HomegearGpio::open().

Parameters

18

HomegearGpio::EDGE_FALLING

I²C Communication

HomegearI2c::close

Signatures

bool close(resource $handle)

Description

This method closes an I²C device that was previously opened with HomegearI2c::open().

Parameters

Return Value

Errors

HomegearI2c::open

Signatures

resource open(string $device, int $address)

Description

This method opens an I²C device and returns a device handle that is needed for HomegearI²C::read() and HomegearI²C::write().

Parameters

/dev/ttyAMA0

0x28

Return Value

Errors

HomegearI2c::read

Signatures

string read(resource $handle, int length, bool $returnBinary)

Description

This method reads data from an I²C device that was previously opened with HomegearI2c::open().

Parameters

5

false

Return Value

Errors

HomegearI2c::write

Signatures

bool write(resource $handle, string $data [, bool $dataIsBinary = false])

Description

This method writes data to an I²C device that was previously opened with HomegearI2c::open().

Parameters

8F727ACC3022

true

Return Value

Errors

Licensing

Homegear::checkLicense

Signatures

int checkLicense(int $licenseModuleId, int $familyId, int $deviceId [, string $licenseKey])

Description

This method checks if a device or module is licensed or registers a new license key.

Parameters

0x7000

12

216

ABCDEF-GHIJKL-MNOPQR

Return Value

Errors

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->checkLicense(0x7000, 12, -1, "ABCDEF"));'

Homegear::getLicenseStates

Signatures

array getLicenseStates(int $licenseModuleId)

Description

This method returns all license information known to a license module.

Parameters

0x7000

Return Value

Errors

Exceptions

Homegear::removeLicense

Signatures

int removeLicense(int $licenseModuleId, int $familyId, int $deviceId)

Description

This method removes a license key and activation data previously registered with checkLicense().

Parameters

0x7000

12

216

Return Value

Errors

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->removeLicense(0x7000, 12, -1));'

Modules

Homegear::listModules

Signatures

array listModules()

Description

This method lists all Homegear modules (loaded and not loaded) located in the module directory (/var/lib/homegear/modules by default).

Parameters

This method has no parameters.

Return Value

Exceptions

Example Output

var_dump($hg->listModules())

array(3) {
  [0]=>
  array(5) {
    ["BASELIB_VERSION"]=>
    string(10) "0.6.0-1051"
    ["FAMILY_ID"]=>
    int(0)
    ["FAMILY_NAME"]=>
    string(16) "HomeMatic BidCoS"
    ["FILENAME"]=>
    string(22) "mod_homematicbidcos.so"
    ["LOADED"]=>
    bool(true)
  }
  [1]=>
  array(5) {
    ["BASELIB_VERSION"]=>
    string(10) "0.6.0-1051"
    ["FAMILY_ID"]=>
    int(254)
    ["FAMILY_NAME"]=>
    string(13) "Miscellaneous"
    ["FILENAME"]=>
    string(20) "mod_miscellaneous.so"
    ["LOADED"]=>
    bool(true)
  }
  [2]=>
  array(5) {
    ["BASELIB_VERSION"]=>
    string(10) "0.6.0-1051"
    ["FAMILY_ID"]=>
    int(8)
    ["FAMILY_NAME"]=>
    string(7) "EASYLed"
    ["FILENAME"]=>
    string(14) "mod_easyled.so"
    ["LOADED"]=>
    bool(true)
  }
}

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->loadModule("mod_miscellaneous.so"));'

Homegear::loadModule

Signatures

int loadModule(string $filename)

Description

This method loads a Homegear module from the module directory (/var/lib/homegear/modules by default).

Parameters

mod_insteon.so

Return Value

Errors

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->loadModule("mod_miscellaneous.so"));'

Homegear::reloadModule

Signatures

int reloadModule(string $filename)

Description

This method fully reloads a Homegear module. It can be used to reread the device description files, for example.

Parameters

mod_insteon.so

Return Value

Errors

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->reloadModule("mod_miscellaneous.so"));'

Homegear::unloadModule

Signatures

int unloadModule(string $filename)

Description

This method unloads a Homegear module.

Parameters

mod_insteon.so

Return Value

Errors

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->unloadModule("mod_miscellaneous.so"));'

Nodes

HomegearNodeBase::frontendEventLog

void frontendEventLog(string $message)

frontendEventLog('My message to Node-BLUE.');

HomegearNodeBase::invokeIpcProcessMethod

variant invokeIpcProcessMethod(int $processId, string $methodName, array $parameters)

print_v(invokeIpcProcessMethod(5484, 'myRpcMethod, array('My 1st parameter', 2)));

HomegearNodeBase::invokeNodeMethod

Signatures

mixed invokeNodeMethod(string nodeId, string methodName, array parameters [, bool wait = true])

Description

This method is only available within a Node-BLUE node. It invokes a method defined within another node (except simple PHP and Python nodes) and can therefore be used for inter-node communication. This is especially required for a node to communicate with configuration nodes.

Parameters

"9062b368.e6068"

myMethod

array(5, "param2")

false

Return Value

Example

$this->invokeNodeMethod("9062b368.e6068", "myMethod", array(5, "param2"));

HomegearNodeBase::log

Signatures

bool log(int $logLevel, string $message)

Description

This method is only available within a Node-BLUE node. It writes a message to the flows log and (if there are errors) to the error log file (/var/log/homegear/homegear-flows.log and /var/log/homegear/homegear-flows.err by default). To write to the main log file (homegear.log and homegear.err), use the RPC method writeLog().

Parameters

4

My message

Return Value

Errors

Example

$this->log(3, "Hello Node-BLUE!");

HomegearNodeBase::nodeEvent

Signatures

void nodeEvent(string topic, mixed data[, bool retain = true])

Description

This method sends an event to the Node-BLUE frontend. The following events are available:

• status: Displays a status message below the node. topic needs to be statusBottom/<nodeId> and data an array with the keys text, fill and shape. text can be set to a small string. It is optional and should be short (< 20 characters). fill can be red, green, yellow, blue or grey. Valid values for shape are ring and dot. For example: array('text' => 'connected', 'fill' => 'green', 'shape' => 'dot').
• debug: Appends a message to the frontend debug log. topic has to be set to debug and message to an array with the keys id, name, msg, format and property. id is a node ID that is being displayed as the debug message's header. name is the node's type. msg is the message to display. format is the type of the message and has to be one of: array[<length>], boolean, number, string[<length>], Object or null. property the property of the message that is being shown.

Parameters

"statusBottom/9062b368.e6068"

Return Value

HomegearNodeBase::output

Signatures

void output(int outputIndex, array message)

Description

This method is only available within a Node-BLUE node. It sends data out of the node's outputs to the next connected nodes.

Parameters

2

array('payload' => 21.5)

Serial Communication (TTY)

HomegearSerial::close

Signatures

bool close(resource $handle)

Description

This method closes a serial device that was previously opened with HomegearSerial::open().

Parameters

Return Value

Errors

HomegearSerial::open

Signatures

resource open(string $device, int $baudrate [, bool $evenParity = false [, bool $oddParity = false [, int $characterSize = 8 [, bool $twoStopBits = false]]]])

Description

This method opens a serial device and returns a device handle required for HomegearSerial::read() and HomegearSerial::write(). Remember to close the device with HomegearSerial::close() if you don't need it anymore.

Parameters

/dev/ttyAMA0

19200

true

true

7

true

Return Value

Errors

HomegearSerial::read

Signatures

string read(resource $handle, int $timeout)

Description

This method reads one character from a serial device that was previously opened with HomegearSerial::open().

Parameters

5000

Return Value

Errors

HomegearSerial::readline

Signatures

string readline(resource $handle, int $timeout)

Description

This method reads one line of data (terminated by a new line character: 0x0A, "\n" or 0x0D0A, "\r\n") from a serial device that was previously opened with HomegearSerial::open().

Parameters

5000

Return Value

Errors

Example

<?php
/**
 * This example shows you how to send and receive FS20 packets with a CUL stick.
 * It logs all received FS20 packets and switches a switch on and off.
 */

define("CUL_DEVICE", "/dev/ttyACM0");
define("SWITCH_ON_PACKET", "F2E8E0011");
define("SWITCH_OFF_PACKET", "F2E8E0000");

/**
 * Class to share data between the main script and the read thread.
 */
class SharedData extends Threaded
{
    public $handle;

    public function run() {}
}

/**
 * Class to process events received from Homegear
 */
class ReadThread extends Thread
{
    private $sharedData;
    public function __construct($sharedData)
    {
        $this->sharedData = $sharedData;
    }
    
    public function run()
    {
        // Create a new Homegear object
        $hg = new \Homegear\Homegear;

        //In this special case, no "registerThread" is necessary.
        //To call RPC methods, place a call to "registerThread" here.
        
        // Create a new HomegearSerial object.
        $serial = new \Homegear\HomegearSerial();

        // Run the thread until Homegear shuts down.
        while(!$hg->shuttingDown())
        {
            $result = $serial->readline($this->sharedData->handle, 5000);
            if($result === -1) // Read error
            {
                // Reopen device
                $serial->close($this->sharedData->handle);
                $this->sharedData->handle = $serial->open(CUL_DEVICE, 38400);

                // Listen for FS20 packets
                $serial->write($this->sharedData->handle, "X21\n");
                continue;
            }
            else if($result !== -2) // Timeout?
            {
                $hg->log(4, "FS20 packet received: ".trim($result));
            }
            else $hg->log(4, "Timeout.");
        }
    }
}

// Create a new Homegear object
$hg = new \Homegear\Homegear;

// Create a new HomegearSerial object.
$serial = new \Homegear\HomegearSerial();

// Create new object for sharing data between main and event thread.
$sharedData = new SharedData();

// Open the serial device and set speed to 38400 baud. Store the returned handle in $sharedData.
$sharedData->handle = $serial->open(CUL_DEVICE, 38400);
if($sharedData->handle === false) die("Could not open serial device.");

// Listen for FS20 packets
$serial->write($sharedData->handle, "X21\n");

// Create and start new read thread.
$thread = new ReadThread($sharedData);
$thread->start();

$on = false;

// Run main thread until Homegear shuts down.
while(!$hg->shuttingDown())
{
    // Wait to be notified by event thread with a timeout of 5 seconds.
    $thread->synchronized(function($thread){ $thread->wait(5000000); }, $thread);
    
    if(!$on) // Switch on
    {
        $hg->log(4, "Sending \"switch on packet\"...");
        if($serial->write($sharedData->handle, SWITCH_ON_PACKET."\n") === false)
        {
            $hg->log(2, "Error writing to CUL stick.");
        }
        $on = true;
    }
    else // Switch off
    { 
        $hg->log(4, "Sending \"switch off packet\"...");
        if($serial->write($sharedData->handle, SWITCH_OFF_PACKET."\n") === false)
        {
            $hg->log(2, "Error writing to CUL stick.");
        }
        $on = false;
    }
}

// Wait for event thread to finish.
$thread->join();
?>

HomegearSerial::write

Signatures

bool write(resource $handle, string $data)

Description

This method writes one line of data (terminated by a new line character: 0x0A, "\n" or 0x0D0A, "\r\n") to a serial device that was previously opened with HomegearSerial::open().

Parameters

Hello world!\n

Return Value

Errors

Settings

Homegear::deleteFamilySetting

Signatures

void deleteFamilySetting(int $familyId, string $name)

Description

This method deletes a family setting from the database. The files for the family settings are not modified. If the setting does not exist, nothing happens.

Parameters

6

Errors

Homegear::getFamilySetting

Signatures

mixed getFamilySetting(int $familyId, string $name)

Description

This method returns a family setting from the family settings file or the database. The database value is returned if the same setting exists in the database and in the settings file.

Parameters

6

Return Value

Errors

Homegear::setFamilySetting

Signatures

void setFamilySetting(int $familyId, string $name, mixed $value)

Description

This method sets a family setting and stores it in the database. Database settings take precedence over the family's settings file.

Parameters

6

Errors

Users and Groups

Homegear::auth

Signatures

bool auth($username, $password)

Description

This method checks if a provided user name and password are correct.

Parameters

will

secret

Return Value

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->auth("homegear", "homegear"));'

Homegear::createGroup

Signatures

int createGroup($translations, $acl)

Description

This method creates a new group in Homegear. Each group as an Access Control List (ACL) assigned, which grants or denys a group permissions. The ACL is a struct with the following elements:

Parameters

(Struct length=2)
{
  [en-US]
  {
    (String) Guests
  }
  [de-DE]
  {
    (String) Gäste
  }
}

(Struct length=2)
{
  [eventServerMethods]
  {
    (Struct length=1)
    {
      [*]
      {
        (Boolean) 1
      }
    }
  }
  [methods]
  {
    (Struct length=1)
    {
      [*]
      {
        (Boolean) 1
      }
    }
  }
}

Return Value

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'print_v($hg->createGroup(array("en-US" => "Guests", "de-DE" => "Gäste"), array("variablesRead" => array(3 => array(1 => array("TEMPERATURE" => true, "HUMIDITY" => true)), 5 => array(1 => array("TEMPERATURE" => true))), "variablesWrite" => array(), "methods" => array("*" => true), "eventServerMethods" => array("*" => true))));'

Homegear::createUser

Signatures

bool createUser($username, $password, $groups)
bool createUser($username, $password, $groups, $metadata)

Description

This method creates a new user in Homegear.

Parameters

will

secret

array(1, 7)

array("adminUi" => true)

Return Value

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'print_v($hg->createUser("foo", "foobar01", array(1)));'

Homegear::deleteGroup

Signatures

void deleteGroup($groupId)

Description

This method deletes an existing group.

Parameters

100

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc '$hg->deleteGroup(100);'

Homegear::deleteUser

Signatures

bool deleteUser($username)

Description

This method deletes an existing user from Homegear.

Parameters

will

Return Value

Errors

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->deleteUser("foo"));'

Homegear::getGroup

Signatures

struct getGroup($groupId)

Description

This method returns the translations and the ACL of an existing group.

Parameters

100

Exceptions

Example Output

Homegear::getGroup(1)

(Struct length=3)
{
  [ACL]
  {
    (Struct length=2)
    {
      [eventServerMethods]
      {
        (Struct length=1)
        {
          [*]
          {
            (Boolean) 1
          }
        }
      }
      [methods]
      {
        (Struct length=1)
        {
          [*]
          {
            (Boolean) 1
          }
        }
      }
    }
  }
  [ID]
  {
    (Integer64) 1
  }
  [TRANSLATIONS]
  {
    (Struct length=2)
    {
      [de-DE]
      {
        (String) Administratoren
      }
      [en-US]
      {
        (String) Administrators
      }
    }
  }
}

Homegear::getGroups

Signatures

array getGroups()

Description

This method returns the ID, translations and the ACL of all existing groups.

Parameters

This method has no parameters.

Return Value

Exceptions

Homegear::getUserMetadata

Signatures

struct getUserMetadata($username)

Description

This method retrieves the metadata previously stored for a user.

Parameters

will

Return Value

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'print_v($hg->getUserMetadata("foo"));'

Homegear::getUsersGroups

Signatures

array getUsersGroups($username)

Description

This method returns all IDs of the groups a user is assigned to.

Parameters

will

Return Value

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'print_v($hg->getUsersGroups("foo"));'

Homegear::groupExists

Signatures

bool groupExists($groupId)

Description

This method checks if the group with the given ID exists.

Parameters

100

Return Value

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->groupExists(100));'

Homegear::listUsers

Signatures

array listUsers()

Description

This method returns an array with all user names known to Homegear.

Parameters

This method has no parameters.

Return Value

Exceptions

Example Output

print_v($hg->listUsers())

(Array length=1)
{
  (Struct length=4)
  {
    [groups]
    {
      (Array length=1)
      {
        (Integer64) 1
      }
    }
    [id]
    {
      (Integer64) 1
    }
    [metadata]
    {
      (Struct length=0)
      {
      }
    }
    [name]
    {
      (String) homegear
    }
  }
}

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'print_v($hg->listUsers());'

Homegear::setUserMetadata

Signatures

bool setUserMetadata($username, $metadata)

Description

This method adds arbitrary metadata to an existing user in Homegear.

Parameters

will

Return Value

Errors

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->setUserMetadata("foo", array("bar" => 12, "bar2" => "test")));'

Homegear::setUserPrivileges

Signatures

bool setUserPrivileges($username)

Description

This method drops script engine privileges to the specified user's. By default the script engine runs as system group 2. After executing this method, all Homegear method calls of the executing thread are executed with the privileges of the specified user.

Parameters

will

Return Value

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'print_v($hg->setUserPrivileges("foo"));'

Homegear::updateGroup

Signatures

void updateGroup($groupId, $acl)
void updateGroup($groupId, $translations, $acl)

Description

This method updates the names or the ACL of an existing group.

Parameters

100

(Struct length=2)
{
  [en-US]
  {
    (String) Guests
  }
  [de-DE]
  {
    (String) Gäste
  }
}

(Struct length=2)
{
  [eventServerMethods]
  {
    (Struct length=1)
    {
      [*]
      {
        (Boolean) 1
      }
    }
  }
  [methods]
  {
    (Struct length=1)
    {
      [*]
      {
        (Boolean) 1
      }
    }
  }
}

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'print_v($hg->updateGroup(100, array("en-US" => "Guests", "de-DE" => "Gäste"), array("variablesRead" => array(3 => array(1 => array("TEMPERATURE" => true, "HUMIDITY" => true)), 5 => array(1 => array("TEMPERATURE" => true))), "variablesWrite" => array(), "methods" => array("*" => true), "eventServerMethods" => array("*" => true))));'

Homegear::updateUser

Signatures

bool updateUser($username, $password)
bool updateUser($username, $groups)
bool updateUser($username, $password, $groups)

Description

This method updates the password of an existing user in Homegear.

Parameters

will

new_secret

array(1, 7)

Return Value

Errors

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->updateUser("foo", "foobar02"));'

Homegear::userExists

Signatures

bool userExists($username)

Description

This method checks if a user is known to Homegear.

Parameters

will

Return Value

Exceptions

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'var_dump($hg->userExists("homegear"));'