---
layout: documentation
---

{% include base.html %}

# Freebox Binding

This binding integrates the [Freebox Revolution](http://www.free.fr/adsl/freebox-revolution.html) to your openHab installation.

## Supported Things

This binding supports the following thing types:

| Thing         | Thing Type | Description                                             |
|---------------|------------|---------------------------------------------------------|
| server        | Bridge     | The Freebox Revolution Server.                          |
| phone         | Thing      | The phone wired to the Freebox Revolution.              |
| net_device    | Thing      | A network device on the local network.                  |
| net_interface | Thing      | A network interface from a device on the local network. |

## Discovery

The Freebox Revolution server is discovered automatically through mDNS in the local network. After a Freebox Revolution is discovered and available to openHAB, the binding will automatically discover phone and network devices / interfaces on the local network.

## Binding configuration

There are no overall binding configuration settings that need to be set. All settings are through thing configuration parameters.

## Thing Configuration

### Server

The _server_ bridge thing requires the following configuration parameters:

| Parameter Label          | Parameter ID    | Description                                             | Required | Default |
|--------------------------|-----------------|---------------------------------------------------------|----------|---------|
| Freebox Network Address  | fqdn            | The IP address / FQDN of the Freebox Server (can include port number).| false | mafreebox.freebox.fr |
| Application token        | appToken        | Token generated by the Freebox Server.                  | false    |         |
| Refresh Interval         | refreshInterval | The refresh interval in seconds which is used to poll given Freebox Server.| false | 30 |

If the parameter _ipAddress_ is not set, the binding will use the default address used by Free to access your Freebox Server (mafreebox.freebox.fr). The bridge thing will initialize only if a valid application token (parameter _appToken_) is filled.

### Phone

The _phone_ thing requires the following configuration parameters:

| Parameter Label              | Parameter ID             | Description                           | Required | Default |
|------------------------------|--------------------------|---------------------------------------|----------|---------|
| Phone State Refresh Interval | refreshPhoneInterval     | The refresh interval in seconds which is used to poll given Freebox Server for phone state.| false | 2 |
| Phone Calls Refresh Interval | refreshPhoneCallsInterval | The refresh interval in seconds which is used to poll given Freebox Server for phone calls.| false | 60 |

### Network device

The _net_device_ thing requires the following configuration parameters:

| Parameter Label              | Parameter ID             | Description                                      | Required |
|------------------------------|--------------------------|--------------------------------------------------|----------|
| MAC Address                  | macAddress               | The MAC address of the network device.| true     |         |

### Network interface

The _net_interface_ thing requires the following configuration parameters:

| Parameter Label              | Parameter ID             | Description                                        | Required |
|------------------------------|--------------------------|----------------------------------------------------|----------|
| IP Address                   | ipAddress                | The IP address (v4 or v6) of the network interface.| true     |

## Authentication

You'll have to authorise openHAB to connect to your Freebox. Here is the process described :

**Step 1** At binding startup, if no token is recorded in the Freebox Server (bridge) configuration, the following message
will be displayed in the OSGi console :

```
            ####################################################################
            # Please accept activation request directly on your freebox        #
            # Once done, record Apptoken in the Freebox Item configuration     #
            # bEK7a7O8GkxxxxxxxxxxXBsKu/xxxttttwj5bXSssd5gUvSXs4vrpuhZwelEo804 #
            ####################################################################
```

**Step 2** Run to your Freebox and approve the pairing request for openHAB Freebox Binding that is displayed on the Freebox screen

**Step 3** Record the apptoken in the Freebox Server (bridge) configuration

**Optionally** you can log in your Freebox admin console to allocate needed rights to openhab

Once initialized, the thing will generate all available channels.

## Channels

The following channels are supported:

| Thing         | Channel Type ID          | Item Type    | Access Mode | Description                                          |
|---------------|--------------------------|--------------|--------|------------------------------------------------------|
| server        | fwversion                | String       | R      | Version of the Freebox Server firmware               |
| server        | uptime                   | Number       | R      | Time since last reboot of the Freebox Server         |
| server        | restarted                | Switch       | R      | Indicates whether the Freebox server hase restarted during the last poll period |
| server        | tempcpum                 | Number       | R      | Actual measured CPU Marvell temperature              |
| server        | tempcpub                 | Number       | R      | Actual measured CPU Broadcom (xDSL) temperature      |
| server        | tempswitch               | Number       | R      | Actual measured switch temperature                   |
| server        | fanspeed                 | Number       | R      | Actual measured fan speed (rpm)                      |
| server        | reboot                   | Switch       | W      | Reboots the Freebox server                           |
| server        | lcd_brightness           | Number       | RW     | Brightness level of the screen in percent            |
| server        | lcd_orientation          | Number       | RW     | Screen Orientation in degrees (0 or 90 or 180 or 270) |
| server        | lcd_forced               | Switch       | RW     | Indicates whether the screen orientation forced      |
| server        | wifi_status              | Switch       | RW     | Indicates whether the WiFi network is enabled        |
| server        | ftp_status               | Switch       | RW     | Indicates whether the FTP server  is enabled         |
| server        | airmedia_status          | Switch       | RW     | Indicates whether Air Media  is enabled              |
| server        | upnpav_status            | Switch       | RW     | Indicates whether UPnP AV  is enabled                |
| server        | sambafileshare_status    | Switch       | RW     | Indicates whether Window File Sharing  is enabled    |
| server        | sambaprintershare_status | Switch       | RW     | Indicates whether Window Printer Sharing  is enabled |
| server        | xdsl_status              | String       | R      | Status of the xDSL line                              |
| server        | line_status              | String       | R      | Status of network line connexion                     |
| server        | ipv4                     | String       | R      | Public IP Address of the Freebox Server              |
| server        | rate_up                  | Number       | R      | Current upload rate in byte/s                        |
| server        | rate_down                | Number       | R      | Current download  rate in byte/s                     |
| server        | bytes_up                 | Number       | R      | Total uploaded bytes since last connection           |
| server        | bytes_down               | Number       | R      | Total downloaded  bytes since last connection        |
| phone         | state#onhook             | Switch       | R      | Indicates whether the phone is on hook               |
| phone         | state#ringing            | Switch       | R      | Is the phone ringing                                 |
| phone         | any#call_number          | String       | R      | Last call: number                                    |
| phone         | any#call_duration        | Number       | R      | Last call: duration in seconds                       |
| phone         | any#call_timestamp       | DateTime     | R      | Last call: creation timestamp                        |
| phone         | any#call_status          | String       | R      | Last call: type (ingoing, outgoing, missed)          |
| phone         | any#call_name            | String       | R      | Last call: called name for outgoing calls. Caller name for incoming calls |
| phone         | accepted#call_number     | String       | R      | Last accepted call: number                           |
| phone         | accepted#call_duration   | Number       | R      | Last accepted call: duration in seconds              |
| phone         | accepted#call_timestamp  | DateTime     | R      | Last accepted call: creation timestamp               |
| phone         | accepted#call_name       | String       | R      | Last accepted call: caller name                      |
| phone         | missed#call_number       | String       | R      | Last missed call: number                             |
| phone         | missed#call_duration     | Number       | R      | Last missed call: duration in seconds                |
| phone         | missed#call_timestamp    | DateTime     | R      | Last missed call: creation timestamp                 |
| phone         | missed#call_name         | String       | R      | Last missed call: caller name                        |
| phone         | outgoing#call_number     | String       | R      | Last outgoing call: number                           |
| phone         | outgoing#call_duration   | Number       | R      | Last outgoing call: duration in seconds              |
| phone         | outgoing#call_timestamp  | DateTime     | R      | Last outgoing call: creation timestamp               |
| phone         | outgoing#call_name       | String       | R      | Last outgoing call: called name                      |
| net_device    | reachable                | Switch       | R      | Indicates whether the network device is reachable    |
| net_interface | reachable                | Switch       | R      | Indicates whether the network interface is reachable |

## Example

### Things

Here is an example with minimal configuration parameters (using default values):

```
Bridge freebox:server:fb "Freebox Revolution" [ appToken="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] {
    Thing phone Phone "Phone"
    Thing net_device tv1 "TV living room" [ macAddress="XX:XX:XX:XX:XX:XX" ]
    Thing net_interface tv2 "TV bedroom" [ ipAddress="192.168.0.100" ]
}
```

Here is another example overwritting default configuration parameters:

```
Bridge freebox:server:fb "Freebox Revolution" [ fqdn="192.168.0.254", appToken="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", refreshInterval=20 ] {
    Thing phone Phone "Phone" [ refreshPhoneInterval=10, refreshPhoneCallsInterval=120 ]
    Thing net_device tv1 "TV living room" [ macAddress="XX:XX:XX:XX:XX:XX" ]
    Thing net_interface tv2 "TV bedroom" [ ipAddress="192.168.0.100" ]
}
```

### Items

```
String Freebox_xdsl_status "Freebox state [%s]" {channel="freebox:server:fb:xdsl_status"}
String Freebox_cs_state "State [%s]" {channel="freebox:server:fb:line_status"}
String Freebox_cs_ipv4 "ipV4 [%s]" {channel="freebox:server:fb:ipv4"}
Number Freebox_cs_rate_up "Upload rate [%d b/s]" {channel="freebox:server:fb:rate_up"}
Number Freebox_cs_rate_down "Download rate [%d b/s]" {channel="freebox:server:fb:rate_down"}
Number Freebox_cs_bytes_up "Uploaded [%d bytes]" {channel="freebox:server:fb:bytes_up"}
Number Freebox_cs_bytes_down "Downloaded [%d bytes]" {channel="freebox:server:fb:bytes_down"}
String Freebox_sys_firmware_version "Version [%s]" {channel="freebox:server:fb:fwversion"}
Switch Freebox_reboot "Reboot freebox" {channel="freebox:server:fb:reboot"}
Switch Freebox_restarted "Restarted" {channel="freebox:server:fb:restarted"}
Number Freebox_sys_uptime "Uptime [%d sec]" {channel="freebox:server:fb:uptime"}
Number Freebox_sys_temp_cpum "Temp cpum [%d Â°C]" <temperature> {channel="freebox:server:fb:tempcpum"}
Number Freebox_sys_temp_cpub "Temp cpub [%d Â°C]" <temperature> {channel="freebox:server:fb:tempcpub"}
Number Freebox_sys_temp_sw "Temp sw [%d Â°C]" <temperature> {channel="freebox:server:fb:tempswitch"}
Number Freebox_sys_fan_rpm "Fan [%d rpm]" <fan> {channel="freebox:server:fb:fanspeed"}
Switch FreeboWifi "Wifi" {autoupdate="false", channel="freebox:server:fb:wifi_status"}
Switch FreeboxFTP "FTP" {autoupdate="false", channel="freebox:server:fb:ftp_status"}
Switch FreeboxUPnPAV "UPnP AV" {autoupdate="false", channel="freebox:server:fb:upnpav_status"}
Switch FreeboxAirMedia "AirMedia" {autoupdate="false", channel="freebox:server:fb:airmedia_status"}
Switch FreeboxSambaFiles "Win File Share" {autoupdate="false", channel="freebox:server:fb:sambafileshare_status"}
Switch FreeboxSambaPrinters "Win Print Share" {autoupdate="false", channel="freebox:server:fb:sambaprintershare_status"}
Number Freebox_lcd_brightness "Brightness [%d %%]" {channel="freebox:server:fb:lcd_brightness"}
Number Freebox_lcd_orientation "Orientation [%d Â°]" {channel="freebox:server:fb:lcd_orientation"}
Switch Freebox_lcd_forced "LCD Forced" {channel="freebox:server:fb:lcd_forced"}

Switch Freebox_onhook "Phone on hook" {channel="freebox:phone:fb:Phone:state#onhook"}
Switch Freebox_ringing "Phone ringing" {channel="freebox:phone:fb:Phone:state#ringing"}
String Freebox_call_number "Last call [%s]" {channel="freebox:phone:fb:Phone:any#call_number"}
String Freebox_call_name "Name [%s]" {channel="freebox:phone:fb:Phone:any#call_name"}
Number Freebox_call_duration "Duration [%d sec]" {channel="freebox:phone:fb:Phone:any#call_duration"}
DateTime Freebox_call_ts "TimeStamp [%1$tA %1$td %1$tR]" <calendar> {channel="freebox:phone:fb:Phone:any#call_timestamp"}
String Freebox_call_status "Status [%s]" {channel="freebox:phone:fb:Phone:any#call_status"}
String Freebox_accepted_call_number "Last accepted call [%s]" {channel="freebox:phone:fb:Phone:accepted#call_number"}
String Freebox_accepted_call_name "Caller name [%s]" {channel="freebox:phone:fb:Phone:accepted#call_name"}
Number Freebox_accepted_call_duration "Duration [%d sec]" {channel="freebox:phone:fb:Phone:accepted#call_duration"}
DateTime Freebox_accepted_call_ts "TimeStamp [%1$tA %1$td %1$tR]" <calendar> {channel="freebox:phone:fb:Phone:accepted#call_timestamp"}
String Freebox_missed_call_lastnum "Last missed call [%s]" {channel="freebox:phone:fb:Phone:missed#call_number"}
String Freebox_missed_call_name "Caller name [%s]" {channel="freebox:phone:fb:Phone:missed#call_name"}
Number Freebox_missed_call_duration "Duration [%d sec]" {channel="freebox:phone:fb:Phone:missed#call_duration"}
DateTime Freebox_missed_call_ts "TimeStamp [%1$tA %1$td %1$tR]" <calendar> {hannel="freebox:phone:fb:Phone:missed#call_timestamp"}
String Freebox_outcall_lastnum "Last outgoing call [%s]" {channel="freebox:phone:fb:Phone:outgoing#call_number"}
String Freebox_outcall_name "Called name [%s]" {channel="freebox:phone:fb:Phone:outgoing#call_name"}
Number Freebox_outcall_duration "Duration [%d sec]" {channel="freebox:phone:fb:Phone:outgoing#call_duration"}
DateTime Freebox_outcall_ts "TimeStamp [%1$tA %1$td %1$tR]" <calendar> {channel="freebox:phone:fb:Phone:outgoing#call_timestamp"}

Switch TVLivingRoom "TV living room" <television> {channel="freebox:net_device:fb:tv1:reachable"}
Switch TVBedroom "TV bedroom" <television> {channel="freebox:net_interface:fb:tv2:reachable"}
```
