Skip to content

devices

ibox.devices in the library, ibox devices in the CLI.

Information about connected devices, network topology, and hardware.

info

info() -> str

Device information such as model name, serial number, firmware version, uptime, etc.

get

get(expression: str | None = None, flags: str | None = None) -> str

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

summary() -> str

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", ...}]

usb

usb() -> str

USB information.

topology

topology() -> str

Detailed device and network topology information.

Includes public IP addresses, connected devices, network interfaces, and more.

network_xt

network_xt() -> str

Network information from the extended network topology.

memory_status

memory_status() -> str

Device memory status.

rename

rename(key: str, name: str) -> str

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

reset_name(key: str) -> str

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_type(key: str, device_type: str) -> str

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

set_dns_name(key: str, name: str) -> str

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_dns_name(key: str) -> str

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

reset_traffic_counters() -> str

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

clear_traffic_history(mac: str) -> str

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(mac: str) -> str

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_on_lan(mac: str) -> str

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(mac: str) -> str

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

unblock(mac: str) -> str

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