mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-10 23:22:02 +01:00
1f17e53bc2
Also rename actions to avoid name conflicts. Fix #17225 Signed-off-by: Laurent Garnier <lg.hc@free.fr>
226 lines
20 KiB
Markdown
226 lines
20 KiB
Markdown
# 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 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: 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, 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 |
|