WebService::Freebox - Freebox API wrappers.
version 0.001
Interface to Freebox (see http://en.wikipedia.org/wiki/Freebox) API.
Notice that even creating objects of this class will not work if Freebox is not available on the network (i.e. if request to http://mafreebox.freebox.fr/api_version fails), so it is only useful for customers of the French ISP called "Free" who do have access to Freebox.
To use the API, a unique authorization token must be obtained for every new installation of the given application, which requires the user to allow API access for this application by physically pressing the Freebox buttons. Once this is done, the token needs to be saved and reused the next time a WebService::Freebox object needs to be created:
WebService::Freebox
# First time, if app token is not available: my $fb = WebService::Freebox->new(app_id => 'org.example.testapp', app_version => '1.0'); my $app_token = $fb->authorize('Test App', 'Device to authorize'); # save $app_token somewhere, e.g. using Config::XXX module # Subsequent runs: my $fb = WebService::Freebox->new(app_id => 'org.example.testapp', app_version => '1.0', app_token => $app_token);
Notice that the app token must be kept secret as it is sufficient to authenticate with the Freebox.
Additionally, a session must be opened by calling login() method before using any other API methods. The session token is ephemeral, unlike the app token, but still needs to be saved and reused if possible to avoid reopening the session every time unnecessarily:
# If no previous session token: my $session_token = $fb->login(); # Reuse the previous session token if possible (if it doesn't work, a new # session is opened): $fb->login($session_token);
Finally, once the session is opened, the API can be used in the expected way:
my $sc = $fb->get_system_config(); say "Freebox is up for $sc->{uptime}."
app_id and app_version values must be specified when creating the object. app_token may be also specified here or obtained from authorize() later (and saved for future use).
app_id
app_version
app_token
my $fb = WebService::Freebox->new(app_id => 'My App', app_version => '1.0', app_token=> '...64 alphanumeric characters ...');
The validity of the token is not checked here but using an invalid token will result in a failure in login() later.
login()
Request an authorization token for the app:
my $app_token = $fb->authorize('Test App', 'Device to authorize');
This method must be called before doing anything else with this object if no valid token was supplied when constructing it and its return value must be saved and reused in the future, to avoid asking the user once again.
Notice that it may take a long time to return as it blocks until the user physically presses a button on the Freebox to either accept or deny the authorization request.
A session must be started by logging in using this method before calling any methods other than authorize().
Returns the session token which may be saved and reused by passing it to the next call to this method during some (relatively short) time until it times out.
Return information about the Freebox as a hash with the following keys:
firmware_version
mac
serial
uptime
uptime_val
board_name
temp_cpum
temp_sw
temp_cpub
fan_rpm
Return the connection status as a hash with the fields described at http://dev.freebox.fr/sdk/os/connection/#connection-status
Return a reference to an array containing information about all the available freeplugs. Each array element is a hash with the fields described at http://dev.freebox.fr/sdk/os/freeplug/#freeplug-object
Vadim Zeitlin <vz-cpan@zeitlins.org>
This software is copyright (c) 2014 by Vadim Zeitlin.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install WebService::Freebox, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::Freebox
CPAN shell
perl -MCPAN -e shell install WebService::Freebox
For more information on module installation, please visit the detailed CPAN module installation guide.