| 1 | =encoding UTF-8 | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | AHA - Simple access to the AHA interface for AVM based home automation | ||
| 6 | |||
| 7 | =head1 SYNOPSIS | ||
| 8 | |||
| 9 | my $aha = AHA->new( { host => "fritz.box", password => "s!cr!t" } ); | ||
| 10 | |||
| 11 | # Get all switches as array ref of AHA::Switch objects | ||
| 12 | my $switches = $aha->list(); | ||
| 13 | |||
| 14 | # For all switches found | ||
| 15 | for my $switch (@$switches) { | ||
| 16 | say "Name: ",$switch->name(); | ||
| 17 | say "State: ",$switch->is_on(); | ||
| 18 | say "Present: ",$switch->is_present(); | ||
| 19 | say "Energy: ",$switch->energy(); | ||
| 20 | say "Power: ",$switch->power(); | ||
| 21 | say "Temp.°C: ",$switch->temperature() / 10; | ||
| 22 | |||
| 23 | # If switch is on, switch if off and vice versa | ||
| 24 | $switch->is_on() ? $switch->off() : $switch->on(); | ||
| 25 | } | ||
| 26 | |||
| 27 | # Access switch directly via name as configured | ||
| 28 | $aha->energy("Lava lamp"); | ||
| 29 | |||
| 30 | # ... or by AIN | ||
| 31 | $aha->energy("087610077197"); | ||
| 32 | |||
| 33 | # Logout | ||
| 34 | $aha->logout(); | ||
| 35 | |||
| 36 | =head1 DESCRIPTION | ||
| 37 | |||
| 38 | This module allows programatic access to AVM's Home Automation (AHA) system as | ||
| 39 | it is specified in L<AVM AHA HTTP Protocol | ||
| 40 | specification|http://www.avm.de/de/Extern/files/session_id/AHA-HTTP-Interface.pdf>. | ||
| 41 | |||
| 42 | Please note that this module is not connected to AVM in any way. It's a hobby | ||
| 43 | project, without any warranty and no guaranteed support. | ||
| 44 | |||
| 45 | Typical it is used to manage and monitor L<AHA::Switch>es. The following | ||
| 46 | operations are supported: | ||
| 47 | |||
| 48 | =over 4 | ||
| 49 | |||
| 50 | =item * | ||
| 51 | |||
| 52 | Switching on and off a certain actor (switch) | ||
| 53 | |||
| 54 | =item * | ||
| 55 | |||
| 56 | Get the current state of an actor | ||
| 57 | |||
| 58 | =item * | ||
| 59 | |||
| 60 | Get the current power consumption and consumed energy of an actor (if | ||
| 61 | it is a plug like the Dect!200) | ||
| 62 | |||
| 63 | =back | ||
| 64 | |||
| 65 | =head1 METHODS | ||
| 66 | |||
| 67 | Many methods of this class take an 8-digit AIN (actor id) or a symbolic name as | ||
| 68 | argument. This symbolic name can be configured in the admin UI of the Fritz | ||
| 69 | Box. | ||
| 70 | |||
| 71 | If the argument (name or AIN) is not known, an error is raised (die). The same | ||
| 72 | is true, if authorization fails. | ||
| 73 | |||
| 74 | =over | ||
| 75 | |||
| 76 | =cut | ||
| 77 | |||
| 78 | package AHA; | ||
| 79 | |||
| 80 | use 5.01; | ||
| 81 | use strict; | ||
| 82 | use Carp qw(cluck confess); | ||
| 83 | use LWP::UserAgent; | ||
| 84 | use AHA::Switch; | ||
| 85 | use Encode; | ||
| 86 | use Digest::MD5; | ||
| 87 | use vars qw($VERSION); | ||
| 88 | |||
| 89 | $VERSION = "0.7"; | ||
| 90 | |||
| 91 | =item $aha = new AHA({host => "fritz.box", password => "s!cr!t", user => "admin"}) | ||
| 92 | |||
| 93 | =item $aha = new AHA("fritz.box","s!cr!t","admin") | ||
| 94 | |||
| 95 | Create a new AHA object for accessing a Fritz Box via the HTTP interface. The | ||
| 96 | parameters can be given as a hashref (for named parameters) or in a simple form | ||
| 97 | with host, password and user (optional) as unnamed arguments. | ||
| 98 | |||
| 99 | The named arguments which can be used: | ||
| 100 | |||
| 101 | =over | ||
| 102 | |||
| 103 | =item host | ||
| 104 | |||
| 105 | Name or IP of the Fritz box to access | ||
| 106 | |||
| 107 | =item port | ||
| 108 | |||
| 109 | Port to connect to. It's 80 by default | ||
| 110 | |||
| 111 | =item password | ||
| 112 | |||
| 113 | Password for connecting to the Fritz Box | ||
| 114 | |||
| 115 | =item user | ||
| 116 | |||
| 117 | User role for login. Only required if a role based login is configured for the | ||
| 118 | Fritz box | ||
| 119 | |||
| 120 | =back | ||
| 121 | |||
| 122 | If used without an hashref as argument, the first argument must be the host, | ||
| 123 | the second the password and the third optionally the user. | ||
| 124 | |||
| 125 | =cut | ||
| 126 | |||
| 127 | sub new { | ||
| 128 | my $class = shift; | ||
| 129 | bless my $self = { ua => LWP::UserAgent->new }, $class; | ||
| 130 | |||
| 131 | my $arg1 = shift; | ||
| 132 | if (ref($arg1) ne "HASH") { | ||
| 133 | $self->{host} = $arg1; | ||
| 134 | $self->{password} = shift; | ||
| 135 | $self->{user} = shift; | ||
| 136 | } else { | ||
| 137 | map { $self->{$_} = delete $arg1->{$_} } qw(host password user port); | ||
| 138 | my $debug = delete $arg1->{debug}; | ||
| 139 | $self->debug($debug) if defined $debug; | ||
| 140 | cluck 'Unknown parameter' | ||
| 141 | . ( keys %$arg1 != 1 && 's' ) . ' ' | ||
| 142 | . join( ' and ', sort keys %$arg1 ) . ' to ' | ||
| 143 | . __PACKAGE__ . '->new' | ||
| 144 | if keys %$arg1; | ||
| 145 | } | ||
| 146 | die "No host given" unless $self->{host}; | ||
| 147 | die "No password given" unless $self->{password}; | ||
| 148 | |||
| 149 | my $base = $self->{port} ? $self->{host} . ":" . $self->{port} : $self->{host}; | ||
| 150 | |||
| 151 | $self->{login_url} = "http://" . $base . "/login_sid.lua"; | ||
| 152 | $self->{ws_url} = "http://" . $base . "/webservices/homeautoswitch.lua"; | ||
| 153 | $self->{ain_map} = {}; | ||
| 154 | $self; | ||
| 155 | } | ||
| 156 | |||
| 157 | =item $switches = $aha->list() | ||
| 158 | |||
| 159 | List all switches know to AHA. An arrayref with L<AHA::Switch> objects is | ||
| 160 | returned, one for each device. When no switch is registered an empty arrayref | ||
| 161 | is returned. | ||
| 162 | |||
| 163 | =cut | ||
| 164 | |||
| 165 | sub list { | ||
| 166 | my $self = shift; | ||
| 167 | return [ map { new AHA::Switch($self,$_) } (split /\s*,\s*/,$self->_execute_cmd("getswitchlist")) ]; | ||
| 168 | } | ||
| 169 | |||
| 170 | =item $aha->is_on($ain) | ||
| 171 | |||
| 172 | Check, whether the switch C<$ain> is in state "on", in which case this methods | ||
| 173 | returns 1. If it is "off", 0 is returned. If the switch is not connected, | ||
| 174 | C<undef> is returned. | ||
| 175 | |||
| 176 | =cut | ||
| 177 | |||
| 178 | sub is_on { | ||
| 179 | my $self = shift; | ||
| 180 | return &_inval_check($self->_execute_cmd("getswitchstate",$self->_ain(shift))); | ||
| 181 | } | ||
| 182 | |||
| 183 | =item $aha->on($ain) | ||
| 184 | |||
| 185 | Switch on the switch with the name or AIN C<$ain>. | ||
| 186 | |||
| 187 | =cut | ||
| 188 | |||
| 189 | sub on { | ||
| 190 | my $self = shift; | ||
| 191 | my $ain = $self->_ain(shift); | ||
| 192 | return $self->_execute_cmd("setswitchon",$ain); | ||
| 193 | } | ||
| 194 | |||
| 195 | =item $aha->off($ain) | ||
| 196 | |||
| 197 | Switch off the switch with the name or AIN C<$ain>. | ||
| 198 | |||
| 199 | =cut | ||
| 200 | |||
| 201 | sub off { | ||
| 202 | my $self = shift; | ||
| 203 | return $self->_execute_cmd("setswitchoff",$self->_ain(shift)); | ||
| 204 | } | ||
| 205 | |||
| 206 | =item $is_present = $aha->is_present($ain) | ||
| 207 | |||
| 208 | Check whether the switch C<$ain> is present. This means, whether it is | ||
| 209 | registered at the Fritz Box at all in which case 1 is returned. If the switch | ||
| 210 | is not connected, 0 is returned. | ||
| 211 | |||
| 212 | =cut | ||
| 213 | |||
| 214 | sub is_present { | ||
| 215 | my $self = shift; | ||
| 216 | return $self->_execute_cmd("getswitchpresent",$self->_ain(shift)); | ||
| 217 | } | ||
| 218 | |||
| 219 | =item $energy = $aha->energy($ain) | ||
| 220 | |||
| 221 | Get the amount of energy which has been consumed by the switch C<$ain> since | ||
| 222 | ever or since the reset of the energy statistics via the admin UI. The amount | ||
| 223 | is measured in Wh. | ||
| 224 | |||
| 225 | =cut | ||
| 226 | |||
| 227 | sub energy { | ||
| 228 | my $self = shift; | ||
| 229 | return $self->_execute_cmd("getswitchenergy",$self->_ain(shift)); | ||
| 230 | } | ||
| 231 | |||
| 232 | =item $power = $aha->power($ain) | ||
| 233 | |||
| 234 | Get the current power consumption of the switch C<$ain> in mW. | ||
| 235 | If the switch is not connected, C<undef> is returned. | ||
| 236 | |||
| 237 | =cut | ||
| 238 | |||
| 239 | sub power { | ||
| 240 | my $self = shift; | ||
| 241 | return &_inval_check($self->_execute_cmd("getswitchpower",$self->_ain(shift))); | ||
| 242 | } | ||
| 243 | |||
| 244 | =item $temperature = $aha->temperature($ain) | ||
| 245 | |||
| 246 | Get the current temperature of the switch C<$ain> in 0,1 °C. | ||
| 247 | If the switch is not connected, C<undef> is returned. | ||
| 248 | |||
| 249 | =cut | ||
| 250 | |||
| 251 | sub temperature { | ||
| 252 | my $self = shift; | ||
| 253 | return &_inval_check($self->_execute_cmd("gettemperature",$self->_ain(shift))); | ||
| 254 | } | ||
| 255 | |||
| 256 | =item $name = $aha->name($ain) | ||
| 257 | |||
| 258 | Get the symbolic name for the AIN given. In this case C<$ain> must be an real | ||
| 259 | AIN. | ||
| 260 | |||
| 261 | =cut | ||
| 262 | |||
| 263 | sub name { | ||
| 264 | my $self = shift; | ||
| 265 | my $ain = shift || die "No AIN given for which to fetch the name"; | ||
| 266 | return $self->_execute_cmd("getswitchname",$ain); | ||
| 267 | } | ||
| 268 | |||
| 269 | =item $ain = $aha->ain_by_name($name) | ||
| 270 | |||
| 271 | This is the inverse method to C<name()>. It takes a symbolic name C<$name> as | ||
| 272 | argument and returns the AIN. If no such name is registered, an error is | ||
| 273 | raised. | ||
| 274 | |||
| 275 | =cut | ||
| 276 | |||
| 277 | sub ain_by_name { | ||
| 278 | my $self = shift; | ||
| 279 | my $name = shift; | ||
| 280 | my $map = $self->{ain_map}; | ||
| 281 | return $map->{$name} if $map->{$name}; | ||
| 282 | $self->_init_ain_map(); | ||
| 283 | my $ain = $self->{ain_map}->{$name}; | ||
| 284 | die "No AIN for '$name' found" unless $ain; | ||
| 285 | return $ain; | ||
| 286 | } | ||
| 287 | |||
| 288 | =item $aha->logout() | ||
| 289 | |||
| 290 | Logout from the connected fritz.box in order to free up any resources. You | ||
| 291 | can still use any other method on this object, in which case it is | ||
| 292 | logs in again (which eats up some performance, of course) | ||
| 293 | |||
| 294 | =cut | ||
| 295 | |||
| 296 | sub logout { | ||
| 297 | my $self = shift; | ||
| 298 | return unless $self->{sid}; | ||
| 299 | |||
| 300 | # Send a post request as defined in | ||
| 301 | # http://www.avm.de/de/Extern/files/session_id/AVM_Technical_Note_-_Session_ID.pdf | ||
| 302 | my $req = HTTP::Request->new(POST => $self->{login_url}); | ||
| 303 | $req->content_type("application/x-www-form-urlencoded"); | ||
| 304 | my $login = "sid=".$self->{sid}."&security:command/logout=fcn"; | ||
| 305 | $req->content($login); | ||
| 306 | my $resp = $self->{ua}->request($req); | ||
| 307 | die "Cannot logout SID ",$self->{sid},": ",$resp->status_line unless $resp->is_success; | ||
| 308 | print "--- Logout ",$self->{sid} if $self->debug; | ||
| 309 | delete $self->{sid}; | ||
| 310 | } | ||
| 311 | |||
| 312 | =item $aha->debug($verbosity) | ||
| 313 | |||
| 314 | Enable the output of debugging messages to standard error. | ||
| 315 | Requires L<LWP::ConsoleLogger::Easy> to be installed. | ||
| 316 | For details on the semantics of the C<$verbosity> argument | ||
| 317 | please refer to its documentation. | ||
| 318 | |||
| 319 | =cut | ||
| 320 | |||
| 321 | sub debug { | ||
| 322 | my ( $self, $level ) = @_; | ||
| 323 | if ( defined $level ) { | ||
| 324 | require LWP::ConsoleLogger::Easy | ||
| 325 | and LWP::ConsoleLogger::Easy->import('debug_ua') | ||
| 326 | unless defined &debug_ua; | ||
| 327 | $self->{logger} = debug_ua( $self->{ua}, $level ); | ||
| 328 | } | ||
| 329 | $self->{logger}; | ||
| 330 | } | ||
| 331 | |||
| 332 | =back | ||
| 333 | |||
| 334 | |||
| 335 | |||
| 336 | =cut | ||
| 337 | |||
| 338 | # ====================================================================== | ||
| 339 | # Private methods | ||
| 340 | |||
| 341 | # Decide whether an AIN or a name is given | ||
| 342 | sub _ain { | ||
| 343 | my $self = shift; | ||
| 344 | my $ain = shift || die "No AIN or name given"; | ||
| 345 | return $ain =~ /^\d{12}$/ ? $ain : $self->ain_by_name($ain); | ||
| 346 | } | ||
| 347 | |||
| 348 | # Execute a command as defined in | ||
| 349 | # http://www.avm.de/de/Extern/files/session_id/AHA-HTTP-Interface.pdf | ||
| 350 | sub _execute_cmd { | ||
| 351 | my $self = shift; | ||
| 352 | my $cmd = shift || die "No command given"; | ||
| 353 | my $ain = shift; | ||
| 354 | my $url = $self->{ws_url} . "?sid=" . $self->_sid() . "&switchcmd=" . $cmd; | ||
| 355 | $url .= "&ain=" . $ain if $ain; | ||
| 356 | my $resp = $self->{ua}->get($url); | ||
| 357 | say STDERR ">>> $url" if $self->debug; | ||
| 358 | die "Cannot execute ",$cmd,": ",$resp->status_line unless $resp->is_success; | ||
| 359 | my $c = $resp->content; | ||
| 360 | chomp $c; | ||
| 361 | say STDERR "<<< $c" if $self->debug; | ||
| 362 | return $c; | ||
| 363 | } | ||
| 364 | |||
| 365 | # Return the cached SID or perform the login as described in | ||
| 366 | # http://www.avm.de/de/Extern/files/session_id/AVM_Technical_Note_-_Session_ID.pdf | ||
| 367 | sub _sid { | ||
| 368 | my $self = shift; | ||
| 369 | |||
| 370 | return $self->{sid} if $self->{sid}; | ||
| 371 | |||
| 372 | # Get the challenge | ||
| 373 | my $resp = $self->{ua}->get($self->{login_url}); | ||
| 374 | my $content = $resp->content(); | ||
| 375 | |||
| 376 | my $challenge = ($content =~ /<Challenge>(.*?)<\/Challenge>/ && $1); | ||
| 377 | my $input = $challenge . '-' . $self->{password}; | ||
| 378 | Encode::from_to($input, 'ascii', 'utf16le'); | ||
| 379 | my $challengeresponse = $challenge . '-' . lc(Digest::MD5::md5_hex($input)); | ||
| 380 | |||
| 381 | # Send the challenge back with encoded password | ||
| 382 | my $req = HTTP::Request->new(POST => $self->{login_url}); | ||
| 383 | $req->content_type("application/x-www-form-urlencoded"); | ||
| 384 | my $login = "response=$challengeresponse"; | ||
| 385 | if ($self->{user}) { | ||
| 386 | $login .= "&username=" . $self->{user}; | ||
| 387 | } | ||
| 388 | $req->content($login); | ||
| 389 | $resp = $self->{ua}->request($req); | ||
| 390 | if (! $resp->is_success()) { | ||
| 391 | die "Cannot login to ", $self->{host}, ": ",$resp->status_line(); | ||
| 392 | } | ||
| 393 | $content = $resp->content(); | ||
| 394 | $self->{sid} = ($content =~ /<SID>(.*?)<\/SID>/ && $1); | ||
| 395 | say STDERR "-- Login, received SID ",$self->{sid} if $self->debug; | ||
| 396 | confess "Cannot login to $self->{host}; wrong credentials?\n" | ||
| 397 | if $self->{sid} =~ /^0+$/; | ||
| 398 | return $self->{sid}; | ||
| 399 | } | ||
| 400 | |||
| 401 | # Initialize the reverse name -> AIN map | ||
| 402 | sub _init_ain_map { | ||
| 403 | my $self = shift; | ||
| 404 | my $devs = $self->list(); | ||
| 405 | $self->{ain_map} = {}; | ||
| 406 | for my $dev (@$devs) { | ||
| 407 | $self->{ain_map}->{$self->name($dev->ain())} = $dev->ain(); | ||
| 408 | } | ||
| 409 | } | ||
| 410 | |||
| 411 | # Convert "inval" to undef | ||
| 412 | sub _inval_check { | ||
| 413 | my $ret = shift; | ||
| 414 | return $ret eq "inval" ? undef : $ret; | ||
| 415 | } | ||
| 416 | |||
| 417 | =head1 LICENSE | ||
| 418 | |||
| 419 | AHA is free software: you can redistribute it and/or modify | ||
| 420 | it under the terms of the GNU General Public License as published by | ||
| 421 | the Free Software Foundation, either version 2 of the License, or | ||
| 422 | (at your option) any later version. | ||
| 423 | |||
| 424 | AHA is distributed in the hope that it will be useful, | ||
| 425 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 426 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
| 427 | GNU General Public License for more details. | ||
| 428 | |||
| 429 | You should have received a copy of the GNU General Public License | ||
| 430 | along with AHA. If not, see <http://www.gnu.org/licenses/>. | ||
| 431 | |||
| 432 | =head1 AUTHOR | ||
| 433 | |||
| 434 | Originally: roland@cpan.org | ||
| 435 | |||
| 436 | Currently maintained by Martin Sluka E<lt>perl@sluka.deE<gt> | ||
| 437 | |||
| 438 | =cut | ||
| 439 | |||
| 440 | 1; |