# FreeboxOS Binding
Free is a French telecom operator providing advanced equipments to manage your broadband access.
This binding integrates the Freebox Revolution (opens new window) and Freebox Delta (opens new window) 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 (opens new window) |
| 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 |
| 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 (opens new window)). 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 (opens new window)' | 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 |
← Freebox Freecurrency →