Wi-Fi¶
The Wi-Fi API allow you to control the settings of the Freebox Wi-Fi.
Wi-Fi Errors¶
When attempting to access this API, you may encounter the following errors:
error_code | Description |
---|---|
inval | invalid parameters |
exist | entry already exists |
nospc | maximum entry count reached |
nodev | invalid device id |
noent | invalid id |
busy | device busy |
inval_band | invalid wifi band |
inval_ssid | invalid ssid |
inval_freq | invalid wifi frequency |
inval_cipher | invalid cipher mod |
inval_key_len | invalid key length |
inval_key | invalid key |
inval_ht_mode | invalid 802.11n mode |
inval_ht_mode | invalid wifi frequency for this 802.11n mode |
inval_ht_needs_wmm | wmm must be enabled for 802.11n |
inval_ac_needs_ht | invalid configuration 802.11ac need ht support |
inval_ac_not_2d4g | invalid configuration 802.11ac is not supported on 2.4G band |
Wi-Fi Global Config¶
Global config gives quick access to major configuration settings (eg: toggle Wi-Fi)
WifiGlobalConfig has the following attributes:
Wi-Fi global config API¶
Get the current Wi-Fi global configuration¶
-
GET
/api/v2/wifi/config/
¶ Get the
WifiGlobalConfig
Example request:
GET /api/v2/wifi/config/ HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "enabled": true, "mac_filter_state": "blacklist" } }
Update the Wi-Fi global configuration¶
-
PUT
/api/v2/wifi/config/
¶ Update the
WifiGlobalConfig
Example request:
PUT /api/v2/wifi/config/ HTTP/1.1 Host: mafreebox.freebox.fr
{ "enabled": false }
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "enabled": false, "mac_filter_state": "blacklist" } }
Wi-Fi Access Point¶
Wi-Fi AP objects¶
The Freebox may have one or more access points, you can configure each access point with this api.
-
WifiAp
¶ -
id
int Read-only¶ wifi ap id
-
name
string Read-only¶ wifi ap name
-
status
WifiApStatus Read-only¶ ap status
-
capabilites
WifiApCapabilities Read-only¶ ap capabilities
-
config
WifiApConfig¶ ap configuration
-
-
WifiApStatus
¶ -
state
enum Read-only¶ state Description scanning Ap is probing wifi channels no_param Ap is not configured bad_param Ap has an invalid configuration disabled Ap is permanently disabled disabled_planning Ap is currently disabled according to planning no_active_bss Ap has no active BSS starting Ap is starting acs Ap is selecting the best available channel ht_scan Ap is scanning for other access point dfs Ap is performing dynamic frequency selection active Ap is active failed Ap has failed to start
-
-
WifiApCapabilities
¶ - [UNSTABLE]
-
2d4g
int Read-only¶ map of capabilites in 2.4 GHz band
-
5g
int Read-only¶ map of capabilites in 5 GHz band
-
60g
int Read-only¶ map of capabilites in 60 GHz band
-
NOTE: before enabling some feature in ap config, you should ensure that AP supports the feature using its provided capabilities.
-
WifiApConfig
¶ -
band
enum¶ band Description 2d4g 2.4 GHz 5g 5 GHz 60g 60 GHz
-
channel_width
int¶ wanted channel width (in MHz) :
- 20 MHz
- 40 MHz
- 80 MHz
- 160 MHz
-
primary_channel
int¶ wanted primary channel, value of 0 means automatic selection
-
secondary_channel
int¶ wanted secondary channel, value of 0 means automatic selection
-
dfs_enabled
bool¶ enable channels that require DFS
-
ht
WifiApHtConfig¶ wifi ht config
-
Wi-Fi AP API¶
Get the ap list¶
-
GET
/api/v2/wifi/ap/
¶ Get the list of Freebox Access Points
WifiAp
Example request:
GET /api/v2/wifi/ap/ HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": [ { "capabilities": { "2d4g": { "shortgi20": true, "vht_rx_ldpc": false, [ ... ] "shortgi40": true, }, "60g": { [ ... ] }, "5g": { [ ... ] } }, "name": "2.4G", "id": 0, "config": { "channel_width": "40", "ht": { "ht_enabled": true, "ac_enabled": false, [ ... ] }, "dfs_enabled": false, "band": "2d4g", "secondary_channel": 13, "primary_channel": 9 }, "status": { "channel_width": "20", "primary_channel": 9, "dfs_cac_remaining_time": 0, "secondary_channel": 0, "state": "active" } } ] }
Get a particular AP¶
-
GET
/api/v2/wifi/ap/{id}
¶ Get the
WifiAp
with the requested idExample request:
GET /api/v2/wifi/ap/0 HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "capabilities": { "2d4g": { "shortgi20": true, "vht_rx_ldpc": false, [ ... ] "shortgi40": true, }, "60g": { [ ... ] }, "5g": { [ ... ] } }, "name": "2.4G", "id": 0, "config": { "channel_width": "40", "ht": { "ht_enabled": true, "ac_enabled": false, [ ... ] }, "dfs_enabled": false, "band": "2d4g", "secondary_channel": 13, "primary_channel": 9 }, "status": { "channel_width": "20", "primary_channel": 9, "dfs_cac_remaining_time": 0, "secondary_channel": 0, "state": "active" } } }
Update an AP¶
-
PUT
/api/v2/wifi/ap/{id}
¶ Update the
WifiAp
Example request:
PUT /api/v2/wifi/ap/0 HTTP/1.1 Host: mafreebox.freebox.fr
{ "config": { "channel_width": "20", "ht": { "ht_enabled": false }, "primary_channel": 0, "secondary_channel": 0 } }
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "capabilities": [ ... ], "name": "2.4G", "id": 0, "config": { "channel_width": "20", "ht": { "ht_enabled": false, "ac_enabled": false [ ... ] }, "dfs_enabled": false, "band": "2d4g", "secondary_channel": 0, "primary_channel": 0 }, "status": { "channel_width": "20", "primary_channel": 0, "dfs_cac_remaining_time": 0, "secondary_channel": 0, "state": "scanning" } } }
Wi-Fi AP allowed channels¶
To be able to allow user to pick a valid channel combination for a given AP you should use the following api to retreive the list of allowed channel combination.
-
WifiAllowedComb
¶ -
band
enum Read-only¶ the band for which the combination can be used
band Description 2d4g 2.4 GHz 5g 5 GHz 60g 60 GHz
-
channel_width
string Read-only¶ the channel_width for which the combination can be used
-
need_dfs
bool Read-only¶ does this combination requires DFS.
You should only allow this combination if ap has allowed dfs.
-
dfs_cac_time
int Read-only¶ time required in dfs state before behing able to start the AP.
-
primary
int Read-only¶ primary channel
-
secondary
int Read-only¶ secondary channel (zero means that secondary channel will not be used)
-
-
GET
/api/v2/wifi/ap/{id}/allowed_channel_comb
¶ Get the
WifiAllowedComb
for the given ap idExample request:
GET /api/v2/wifi/ap/0/allowed_channel_comb HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": [ { "channel_width": "20", "dfs_cac_time": 0, "need_dfs": false, "primary": 1, "band": "2d4g", "secondary": 0 }, [ ... ] { "channel_width": "20", "dfs_cac_time": 0, "need_dfs": false, "primary": 13, "band": "2d4g", "secondary": 0 }, { "channel_width": "40", "dfs_cac_time": 0, "need_dfs": false, "primary": 1, "band": "2d4g", "secondary": 5 }, [ ... ] { "channel_width": "40", "dfs_cac_time": 0, "need_dfs": false, "primary": 13, "band": "2d4g", "secondary": 9 } ] }
Wi-Fi AP stations¶
Wi-Fi AP Stations objects¶
WifiStation has the following attributes:
-
WifiStation
¶ -
id
string Read-only¶ station id
-
mac
string Read-only¶ client MAC address
-
bssid
string Read-only¶ bssid on which the client is associated
-
hostname
string Read-only¶ client host name
-
state
enum Read-only¶ state Description associated station is associated authenticated station is authenticated
-
inactive
int Read-only¶ inactive duration (in seconds)
-
conn_duration
int Read-only¶ connection duration (in seconds)
-
rx_bytes
int Read-only¶ received bytes (from station to Freebox)
-
tx_bytes
int Read-only¶ transmitted bytes (from Freebox to station)
-
tx_rate
int Read-only¶ reception data rate (in bytes/s)
-
rx_rate
int Read-only¶ transmission data rate (in bytes/s)
-
signal
int Read-only¶ signal attenuation (in dB)
-
flags
WifiStationFlags Read-only¶ station flags
-
last_rx
WifiStationStats Read-only¶ last rx stats
-
last_tx
WifiStationStats Read-only¶ last tx stats
-
-
WifiStationFlags
¶ - [UNSTABLE]
-
legacy
bool Read-only¶ does station uses legacy wifi (802.11a, 802.11b)
-
ht
bool Read-only¶ does station support ht (802.11n)
-
vht
bool Read-only¶ does station support vht (802.11ac)
is the station authenticated
-
-
WifiStationStats
¶ - [UNSTABLE]
-
bitrate
int Read-only¶ physical link rate (in 1/10th of MBit/s), -1 if unknown
-
mcs
int Read-only¶ current link mcs, -1 if not used
-
vht_mcs
int Read-only¶ current link vht mcs, -1 if not used
-
width
string Read-only¶ current channel width
-
shortgi
bool Read-only¶ is shortgi enabled
-
Get Wi-Fi Stations List¶
-
GET
/api/v2/wifi/ap/{id}/stations/
¶ Get the list of
WifiStation
associated to the APExample request:
GET /api/v2/wifi/ap/0/stations/ HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": [ { "mac": "18:AF:36:15:69:42", "last_rx": { "bitrate": 110, "mcs": -1, "shortgi": false, "vht_mcs": -1, "width": "20" }, "tx_bytes": 2651, "last_tx": { "bitrate": 360, "mcs": -1, "shortgi": false, "vht_mcs": -1, "width": "20" }, "id": "00:24:D4:AC:DC:88-18:AF:36:15:69:42", "bssid": "00:24:D4:AC:DC:88", "flags": { "vht": false, "legacy": false, "authorized": true, "ht": false }, "tx_rate": 0, "host": { [ ... ] }, "inactive": 168, "conn_duration": 263, "hostname": "iPhone-de-r0ro", "state": "authenticated", "rx_bytes": 781, "rx_rate": 0, "signal": -38 } ] }
Wi-Fi BSS¶
Each AP can manage a set of BSS, with this api you can manage BSS settings
Wi-Fi BSS objects¶
-
WifiBss
¶ -
id
int Read-only¶ bss id
-
phy_id
string Read-only¶ associated AP id
-
status
WifiBssStatus Read-only¶ bss status
-
config
WifiBssConfig¶ bss configuration
-
-
WifiBssStatus
¶ -
state
enum Read-only¶ state Description phy_stopped associated AP is stopped no_param bss is missing config bad_param bss has an invalid config disabled bss is disabled starting bss is starting active bss is active failed bss has failed to start
-
sta_count
int Read-only¶ - number of stations for this bss
number of authenticated stations for this bss
-
is_main_bss
bool Read-only¶ if bss is main bs, its configuration will be reused for other bss with attribute use_default_config set as true. This can be used to apply the same configuration to 2 bss on 2 AP operating on different wifi bands.
-
-
WifiBssConfig
¶ -
enabled
bool¶ enable this BSS. Note that if you want the AP to completely stop emitting wifi you should use
WifiGlobalConfig
enabled attribute, otherwise FreeWifi and FreeWifi Secure may still be active.
-
use_default_config
bool¶ - if true, share the configuration with the main bss
-
ssid
str¶ bss displayed name
-
hide_ssid
str¶ don’t show bss in bss list
-
encryption
enum¶ encryption Description wep wep (should not use) wpa_psk_auto wpa/psk auto wpa_psk_tkip wpa/psk tkip wpa_psk_ccmp wpa/psk ccmp wpa2_psk_auto wpa2/psk auto wpa2_psk_tkip wpa2/psk tkip wpa2_psk_ccmp wpa2/psk ccmp
-
-
key
string Write-only¶ wifi key
-
eapol_version
int Read-only¶ eapol version
-
Wi-Fi BSS API¶
Get the bss list¶
-
GET
/api/v2/wifi/bss/
¶ Get the list of Freebox Access Points
WifiBss
Example request:
GET /api/v2/wifi/bss/ HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": [ { "id": "00:24:D4:AA:BB:CC", "config": { "enabled": true, "ssid": "Freebox r0ro", "encryption": "wpa2_psk_auto", "use_default_config": true, "hide_ssid": false, "eapol_version": 2, "key": "jesaispasdevine!" }, "phy_id": 0, "status": { "state": "active", "sta_count": 1, "authorized_sta_count": 1, "is_main_bss": true } }, { "id": "14:0C:76:AA:BB:CC", "config": { "enabled": true, "ssid": "Freebox r0ro", "encryption": "wpa2_psk_auto", "use_default_config": true, "hide_ssid": false, "eapol_version": 2, "key": "jesaispasdevine!" }, "phy_id": 1, "status": { "state": "active", "sta_count": 0, "authorized_sta_count": 0, "is_main_bss": false } } ] }
Get a particular BSS¶
-
GET
/api/v2/wifi/bss/{id}
¶ Get the
WifiBss
with the requested idExample request:
GET /api/v2/wifi/bss/00:24:D4:AA:BB:CC HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "id": "00:24:D4:AA:BB:CC", "config": { "enabled": true, "ssid": "Freebox r0ro", "encryption": "wpa2_psk_auto", "use_default_config": true, "hide_ssid": false, "eapol_version": 2, "key": "jesaispasdevine!" }, "phy_id": 0, "status": { "state": "active", "sta_count": 1, "authorized_sta_count": 1, "is_main_bss": true } } }
Update an BSS¶
-
PUT
/api/v2/wifi/bss/{id}
¶ Update the
WifiAp
Example request:
PUT /api/v2/wifi//bss/00:24:D4:AA:BB:CC HTTP/1.1 Host: mafreebox.freebox.fr
{ "config": { "key": "c'était trop facile" } }
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "id": "00:24:D4:AA:BB:CC", "config": { "enabled": true, "ssid": "Freebox r0ro", "encryption": "wpa2_psk_auto", "use_default_config": true, "hide_ssid": false, "eapol_version": 2, "key": "c'était trop facile" }, "phy_id": 0, "status": { "state": "active", "sta_count": 0, "authorized_sta_count": 0, "is_main_bss": true } } }
Wi-Fi Radar¶
With this api you can list the surrounding Wi-Fi access points, and Wi-fi channel usage.
This a new feature introduced in firmware 2.1.0 (api v2).
A scan is automatically done at AP startup, if you need to refresh the information you can use the scan api
Wi-Fi Neighbor Object¶
WifiNeighbor has the following attributes:
-
WifiNeighbor
¶ -
bssid
string Read-only¶ neighbor bssid
-
ssid
string Read-only¶ neighbor ssid
-
band
enum Read-only¶ the band for which the combination can be used
band Description 2d4g 2.4 GHz 5g 5 GHz 60g 60 GHz
-
channel_width
int Read-only¶ neighbor channel_width
-
channel
int Read-only¶ neighbor primary channel
-
secondary_channel
int Read-only¶ neighbor secondary channel (0 for unused)
-
signal
int Read-only¶ signal attenuation in dB
-
capabilities
WifiNeighborCap Read-only¶ neighbor capabilities
-
List AP neighbors¶
-
GET
/api/v2/wifi/ap/{id}/neighbors/
¶ Get the list of
WifiNeighbor
seen by the APExample request:
GET /api/v2/wifi/ap/0/neighbors/ HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": [ { "channel_width": "20", "capabilities": { "legacy": false, "vht": false, "ht": true }, "ssid": "FreeWifi_secure", "channel": 1, "band": "2d4g", "bssid": "00:24:D4:BA:BB:EE", "secondary_channel": 0, "signal": -27 }, [ ... ] { "channel_width": "20", "capabilities": { "legacy": false, "vht": false, "ht": true }, "ssid": "Encore une freebox", "channel": 1, "band": "2d4g", "bssid": "F4:CA:E5:5E:AC:4F", "secondary_channel": 0, "signal": -33 }, { "channel_width": "20", "capabilities": { "legacy": false, "vht": false, "ht": true }, "ssid": "lav6-140c76670212", "channel": 1, "band": "2d4g", "bssid": "00:07:CB:00:00:FD", "secondary_channel": 0, "signal": -33 } ] }
Wi-Fi Channel usage Object¶
List Wi-Fi channels usage¶
-
GET
/api/v2/wifi/ap/{id}/channel_usage/
¶ Get the list of
WifiChannelUsage
for the given APExample request:
GET /api/v2/wifi/ap/0/channel_usage/ HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": "result": [ { "band": "2d4g", "noise_level": -66, "rx_busy_percent": 35, "channel": 1 }, [ ... ] { "band": "2d4g", "noise_level": -58, "rx_busy_percent": 46, "channel": 13 } ] }
Refresh radar informations¶
WARNING durring the scan the AP will be unavailable. Therefore, you should ask for user confirmation prior to launching a scan.
Once launched you should wait until the ap state comes back from scanning to get updated info.
-
POST
/api/v2/wifi/ap/{id}/neighbors/scan
¶ Launch a wifi scan on given ap
Example request:
POST /api/v2/wifi/ap/0/neighbors/scan HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true }
Wi-Fi Planning¶
With api v2 you can now specify time range when you want to enable your wifi.
Wi-Fi Planning Object¶
-
WifiPlanning
¶ -
use_planning
bool¶ is the planning enabled
-
resolution
int Read-only¶ planning resolution (number of slots per day)
-
mapping
[] array of str¶ mapping for planning : “on” or “off” mapping[0] is monday at 0:0 mapping[7 * resolution - 1] is sunday last slot
(each slot has a duration of 60 * 24 / resolution minutes)
-
Get Wi-Fi Planning¶
-
GET
/api/v2/wifi/planning/
¶ Get the list of
WifiChannelUsage
for the given APExample request:
GET /api/v2/wifi/planning/ HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "use_planning": false, "resolution": 48, "mapping": [ "on", "on", "on", "on", [ ... ] "on", "on", "on", "on" ] } }
Update Wi-Fi Planning¶
-
PUT
/api/v2/wifi/planning/
¶ Get the list of
WifiChannelUsage
for the given APExample request:
PUT /api/v2/wifi/planning/ HTTP/1.1 Host: mafreebox.freebox.fr
{ "use_planning": true }
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "use_planning": true, "resolution": 48, "mapping": [ "on", "on", "on", "on", [ ... ] "on", "on", "on", "on" ] } }
Wi-Fi MAC Filter API¶
Wi-Fi MAC Filter object¶
WifiMacFilter has the following attributes:
-
WifiMacFilter
¶ -
id
string Read-only¶ filter id
-
mac
string Read-only¶ MAC address to filter
-
comment
string¶ comment
-
type
enum¶ type Description whitelist if mac_filter is set to whitelist this station will be allowed blacklist if mac_filter is set to blacklist this station will be rejected
-
hostname
string Read-only¶ host name when available
-
Get the MAC filter list¶
-
GET
/api/v2/wifi/mac_filter/
¶ Get the list of
WifiMacFilter
Example request:
GET /api/v2/wifi/mac_filter/ HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": [ { "mac": "00:07:CB:01:02:03", "type": "whitelist", "comment": "test", "hostname": "00:07:CB:01:02:03", "id": "00:07:CB:01:02:03" }, { "mac": "00:24:D4:00:00:69", "type": "blacklist", "comment": "plop", "hostname": "r0ro's iPad", "id": "00:24:D4:00:00:69", "host": { [ ... ] } } ] }
Getting a particular MAC filter¶
-
GET
/api/v2/wifi/mac_filter/{filter_id}
¶ Returns the requested
WifiMacFilter
propertiesExample request:
GET /api/v2/wifi/mac_filter/00:07:CB:01:02:03 HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "mac": "00:07:CB:01:02:03", "type": "whitelist", "comment": "test", "hostname": "00:07:CB:01:02:03", "id": "00:07:CB:01:02:03" } }
Updating a MAC filter¶
-
PUT
/api/v2/wifi/mac_filter/{filter_id}
¶ Update a
WifiMacFilter
propertiesExample request:
PUT /api/v2/wifi/mac_filter/ HTTP/1.1 Host: mafreebox.freebox.fr
{ "comment": "filtre de test", "type": "blacklist" }
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "mac": "00:07:CB:01:02:03", "type": "blacklist", "comment": "filtre de test", "hostname": "00:07:CB:01:02:03", "id": "00:07:CB:01:02:03" } }
Delete a MAC filter¶
-
DELETE
/api/v2/wifi/mac_filter/{filter_id}
¶ Delete the
WifiMacFilter
with the given idExample request:
DELETE /api/v2/wifi/mac_filter/00:07:CB:01:02:03 HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true }
Create a new MAC filter¶
-
POST
/api/v2/wifi/mac_filter/
¶ Crate a new the
WifiMacFilter
Example request:
POST /api/v2/wifi/mac_filter/00:07:CB:01:02:03 HTTP/1.1 Host: mafreebox.freebox.fr
{ "comment": "filtre de test", "type": "blacklist", "mac": "00:07:CB:CB:07:00" }
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true, "result": { "mac": "00:07:CB:CB:07:00", "type": "blacklist", "comment": "filtre de test", "hostname": "00:07:CB:CB:07:00", "id": "00:07:CB:CB:07:00" } }
Wifi Config reset¶
You can reset Wifi to default configuration with this api
-
POST
/api/v2/wifi/config/reset/
¶ Crate a new the
WifiMacFilter
Example request:
POST /api/v2/wifi/config/reset/ HTTP/1.1 Host: mafreebox.freebox.fr
Example response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
{ "success": true }