Freebox OS API bindings for Ruby

WARNING: Work In Progress.

Overview

This gem contains Freebox OS API bindings for the Ruby language. I started working on that to use it with https://github.com/mcanevet/puppet-freebox.

The official documentation is located here: http://dev.freebox.fr/sdk/os/

Building the Freebox object

require 'freebox_api'

myFreebox = FreeboxApi::Freebox.new

or

require 'freebox_api'

myFreebox = FreeboxApi::Freebox.new({
  :freebox_ip   => 'mafreebox.example.com',
  :freebox_port => 4242,
})

Login

Obtaining an app_token

Request authorization

This is the first step, the app will ask for an app_token using the following call. A message will be displayed on the Freebox LCD asking the user to grant/deny access to the requesting app.

Once the app has obtained a valid app_token, it will not have to do this procedure again unless the user revokes the app_token.

token_request = {
  :app_id      => 'fr.freebox.testapp',
  :app_name    => 'Test App',
  :app_version => '0.0.7',
  :device_name => 'Pc de Xavier'
}

auth_request = myFreebox.authorize(token_request)

app_token = auth_request['app_token']

Creating the session object

myApp = {
  :app_id      => 'fr.freebox.testapp',
  :app_version => '0.0.7',
  :app_token   => 'dyNYgfK0Ya6FWGqq83sBHa7TwzWo+pg4fDFUJHShcjVYzTfaRrZzm93p7OTAfH/0',
}
mySession = FreeboxApi::Session.new(myApp, myFreebox)

or

mySession = FreeboxApi::Session.new({
  :app_id      => 'fr.freebox.testapp',
  :app_version => '0.0.7',
  :app_token   => 'dyNYgfK0Ya6FWGqq83sBHa7TwzWo+pg4fDFUJHShcjVYzTfaRrZzm93p7OTAfH/0',
}, FreeboxApi::Freebox.new)

Reference

Configuration

Connection

Get the current Connection status

FreeboxApi::Configuration::Connection.getStatus(mySession)

Get the current Connection configuration

FreeboxApi::Configuration::Connection.getConfig(mySession)

Update the Connection configuration

FreeboxApi::Configuration::Connection.updateConfig(mySession, {
  :ping => true,
  :wol  => false,
})

IPv6

Get the current IPv6 Connection configuration

FreeboxApi::Configuration::Connection::IPv6.getConfig(mySession)

Update the IPv6 Connection configuration

FreeboxApi::Configuration::Connection::IPv6.updateConfig(mySession, {
  :delegations => [
    {
     :prefix   => '2a01:e30:d252:a2a2::/64',
     :next_hop => 'fe80::be30:5bff:feb5:fcc7',
    }
  ]
})

Connection DynDNS status

Get the status of a DynDNS service

FreeboxApi::Configuration::Connection::DDNS.getStatus(mySession, 'dyndns')

or

ddns = FreeboxApi::Configuration::Connection::DDNS.new(mySession, 'dyndns')
ddns.status

Get the config of a DynDNS service

FreeboxApi::Configuration::Connection::DDNS.getConfig(mySession, 'dyndns')

or

ddns = FreeboxApi::Configuration::Connection::DDNS.new(mySession, 'dyndns')
ddns.config

Set the config of a DynDNS service

FreeboxApi::Configuration::Connection::DDNS.updateConfig(mySession, 'dyndns', {
  :enabled  => false,
  :user     => 'test',
  :password => 'ssss',
  :hostname => 'ttt',
})

or

ddns = FreeboxApi::Configuration::Connection::DDNS.new(mySession, 'dyndns')
ddns.config = {
  :enabled  => false,
  :user     => 'test',
  :password => 'ssss',
  :hostname => 'ttt',
}

Lan

Get the current Lan configuration

FreeboxApi::Configuration::Lan.getConfig(mySession)

Update the current Lan configuration

FreeboxApi::Configuration::Lan.updateConfig({
  :mode         => 'router',
  :ip           => '192.168.69.254',
  :name         => 'Freebox de r0ro',
  :name_dns     => 'freebox-de-r0ro',
  :name_mdns    => 'Freebox-de-r0ro',
  :name_netbios => 'Freebox_de_r0ro',
})

Lan Browser

Getting the list of browsable LAN interfaces

FreeboxApi::Configuration::Lan::Browser.interfaces(mySession)

Getting the list of hosts on a given interface

FreeboxApi::Configuration::Lan::Browser::Interface.getLanHosts(mySession, 'pub')

interface = FreeboxApi::Configuration::Lan::Browser::Interface.new(mySession, 'pub')
interface.lan_hosts

Getting an host information

FreeboxApi::Configuration::Lan::Browser::LanHost.show(mySession, 'pub', 'ether-00:24:d4:7e:00:4c')

or

lan_host = FreeboxApi::Configuration::Lan::Browser::LanHost.new(mySession, 'pub', 'ether-00:24:d4:7e:00:4c')
lan_host.show

Updating an host information

FreeboxApi::Configuration::Lan::Browser::LanHost.update(mySession, 'pub', 'ether-00:24:d4:7e:00:4c', {
  :id           => 'ether-00:24:d4:7e:00:4c',
  :primary_name => 'Freebox Tv',
})

or

lan_host = FreeboxApi::Configuration::Lan::Browser::LanHost.new(mySession, 'pub', 'ether-00:24:d4:7e:00:4c')
lan_host.update({
  :id           => 'ether-00:24:d4:7e:00:4c',
  :primary_name => 'Freebox Tv',
})

Wake on LAN

Send Wake ok Lan packet to an host

FreeboxApi::Configuration::Lan::Browser::Interface.wol(mySession, 'pub', {
  :mac      => '00:24:d4:7e:00:4c',
  :password => '',
}

or

interface = FreeboxApi::Configuration::Lan::Browser::Interface.new(mySession, 'pub')
interface.wol({
  :mac      => '00:24:d4:7e:00:4c',
  :password => '',
}

or

lan_host = FreeboxApi::Configuration::Lan::Browser::LanHost.new(mySession, 'pub', 'ether-00:24:d4:7e:00:4c')
lan_host.wol({ :password => '' })

Freeplug

Get the current Freeplugs networks

FreeboxApi::Configuration::Freeplug.network(mySession)

Get a particular Freeplug information

FreeboxApi::Configuration::Freeplug.show(mySession, 'F4:CA:E5:1D:46:AE')

or

freeplug = FreeboxApi::Configuration::Freeplug.new(mySession, 'F4:CA:E5:1D:46:AE')
freeplug.show

Reset a Freeplug

FreeboxApi::Configuration::Freeplug.reset(mySession, 'F4:CA:E5:1D:46:AE')

or

freeplug = FreeboxApi::Configuration::Freeplug.new(mySession, 'F4:CA:E5:1D:46:AE')
freeplug.reset

DHCP

Get the current DHCP configuration

FreeboxApi::Configuration::Dhcp.getConfig(mySession)

Update the current DHCP configuration

FreeboxApi::Configuration::Dhcp.updateConfig(mySession, {
  :enabled => false,
})

Get the list of DHCP static leases

FreeboxApi::Configuration::Dhcp.static_leases(mySession)

Get a given DHCP static lease

FreeboxApi::Configuration::Dhcp::StaticLease.show(mySession, '00:DE:AD:B0:0B:55')

or

static_lease = FreeboxApi::Configuration::Dhcp::StaticLease.new(mySession, '00:DE:AD:B0:0B:55')
static_lease.show

Update DHCP static lease

FreeboxApi::Configuration::Dhcp::StaticLease.update(mySession, {
  :id      => '00:DE:AD:B0:0B:55',
  :comment => 'Mon PC',
})

or

static_lease = FreeboxApi::Configuration::Dhcp::StaticLease.new(mySession, '00:DE:AD:B0:0B:55')
static_lease.update({
  :id      => '00:DE:AD:B0:0B:55',
  :comment => 'Mon PC',
})

Delete a DHCP static lease

FreeboxApi::Configuration::Dhcp::StaticLease.delete(mySession, '00:DE:AD:B0:0B:55')

or

static_lease = FreeboxApi::Configuration::Dhcp::StaticLease.new(mySession, '00:DE:AD:B0:0B:55')
static_lease.delete

Add a DHCP static lease

FreeboxApi::Configuration::Dhcp::StaticLease.create(mySession, {
  :ip  => '192.168.1.222',
  :mac => '00:00:00:11:11:11',
})

or

static_lease = FreeboxApi::Configuration::Dhcp::StaticLease.new(mySession, '00:00:00:11:11:11')
static_lease.create({
  :ip  => '192.168.1.222',
  :mac => '00:00:00:11:11:11',
})

Get the list of DHCP dynamic leases

FreeboxApi::Configuration::Dhcp.dynamic_leases(mySession)

FTP

Get the current FTP configuration

FreeboxApi::Configuration::Ftp.getConfig(mySession)

Update the current FTP configuration

FreeboxApi::Configuration::Ftp.updateConfig(mySession, {
  :enabled => true,
})

NAT

DMZ

Get the current Dmz configuration

FreeboxApi::Configuration::Nat::Dmz.getConfig(mySession)

Update the current Dmz configuration

FreeboxApi::Configuration::Nat::Dmz.updateConfig(mySession, {
  :enabled => true,
  :ip      => '192.168.1.42',
})

Port Forwarding

Getting the list of port forwarding

FreeboxApi::Configuration::Nat.port_forwardings(mySession)

Getting a specific port forwarding

FreeboxApi::Configuration::Nat::PortForwarding.show(mySession, 1)

###### Updating a port forwarding

FreeboxApi::Configuration::Nat::PortForwarding.update(mySession, 1, {
  :enabled => false,
})

Add a port forwarding

FreeboxApi::Configuration::Nat::PortForwarding.create(mySession, {
  :enabled        => true,
  :comment        => 'test',
  :lan_port       => 4242,
  :wan_port_end   => 4242,
  :wan_port_start => 4242,
  :lan_ip         => '192.168.1.42',
  :ip_proto       => 'tcp',
  :src_ip         => '0.0.0.0',
})

Delete a port forwarding

FreeboxApi::Configuration::Nat::PortForwarding.delete(mySession, 3)