AHA.pm untested

filter: Statementstmt 0.0% 0 / 135 Branchbran 0.0% 0 / 48 Conditioncond 0.0% 0 / 17 MC/DCmcdc 0.0% 0 / 10 Subroutinesub 0.0% 0 / 27 Podpod 0.0% 0 / 18 totaltotal 0.0% 0 / 255 CC 25 SCAR 29.8
CC
25
Cov
0%
new
56.0
_sid
42.0
_execute_cmd
30.0
CRAP 19.8
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;