# FreeboxOS Binding

Free is a French telecom operator providing advanced equipments to manage your broadband access.

This binding integrates the [Freebox Revolution](https://www.free.fr/freebox/freebox-revolution/) and [Freebox Delta](https://www.free.fr/freebox/freebox-delta/) to your openHAB installation.

The server can be connected to Free infrastructures either by xDSL or fiber optic.

This binding provides metrics about your network bridge/router and attached devices (wifi repeaters, TV boxes ...).
It also provides home automation capabilities when appropriate dongle has been inserted in the server.

IliadBox, italian version of the Freebox Pop are also compatible.

## Supported Things

This binding supports the following thing types:

| Thing             | Thing Type | Description                                                   |
|-------------------|------------|---------------------------------------------------------------|
| api               | Bridge     | Bridge to access freebox OS API hosted by the server          |
| delta             | Thing      | A Freebox Delta server                                        |
| revolution        | Thing      | A Freebox Revolution server                                   |
| player            | Thing      | A TV player equipment                                         |
| active-player     | Thing      | The TV player equipment with API capabilities (e.g. Devialet) |
| landline          | Thing      | The phone wired to the Freebox Server                         |
| host              | Thing      | A network device on the local network                         |
| wifihost          | Thing      | A wifi networked device on the local network                  |
| vm            (*) | Thing      | A virtual machine hosted on the server                        |
| freeplug          | Thing      | A virtual machine hosted on the server                        |
| repeater          | Thing      | A Free wifi repeater                                          |
| basic-shutter (*) | Thing      | RTS Shutter configured in Freebox Home                        |
| shutter       (*) | Thing      | IO Home Control shutter configured in Freebox Home            |
| kfb (*)           | Thing      | A keyfob associated with your alarm system                    |
| alarm (*)         | Thing      | The Freebox Home Alarm System                                 |

(*) Restricted to servers >= Delta

## Discovery

The API bridge is discovered automatically through mDNS in the local network.
After the bridge is discovered and available to openHAB, the binding will automatically discover phone, network devices available on the local network.
Note that the discovered thing will be setup to use only HTTP API (and not HTTPS) because only an IP can be automatically determined while a domain name is required to use HTTPS with a valid certificate.

## Binding configuration

FreeboxOS binding has the following configuration parameters:

| Name            | Description                                        | Mandatory |
|-----------------|----------------------------------------------------|-----------|
| timeout         | The timeout for reading from the device in seconds | yes       |


## Thing Configuration

### API bridge

| Parameter Label               | Parameter ID      | Description                                            | Required | Default              |
|-------------------------------|-------------------|--------------------------------------------------------|----------|----------------------|
| Freebox Server Address        | apiDomain         | The domain to use in place of hardcoded Freebox ip     | No       | mafreebox.freebox.fr |
| Application Token             | appToken          | Token generated by the Freebox Server.                 | Yes      |                      |
| Network Device Discovery      | discoverNetDevice | Enable the discovery of network device things.         | No       | false                |
| Background Discovery Interval | discoveryInterval | Interval in minutes - 0 disables background discovery  | No       | 10                   |
| HTTPS Available               | httpsAvailable    | Tells if https has been configured on the Freebox      | No       | false                |
| HTTPS port                    | httpsPort         | Port to use for remote https access to the Freebox Api | No       | 15682                |

If the parameter *apiDomain* 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.

### Server: Revolution or Delta

The *revolution* or *delta* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                              | Required | Default |
|------------------|-----------------|--------------------------------------------------------------------------|----------|---------|
| Refresh Interval | refreshInterval | The refresh interval (seconds) which is used to poll the Freebox Server. | No       | 30      |

### Player thing 

The *player* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                                | Required | Default |
|------------------|-----------------|----------------------------------------------------------------------------|----------|---------|
| MAC Address      | macAddress      | The MAC address of the player device.                                      | Yes      |         |
| ID               | id              | Id of the player within Freebox Api                                        | Yes      | 1       |
| Player port      | port            |                                                                            | No       | 24322   |
| Password         | password        | AirPlay password                                                           | No       |         |
| Remote Code      | remoteCode      | Code associated to remote control                                          | No       |         |
| Accept all MP3   | acceptAllMp3    | Accept any bitrate for MP3 audio or only bitrates greater than 64 kbps     | No       | true    |
| Refresh Interval | refreshInterval | The refresh interval in seconds which is used to poll the player           | Yes      | 30      |
| Callback URL     | callbackUrl     | URL to use for playing notification sounds, e.g. 'http://192.168.0.2:8080' | No       |         |

### Landline

The *landline* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                            | Required | Default |
|------------------|-----------------|------------------------------------------------------------------------|----------|---------|
| Refresh Interval | refreshInterval | The refresh interval in seconds which is used to poll for phone state. | No       | 2       |

### Network devices: Host

The *host* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                            | Required | Default |
|------------------|-----------------|------------------------------------------------------------------------|----------|---------|
| MAC Address      | macAddress      | The MAC address of the network host.                                   | Yes      |         |
| Refresh Interval | refreshInterval | The refresh interval in seconds which is used to poll for phone state. | No       | 30      |

### Network devices: WifiHost

The *wifihost* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                            | Required | Default |
|------------------|-----------------|------------------------------------------------------------------------|----------|---------|
| MAC Address      | macAddress      | The MAC address of the network host.                                   | Yes      |         |
| Refresh Interval | refreshInterval | The refresh interval in seconds which is used to poll for phone state. | No       | 30      |
| mDNS Name        | mDNS            | The mDNS name of the host. Useful in case of virtual MAC.              | No       |         |

When used, mDNS will search the host based on its mDNS name and eventually update the MAC address accordingly.
This is useful with devices, especially Apple equipment, that uses randomly generated MAC addresses.

### Repeater and Vm thing 

The *repeater* thing is a specialized case of a *wifihost*. The *vm* derives from *host*. They share the same configuration definition: 

| Parameter Label  | Parameter ID    | Description                                                      | Required | Default |
|------------------|-----------------|------------------------------------------------------------------|----------|---------|
| MAC Address      | macAddress      | The MAC address of the player device.                            | No       |         |
| ID               | id              | Id of the repeater within Freebox Api                            | Yes      | 1       |
| Refresh Interval | refreshInterval | The refresh interval in seconds which is used to poll the player | Yes      | 30      |

### Basic shutter thing

The *basic-shutter* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                      | Required | Default |
|------------------|-----------------|------------------------------------------------------------------|----------|---------|
| ID               | id              | Id of the Home Node                                              | Yes      | 1       |
| UP Slot ID       | upSlotId        | Id of the UP Slot.                                               | Yes      | 0       |
| STOP Slot ID     | stopSlotId      | Id of the STOP Slot.                                             | Yes      | 1       |
| DOWN Slot ID     | downSlotId      | Id of the DOWN Slot.                                             | Yes      | 2       |
| STATE Signal ID  | stateSignalId   | Id of the STATE Signal.                                          | Yes      | 3       |

## Authentication

You will have to authorize 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 binding will run a pairing request

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

**Step 3** the application token is automatically recorded in the Freebox Server (bridge) configuration

**Step 4** you can use the console command `freeboxos apptoken` to display the application token and use it later to set up your thing in a configuration file

**Step 5** log in your Freebox admin console to allocate needed rights to FreeboxOS Binding

Once initialized, the thing will generate all available channels.

## Channels

The following channels are supported:

| Thing         | Channel Type ID             | Item Type     | Access Mode | Description                                                                    |
|---------------|-----------------------------|---------------|-------------|--------------------------------------------------------------------------------|
| revolution    | lcd-brightness              | Number        | RW          | Brightness level of the screen in percent                                      |
| revolution    | lcd-orientation             | Number        | RW          | Screen Orientation in degrees (0 or 90 or 180 or 270)                          |
| revolution    | lcd-forced                  | Switch        | RW          | Indicates whether the screen orientation forced                                |
| server (*)    | uptime                      | Number        | R           | Time since last reboot of the Freebox Server                                   |
| server (*)    | restarted                   | Switch        | R           | Indicates whether the Freebox server has restarted during the last poll period |
| 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 (*)    | samba-file-status           | Switch        | RW          | Indicates whether Window File Sharing is enabled                               |
| server (*)    | samba-printer-status        | Switch        | RW          | Indicates whether Window Printer Sharing is enabled                            |
| server (*)    | xdsl-status                 | String        | R           | Status of the xDSL line                                                        |
| server (*)    | ftth-status                 | Switch        | R           | Status of the Ftth 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                                                           |
| call          | incoming#number             | Call          | R           | Current incoming call number                                                   |
| call          | incoming#timestamp          | DateTime      | R           | Current incoming call creation timestamp                                       |
| call          | incoming#name               | String        | R           | Current incoming caller name                                                   |
| call          | accepted#number             | Call          | R           | Last accepted call number                                                      |
| call          | accepted#duration           | Number        | R           | Last accepted call duration in seconds                                         |
| call          | accepted#timestamp          | DateTime      | R           | Last accepted call creation timestamp                                          |
| call          | accepted#name               | String        | R           | Last accepted caller name                                                      |
| call          | missed#number               | Call          | R           | Last missed call number                                                        |
| call          | missed#timestamp            | DateTime      | R           | Last missed call creation timestamp                                            |
| call          | missed#name                 | String        | R           | Last missed caller name                                                        |
| call          | outgoing#number             | Call          | R           | Last outgoing call number                                                      |
| call          | outgoing#duration           | Number        | R           | Last outgoing call duration in seconds                                         |
| call          | outgoing#timestamp          | DateTime      | R           | Last outgoing call creation timestamp                                          |
| call          | outgoing#name               | String        | R           | Last outgoing 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                           |
| airplay       | playurl                     | String        | W           | Play an audio or video media from the given URL                                |
| airplay       | stop                        | Switch        | W           | Stop the media playback                                                        |
| basic-shutter | basic-shutter#basic-shutter | RollerShutter | W           | Up, stop and down commands for a RTS shutter                                   |

(*): server means *delta* or *revolution*

## Actions for rules

The following actions are available in rules/scripting:

| Thing Type  | Action Name      | Parameters              | Description                                          | 
|-------------|------------------|-------------------------|------------------------------------------------------|
| host        | wol              | None                    | Sends a wake on lan packet to the lan connected host |
| player      | reboot           | None                    | Reboots the player device                            |
| player      | sendKey          | key: String             | Send a key (remote emulation) to the player          |
| player      | sendLongKey      | key: String             | Sends the key emulating a longpress on the button    |
| player      | sendMultipleKeys | keys: String            | Sends multiple keys to the player, comma separated   |
| player      | sendKeyRepeat    | key: String, count: int | Sends the key multiple times                         |
| server      | reboot           | None                    | Reboots the Freebox Server                           |
| freeplug    | reset            | None                    | Resets the Freeplug                                  |
| call        | reset            | None                    | Clears the call log queue                            |
| repeater    | reboot           | None                    | Reboots the Repeater                                 |
