{"id":13640418,"url":"https://github.com/finish06/pyunifi","last_synced_at":"2025-04-20T02:33:33.816Z","repository":{"id":39708256,"uuid":"75498418","full_name":"finish06/pyunifi","owner":"finish06","description":null,"archived":false,"fork":true,"pushed_at":"2024-05-02T16:32:00.000Z","size":201,"stargazers_count":224,"open_issues_count":28,"forks_count":100,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-08-10T10:21:35.720Z","etag":null,"topics":["python3","ubiquiti","unifi","unifios"],"latest_commit_sha":null,"homepage":"https://unifi-sdn.ubnt.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"calmh/unifi-api","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/finish06.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-12-03T20:27:24.000Z","updated_at":"2024-07-30T17:16:46.000Z","dependencies_parsed_at":"2023-07-15T10:53:32.115Z","dependency_job_id":null,"html_url":"https://github.com/finish06/pyunifi","commit_stats":null,"previous_names":["finish06/unifi-api"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finish06%2Fpyunifi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finish06%2Fpyunifi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finish06%2Fpyunifi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finish06%2Fpyunifi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/finish06","download_url":"https://codeload.github.com/finish06/pyunifi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223816581,"owners_count":17207883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python3","ubiquiti","unifi","unifios"],"created_at":"2024-08-02T01:01:10.980Z","updated_at":"2024-11-09T10:31:13.614Z","avatar_url":"https://github.com/finish06.png","language":"Python","funding_links":[],"categories":["API Libraries"],"sub_categories":[],"readme":"[![PyPI version](https://badge.fury.io/py/pyunifi.svg)](https://badge.fury.io/py/pyunifi)\n[![Build Status](https://travis-ci.org/finish06/pyunifi.svg?branch=master)](https://travis-ci.org/finish06/pyunifi)\n\n\nPyUnifi\n=========\n\n---\nA rewrite of https://github.com/unifi-hackers/unifi-lab in cleaner Python.\nForked from https://github.com/calmh/unifi-api due to unmaintained status and rewritten to use the Requests module.\n\nDevelopment \u0026 Pull Request\n--------------------------\nPerform all pull requests against the development branch.  Pull requests against the master branch will not be merged, but closed.\n\nInstall\n-------\n\n    sudo pip install -U pyunifi\n\nAPI Example\n-----------\n\n```python\nfrom pyunifi.controller import Controller\nc = Controller('192.168.1.99', 'admin', 'p4ssw0rd')\nfor ap in c.get_aps():\n\tprint('AP named %s with MAC %s' % (ap.get('name'), ap['mac']))\n```\n\nSee also the scripts `unifi-ls-clients` and `unifi-low-rssi-reconnect` for more\nexamples of how to use the API.\n\nAPI\n---\n\n### `class Controller`\n\nInteract with a UniFi controller.\n\nUses the JSON interface on port 8443 (HTTPS) to communicate with a UniFi\ncontroller. Operations will raise unifi.controller.APIError on obvious\nproblems (such as login failure), but many errors (such as disconnecting a\nnonexistant client) will go unreported.\n\n### `__init__(self, host, username, password)`\n\nCreate a Controller object.\n\n - `host`\t\t-- the address of the controller host; IP or name\n - `username`\t-- the username to log in with\n - `password`\t-- the password to log in with\n - `port`\t\t-- the port of the controller host\n - `version`\t-- the base version of the controller API [v4|v5|unifiOS|UDMP-unifiOS]\n - `site_id`\t-- the site ID to access\n - `ssl_verify`\t-- Verify the controllers SSL certificate, default=True, can also be False or \"path/to/custom_cert.pem\"\n\n### `block_client(self, mac)`\n\nAdd a client to the block list.\n\n - `mac` -- the MAC address of the client to block.\n\n### `disconnect_client(self, mac)`\n\nDisconnects a client, forcing them to reassociate. Useful when the\nconnection is of bad quality to force a rescan.\n\n - `mac` -- the MAC address of the client to disconnect.\n\n### `get_alerts(self)`\n\nReturn a list of Alerts.\n\n### `get_alerts_unarchived(self)`\n\nReturn a list of unarchived Alerts.\n\n### `get_events(self)`\n\nReturn a list of Events.\n\n### `get_aps(self)`\n\nReturn a list of all AP:s, with significant information about each.\n\n### `get_clients(self)`\n\nReturn a list of all active clients, with significant information about each.\n\n### `get_statistics_last_24h(self)`\n\nReturn statistical data of the last 24h\n\n### `get_statistics_24h(self, endtime)`\n\nReturn statistical data last 24h from endtime\n\n - `endtime` -- the last time of statistics.\n\n### `get_users(self)`\n\nReturn a list of all known clients, with significant information about each.\n\n### `get_user_groups(self)`\n\nReturn a list of user groups with its rate limiting settings.\n\n### `update_user_group(self, group_id, down_kbps=-1, up_kbps=-1)`\n\nUpdate user group bandwidth settings.\n\n- `group_id` -- Group ID to modify.\n- `down_kbps` -- New bandwidth in KBPS for download.\n- `up_kbps` -- New bandwidth in KBPS for upload.\n\n### `get_healthinfo(self)`\n\nReturn high level health information on status of the setup\n\n### `get_wlan_conf(self)`\n\nReturn a list of configured WLANs with their configuration parameters.\n\n### `restart_ap(self, mac)`\n\nRestart an access point (by MAC).\n\n - `mac` -- the MAC address of the AP to restart.\n\n### `restart_ap_name(self, name)`\n\nRestart an access point (by name).\n\n - `name` -- the name address of the AP to restart.\n\n### `unblock_client(self, mac)`\n\nRemove a client from the block list.\n\n - `mac` -- the MAC address of the client to unblock.\n\n### `archive_all_alerts(self)`\n\nArchive all alerts of site.\n\n### `create_backup(self)`\n\nTells the controller to create a backup archive that can be downloaded with download_backup() and\nthen  be used to restore a controller on another machine.\n\nRemember that this puts significant load on a controller for some time (depending on the amount of users and managed APs).\n\n### `get_backup(self, targetfile)`\n\nTells the controller to create a backup archive and downloads it to a file. It should have a .unf extension for later restore.\n\n - `targetfile` -- the target file name, you can also use a full path. Default creates unifi-backup.unf in the current directoy.\n\n### `authorize_guest(self, guest_mac, minutes, up_bandwidth=None, down_bandwidth=None, byte_quota=None, ap_mac=None)`\n\nAuthorize a guest based on his MAC address.\n\n   - `guest_mac`     -- the guest MAC address : aa:bb:cc:dd:ee:ff\n   - `minutes`      -- duration of the authorization in minutes\n   - `up_bandwith`  -- up speed allowed in kbps (optional)\n   - `down_bandwith` -- down speed allowed in kbps (optional)\n   - `byte_quota`    -- quantity of bytes allowed in MB (optional)\n   - `ap_mac`        -- access point MAC address (UniFi \u003e= 3.x) (optional)\n\n### `unauthorize_guest(self, guest_mac)`\nUnauthorize a guest based on his MAC address.\n\n  - `guest_mac` -- the guest MAC address : aa:bb:cc:dd:ee:ff\n\n### `set_client_alias(self, mac, alias)`\nSet client alias. Use \"\" to reset to the default.\n  - mac: The target MAC: aa:bb:cc:dd:ee:ff\n  - alias: The alias to set\n\n### `create_voucher(self, number, quota, expire, up_bandwidth=None, down_bandwidth=None, byte_quota=None, note=None)`\nCreate voucher for guests. Return list of new vouchers.\n\n  - `number`          -- number of vouchers\n  - `quota`           -- maximal number of using; 0 = unlimited\n  - `expire`          -- expiration of vouchers in minutes\n  - `up_bandwidth`    -- up speed allowed in kbps (optional)\n  - `down_bandwidth`  -- down speed allowed in kbps (optional)\n  - `byte_quota`      -- quantity of bytes allowed in MB (optional)\n  - `note`            -- description of vouchers (optional)\n\n### `list_vouchers(self, **filter)`\nGet list of vouchers.\n\n  - `filter`  --  Voucher filter  (create_time, code, quota, used, note, status_expires, status, ...)\n\n```\n  c.list_vouchers(code='12345-67890')\n```\n\n### `delete_voucher(self, id)`\nDelete / revoke voucher.\n\n  - `id`    -- voucher id\n\n### `get_device_stat(self, target_mac)`\nGets the current state \u0026 configuration of the given device based on its MAC Address.\n\n  - `target_mac` -- MAC address of the device\n\n### `get_radius_users(self)`\nReturns a list of all RADIUS users, name, password, 24 digit user id, and 24 digit site id.\n\n### `add_radius_user(self, name, password)`\nAdd a new RADIUS user with this username and password.\n\n- `name` -- the new user's username\n- `password` -- the new user's password\n\n### `update_radius_user(self, name, password, id)`\nUpdate a RADIUS user to this new username and password. \nRequires the user's 24 digit user id, which can be gotten from `get_radius_users(self)`.\n\n- `name` -- the user's new username\n- `password` -- the user's new password\n- `id` -- the user's 24 digit user id.\n\n### `delete_radius_user(self, id)`\nDelete a RADIUS user. \nRequires the user's 24 digit user id, which can be gotten from `get_radius_users(self)`.\n\n- `id` -- the user's 24 digit user id.\n\n### `get_switch_port_overrides(self, target_mac)`\nGets a list of port overrides, in dictionary format, for the given target MAC address. The dictionary contains the port_idx, portconf_id, poe_mode, \u0026 name.\n\n  - `target_mac` -- MAC address of the device\n\n### `switch_port_power_off(self, target_mac, port_idx)`\nPowers Off the given port on the Switch identified by the given MAC Address.\n\n  - `target_mac` -- MAC address of the device\n  - `port_idx`   -- Port ID to power off\n\n### `switch_port_power_on(self, target_mac, port_idx)`\nPowers On the given port on the Switch identified by the given MAC Address.\n\n  - `target_mac` -- MAC address of the device\n  - `port_idx`   -- Port ID to power on\n\nUtilities\n---------\n\nThe following small utilities are bundled with the API:\n\n### unifi-ls-clients\n\nLists the currently active clients on the networks. Can take the following parameters:\n|Parameters    \t|Description   \t\t\t\t|Default |\n| ------------- |---------------------------------------| -------|\n| -c      \t| controller address \t\t\t|unifi   |\n| -u      \t| controller username      \t\t|admin   |\n| -p \t\t| controller password     \t\t| \t |\n| -b \t\t| controller port      \t\t\t|8443\t |\n| -v \t\t| controller base version      \t\t|v5\t |\n| -s \t\t| site ID, UniFi \u003e=3.x only      \t|default |\n| -V \t\t| ignore SSL certificates      \t\t|\t |\n| -C \t\t| verify with ssl certificate pem file\t| \t |\n\n```\njb@unifi:~ % unifi-ls-clients -c localhost -u admin -p p4ssw0rd -v v3 -s default\nNAME                             MAC  AP            CHAN  RSSI   RX   TX\nclient-kitchen     00:24:36:9a:0d:ab  Study          100    51  300  216\njborg-mbp          28:cf:da:d6:46:20  Study          100    45  300  300\njb-iphone          48:60:bc:44:36:a4  Living Room      1    45   65   65\njb-ipad            1c:ab:a7:af:05:65  Living Room      1    22   52   65\n```\n\n### unifi-low-snr-reconnect\n\nPeriodically checks all clients for low SNR values, and disconnects those who\nfall below the limit. The point being that these clients will then try to\nreassociate, hopefully finding a closer AP. Take the same parameters as above,\nplus settings for intervals and SNR threshold. Use `unifi-low-snr-reconnect -h`\nfor an option summary.\n\nA good source of understanding for RSSI/SNR values is [this\narticle](http://www.wireless-nets.com/resources/tutorials/define_SNR_values.html).\nAccording to that, an SNR of 15 dB seems like a good cutoff, and that's also\nthe default value in the script. You can set a higher value for testing:\n\n```\njb@unifi:~ % unifi-low-snr-reconnect -c localhost -u admin -p p4ssw0rd -v v3 -s default --minsnr 30\n2012-11-15 11:23:01 INFO unifi-low-snr-reconnect: Disconnecting jb-ipad/1c:ab:a7:af:05:65@Study (SNR 22 dB \u003c 30 dB)\n2012-11-15 11:23:01 INFO unifi-low-snr-reconnect: Disconnecting Annas-Iphone/74:e2:f5:97:da:7e@Living Room (SNR 29 dB \u003c 30 dB)\n```\n\nFor production use, launching the script into the background is recommended...\n\n### unifi-save-statistics\n\nGet a csv file with statistics\n\n```\nunifi-save-statistics -c localhost -u admin -p p4ssw0rd -v v3 -s default -f filename.csv\n```\n\n\nLicense\n-------\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinish06%2Fpyunifi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffinish06%2Fpyunifi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinish06%2Fpyunifi/lists"}