unificontrol

https://unificontrol.readthedocs.io/en/latest/
Admin
unificontrol is a full-featured Python interface to the Ubiquiti Unifi software defined network...
Tokens:4,373
Snippets:50
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install unificontrol

Source: https://unificontrol.readthedocs.io/en/latest/introduction.html

Commands to install the package from PyPI or directly from the GitHub repository.

```bash
pip install unificontrol
```

```bash
pip install -e git+https://github.com/nickovs/unificontrol.git@master#egg=unificontrol
```

--------------------------------

### Define a basic API call

Source: https://unificontrol.readthedocs.io/en/latest/extending_API.html

Use UnifiAPICall with a documentation string and the endpoint path for simple GET requests.

```python
list_alarms = UnifiAPICall(
    "List all alarms",
    "list/alarm",
    )
```

--------------------------------

### list_events

Source: https://unificontrol.readthedocs.io/en/latest/API.html

List events from the controller with optional filtering for history, start index, and limit.

```APIDOC
## list_events(historyhours=720, start=0, limit=1000)

### Description
List events.

### Parameters
- **historyhours** (int) - Optional - how far back to list events
- **start** (int) - Optional - index of the first event to return
- **limit** (int) - Optional - maximum number of events to return
```

--------------------------------

### Initialize UnifiClient

Source: https://unificontrol.readthedocs.io/en/latest/introduction.html

Create a client instance to connect to the Unifi controller.

```python
client = UnifiClient(host="unifi.localdomain",
    username=UNIFI_USER, password=UNIFI_PASSWORD, site=UNIFI_SITE)
```

--------------------------------

### create_client

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Creates a new user or client device entry in the controller.

```APIDOC
## create_client(mac, usergroup_id, name=None, note=None)

### Description
Create a new user/client device.

### Parameters
- **mac** (str) - Required - MAC address of new client
- **usergroup_id** (str) - Required - _id value for the user group for the client
- **name** (str) - Optional - Name for the new client
- **note** (str) - Optional - Note to attach to the new client
```

--------------------------------

### Execute API calls

Source: https://unificontrol.readthedocs.io/en/latest/introduction.html

Perform common operations like listing guests or upgrading devices using the client instance.

```python
# Get a list of all the guest devices for the last day
guests = client.list_guests(within=24)

# Upgrade one of the access points
client.upgrade_device("11:22:33:44:55:66")
```

--------------------------------

### Configure SSL certificates

Source: https://unificontrol.readthedocs.io/en/latest/introduction.html

Fetch and use a server certificate for secure connections to the controller.

```python
import ssl
cert = ssl.get_server_certificate(("unifi.localdomain", 8443))
# Store the cert in a safe place
...
# Fetch the cert from a safe place
client = UnifiClient(host="unifi.localdomain",
    username=UNIFI_USER, password=UNIFI_PASSWORD, site=UNIFI_SITE,
    cert=cert)
```

--------------------------------

### stat_5minutes_user

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Fetches client device statistics with 5 minute granularity.

```APIDOC
## stat_5minutes_user(mac, start=None, end=None, attrs=[...])

### Description
Fetch client device statistics with 5 minute granularity.

### Parameters
- **mac** (str) - Required - MAC address of client device.
- **start** (int) - Optional - Start of reporting period (Unix epoch). Defaults to 12 hours before end time.
- **end** (int) - Optional - End of reporting period (Unix epoch). Defaults to current time.
- **attrs** (list) - Optional - List of statistics to return.

### Returns
- List of dictionaries of statistics
```

--------------------------------

### authorize_guest

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Authorizes a guest client device for a specified duration and optional bandwidth limits.

```APIDOC
## authorize_guest(mac, minutes, up=None, down=None, MBytes=None, ap_mac=None)

### Description
Authorize a client device on the network.

### Parameters
- **mac** (str) - Required - MAC address of the guest client to be authorized
- **minutes** (int) - Required - Duration for which the client is authorised
- **up** (int) - Optional - Upstream bandwidth limit in Kb/sec
- **down** (int) - Optional - Downstream bandwidth limit in Kb/sec
- **MBytes** (int) - Optional - Total data volume limit in megabytes
- **ap_mac** (str) - Optional - MAC address of the access point to which the client will attach
```

--------------------------------

### stat_5minutes_site

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Fetches site statistics with 5 minute granularity.

```APIDOC
## stat_5minutes_site(start=None, end=None, attrs=[...])

### Description
Fetch site statistics with 5 minute granularity.

### Parameters
- **start** (int) - Optional - Start of reporting period (Unix epoch). Defaults to 12 hours before end time.
- **end** (int) - Optional - End of reporting period (Unix epoch). Defaults to current time.
- **attrs** (list) - Optional - List of statistics to return.

### Returns
- List of dictionaries of statistics
```

--------------------------------

### Define an API call with URL path arguments

Source: https://unificontrol.readthedocs.io/en/latest/extending_API.html

Use path_arg_name to include dynamic components in the URL path.

```python
list_devices = UnifiAPICall(
    """List details of one or more managed device on this site

    Args:
        device_mac (str): `optional` MAC address of device on which to fetch details

    Returns:
        list of dictionaries of device details.
    """,
    "stat/device",
    path_arg_name="device_mac",
    )
```

--------------------------------

### list_devices

Source: https://unificontrol.readthedocs.io/en/latest/API.html

List details of one or more managed device on this site.

```APIDOC
## list_devices(device_mac=None)

### Description
List details of one or more managed device on this site.

### Parameters
- **device_mac** (str) - Optional - MAC address of device on which to fetch details

### Returns
- list of dictionaries of device details.
```

--------------------------------

### stat_daily_site

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Fetches site statistics with 1 day granularity.

```APIDOC
## stat_daily_site(start=None, end=None, attrs=[...])

### Description
Fetch site statistics with 1 day granularity.

### Parameters
- **start** (int) - Optional - Start of reporting period (Unix epoch). Defaults to 1 year before end time.
- **end** (int) - Optional - End of reporting period (Unix epoch). Defaults to current time.
- **attrs** (list) - Optional - List of statistics to return.

### Returns
- List of dictionaries of statistics
```

--------------------------------

### stat_hourly_site

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Fetches site statistics with 1 hour granularity.

```APIDOC
## stat_hourly_site(start=None, end=None, attrs=[...])

### Description
Fetch site statistics with 1 hour granularity.

### Parameters
- **start** (int) - Optional - Start of reporting period (Unix epoch). Defaults to 7 days before end time.
- **end** (int) - Optional - End of reporting period (Unix epoch). Defaults to current time.
- **attrs** (list) - Optional - List of statistics to return.

### Returns
- List of dictionaries of statistics
```

--------------------------------

### stat_hourly_user

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Fetch client device statistics with 1 hour granularity.

```APIDOC
## stat_hourly_user(mac, start=None, end=None, attrs=['time', 'rx_bytes', 'tx_bytes'])

### Description
Fetch client device statistics with 1 hour granularity.

### Parameters
- **mac** (str) - Required - MAC address of client device for which to fetch statistics
- **start** (int) - Optional - Start of reporting period, as seconds in the Unix epoch. Defaults to 7 days before the end time.
- **end** (int) - Optional - End of reporting period, as seconds in the Unix epoch. Defaults to the current time.
- **attrs** (list) - Optional - List of statistics to return

### Returns
- List of dictionaries of statistics
```

--------------------------------

### stat_5minutes_aps

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Fetches access point statistics with 5 minute granularity.

```APIDOC
## stat_5minutes_aps(mac=None, start=None, end=None, attrs=[...])

### Description
Fetch access point statistics with 5 minute granularity.

### Parameters
- **mac** (str) - Optional - MAC address of single AP.
- **start** (int) - Optional - Start of reporting period (Unix epoch). Defaults to 12 hours before end time.
- **end** (int) - Optional - End of reporting period (Unix epoch). Defaults to current time.
- **attrs** (list) - Optional - List of statistics to return.

### Returns
- List of dictionaries of statistics
```

--------------------------------

### stat_daily_user

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Fetch client device statistics with 1 day granularity.

```APIDOC
## stat_daily_user(mac, start=None, end=None, attrs=['time', 'rx_bytes', 'tx_bytes'])

### Description
Fetch client device statistics with 1 day granularity.

### Parameters
- **mac** (str) - Required - MAC address of client device for which to fetch statistics
- **start** (int) - Optional - Start of reporting period, as seconds in the Unix epoch. Defaults to 1 year before the end time.
- **end** (int) - Optional - End of reporting period, as seconds in the Unix epoch. Defaults to the current time.
- **attrs** (list) - Optional - List of statistics to return

### Returns
- List of dictionaries of statistics
```

--------------------------------

### UnifiClient Class

Source: https://unificontrol.readthedocs.io/en/latest/API.html

The UnifiClient class is the primary interface for interacting with a Unifi controller. It requires connection details such as host, port, and credentials.

```APIDOC
## UnifiClient(host='localhost', port=8443, username='admin', password=None, site='default', cert='FETCH_CERT')

### Description
Initializes an instance of the Unifi controller interface.

### Parameters
- **host** (str) - Optional - Hostname of Unifi controller
- **port** (int) - Optional - Port on which controller is to be accessed
- **username** (str) - Optional - User name for admin account
- **password** (str) - Optional - Password for admin account
- **site** (str) - Optional - Identifier of site to be managed
- **cert** (str or bytes) - Optional - Server SSL certificate to pin for secure access
```

--------------------------------

### stat_daily_aps

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Fetches access point statistics with 1 day granularity.

```APIDOC
## stat_daily_aps(mac=None, start=None, end=None, attrs=[...])

### Description
Fetch access point statistics with 1 day granularity.

### Parameters
- **mac** (str) - Optional - MAC address of single AP.
- **start** (int) - Optional - Start of reporting period (Unix epoch). Defaults to 1 year before end time.
- **end** (int) - Optional - End of reporting period (Unix epoch). Defaults to current time.
- **attrs** (list) - Optional - List of statistics to return.

### Returns
- List of dictionaries of statistics
```

--------------------------------

### Define an API call with JSON payload and HTTP method

Source: https://unificontrol.readthedocs.io/en/latest/extending_API.html

Configure json_args for payload data and specify the HTTP method (e.g., PUT) for operations requiring body data.

```python
edit_usergroup = UnifiAPICall(
    "Update user group",
    "rest/usergroup",
    path_arg_name="group_id",
    path_arg_optional=False,
    json_args=['site_id',
               'name',
               ('qos_rate_max_down', -1),
               ('qos_rate_max_up', -1)],
    method="PUT",
    )
```

--------------------------------

### stat_hourly_aps

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Fetches access point statistics with 1 hour granularity.

```APIDOC
## stat_hourly_aps(mac=None, start=None, end=None, attrs=[...])

### Description
Fetch access point statistics with 1 hour granularity.

### Parameters
- **mac** (str) - Optional - MAC address of single AP.
- **start** (int) - Optional - Start of reporting period (Unix epoch). Defaults to 7 days before end time.
- **end** (int) - Optional - End of reporting period (Unix epoch). Defaults to current time.
- **attrs** (list) - Optional - List of statistics to return.

### Returns
- List of dictionaries of statistics
```

--------------------------------

### block_client

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Blocks a specific client device from the network.

```APIDOC
## block_client(mac)

### Description
Block a client device.

### Parameters
- **mac** (str) - Required - MAC address of the client to block
```

--------------------------------

### enable_portforwarding_rule

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Enable or disable a specific port forwarding rule.

```APIDOC
## enable_portforwarding_rule(pfr_id, enabled)

### Description
Enable or disable a port forwarding rule.

### Parameters
- **pfr_id** (str) - Required - _id value of the portforwarding rule
- **enabled** (bool) - Required - true to enable the rule, false to disable the rule
```

--------------------------------

### Define an API call with a REST command

Source: https://unificontrol.readthedocs.io/en/latest/extending_API.html

Include a rest_command parameter when the endpoint requires a specific command string within the JSON payload.

```python
revoke_admin = UnifiAPICall(
    "Revoke an admin user",
    "cmd/sitemgr",
    rest_command="revoke-admin",
    json_args=['admin'],
    )
```

--------------------------------

### Define an API call with a JSON body

Source: https://unificontrol.readthedocs.io/en/latest/extending_API.html

Use json_body_name to pass a dictionary as the JSON request body instead of individual method arguments.

```python
set_site_snmp = UnifiAPICall(
    "Set site snmp",
    "rest/setting/snmp",
    json_body_name="setting",
    method="PUT",
    )
```

--------------------------------

### Define an API call with JSON argument filtering

Source: https://unificontrol.readthedocs.io/en/latest/extending_API.html

Use the json_fix argument to pass a list of transformation functions to modify or validate arguments before they are sent to the controller.

```python
invite_admin = UnifiAPICall(
    "Invite a new admin for access to the current site",
    "cmd/sitemgr",
    json_args=['name',
               'email',
               ('readonly', False),
               ('enable_sso', True),
               ('device_adopt', False),
               ('device_restart', False)],
    rest_command='invite-admin',
    json_fix=[fix_arg_names({'enable_sso':'for_sso'}),
              fix_admin_permissions,
              fix_check_email('email')],
    )
```

--------------------------------

### Rename JSON arguments with fix_arg_names

Source: https://unificontrol.readthedocs.io/en/latest/extending_API.html

Use fix_arg_names to map user-friendly argument names to the internal names required by the API.

```python
json_fix = [fix_arg_names({'enable_sso':'for_sso'})] # Let the user write ``enable_sso`` when the API wants ``for_sso``
```

--------------------------------

### set_client_fixed_ip

Source: https://unificontrol.readthedocs.io/en/latest/API.html

Adds, modifies, or removes a fixed IP address for a specific client device.

```APIDOC
## set_client_fixed_ip(user_id, fixed_ip, network_id)

### Description
Add, modify or remove a fixed ip of a client device.

### Parameters
- **user_id** (str) - Required - _id value of the user for which the name is set
- **fixed_ip** (str) - Required - IP to attach, or None to remove IP
- **network_id** (str) - Required - network to attach
```
Tokens:
Raw