### Device/Service Name
Freebox Player Delta (Devialet) and Révolution — Freebo…xOS Player API
### Existing Integrations & Documentation
1. Homebridge plugin (JavaScript, référence principale) :
https://github.com/securechicken/homebridge-freebox-player-delta
2. OpenHAB binding (Java, bonne référence pour la découverte mDNS et le flow auth) :
https://www.openhab.org/addons/bindings/freeboxos/
3. Documentation officielle FreeboxOS API :
https://dev.freebox.fr/sdk/os/
### Device Capabilities
- Power on/off detection (via AirPlay TCP port 7000 probe)
- Volume control (set level, mute/unmute)
- Media control (play, pause, stop, next, previous)
- Channel change (open TV channel by number)
- Virtual remote key sending (up, down, left, right, ok, back, home)
- Current status reading (current app, current channel, volume level)
### Additional Context
{
"notes": "Cheat-sheet pour Freebox Player via FreeboxOS (endpoints JSON). Remplace `MAFREEBOX` par l'IP/hostname local (ex: mafreebox.freebox.fr) et {id_player} par l'id renvoyé par /api/vX/player. Les versions d'API (vX / v6 / vN) peuvent varier selon box/firmware.",
"auth": {
"overview": "Flow d'authentification FreeboxOS : register app -> authorize (user confirme sur panneau) -> GET /api/vX/login to obtain challenge -> POST /api/vX/login/session with hmac(challenge, app_token) -> use session_token in header X-Fbx-App-Auth for subsequent calls.",
"endpoints": [
{
"description": "Get API version / discovery",
"method": "GET",
"url": "https://MAFREEBOX/api_version"
},
{
"description": "Request authorization (register app)",
"method": "POST",
"url": "https://MAFREEBOX/api/vX/login/authorize/",
"body_example": {
"app_id": "com.matterbridge.freebox",
"app_name": "Matterbridge Freebox",
"app_version": "1.0.0",
"device_name": "Matterbridge"
},
"notes": "User must validate the request on the Freebox front panel. Returns app_token to store persistently."
},
{
"description": "Get challenge",
"method": "GET",
"url": "https://MAFREEBOX/api/vX/login/"
},
{
"description": "Open session",
"method": "POST",
"url": "https://MAFREEBOX/api/vX/login/session/",
"body_example": {
"app_id": "com.matterbridge.freebox",
"password": "HMAC_SHA1(app_token, challenge)"
},
"note": "Use returned session_token as header X-Fbx-App-Auth."
}
]
},
"discovery": {
"mdns": "The Freebox broadcasts '_fbx-api._tcp' via mDNS for automatic discovery on local network.",
"fallback": "If mDNS fails, use hardcoded http://mafreebox.freebox.fr or user-supplied IP.",
"list_players": {
"method": "GET",
"url": "https://MAFREEBOX/api/vX/player",
"note": "Returns player list with id, model, api_version, reachable fields."
}
},
"player_endpoints": {
"get_status": {
"method": "GET",
"url": "https://MAFREEBOX/api/vX/player/{id}/api/{api_version}/status"
},
"set_volume": {
"method": "PUT",
"url": "https://MAFREEBOX/api/vX/player/{id}/api/{api_version}/control/volume/",
"body_examples": [{ "volume": 40 }, { "mute": true }]
},
"media_control": {
"method": "POST",
"url": "https://MAFREEBOX/api/vX/player/{id}/api/{api_version}/control/mediactrl",
"body_examples": [{ "command": "play" }, { "command": "pause" }, { "command": "stop" }]
},
"open_channel": {
"method": "POST",
"url": "https://MAFREEBOX/api/vX/player/{id}/api/{api_version}/control/open",
"body_example": { "url": "tv:?channel=2" }
},
"remote_key": {
"method": "POST",
"url": "https://MAFREEBOX/api/vX/player/{id}/api/{api_version}/control/remote",
"body_examples": [{ "key": "ok" }, { "key": "back" }, { "key": "home" }]
}
},
"power_detection": {
"method": "TCP port probe on port 7000 (AirPlay service)",
"note": "AirPlay must be enabled on the player (default). If port 7000 open = player ON, closed = OFF."
},
"compatibility": {
"confirmed_working": ["Freebox Delta / Devialet"],
"should_work": ["Freebox Révolution"],
"limited": ["Freebox Pop / Mini 4K (AndroidTV, Player API incomplete)"]
}
}
- Priority: support Delta/Devialet first, Révolution as secondary target
- Auth flow: the app_token obtained after user validation on Freebox front panel
must be stored persistently in plugin config (not re-requested on each start)
- Discovery: try mDNS first (_fbx-api._tcp), fallback to mafreebox.freebox.fr,
then user-supplied IP/hostname
- Power status: probe AirPlay TCP:7000 (default) with configurable alternative
port 54243
- Handle gracefully: not_implemented errors (some endpoints missing on some models)
- Session renewal: session_token expires, implement automatic re-login using
stored app_token
### Confirmations
- [x] I have provided links to existing integrations in other projects
- [x] I have verified the API documentation is accessible
- [x] I understand this is an automated AI process and results may vary
- [x] I am willing to test the generated plugin and provide feedback
Authentication via validation on the Freebox screen