NAME

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

SYNOPSIS

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

    # Get all switches as array ref of 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();
       say "Temp.°C: ",$switch->temperature() / 10;

       # 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");

    # Logout 
    $aha->logout();

DESCRIPTION

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

Please note that this module is not connected to AVM in any way. It's a hobby project, without any warranty and no guaranteed support.

Typical it is used to manage and monitor 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 AHA({host => "fritz.box", password => "s!cr!t", user => "admin"})

$aha = new 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 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.

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

Get the current temperature of the switch $ain in 0,1 °C. 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_by_name($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.

$aha->logout()

Logout from the connected fritz.box in order to free up any resources. You can still use any other method on this object, in which case it is logs in again (which eats up some performance, of course)

$aha->debug($verbosity)

Enable the output of debugging messages to standard error. Requires LWP::ConsoleLogger::Easy to be installed. For details on the semantics of the $verbosity argument please refer to its documentation.

LICENSE

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.

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 AHA. If not, see <http://www.gnu.org/licenses/>.

AUTHOR

Originally: roland@cpan.org

Currently maintained by Martin Sluka <perl@sluka.de>