/ 
avm-aha-0.50
/ AVM::AHA

NAME

AVM::AHA - Simple access to the AHA interface for AVM based home automation

SYNOPSIS

my $aha = new AVM::AHA({host: "fritz.box", password: "s!cr!t"});

# Get all switches as array ref of AVM::AHA::Switch objects
my $switches = $aha->list();

# For all switches found
for my $switch (@$switches) {
   say "Name:    ",$switch->name();
   say "State:   ",$switch->is_on();
   say "Present: ",$switch->is_present()
   say "Energy:  ",$switch->energy();
   say "Power:   ",$switch->power();

   # If switch is on, switch if off and vice versa
   $switch->is_on() ? $switch->off() : $switch->on();
}

# Access switch directly via name as configured 
$aha->energy("Lava lamp");

# ... or by AIN
$aha->energy("087610077197");

DESCRIPTION

This module allows programatic access to AVM's Home Automation (AHA) system as it is specified in AVM HTTP Protocol specification.

Typical it is used to manage and monitor AVM::AHA::Switches. The following operations are supported:

  • Switching on and off a certain actor (switch)

  • Get the current state of an actor

  • Get the current power consumption and consumed energy of an actor (if it is a plug like the Dect!200)

METHODS

Many methods of this class take an 8-digit AIN (actor id) or a symbolic name as argument. This symbolic name can be configured in the admin UI of the Fritz Box.

If the argument (name or AIN) is not known, an error is raised (die). The same is true, if authorization fails.

$aha = new AVM::AHA({host => "fritz.box", password => "s!cr!t", user => "admin"})
$aha = new AVM::AHA("fritz.box","s!cr!t","admin")

Create a new AHA object for accessing a Fritz Box via the HTTP interface. The parameters can be given as a hashref (for named parameters) or in a simple form with host, password and user (optional) as unnamed arguments.

The named arguments which can be used:

host

Name or IP of the Fritz box to access

port

Port to connect to. It's 80 by default

password

Password for connecting to the Fritz Box

user

User role for login. Only required if a role based login is configured for the Fritz box

If used without an hashref as argument, the first argument must be the host, the second the password and the third optionally the user.

$switches = $aha->list()

List all switches know to AHA. An arrayref with AVM::AHA::Switch objects is returned, one for each device. When no switch is registered an empty arrayref is returned.

$aha->is_on($ain)

Check, whether the switch $ain is in state "on", in which case this methods returns 1. If it is "off", 0 is returned. If the switch is not connected, undef is returned.

$aha->on($ain)

Switch on the switch with the name or AIN $ain.

$aha->off($ain)

Switch off the switch with the name or AIN $ain.

$is_present = $aha->is_present($ain)

Check whether the switch $ain is present. This means, whether it is registered at the Fritz Box at all in which case 1 is returned. If the switch is not connected, 0 is returned.

$energy = $aha->energy($ain)

Get the amount of energy which has been consumed by the switch $ain since ever or since the reset of the energy statistics via the admin UI. The amount is measured in Wh.

$power = $aha->power($ain)

Get the current power consumption of the switch $ain in mW. If the switch is not connected, undef is returned.

$name = $aha->name($ain)

Get the symbolic name for the AIN given. In this case $ain must be an real AIN.

$ain = $aha->ain($name)

This is the inverse method to name(). It takes a symbolic name $name as argument and returns the AIN. If no such name is registered, an error is raised.

LICENSE

AVM::AHA is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

AVM::AHA is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with AVM::AHA. If not, see <http://www.gnu.org/licenses/>.

AUTHOR

roland@cpan.org