File Coverage

blib/lib/Device/WallyHome.pm
Criterion Covered Total %
statement 18 28 64.2
branch n/a
condition n/a
subroutine 5 9 55.5
pod 2 2 100.0
total 25 39 64.1


line stmt bran cond sub pod time code
1             package Device::WallyHome;
2 2     2   219885 use Moose;
  2         1177397  
  2         17  
3 2     2   17916 use MooseX::AttributeShortcuts;
  2         735227  
  2         17  
4 2     2   81034 use namespace::autoclean;
  2         16  
  2         26  
5              
6 2     2   222 use List::Util qw(first);
  2         5  
  2         1170  
7              
8             our $VERSION = '0.21.3';
9              
10             with 'Device::WallyHome::Role::Creator';
11             with 'Device::WallyHome::Role::REST';
12             with 'Device::WallyHome::Role::Validator';
13              
14              
15             #== ATTRIBUTES =================================================================
16              
17             has 'places' => (
18             is => 'lazy',
19             );
20              
21              
22             #== ATTRIBUTE BUILDERS =========================================================
23              
24             sub _build_places {
25 1     1   2 my ($self) = @_;
26              
27 1         7 my $placeList = $self->request({
28             uri => 'places',
29             });
30              
31 1         4 my $placeObjectList = [];
32              
33 1         2 foreach my $placeData (@$placeList) {
34 1         9 push @$placeObjectList, $self->loadPlaceFromApiResponseData($placeData);
35             }
36              
37 1         38 return $placeObjectList;
38             }
39              
40              
41             #== PUBLIC METHODS =============================================================
42              
43             sub getPlaceById {
44 0     0 1   my ($self, $placeId) = @_;
45              
46 0           $self->_checkRequiredScalarParam($placeId, 'placeId');
47              
48 0     0     return first { $_->id() eq $placeId } @{ $self->places() };
  0            
  0            
49             }
50              
51             sub getPlaceByLabel {
52 0     0 1   my ($self, $label) = @_;
53              
54 0           $self->_checkRequiredScalarParam($label, 'label');
55              
56 0     0     return first { $_->label() eq $label } @{ $self->places() };
  0            
  0            
57             }
58              
59              
60             __PACKAGE__->meta->make_immutable;
61              
62             1;
63              
64             __END__
65              
66             =pod
67              
68             =encoding utf8
69              
70             =head1 NAME
71              
72             Device::WallyHome - WallyHome Device/Sensor REST API Interface
73              
74             =head1 SYNOPSIS
75              
76             use Device::WallyHome;
77              
78             # Instantiate a new Device::WallyHome object, replace Token with actual Security Token
79             my $wally = Device::WallyHome->new(
80             token => 'f4379e51-222f-4def-8ee1-edf0b15be3b8',
81             );
82              
83             # Retrieve a list (ArrayRef) of all places associated with your account
84             my $places = $wally->places();
85              
86             # Load a new place via its unique identifier
87             my $place = $wally->getPlaceById('qyWIClYakQX8TQxtFv1ypN6c');
88              
89             # Load a new place via its friendly label
90             my $home = $wally->getPlaceByLabel('Home');
91              
92             # Retrieve a list (ArrayRef) of all Sensors associated with a place
93             my $sensors = $home->sensors();
94              
95             =head1 DESCRIPTION
96              
97             B<Device::WallyHome> is the Perl5 interface into the WallyHome REST API.
98              
99             WallyHome is a home sensing solution that detects and alerts you of water leaks,
100             changes in temperature and humidity, as well as when doors and windows open.
101             The WallyHome REST API provides an interface into the places and sensors
102             associated with a WallyHome account.
103              
104             Device::WallyHome provides an object oriented interface wrapped around
105             the WallyHome REST API, designed to simplify integration for any associated
106             scripting needs.
107              
108             The only information to get started with Device::WallyHome is the
109             Security Token that can be generated from the Account Settings page
110             within your WallyHome account.
111              
112              
113             =head2 Constructor
114              
115             =over
116              
117             =item B<new>
118              
119             use Device::WallyHome;
120              
121             my $wally = Device::WallyHome->new(
122             token => 'f4379e51-222f-4def-8ee1-edf0b15be3b8',
123             );
124              
125             =over
126              
127             =item token
128              
129             The Security Token for your WallyHome account can be found or generated
130             from within the Account Settings page. This security token is all that
131             is needed to successfully connect to the WallyHome REST API.
132              
133              
134             =back
135              
136             =back
137              
138              
139             =head2 Methods
140              
141             =over
142              
143             =item B<places>
144              
145             my $places = $wally->places();
146              
147             Returns a list of all places assoiated with the given WallyHome account.
148             Each place will be returned as a L<Device::WallyHome::Place> object. If
149             no places are found, an empty list will be returned.
150              
151             =item B<getPlaceById>
152              
153             my $place = $device->getPlaceById('qyWIClYakQX8TQxtFv1ypN6c');
154              
155             Returns a single L<Device::WallyHome::Place> object matching the passed
156             place identifier. If no matching place is found, C<undef> will be
157             returned.
158              
159             =item B<getPlaceByLabel>
160              
161             my $home = $device->getPlaceByLabel('Home');
162              
163             Returns a single L<Device::WallyHome::Place> object matching the passed
164             place label. If no matching place is found, C<undef> will be
165             returned.
166              
167             =back
168              
169              
170             =head1 EXAMPLES
171              
172             =head2 Basic Examples
173              
174             # Iterate through a list of places, printing the identifier and label for each, typically only a single place
175             foreach my $place (@$places) {
176             printf("%s - %s\n", $place->id(), $place->label());
177             }
178              
179             # Iterate through a list of sensors, printing the identifier (snid) and label for each
180             foreach my $sensor (@$sensors) {
181             printf("%s - %s\n", $sensor->snid(), $sensor->location()->room());
182             }
183              
184             =head2 Checking Sensor Data
185              
186             # Determine if Relative Humidity is within specified thresholds
187             my $state = $sensor->state('RH');
188             my $threshold = $sensor->threshold('RH');
189              
190             my $currentValue = $state->value();
191             my $min = $threshold->min() // 0;
192             my $max = $threshold->max() // 999;
193              
194             if ($currentValue < $min || $currentValue > $max) {
195             print "Danger, Will Robinson!\n";
196             }
197              
198             =head1 AUTHOR
199              
200             Chris Hamilton
201              
202              
203             =head1 COPYRIGHT AND LICENSE
204              
205             This software is copyright (c) 2016 by Chris Hamilton.
206              
207             This is free software; you can redistribute it and/or modify it under the
208             same terms as the Perl 5 programming language system itself.
209              
210              
211             =head1 BUG REPORTING, ENHANCEMENT/FEATURE REQUESTS
212              
213             Please report bugs or enhancement requests on GitHub directly at
214             L<https://github.com/cjhamil/Device-WallyHome/issues>
215              
216             =cut