further changes and updates to the README file

2023-12-21 11:09:36 +01:00
parent 3aa658eab0
commit b6a22abc01
1 changed files with 72 additions and 66 deletions
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@ The package can be installed manually or by using
 composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for
 easy inclusion in your projects.

+
 ## Requirements

 - a server with:
@@ -20,27 +21,35 @@ easy inclusion in your projects.
  UniFi OS) where the UniFi Controller is running
 - you must use **accounts with local access** to access the UniFi Controller API through this class, do not use UniFi Cloud accounts and do not enable 2FA on the accounts that you use with this class

+
 ## UniFi OS Support

-Support for UniFi OS-based controllers has been added as of version 1.1.47:
+Support for UniFi OS-based controllers has been added as of version 1.1.47. These devices have been verified to work:
 - UniFi Dream Router (UDR)
 - UniFi Dream Machine (UDM)
 - UniFi Dream Machine Pro (UDM PRO)
 - UniFi Cloud Key Gen2 (UCK G2), firmware version 2.0.24 or higher
 - UniFi Cloud Key Gen2 Plus (UCK G2 Plus), firmware version 2.0.24 or higher
 - UniFi Cloud Console, details [here](https://help.ui.com/hc/en-us/articles/4415364143511)
+- UniFi Express (UX)

 The class automatically detects UniFi OS consoles and adjusts the URLs and several functions/methods accordingly.

-If your own code implements strict validation of the URL that is passed to the constructor, please adapt your
-logic to allow URLs without a port suffix or with port 443 when working with a UniFi OS-based controller.
+UniFi OS consoles require you to connect using port **443** instead of **8443** which is used for "software-based"
+controllers. If your own code implements strict validation of the URL that is passed to the constructor, please adapt
+your logic to allow URLs without a port suffix or with port 443 when working with a UniFi OS-based controller.

+### Remote access to UniFi OS-based controllers
+When connecting to a UniFi OS gateway through the WAN interface, you need to create a specific firewall rule to
+allow this. See this blog post on the Art of WiFi website for more details:
+https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro

 ## Installation

 Use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the 
 API client class.

+
 ### Composer

 The preferred installation method is through [composer](https://getcomposer.org). 
@@ -125,6 +134,7 @@ $results          = $unifi_connection->list_alarms(); // returns a PHP array con
 Please refer to the `examples/` directory for some more detailed examples which can be used as a starting point for your
 own PHP code.

+
 #### IMPORTANT NOTES:

 1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when
@@ -145,15 +155,15 @@ own PHP code.
   [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/94) for an example where the WPA2 password isn't
   visible for **read-only** administrator accounts.

+
 ## Functions/methods supported

-The class currently supports the following functions/methods to GET/POST/PUT/DELETE data
-through the UniFi Controller API. Please refer to the comments in the source code for
-more details on each of the functions/methods and their respective parameters.
+The class currently supports the following functions/methods to access the UniFi Controller API. This list is sorted
+alphabetically. Please refer to the comments in the source code for more details on each of the functions/methods,
+their purpose, and their respective parameters.

- login()
- logout()
 - adopt_device()
+- advanced_adopt_device()
 - archive_alarm()
 - assign_existing_admin()
 - authorize_guest()
@@ -163,19 +173,18 @@ more details on each of the functions/methods and their respective parameters.
 - check_firmware_update()
 - cmd_stat()
 - count_alarms()
- create_apgroup() (supported with controller versions 6.0.X and higher)
+- create_apgroup()
 - create_dynamicdns()
 - create_firewallgroup()
 - create_hotspotop()
 - create_network()
 - create_radius_account()
- create_site()
 - create_user()
 - create_usergroup()
 - create_voucher()
 - create_wlan()
 - custom_api_request()
- delete_apgroup() (supported with controller versions 6.0.X and higher)
+- delete_apgroup()
 - delete_device()
 - delete_firewallgroup()
 - delete_network()
@@ -184,30 +193,46 @@ more details on each of the functions/methods and their respective parameters.
 - delete_usergroup()
 - delete_wlan()
 - disable_ap()
- edit_apgroup() (supported with controller versions 6.0.X and higher)
+- disable_wlan()
+- edit_apgroup()
 - edit_client_fixedip()
 - edit_client_name()
 - edit_firewallgroup()
 - edit_usergroup()
 - extend_guest_validity()
- forget_sta() (supported on controller version 5.9.X and higher)
+- forget_sta()
 - generate_backup()
 - generate_backup_site()
+- get_class_version()
+- get_cookie()
+- get_cookies()
+- get_curl_connection_timeout()
+- get_curl_http_version()
+- get_curl_method()
+- get_curl_request_timeout()
+- get_curl_request_timeout()
+- get_curl_ssl_verify_host()
+- get_curl_ssl_verify_peer()
+- get_debug()
+- get_is_unifi_os()
+- get_last_error_message()
+- get_last_results_raw()
+- get_site()
 - invite_admin()
 - led_override()
 - list_admins()
- list_alarms()
 - list_all_admins()
- list_apgroups() (supported with controller versions 6.0.X and higher)
- list_aps() (deprecated but still available as alias)
+- list_alarms()
+- list_aps()
 - list_backups()
 - list_clients()
 - list_country_codes()
 - list_current_channels()
 - list_dashboard()
 - list_device_name_mappings()
+- list_device_states()
 - list_devices()
- list_dpi_stats()
+- list_devices_basic()
 - list_dynamicdns()
 - list_events()
 - list_extension()
@@ -221,38 +246,46 @@ more details on each of the functions/methods and their respective parameters.
 - list_portconf()
 - list_portforward_stats()
 - list_portforwarding()
- list_radius_accounts() (supported on controller version 5.5.19 and higher)
+- list_radius_accounts()
 - list_radius_profiles()
- list_rogueaps()
- list_routing()
 - list_self()
 - list_settings()
 - list_sites()
- list_tags() (supported on controller version 5.5.19 and higher)
- list_usergroups()
+- list_tags()
 - list_users()
 - list_wlan_groups()
 - list_wlanconf()
 - locate_ap()
+- login()
+- logout()
 - move_device()
 - power_cycle_switch_port()
 - reboot_cloudkey()
- reconnect_sta()
 - rename_ap()
- restart_ap() (deprecated but still available as alias)
- restart_device()
 - revoke_admin()
 - revoke_voucher()
 - set_ap_radiosettings()
+- set_ap_wlangroup()
+- set_connection_timeout()
+- set_cookies()
+- set_curl_http_version()
+- set_curl_request_timeout()
+- set_curl_ssl_verify_host()
+- set_curl_ssl_verify_peer()
+- set_debug()
 - set_device_settings_base()
 - set_dynamicdns()
- set_element_adoption() (supported on controller version 5.13.X and higher)
+- set_element_adoption()
 - set_guestlogin_settings()
 - set_guestlogin_settings_base()
- set_ips_settings_base() (supported on controller version 5.9.10 and higher)
+- set_ips_settings_base()
+- set_is_unifi_os()
 - set_locate_ap() (deprecated but still available as alias)
 - set_networksettings_base()
 - set_radius_account_base()
+- set_request_method()
+- set_request_timeout()
+- set_site()
 - set_site_connectivity()
 - set_site_country()
 - set_site_guest_access()
@@ -271,28 +304,26 @@ more details on each of the functions/methods and their respective parameters.
 - set_wlansettings()
 - set_wlansettings_base()
 - site_leds()
- site_ledsoff() (deprecated but still available as alias)
- site_ledson() (deprecated but still available as alias)
 - spectrum_scan()
 - spectrum_scan_state()
 - start_rolling_upgrade()
- stat_5minutes_aps() (supported on controller version 5.5.X and higher)
- stat_5minutes_gateway() (supported on controller version 5.7.X and higher)
- stat_5minutes_site() (supported on controller version 5.5.X and higher)
- stat_5minutes_user (supported on controller version 5.7.X and higher)
+- stat_5minutes_aps()
+- stat_5minutes_gateway()
+- stat_5minutes_site()
+- stat_5minutes_user()
 - stat_allusers()
 - stat_auths()
 - stat_client()
 - stat_daily_aps()
- stat_daily_gateway() (supported on controller version 5.7.X and higher)
+- stat_daily_gateway()
 - stat_daily_site()
- stat_daily_user() (supported on controller version 5.7.X and higher)
+- stat_daily_user()
 - stat_full_status()
 - stat_hourly_aps()
- stat_hourly_gateway() (supported on controller version 5.7.X and higher)
+- stat_hourly_gateway()
 - stat_hourly_site()
- stat_hourly_user() (supported on controller version 5.7.X and higher)
- stat_ips_events() (supported on controller version 5.9.10 and higher)
+- stat_hourly_user()
+- stat_ips_events()
 - stat_monthly_aps()
 - stat_monthly_gateway()
 - stat_monthly_site()
@@ -311,34 +342,6 @@ more details on each of the functions/methods and their respective parameters.
 - upgrade_device()
 - upgrade_device_external()

-Other functions, getters/setters:
-
- get_class_version()
- get_cookie() (renamed from getcookie(), deprecated but still available, use get_cookies() instead)
- get_cookies()
- get_curl_connection_timeout()
- get_curl_http_version()
- get_curl_method()
- get_curl_request_timeout()
- get_curl_request_timeout()
- get_curl_ssl_verify_host()
- get_curl_ssl_verify_peer()
- get_debug()
- get_is_unifi_os()
- get_last_error_message()
- get_last_results_raw()
- get_site()
- set_connection_timeout()
- set_cookies()
- set_curl_http_version()
- set_curl_request_timeout()
- set_curl_ssl_verify_host()
- set_curl_ssl_verify_peer()
- set_debug()
- set_is_unifi_os()
- set_request_method()
- set_request_timeout()
- set_site()

 ## Need help or have suggestions?

@@ -348,11 +351,13 @@ this class, so all suggestions/comments are welcome. Please use the GitHub
 Community forums (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td-p/1512870)
 to share your suggestions and questions.

+
 ## Contribute

 If you would like to contribute code (improvements), please open an issue and include
 your code there or else create a pull request.

+
 ## Credits

 This class is based on the initial work by the following developers:
@@ -364,6 +369,7 @@ and the API as published by Ubiquiti:

 - https://dl.ui.com/unifi/7.0.25/unifi_sh_api

+
 ## Important Disclaimer

 Many of the functions in this API client class are not officially supported by Ubiquiti