This page is part of archived documentation for openHAB 4.1. Go to the current stable version

# 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