Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[FreeboxOs] Introducing new version of the Freebox binding. #9180

Closed
wants to merge 21 commits into from
Closed

[FreeboxOs] Introducing new version of the Freebox binding. #9180

Show file tree
Hide file tree
Changes from 15 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
f883b85
Introducing new version of the Freebox binding.
clinique Nov 29, 2020
2ff5d12
Solving SAT findings
clinique Nov 30, 2020
cc2b862
Handling periodical disconnection from the server
clinique Dec 2, 2020
a0836fe
Headers update and removal of SmartHomeUnits
clinique Jan 7, 2021
5e0dd68
Solving Nullables
clinique Jan 7, 2021
7d2f4a7
Code review modifications and documentation rewrite.
clinique Jun 16, 2021
7076361
Removing unused code
clinique Jun 19, 2021
53cf95b
Applying spotless
clinique Jun 19, 2021
4591e53
Forgot two files
clinique Jun 19, 2021
d3b0833
Code review corrections and pom update
clinique Aug 9, 2021
464b8b5
Solving SAT findings
clinique Aug 9, 2021
d79d90c
First review of @lolodomo
clinique Aug 10, 2021
748afe2
Configuration simplification (removed api version and base url as the…
clinique Aug 10, 2021
350052b
Code review corrections
clinique Sep 1, 2021
27d4bcc
Code review #5
clinique Sep 1, 2021
f8c7811
Code review number 6
clinique Sep 3, 2021
349029d
Properties are now filled if thing created from file or for discovery.
clinique Sep 18, 2021
867a8c8
Adding AirMediaSink as a capability of various things.
clinique Sep 27, 2021
9583554
Solving feature.xml issue regarding hibernate validator
clinique Sep 27, 2021
cfb8b34
Integrating AirMediaSink
clinique Sep 29, 2021
54ab9eb
Finalized proper handling of AirMedia
clinique Sep 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CODEOWNERS
View file
Open in desktop
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@
/bundles/org.openhab.binding.folding/ @fa2k
/bundles/org.openhab.binding.foobot/ @airboxlab @Hilbrand
/bundles/org.openhab.binding.freebox/ @lolodomo
/bundles/org.openhab.binding.freeboxos/ @clinique
/bundles/org.openhab.binding.fronius/ @trokohl
/bundles/org.openhab.binding.fsinternetradio/ @paphko
/bundles/org.openhab.binding.ftpupload/ @paulianttila
Expand Down
5 changes: 5 additions & 0 deletions bom/openhab-addons/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -441,6 +441,11 @@
<artifactId>org.openhab.binding.freebox</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.openhab.addons.bundles</groupId>
<artifactId>org.openhab.binding.freeboxos</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.openhab.addons.bundles</groupId>
<artifactId>org.openhab.binding.fronius</artifactId>
Expand Down
13 changes: 13 additions & 0 deletions bundles/org.openhab.binding.freeboxos/NOTICE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
This content is produced and maintained by the openHAB project.

* Project home: https://www.openhab.org

== Declared Project Licenses

This program and the accompanying materials are made available under the terms
of the Eclipse Public License 2.0 which is available at
https://www.eclipse.org/legal/epl-2.0/.

== Source Code

https://github.com/openhab/openhab-addons
172 changes: 172 additions & 0 deletions bundles/org.openhab.binding.freeboxos/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
# Freebox Binding

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.

## 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 | The TV player equipment (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 (>= Delta). |
| repeater | Thing | A Free wifi repeater. |

## 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

The binding itself is not configurable.

## 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 |
| 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 |

clinique marked this conversation as resolved.
Show resolved Hide resolved
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 |
clinique marked this conversation as resolved.
Show resolved Hide resolved
| 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 and WifiHost

The *host* and *wifihost* things requires the following configuration parameters:
clinique marked this conversation as resolved.
Show resolved Hide resolved

| 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 |

### 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 | |
clinique marked this conversation as resolved.
Show resolved Hide resolved
| ID | id | Id of the repeater within Freebox Api | Yes | 1 |
clinique marked this conversation as resolved.
Show resolved Hide resolved
| Refresh Interval | refreshInterval | The refresh interval in seconds which is used to poll the player | Yes | 30 |
clinique marked this conversation as resolved.
Show resolved Hide resolved

## 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 Freebox 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

**Optionally** you can log in your Freebox admin console to allocate needed rights to openHAB

Once initialized, the thing will generate all available channels.

clinique marked this conversation as resolved.
Show resolved Hide resolved
## 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 |
| phone | accepted#number | Call | R | Last accepted call: number |
| phone | accepted#duration | Number | R | Last accepted call: duration in seconds |
| phone | accepted#timestamp | DateTime | R | Last accepted call: creation timestamp |
| phone | accepted#name | String | R | Last accepted call: caller name |
| phone | missed#number | Call | R | Last missed call: number |
| phone | missed#timestamp | DateTime | R | Last missed call: creation timestamp |
| phone | missed#name | String | R | Last missed call: caller name |
| phone | outgoing#number | Call | R | Last outgoing call: number |
| phone | outgoing#duration | Number | R | Last outgoing call: duration in seconds |
| phone | outgoing#timestamp | DateTime | R | Last outgoing call: creation timestamp |
| phone | outgoing#name | String | R | Last outgoing call: 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 |

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

## Actions for ules

The following actions are available in rules/scripting:

| Thing Type | Action Name | Description |
|-------------|------------------|------------------------------------------------------|
| host | wol | Sends a wake on lan packet to the lan connected host |
| player | reboot | Reboots the player device. |
| player | sendKey | Send a key (remote emulation) to the player |
| player | sendLongKey | Sends the key emulating a longpress on the button |
| player | sendMultipleKeys | Sends multiple keys to the player, comma separated |
| player | sendKeyRepeat | Sends the key multiple times |
| server | reboot | Reboots the Freebox Server. |

Copy link
Contributor

@lolodomo lolodomo Aug 10, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you should add a last section listing all features or channels that are no more present in this new version of the binding, compared to the current binding.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There should not be missing channels between the two versions, maybe only new ways to access the same info.

Copy link
Contributor

@lolodomo lolodomo Aug 10, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok for the channels, I will compare later. So maybe just add a sentence in this new section mentioning that all channels from the freebox binding are still available but sometimes with a different name, a different type (UoM) and on a different thing.

In this case, just focus on missing features. In the current binding, I distinguished between network device and network interface to monitor reachability. You did it, I believe, only on network devices. So add something like "Monitoring of network interfaces reachability is no more available while monitoring of network devices reachability is still available."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A missing feature to be mentioned: no more possible to monitor the reachability of a particular IP address. Only the reachability of a device defined by its MAC is now available.

17 changes: 17 additions & 0 deletions bundles/org.openhab.binding.freeboxos/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>org.openhab.addons.bundles</groupId>
<artifactId>org.openhab.addons.reactor.bundles</artifactId>
<version>3.2.0-SNAPSHOT</version>
</parent>

<artifactId>org.openhab.binding.freeboxos</artifactId>

<name>openHAB Add-ons :: Bundles :: FreeboxOS Binding</name>

</project>
10 changes: 10 additions & 0 deletions bundles/org.openhab.binding.freeboxos/src/main/feature/feature.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<features name="org.openhab.binding.freeboxos-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
<repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository>

<feature name="openhab-binding-freeboxos" description="Freebox OS Binding" version="${project.version}">
<feature>openhab-runtime-base</feature>
<feature>openhab-transport-mdns</feature>
<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.freeboxos/${project.version}</bundle>
</feature>
</features>
Loading