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)

OLD API

Ftp

Ftp config API

Get the current Ftp configuration

[X] GET /api/v1/ftp/config/

config.show('ftp')

Update the FTP configuration

[X] PUT /api/v1/ftp/config/

config.update('ftp', {
  :enabled => true
})

NAT

Dmz Config API

Get the current Dmz configuration

[X] GET /api/v1/fw/dmz/

config.show('dmz')

Update the current Dmz configuration

[X] PUT /api/v1/fw/dmz/

config.update('dmz', {
  :enabled => true,
  :ip      => '192.168.1.42',
})

Port Forwarding

Port Forwarding API

Getting the list of port forwarding

[X] GET /api/v1/fw/redir/

port_forwardings = FreeboxApi::Resources::PortForwarding.new(mySession)
port_forwardings.index

Getting a specific port forwarding

[X] GET /api/v1/fw/redir/redir_id

port_forwardings.show(1)

Updating a port forwarding

[X] PUT /api/v1/fw/redir/redir_id

port_forwardings.update({
  :id      => 1,
  :enabled => false,
})

Add a port forwarding

[X] POST /api/v1/fw/redir/

port_forwardings.create({
  :enabled        => true,
  :comment        => 'test',
  :lan_port       => 4242,
  :wan_port_end   => 4242,
  :wan_port_start => 4242,
  :lan_ip         => '192.168.1.42',
  :ip_proto       => 'tcp',
})

Delete a port forwarding

[X] DELETE /api/v1/fw/redir/redir_id

port_forwardings.destroy(3)

UPnP IGD

UPnP IGD config API

Get the current UPnP IGD configuration

[X] GET /api/v1/upnpigd/config/

config.show('upnpigd')

Update the UPnP IGD configuration

[X] PUT /api/v1/upnpigd/config/

config.update('upnpigd', {
  :enabled => true,
})

UPnP IGD Redirection API

Get the list of current redirection

[X] GET /api/v1/upnpigd/redir/

upnp_redir = FreeboxApi::Resources::UPnPRedir.new(mySession)
upnp_redir.index

Delete a redirection

[X] DELETE /api/v1/upnpigd/redir/id

upnp_redir.destroy('0.0.0.0-53644-udp')

LCD

LCD config API

Get the current LCD configuration

[X] GET /api/v1/lcd/config/

config.show('lcd')

Update the lcd configuration

[X] PUT /api/v1/lcd/config/

config.update('lcd', {
  :brightness => 50,
})

Network Share

Samba config API

Get the current Samba configuration

[X] GET /api/v1/netshare/samba/

config.show('samba')

Update the Samba configuration

[X] PUT /api/v1/netshare/samba/

config.update('samba', {
  :print_share_enabled => false,
})

Afp config API

Get the current Afp configuration

[X] GET /api/v1/netshare/afp/

config.show('afp')

Update the Afp configuration

[X] PUT /api/v1/netshare/afp/

config.update('afp', {
  :guest_allow => false,
})

UPnP AV

UPnP AV config API

Get the current UPnP AV configuration

[X] GET /api/v1/upnpav/config/

config.show('upnpav')

Update the UPnP AV configuration

[X] PUT /api/v1/upnpav/config/

config.update('upnpav', {
  :enabled => false,
})

Switch

Switch API

Get the current switch status

[ ] GET /api/v1/switch/status/

Get a port configuration

[ ] GET /api/v1/switch/port/id

Update a port configuration

[ ] PUT /api/v1/switch/port/id

Get a port stats

[ ] GET /api/v1/switch/port/id/stats

Wi-Fi

Wi-Fi Status API

Get the current Wi-Fi status

[ ] GET /api/v1/wifi/

Wi-Fi config API

Get the current Wi-Fi configuration

[X] GET /api/v1/wifi/config/

config.show('wifi')

Update the Wi-Fi configuration

[X] PUT /api/v1/wifi/config/

config.update('wifi', {
  :ap_params => {
    :ht_mode => 'disabled',
  }
})

Reset the Wi-Fi configuration

[ ] POST /api/v1/wifi/config/reset/

Wi-Fi Stations API

Get Wi-Fi Stations List

[ ] GET /api/v1/wifi/stations/bss_name/

Wi-Fi MAC Filter API

 Get the MAC filter list

[ ] GET /api/v1/wifi/mac_filter/

Getting a particular MAC filter

[ ] GET /api/v1/wifi/mac_filter/filter_id

Updating a MAC filter

[ ] PUT /api/v1/wifi/mac_filter/filter_id

Delete a MAC filter

[ ] DELETE /api/v1/wifi/mac_filter/filter_id

Create a new MAC filter

[ ] POST /api/v1/wifi/mac_filter/