wifi¶
ibox.wifi in the library, ibox wifi in the CLI.
Query and configure Wi-Fi radios, SSIDs, guest networks, and band steering.
summary ¶
A short overview of the Wi-Fi and guest Wi-Fi networks: name, password, channel and devices of each band.
Each band's entry also has its encryption and whether it's up and visible. The overview also says whether Wi-Fi and WPS are on and whether the bands share their settings. The access points' full settings take about 60 KB in lan.mibs() and in guest_mibs().
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
a JSON object, e.g. {"enabled": true, "bands_share_settings": false, "wps": true, "networks": [{"network": "Wi-Fi", "band": "5GHz", "ssid": "MyHome", ...}]} |
set_enabled ¶
Turn all Wi-Fi networks on or off, like the Wi-Fi switch in the web UI.
Turning Wi-Fi off disconnects every wireless device, including this computer if it uses Wi-Fi. Turn it back on from a wired connection or with the button on the router. The guest network stays off when Wi-Fi comes back on (the web UI's switch doesn't turn it on again either): use set_guest_enabled() for that.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enable
|
bool
|
True to turn Wi-Fi on, False to turn it off. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
set_network ¶
set_network(ssid: str | None = None, password: str | None = None, visible: bool | None = None, band: Literal['2.4GHz', '5GHz'] | None = None) -> str
Change the Wi-Fi network's name, password or visibility, like the Wi-Fi settings in the web UI.
Settings you leave out stay as they are, and so does the encryption. Wireless devices lose their connection while the router applies the change, and must then reconnect with the new name and password. The guest network has its own settings: see set_guest_network().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ssid
|
str | None
|
network name, 2 to 32 letters, digits, spaces or symbols, e.g. "MyHome". |
None
|
password
|
str | None
|
12 to 63 characters, with a lower-case letter, an upper-case letter, a digit and a symbol such as - or !. |
None
|
visible
|
bool | None
|
False hides the network name: devices then have to enter it to join. |
None
|
band
|
str | None
|
"2.4GHz" or "5GHz" to change one band only. Only when the bands have separate settings (see ConfigurationMode in status()). Default: all bands. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
Raises:
| Type | Description |
|---|---|
ValueError
|
if a value would be refused by the web UI, or the router doesn't accept the change. Bands changed before the router refused keep their new settings. |
set_guest_network ¶
Change the guest Wi-Fi network's name or password, like the guest Wi-Fi settings in the web UI.
Settings you leave out stay as they are, and so do the encryption and whether the guest network is on (see set_guest_enabled()). Devices on the guest network must reconnect with the new name and password.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ssid
|
str | None
|
network name, 2 to 32 letters, digits, spaces or symbols, different from the Wi-Fi's. |
None
|
password
|
str | None
|
12 to 63 characters, with a lower-case letter, an upper-case letter, a digit and a symbol such as - or !, different from the Wi-Fi's. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
Raises:
| Type | Description |
|---|---|
ValueError
|
if a value would be refused by the web UI, or the router doesn't accept the change. |
set_wps_enabled ¶
Turn WPS on or off, like the WPS switch in the web UI's Wi-Fi settings.
With WPS on, the WPS button on the router or start_wps_pairing() lets a device join without the password.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enable
|
bool
|
True to turn WPS on, False to turn it off. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
start_wps_pairing ¶
Start WPS pairing, like pressing the WPS button on the router.
For the next 2 minutes, a device that starts WPS (push button) joins the Wi-Fi without the password. The response doesn't say whether one did: the router reports that as an event. stop_wps_pairing() ends it early.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
Raises:
| Type | Description |
|---|---|
ValueError
|
if WPS is off. Turn it on with set_wps_enabled(True). |
stop_wps_pairing ¶
Stop WPS pairing started with the WPS button or start_wps_pairing().
set_channel ¶
set_channel(band: Literal['2.4GHz', '5GHz'], channel: int | Literal['auto'], bandwidth: str | None = None) -> str
Set a band's Wi-Fi channel, or let the router choose it, like the channel settings in the web UI.
Devices on the band lose their connection for a moment while the radio changes channel. On 5 GHz channels 52 to 112 (DFS), the router first listens for radar for about a minute, and moves to another channel by itself when it hears one. The guest network uses the same radios, so it changes too.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
band
|
str
|
"2.4GHz" or "5GHz". |
required |
channel
|
int | str
|
a channel, or "auto" to let the router choose. 2.4 GHz: one of the radio's PossibleChannels in lan.mibs(), usually 1 to 13. 5 GHz: 36 to 64 or 100 to 112, like the web UI. |
required |
bandwidth
|
str | None
|
channel width. 2.4 GHz: "20MHz" or "40MHz". 5 GHz: "80MHz", or "Auto" for 80 or 160 MHz. Default: keep the current width. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the router has no such band, the channel or width isn't one the web UI offers, or the router doesn't accept the change. |
search_channel ¶
Let the router choose a band's channel again now, like "Search again" in the web UI's Wi-Fi settings.
Only when the band's channel is set to "auto" (see set_channel()). Finding a channel may take a minute; if the router moves to another one, devices on the band lose their connection for a moment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
band
|
str
|
"2.4GHz" or "5GHz". |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the router has no such band, or its channel is set by hand. |
set_steering_enabled ¶
Turn band steering on or off, like the WLAN steering switch in the web UI.
With band steering on, the router moves wireless devices to the band, or WLAN-Box, that suits them best, e.g. by signal strength and load. Devices may lose their connection for a moment when they're moved. It only works if the 2.4 and 5 GHz networks have the same name and password. set_device_steering() leaves out single devices.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enable
|
bool
|
True to turn band steering on, False to turn it off. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
Raises:
| Type | Description |
|---|---|
ValueError
|
when turning it on while the 2.4 and 5 GHz networks have different names or passwords, like the web UI. set_network() gives them the same. |
set_guest_enabled ¶
Turn the guest Wi-Fi on or off.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enable
|
bool
|
True to turn the guest network on, False to turn it off. |
required |
hours
|
int
|
when turning it on, turn it off again automatically after this many hours. Default is 0: stay on until turned off. |
0
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
radio ¶
Get Wi-Fi radio settings
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
radio number, as in the radio's name "wifi{id}_bcm". Which band a radio serves differs between routers: OperatingFrequencyBand in the response shows it. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
spectrum_info ¶
Get spectrum information for a radio
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
radio number, as in the radio's name "wifi{id}_bcm". Which band a radio serves differs between routers: OperatingFrequencyBand in radio(id) shows it. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
scan ¶
Scan for nearby networks for a radio
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
radio number, as in the radio's name "wifi{id}_bcm". Which band a radio serves differs between routers: OperatingFrequencyBand in radio(id) shows it. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
power ¶
Set Wi-Fi power level For Duel band/tri band models, setting 1 radio may set the others to the same level as well. Use the radio method to check the supported power levels for each radio.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
radio number, as in the radio's name "wifi{id}_bcm". Which band a radio serves differs between routers: OperatingFrequencyBand in radio(id) shows it. |
required |
power
|
int
|
Wi-Fi power level (0-100) |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
latest_power ¶
Get latest Wi-Fi power for a radio
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
radio number, as in the radio's name "wifi{id}_bcm". Which band a radio serves differs between routers: OperatingFrequencyBand in radio(id) shows it. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
per_antenna_rssi ¶
Get per-antenna RSSI for a radio
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
radio number, as in the radio's name "wifi{id}_bcm". Which band a radio serves differs between routers: OperatingFrequencyBand in radio(id) shows it. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
station_stats ¶
Get station statistics for a radio
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
int
|
access point number, as in its name "wl{id}". Which band an access point serves differs between routers: in lan.mibs(), "base" lists its radio (LLIntf) and "wlanradio" the radio's OperatingFrequencyBand. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
steering_master_config ¶
Get the settings band steering shares with WLAN-Boxes, e.g. whether they follow the router's Wi-Fi switch and schedule ("SyncEnableField").
set_wlan_box_sync ¶
Choose whether WLAN-Boxes turn their Wi-Fi on and off with the router's, like the web UI's setting to synchronise the WLAN status between the Internet-Box and the WLAN-Boxes.
Off lets you turn off the router's Wi-Fi, e.g. when it's in a cellar, while the WLAN-Boxes keep theirs on: set_enabled() and the Wi-Fi schedule then only control the router's Wi-Fi. Without WLAN-Boxes it changes nothing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enable
|
bool
|
True (the default setting) to synchronise, False to let the WLAN-Boxes' Wi-Fi stay on. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
steering_operating_standards ¶
Get the Wi-Fi standards each band offers, e.g. "Enabled5GHz": "a,n,ac,ax,be" (be is Wi-Fi 7).
set_standard ¶
Set the newest Wi-Fi standard a band offers, like the WLAN standard setting in the web UI's Wi-Fi settings. The Internet Box 3 and 4's web UI only offers these choices with a WLAN-Box 4 or 5, and otherwise a Wi-Fi 6 switch.
Older devices can always connect. Newer ones then use the newest standard the band offers: e.g. 6 turns off Wi-Fi 7. Devices on the band may lose their connection for a moment. WLAN-Boxes get the same setting.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
band
|
str
|
"2.4GHz", "5GHz", or "6GHz" (on the Internet Box 4, only WLAN-Boxes have 6 GHz). |
required |
standard
|
int
|
7 for Wi-Fi 7, 6 for Wi-Fi 6, 4 on 2.4 GHz for Wi-Fi 4 and older, or 5 on 5 GHz for Wi-Fi 5 and older. 6 GHz offers 7 and 6 only. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
the standards each band offers now, as from steering_operating_standards() |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the web UI doesn't offer the standard on this band. |
steering_exception_list ¶
Get the devices band steering treats differently, as set with set_device_steering() or in the web UI.
set_device_steering ¶
Choose how band steering treats a device, like the web UI's band steering settings per device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mac
|
str
|
MAC address of a wireless device. |
required |
steer
|
bool
|
False leaves the device out of band steering: it stays on the band it picks. True (default) lets band steering move it, as it does every other device. |
True
|
access_point
|
str | None
|
with steer, keep the device on this access point while it's in reach, like the web UI's preferred access point: "router" for the Internet-Box, or a WLAN-Box's MAC address. Default: band steering chooses. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content, or the exception list from steering_exception_list() if there was nothing to change |