devices¶
ibox.devices in the library, ibox devices in the CLI.
Information about connected devices, network topology, and hardware.
info ¶
Device information such as model name, serial number, firmware version, uptime, etc.
get ¶
Get devices.
Powerful method to get detailed information about devices connected to the router: user agents, DNS records, network interfaces, hardware identifiers, bandwidth usage, and more. The expression and flags parameters allow filtering and customization of the response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
expression
|
str | None
|
expression to search for, separated by "||" for multiple tags. Default is None to include all main device tags. |
None
|
flags
|
str | None
|
additional flags for the search. Default is None to exclude actions from the response. |
None
|
Expression examples
"self || not self || lan || eth || nemo || interface || events || usb || sysbus" "lan and not self and not interface"
Flags examples
"no_actions" - do not include actions in the response "full_links" - include full links information in the response
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
summary ¶
A short list of the devices on the home network: name, addresses, type, and whether and how they're connected.
A short version of get(): 5 KB instead of 130 KB for 25 devices, with the manufacturer and the last connection time too. The connection is the current or last one, e.g. "Ethernet (ETH4)" or "Wi-Fi 5GHz". Connected Wi-Fi devices also have their signal strength in dBm.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
a JSON list, e.g. [{"name": "iPhone", "mac": "AA:BB:CC:DD:EE:FF", "ip": "192.168.1.20", ...}] |
topology ¶
Detailed device and network topology information.
Includes public IP addresses, connected devices, network interfaces, and more.
rename ¶
Rename a device, as shown in the web UI and in get(). The new name shows up within a second or so.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
device key: the MAC address for network devices (the "Key" field in get()). |
required |
name
|
str
|
new name. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
reset_name ¶
Remove the name given to a device in the web UI or with rename(), so it gets the name it was found with again, e.g. the one it gives the router when it connects.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
device key: the MAC address for network devices (the "Key" field in get()). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
set_type ¶
Set a device's type, which picks its icon, like the device settings in the web UI.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
device key: the MAC address for network devices (the "Key" field in get()). |
required |
device_type
|
str
|
one of the types the web UI offers (DEVICE_TYPES), e.g. "computer", "laptop", "smartphone", "tablette" (a tablet), "tv", "printer", "gameconsole", "camera", "ha-switch" (a smart plug), "bulb", "speaker" or "miscellaneous". |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the web UI doesn't offer the type. |
set_dns_name ¶
Give a device a different name in the router's DNS than the one the web UI shows (see rename()).
The name works straight away, also with the router's local domain (e.g. "nas.home"), and replaces the displayed name in DNS until remove_dns_name(). The web UI keeps showing the displayed name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
device key: the MAC address for network devices (the "Key" field in get()). |
required |
name
|
str
|
1 to 63 letters, digits and hyphens, not starting or ending with a hyphen, e.g. "nas". |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
remove_dns_name ¶
Remove the DNS name given to a device with set_dns_name(), so its displayed name works in DNS again.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
device key: the MAC address for network devices (the "Key" field in get()). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
reset_traffic_counters ¶
Set every device's traffic counters to 0, like the reset button on the web UI's bandwidth page.
The counters are the "Bandwidth" field in get(): what each device received and sent over the last day, week and month. The exporter's device traffic gauges start again from 0. The old counts can't be brought back.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
clear_traffic_history ¶
Delete a Wi-Fi device's recent traffic history, like the web UI's reset button for a device's data usage.
The history is the device's traffic and Wi-Fi signal readings, one every 15 seconds for about the last 25 minutes, from which the web UI draws its graphs. It can't be brought back; the next reading starts a new one. The data the device used today, this week and this month (the "Bandwidth" field in get()) stays, and so do its hourly snapshots (getEventLog type "network_persistent"): only reset_traffic_counters() resets those, for every device. Wired devices have no history.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mac
|
str
|
device MAC address. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the router has no traffic history for the device, e.g. because it's wired or never connected. |
remove ¶
Remove an offline device from the device list, like the delete button in the web UI.
As in the web UI, this also deletes the device's IP address reservation, internet access schedule and daily time limit. If the device connects again, it shows up as a new device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mac
|
str
|
device MAC address. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
Raises:
| Type | Description |
|---|---|
ValueError
|
if the device is connected. It would reappear straight away, without its settings. |
wake_on_lan ¶
Wake up a device with Wake-on-LAN. The device must support it and have it turned on.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mac
|
str
|
device MAC address. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
response content |
block ¶
Block a device's internet access, like the web UI's "Internet access blocked" switch.
This turns the device's parental controls on. A device without an access schedule gets one that blocks it all week. A device with a schedule (see scheduler.set_device_schedule) is only blocked when that schedule says so, and an override that allows access now (see scheduler.override_device_schedule) ends. Its daily time limit (see mst.set) is turned on too.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mac
|
str
|
device MAC address. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
the device's schedule, as from scheduler.device_schedule. "value" is "Disable" while it is blocked. |
unblock ¶
Restore a device's internet access, like turning off the web UI's "Internet access blocked" switch.
This turns off the device's access schedule and daily time limit. Both are kept, so block() brings them back.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mac
|
str
|
device MAC address. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
the device's schedule, as from scheduler.device_schedule ({"status": false} if it has none). |