/ 
WebService-Freebox-0.001
River stage zero No dependents
/ WebService::Freebox

NAME

WebService::Freebox - Freebox API wrappers.

VERSION

version 0.001

SYNOPSIS

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:

# 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}."

METHODS

CONSTRUCTOR

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).

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.

authorize

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.

login

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.

get_system_config

Return information about the Freebox as a hash with the following keys:

firmware_version Firmware version.
mac MAC address.
serial Serial number.
uptime Uptime as a user-readable string.
uptime_val Uptime in seconds.
board_name Hardware revision.
temp_cpum CPU (Marvell) temperature in degrees Celsius.
temp_sw Switch temperature in degrees Celsius.
temp_cpub CPU (Broadcom) temperature in degrees Celsius.
fan_rpm Fan RPM.

get_connection_status

Return the connection status as a hash with the fields described at http://dev.freebox.fr/sdk/os/connection/#connection-status

get_all_freeplugs

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

AUTHOR

Vadim Zeitlin <vz-cpan@zeitlins.org>

COPYRIGHT AND LICENSE

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.