openhab-addons/bundles/org.openhab.binding.freeboxos/README.md

# 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      | A TV player equipment with API capabilities (e.g. Devialet)   |
| fxs               | Thing      | The phone wired to the Freebox Server                         |
| dect              | Thing      | A DECT phone                                                  |
| call              | Thing      | Phone calls                                                   |
| host              | Thing      | A network device on the local network                         |
| wifihost          | Thing      | A wifi networked device on the local network                  |
| freeplug          | Thing      | An Ethernet / CPL gateway                                     |
| repeater          | Thing      | A Free wifi repeater                                          |
| vm            (*) | Thing      | A virtual machine hosted on the server                        |
| basic-shutter (*) | Thing      | A basic shutter configured in your Freebox Server             |
| shutter       (*) | Thing      | An IO Home Control shutter configured in your Freebox Server  |
| kfb           (*) | Thing      | A keyfob configured in your Freebox Server                    |
| alarm         (*) | Thing      | The Alarm system configured in your Freebox Server            |

(*) 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:

| Parameter Label | Parameter ID | Description                                                                | Default |
|-----------------|--------------|----------------------------------------------------------------------------|         |
| Timeout         | timeout      | The timeout for reading from the API in seconds.                           | 10      |
| Callback URL    | callbackUrl  | URL to use for playing notification sounds, e.g. 'http://192.168.0.2:8080' |         |

## Thing Configuration

### Api Bridge

The *api* bridge thing requires the following configuration parameters:

| 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 HTTPS access to the Freebox Api                | No       | 443                  |
| Websocket Reconnect Interval  | wsReconnectInterval | Disconnection interval, in minutes- 0 disables websocket usage | No       | 60                   |

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 Things

The *revolution* or *delta* 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 the Freebox Server | No       | 30      |

### Player Things

The *player* or *active-player* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                                | Required | Default |
|------------------|-----------------|----------------------------------------------------------------------------|----------|---------|
| ID               | id              | Id of the player within Freebox Api                                        | Yes      | 1       |
| 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 Freebox player   | No       | 30      |

### Phone Things

The *fxs* or *dect* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                            | Required | Default |
|------------------|-----------------|------------------------------------------------------------------------|----------|---------|
| ID               | id              | Id of the phone line                                                   | Yes      | 1       |
| Refresh Interval | refreshInterval | The refresh interval in seconds which is used to poll for phone state. | No       | 30      |

The *call* 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 calls. | No       | 30      |

### Network Device Things

The *host* thing requires the following configuration parameters:

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

The *wifihost* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                            | Required | Default |
|------------------|-----------------|------------------------------------------------------------------------|----------|---------|
| MAC Address      | macAddress      | The MAC address of the network device.                                 | Yes      |         |
| Refresh Interval | refreshInterval | The refresh interval in seconds which is used to poll the device.      | No       | 30      |
| mDNS Name        | mDNS            | The mDNS name of the network device. 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.

### Freeplug Thing

The *freeplug* thing requires the following configuration parameters:

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

### Repeater Thing

The *repeater* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                         | Required | Default |
|------------------|-----------------|---------------------------------------------------------------------|----------|---------|

| 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 repeater. | No       | 30      |

### Virtual Machine Thing

The *vm* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                                | Required | Default |
|------------------|-----------------|----------------------------------------------------------------------------|----------|---------|

| ID               | id              | Id of the Virtual Machine                                                  | Yes      | 1       |
| Refresh Interval | refreshInterval | The refresh interval in seconds which is used to poll the virtual machine. | No       | 30      |

### Home Node Things

The *basic-shutter*, *shutter*, *kfb* or *alarm* thing requires the following configuration parameters:

| Parameter Label  | Parameter ID    | Description                                                      | Required | Default |
|------------------|-----------------|------------------------------------------------------------------|----------|---------|
| ID               | id              | Id of the Home Node                                              | Yes      | 1       |
| Refresh Interval | refreshInterval | The refresh interval in seconds which is used to poll the Node   | No       | 30      |

## 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 Type            | Channel Grpup ID  | Channel ID           | Item Type               | Access Mode | Description                                                                    |
|-----------------------|-------------------|----------------------|-------------------------|-------------|--------------------------------------------------------------------------------|
| revolution            | display           | lcd-brightness       | Number:Dimensionless    | RW          | Brightness level of the screen in percent                                      |
| revolution            | display           | lcd-orientation      | Number                  | RW          | Screen Orientation in degrees (0 or 90 or 180 or 270)                          |
| revolution            | display           | lcd-forced           | Switch                  | RW          | Indicates whether the screen orientation is forced                             |
| revolution, delta     | file-sharing      | ftp-status           | Switch                  | RW          | Indicates whether the FTP server is enabled                                    |
| revolution, delta     | file-sharing      | samba-file-status    | Switch                  | RW          | Indicates whether Windows File Sharing is enabled                              |
| revolution, delta     | file-sharing      | samba-printer-status | Switch                  | RW          | Indicates whether Windows Printer Sharing is enabled                           |
| revolution, delta     | file-sharing      | afp-file-status      | Switch                  | RW          | Indicates whether Mac OS File Sharing is enabled                               |
| revolution, delta     | sysinfo           | uptime               | Number:Time             | R           | Time since last reboot of the equipment                                        |
| revolution, delta     | sysinfo           | ip-address           | String                  | R           | Internal IPv4 Address of the Freebox Server                                    |
| revolution, delta     | sysinfo           | box-event            | Trigger                 | -           | Triggers when an event related to the Freebox server has been detected. Possible event: "restarted", "firmware_updated" and "reboot_requested" |
| revolution, delta     | actions           | wifi-status          | Switch                  | RW          | Indicates whether the WiFi network is enabled                                  |
| revolution, delta     | actions           | upnpav-status        | Switch                  | RW          | Indicates whether UPnP AV is enabled                                           |
| revolution, delta     | actions           | airmedia-status      | Switch                  | RW          | Indicates whether Air Media is enabled                                         |
| revolution, delta     | connection-status | line-status          | String                  | R           | Status of network line connection                                              |
| revolution, delta     | connection-status | line-type            | String                  | R           | Type of network line connection                                                |
| revolution, delta     | connection-status | line-media           | String                  | R           | Media of network line connection                                               |
| revolution, delta     | connection-status | ip-address           | String                  | R           | Public IPv4 Address of the Freebox Server                                      |
| revolution, delta     | connection-status | ipv6-address         | String                  | R           | Public IPv6 Address of the Freebox Server                                      |
| revolution, delta     | connection-status | bandwidth-up         | Number:DataTransferRate | R           | Raw value of the upload bandwidth                                              |
| revolution, delta     | connection-status | bandwidth-down       | Number:DataTransferRate | R           | Raw value of the download bandwidth                                            |
| revolution, delta     | connection-status | bandwidth-usage-up   | Number:Dimensionless    | R           | Portion of the upload bandwidth currently used                                 |
| revolution, delta     | connection-status | bandwidth-usage-down | Number:Dimensionless    | R           | Portion of the download bandwidth currently used                               |
| revolution, delta     | connection-status | rate-up              | Number:DataTransferRate | R           | Current upload rate                                                            |
| revolution, delta     | connection-status | rate-down            | Number:DataTransferRate | R           | Current download rate                                                          |
| revolution, delta     | connection-status | bytes-up             | Number:DataAmount       | R           | Total data uploaded since last restart                                         |
| revolution, delta     | connection-status | bytes-down           | Number:DataAmount       | R           | Total data downloaded since last restart                                       |
| active-player, player | player-actions    | key-code             | String                  | W           | Simulates pushing a remote control button                                      |
| active-player         | player-status     | player-status        | String                  | R           | Status of the Freebox TV player                                                |
| active-player         | player-status     | package              | String                  | R           | Name of the package currently active on the player                             |
| active-player         | sysinfo           | uptime               | Number:Time             | R           | Time since last reboot of the equipment                                        |
| active-player         | sysinfo           | box-event            | Trigger                 | -           | Triggers when an event related to the Freebox Player has been detected. Possible event: "restarted", "firmware_updated" and "reboot_requested" |
| vm                    | vmstatus          | status               | Switch                  | RW          | Status of the virtual machine                                                  |
| (*)                   | connectivity      | reachable            | Switch                  | R           | Indicates if the network device is reachable or not                            |
| (*)                   | connectivity      | last-seen            | DateTime                | R           | Date and time of last activity for the network device                          |
| (*)                   | connectivity      | ip-address           | String                  | R           | IPv4 Address of the network device                                             |
| fxs, dect             |                   | telephony-service    | String                  | R           | Status of the telephony service                                                |
| fxs, dect             |                   | ringing              | Switch                  | RW          | Is the phone ringing                                                           |
| fxs, dect             |                   | hardware-status      | String                  | R           | Hardware status of the phone line                                              |
| fxs                   |                   | onhook               | Switch                  | R           | Indicates whether the phone is on hook                                         |
| dect                  |                   | dect-active          | Switch                  | RW          | Activates / stops the integrated DECT base                                     |
| dect                  |                   | alternate-ring       | Switch                  | RW          | Alternating Ring                                                               |
| dect                  |                   | gain-rx              | Dimmer                  | RW          | Gain RX                                                                        |
| dect                  |                   | gain-tx              | Dimmer                  | RW          | Gain TX                                                                        |
| 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:Time             | 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:Time             | 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                                                      |
| basic-shutter | basic-shutter#basic-shutter | RollerShutter | W           | Up, stop and down commands for a RTS shutter                                   |

(*): any thing type amongst *active-player*, *player*, *host*, *wifihost*, *repeater* and *vm*.

## Actions for rules

The following actions are available in rules/scripting:

| Thing Type            | Action Name      | Parameters              | Description                                          |
|-----------------------|------------------|-------------------------|------------------------------------------------------|
| host, wifihost        | wol              | None                    | Sends a wake on lan packet to the lan connected host |
| active-player         | rebootPlayer     | None                    | Reboots the Freebox Player                           |
| active-player, player | sendKey          | key: String             | Sends a key (remote emulation) to the player         |
| active-player, player | sendLongKey      | key: String             | Sends a key emulating a longpress on the button      |
| active-player, player | sendMultipleKeys | keys: String            | Sends multiple keys to the player, comma separated   |
| active-player, player | sendKeyRepeat    | key: String, count: int | Sends a key multiple times                           |
| delta, revolution     | rebootServer     | None                    | Reboots the Freebox Server                           |
| freeplug              | resetPlug        | None                    | Resets the Freeplug                                  |
| call                  | resetCalls       | None                    | Deletes all calls logged in the queue                |
| repeater              | rebootRepeater   | None                    | Reboots the Free Repeater                            |