- added stat_speedtest_results() method/function to collect results from scheduled speed tests

- added list_backups() method/function to list auto backups

README.md

@@ -1,6 +1,6 @@
 ## UniFi Controller API client class
 
-A PHP class which provides access to Ubiquiti's **UniFi Controller API**, versions 4.x.x and 5.x.x of the UniFi Controller software are supported (version 5.6.29 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
+A PHP class which provides access to Ubiquiti's **UniFi Controller API**, versions 4.X.X and 5.X.X of the UniFi Controller software are supported (version 5.8.24 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
 
 This class can be installed using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
 
@@ -15,22 +15,29 @@ The class currently supports the following functions/methods to get/post/put/del
 - authorize_guest()
 - block_sta()
 - count_alarms()
+- create_firewallgroup()
 - create_hotspotop()
 - create_network()
 - create_radius_account()
 - create_site()
 - create_usergroup()
+- create_user()
 - create_voucher()
 - create_wlan()
 - delete_device()
+- delete_firewallgroup()
 - delete_network()
 - delete_radius_account()
 - delete_site()
 - delete_usergroup()
 - delete_wlan()
 - disable_ap()
+- edit_firewallgroup()
 - edit_usergroup()
 - extend_guest_validity()
+- forget_sta() (supported on controller version 5.9.X and higher)
+- invite_admin()
+- revoke_admin()
 - led_override()
 - list_admins()
 - list_all_admins()
@@ -45,6 +52,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - list_dynamicdns()
 - list_events()
 - list_extension()
+- list_firewallgroups()
 - list_guests()
 - list_health()
 - list_hotspotop()
@@ -100,12 +108,15 @@ The class currently supports the following functions/methods to get/post/put/del
 - stat_allusers()
 - stat_auths()
 - stat_client()
-- stat_5minutes_aps() (supported on controller version 5.5.* and higher)
+- stat_5minutes_aps() (supported on controller version 5.5.X and higher)
 - stat_hourly_aps()
 - stat_daily_aps()
-- stat_5minutes_site() (supported on controller version 5.5.* and higher)
+- stat_5minutes_site() (supported on controller version 5.5.X and higher)
 - stat_hourly_site()
 - stat_daily_site()
+- stat_5minutes_user (supported on controller version 5.7.X and higher)
+- stat_hourly_user() (supported on controller version 5.7.X and higher)
+- stat_daily_user() (supported on controller version 5.7.X and higher)
 - stat_payment()
 - stat_sessions()
 - stat_sites()
@@ -118,6 +129,8 @@ The class currently supports the following functions/methods to get/post/put/del
 - unset_locate_ap() (deprecated but still available as alias)
 - upgrade_device()
 - upgrade_device_external()
+- start_rolling_upgrade()
+- cancel_rolling_upgrade()
 
 Internal functions, getters/setters:
 
@@ -133,7 +146,7 @@ Please refer to the source code for more details on the functions/methods and th
 
 ## Requirements
 
-- a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1)
+- a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.0.7 and cURL 7.37.0)
 - network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running
 
 ## Installation ##
@@ -232,7 +245,7 @@ If you would like to contribute code (improvements), please open an issue and in
 This class is based on the work done by the following developers:
 - domwo: http://community.ubnt.com/t5/UniFi-Wireless/little-php-class-for-unifi-api/m-p/603051
 - fbagnol: https://github.com/fbagnol/class.unifi.php
-- and the API as published by Ubiquiti: https://dl.ubnt.com/unifi/5.6.18-8261dc5066/unifi_sh_api
+- and the API as published by Ubiquiti: https://dl.ubnt.com/unifi/5.8.24/unifi_sh_api
 
 ## Important Disclaimer
 

examples/README.md

@@ -1,4 +1,5 @@
 ## API client class usage examples
+
 This directory contains some PHP code examples which demonstrate usage of the PHP API client class and can be used as a good starting point for your own custom code.
 
 ### Usage
@@ -6,6 +7,8 @@ This directory contains some PHP code examples which demonstrate usage of the PH
 Copy the appropriate example file to your working directory together with a copy of the config.template.php file which should be renamed to config.php.
 Then update the contents of your new config.php with your controller details and credentials and modify the example file as required to fit your needs.
 
+Also make sure to update the path for the composer autoloader file (`vendor/autoload.php`) or the file containing the Class itself (`src/Client.php`) in your `require_once()` statement as required.
+
 ### Contribute
 
 If you would like to share your own example file(s), please open an issue and include your code there or else create a pull request.

examples/block_list.php

@@ -0,0 +1,90 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: @malcolmcif, based on another Art of WiFi example
+ * description: basic PHP script to block a list of mac addresses passed in via command line,
+ *              output is to console in non json format
+ *
+ * usage:
+ *  php block_list.php <list of comma seperated mac addresses>
+ *
+ * example:
+ *  php block_list.php 09:09:09:09:09:09,10:10:10:10:10:10
+ *
+ */
+
+/**
+ * using the composer autoloader
+ */
+require_once('vendor/autoload.php');
+
+/**
+ * include the config file (place your credentials etc. there if not already present)
+ * see the config.template.php file for an example
+ */
+require_once('config.php');
+
+$debug=false;
+/**
+  * the MAC address(es) of the device(s) to block
+ */
+$macs_to_block = explode(',',$argv[1]);
+
+/**
+ * The site to authorize the device with
+ */
+$site_id = 'MUST_DEFINE_THIS';
+if ($site_id == "MUST_DEFINE_THIS")
+{
+    print 'ERROR: set the site id in your script';
+    return;
+}
+
+/**
+ * initialize the UniFi API connection class and log in to the controller
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login(); // always true regardless of site id
+
+foreach ($macs_to_block as &$mac)
+{
+    // block_result is always true even if mac address does not exist :(
+    $block_result   = $unifi_connection->block_sta($mac);
+
+    /**
+     * NOTE:
+     * during testing I had some strange behavior where clients were not reconnecting to the network correctly,
+     * they appeared unblocked and received a valid IP address but could not actually get any data.
+     * the clients did not come to life until I disabled the SSID and then re enabled it.
+     * I guessed maybe these commands were occurring too quickly for the controller so I have slowed them down;
+     * since introducing the sleep I have not seen the above behavior so it might be fixed
+     */
+    sleep(1);
+
+    $getid_result   = $unifi_connection->stat_client($mac);
+
+    if (property_exists($getid_result[0], "oui")) // this field(manufacturer) seems to exist on valid mac addresses
+    {
+        if (property_exists($getid_result[0], "name")) // this is the alias field if it has been defined
+        {
+            $name = $getid_result[0]->name;
+        }
+        else
+        {
+            $name = $getid_result[0]->hostname;
+        }
+        print 'blocked ' . $name . PHP_EOL;
+    }
+    else
+    {
+        print 'ERROR: could not block ' . $mac . PHP_EOL;
+        print '       check mac address is valid and part of your network' . PHP_EOL;
+    }
+}
+
+/**
+ * No json formatted data
+ */
+//echo json_encode($block_result, JSON_PRETTY_PRINT);

examples/list_user_stats.php

@@ -0,0 +1,51 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to pull stats for s epcific user/client device from the UniFi controller and output in json format
+ */
+
+/**
+ * using the composer autoloader
+ */
+require_once('vendor/autoload.php');
+
+/**
+ * include the config file (place your credentials etc. there if not already present)
+ * see the config.template.php file for an example
+ */
+require_once('config.php');
+
+/**
+ * the site to use
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * MAC address of client to fetch stats for
+ */
+$mac = '<MAC address>';
+
+/**
+ * array of attributes to collect
+ * valid attributes:
+ * rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets, tx_packets
+ */
+//$attribs = ['rx_bytes', 'tx_bytes', 'signal', 'rx_rate', 'tx_rate', 'rx_retries', 'tx_retries', 'rx_packets', 'tx_packets'];
+$attribs = ['rx_bytes', 'tx_bytes'];
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and do our thing
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, true);
+$set_debug_mode   = $unifi_connection->set_debug(false);
+$loginresults     = $unifi_connection->login();
+//$data             = $unifi_connection->stat_5minutes_user($mac, null, null, $attribs);
+//$data             = $unifi_connection->stat_hourly_user($mac, null, null, $attribs);
+$data             = $unifi_connection->stat_daily_user($mac, null, null, $attribs);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($data, JSON_PRETTY_PRINT);

examples/unblock_list.php

@@ -0,0 +1,90 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: @malcolmcif, based on another Art of WiFi example
+ * description: basic PHP script to unblock a list of mac addresses passed in via command line,
+ *              output is to console in non json format
+ *
+ * usage:
+ *  php unblock_list.php <list of comma seperated mac addresses>
+ *
+ * example:
+ *  php unblock_list.php 09:09:09:09:09:09,10:10:10:10:10:10
+ *
+ */
+
+/**
+ * using the composer autoloader
+ */
+require_once('vendor/autoload.php');
+
+/**
+ * include the config file (place your credentials etc. there if not already present)
+ * see the config.template.php file for an example
+ */
+require_once('config.php');
+
+$debug=false;
+/**
+ * the MAC addresses of the device(s) to unblock
+ */
+$macs_to_unblock = explode(',',$argv[1]);
+
+/**
+ * The site to authorize the device with
+ */
+$site_id = 'MUST_DEFINE_THIS';
+if ($site_id == "MUST_DEFINE_THIS")
+{
+    print 'ERROR: set the site id in your script';
+    return;
+}
+
+/**
+ * initialize the UniFi API connection class and log in to the controller
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login(); // always true regardless of site id
+
+foreach ($macs_to_unblock as &$mac)
+{
+    // block_result is always true even if mac address does not exist :(
+    $block_result   = $unifi_connection->unblock_sta($mac);
+
+    /**
+     * NOTE:
+     * during testing I had some strange behavior where clients were not reconnecting to the network correctly,
+     * they appeared unblocked and received a valid IP address but could not actually get any data.
+     * the clients did not come to life until I disabled the SSID and then re enabled it.
+     * I guessed maybe these commands were occurring too quickly for the controller so I have slowed them down;
+     * since introducing the sleep I have not seen the above behavior so it might be fixed
+     */
+    sleep(1);
+
+    $getid_result   = $unifi_connection->stat_client($mac);
+
+    if (property_exists($getid_result[0], "oui")) // this field(manufacturer) seems to exist on valid mac addresses
+    {
+        if (property_exists($getid_result[0], "name"))
+        {
+            $name = $getid_result[0]->name;
+        }
+        else
+        {
+            $name = $getid_result[0]->hostname;
+        }
+        print 'unblocked ' . $name . PHP_EOL;
+    }
+    else
+    {
+        print 'ERROR: could not unblock ' . $mac . PHP_EOL;
+        print '       check mac address is valid and part of your network' . PHP_EOL;
+    }
+}
+
+/**
+ * provide feedback in json format
+ */
+//echo json_encode($block_result, JSON_PRETTY_PRINT);

src/Client.php

@@ -25,7 +25,7 @@ class Client
      */
     protected $baseurl            = 'https://127.0.0.1:8443';
     protected $site               = 'default';
-    protected $version            = '5.4.16';
+    protected $version            = '5.6.39';
     protected $debug              = false;
     protected $is_loggedin        = false;
     private $cookies              = '';
@@ -138,8 +138,8 @@ class Client
                 }
 
                 if ($code === 400) {
-                     trigger_error('We have received an HTTP response status: 400. Probably a controller login failure');
-                     return $code;
+                    trigger_error('We have received an HTTP response status: 400. Probably a controller login failure');
+                    return $code;
                 }
             }
         }
@@ -358,14 +358,57 @@ class Client
     }
 
     /**
-     * Add/modify/remove a client device note
+     * Forget one or more client devices
+     * ---------------------------------
+     * return true on success
+     * required parameter <macs> = array of client MAC addresses
+     *
+     * NOTE:
+     * only supported with controller versions 5.9.X and higher
+     */
+    public function forget_sta($macs)
+    {
+        if (!$this->is_loggedin) return false;
+        $json     = json_encode(['cmd' => 'forget-sta', 'macs' => $macs]);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/stamgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Create a new user/client-device
+     * -------------------------------
+     * return an array with a single object containing details of the new user/client-device on success, else return false
+     * required parameter <mac>           = client MAC address
+     * required parameter <user_group_id> = _id value for the user group the new user/client-device should belong to which
+     *                                      can be obtained from the output of list_usergroups()
+     * optional parameter <name>          = name to be given to the new user/client-device
+     * optional parameter <note>          = note to be applied to the new user/client-device
+     */
+    public function create_user($mac, $user_group_id, $name = null, $note = null)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'POST';
+        $new_user           = ['mac' => $mac, 'usergroup_id' => $user_group_id];
+        if (!is_null($name)) $new_user['name'] = $name;
+        if (!is_null($note)) {
+            $new_user['note'] = $note;
+            $new_user['noted'] = true;
+        }
+        $json               = ['objects' => [['data' => $new_user]]];
+        $json               = json_encode($json);
+        $response           = $this->exec_curl('/api/s/'.$this->site.'/group/user', 'json='.$json);
+        return $this->process_response($response);
+    }
+
+    /**
+     * Add/modify/remove a client-device note
      * --------------------------------------
      * return true on success
-     * required parameter <user_id> = id of the user device to be modified
-     * optional parameter <note>    = note to be applied to the user device
+     * required parameter <user_id> = id of the client-device to be modified
+     * optional parameter <note>    = note to be applied to the client-device
      *
      * NOTES:
-     * - when note is empty or not set, the existing note for the user will be removed and "noted" attribute set to false
+     * - when note is empty or not set, the existing note for the client-device will be removed and "noted" attribute set to false
      */
     public function set_sta_note($user_id, $note = null)
     {
@@ -397,9 +440,9 @@ class Client
     /**
      * 5 minutes site stats method
      * ---------------------------
-     * returns an array of 5 minutes stats objects for the current site
-     * optional parameter <start> = Unix timestamp in seconds
-     * optional parameter <end>   = Unix timestamp in seconds
+     * returns an array of 5-minute stats objects for the current site
+     * optional parameter <start> = Unix timestamp in milliseconds
+     * optional parameter <end>   = Unix timestamp in milliseconds
      *
      * NOTES:
      * - defaults to the past 12 hours
@@ -422,8 +465,8 @@ class Client
      * Hourly site stats method
      * ------------------------
      * returns an array of hourly stats objects for the current site
-     * optional parameter <start> = Unix timestamp in seconds
-     * optional parameter <end>   = Unix timestamp in seconds
+     * optional parameter <start> = Unix timestamp in milliseconds
+     * optional parameter <end>   = Unix timestamp in milliseconds
      *
      * NOTES:
      * - defaults to the past 7*24 hours
@@ -444,8 +487,8 @@ class Client
      * Daily site stats method
      * ------------------------
      * returns an array of daily stats objects for the current site
-     * optional parameter <start> = Unix timestamp in seconds
-     * optional parameter <end>   = Unix timestamp in seconds
+     * optional parameter <start> = Unix timestamp in milliseconds
+     * optional parameter <end>   = Unix timestamp in milliseconds
      *
      * NOTES:
      * - defaults to the past 52*7*24 hours
@@ -465,9 +508,9 @@ class Client
     /**
      * 5 minutes stats method for a single access point or all access points
      * ---------------------------------------------------------------------
-     * returns an array of 5 minutes stats objects
-     * optional parameter <start> = Unix timestamp in seconds
-     * optional parameter <end>   = Unix timestamp in seconds
+     * returns an array of 5-minute stats objects
+     * optional parameter <start> = Unix timestamp in milliseconds
+     * optional parameter <end>   = Unix timestamp in milliseconds
      * optional parameter <mac>   = AP MAC address to return stats for
      *
      * NOTES:
@@ -492,8 +535,8 @@ class Client
      * Hourly stats method for a single access point or all access points
      * ------------------------------------------------------------------
      * returns an array of hourly stats objects
-     * optional parameter <start> = Unix timestamp in seconds
-     * optional parameter <end>   = Unix timestamp in seconds
+     * optional parameter <start> = Unix timestamp in milliseconds
+     * optional parameter <end>   = Unix timestamp in milliseconds
      * optional parameter <mac>   = AP MAC address to return stats for
      *
      * NOTES:
@@ -516,8 +559,8 @@ class Client
      * Daily stats method for a single access point or all access points
      * -----------------------------------------------------------------
      * returns an array of daily stats objects
-     * optional parameter <start> = Unix timestamp in seconds
-     * optional parameter <end>   = Unix timestamp in seconds
+     * optional parameter <start> = Unix timestamp in milliseconds
+     * optional parameter <end>   = Unix timestamp in milliseconds
      * optional parameter <mac>   = AP MAC address to return stats for
      *
      * NOTES:
@@ -536,6 +579,114 @@ class Client
         return $this->process_response($response);
     }
 
+    /**
+     * 5 minutes stats method for a single user/client device
+     * ------------------------------------------------------
+     * returns an array of 5-minute stats objects
+     * required parameter <mac>     = MAC address of user/client device to return stats for
+     * optional parameter <start>   = Unix timestamp in milliseconds
+     * optional parameter <end>     = Unix timestamp in milliseconds
+     * optional parameter <attribs> = array containing attributes (strings) to be returned, valid values are:
+     *                                rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets, tx_packets
+     *                                default is ['rx_bytes', 'tx_bytes']
+     *
+     * NOTES:
+     * - defaults to the past 12 hours
+     * - only supported with UniFi controller versions 5.8.X and higher
+     * - make sure that the retention policy for 5 minutes stats is set to the correct value in
+     *   the controller settings
+     * - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance section
+     */
+    public function stat_5minutes_user($mac, $start = null, $end = null, $attribs = null)
+    {
+        if (!$this->is_loggedin) return false;
+        $end      = is_null($end) ? ((time())*1000) : intval($end);
+        $start    = is_null($start) ? $end-(12*3600*1000) : intval($start);
+        $attribs  = is_null($attribs) ? ['time', 'rx_bytes', 'tx_bytes'] : array_merge(['time'], $attribs);
+        $json     = ['attrs' => $attribs, 'start' => $start, 'end' => $end, 'mac' => $mac];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/stat/report/5minutes.user', 'json='.$json);
+        return $this->process_response($response);
+    }
+
+    /**
+     * Hourly stats method for a a single user/client device
+     * -----------------------------------------------------
+     * returns an array of hourly stats objects
+     * required parameter <mac>     = MAC address of user/client device to return stats for
+     * optional parameter <start>   = Unix timestamp in milliseconds
+     * optional parameter <end>     = Unix timestamp in milliseconds
+     * optional parameter <attribs> = array containing attributes (strings) to be returned, valid values are:
+     *                                rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets, tx_packets
+     *                                default is ['rx_bytes', 'tx_bytes']
+     *
+     * NOTES:
+     * - defaults to the past 7*24 hours
+     * - only supported with UniFi controller versions 5.8.X and higher
+     * - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance section
+     */
+    public function stat_hourly_user($mac, $start = null, $end = null, $attribs = null)
+    {
+        if (!$this->is_loggedin) return false;
+        $end      = is_null($end) ? ((time())*1000) : intval($end);
+        $start    = is_null($start) ? $end-(7*24*3600*1000) : intval($start);
+        $attribs  = is_null($attribs) ? ['time', 'rx_bytes', 'tx_bytes'] : array_merge(['time'], $attribs);
+        $json     = ['attrs' => $attribs, 'start' => $start, 'end' => $end, 'mac' => $mac];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/stat/report/hourly.user', 'json='.$json);
+        return $this->process_response($response);
+    }
+
+    /**
+     * Daily stats method for a single user/client device
+     * --------------------------------------------------
+     * returns an array of daily stats objects
+     * required parameter <mac>     = MAC address of user/client device to return stats for
+     * optional parameter <start>   = Unix timestamp in milliseconds
+     * optional parameter <end>     = Unix timestamp in milliseconds
+     * optional parameter <attribs> = array containing attributes (strings) to be returned, valid values are:
+     *                                rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets, tx_packets
+     *                                default is ['rx_bytes', 'tx_bytes']
+     *
+     * NOTES:
+     * - defaults to the past 7*24 hours
+     * - only supported with UniFi controller versions 5.8.X and higher
+     * - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance section
+     */
+    public function stat_daily_user($mac, $start = null, $end = null, $attribs = null)
+    {
+        if (!$this->is_loggedin) return false;
+        $end      = is_null($end) ? ((time())*1000) : intval($end);
+        $start    = is_null($start) ? $end-(7*24*3600*1000) : intval($start);
+        $attribs  = is_null($attribs) ? ['time', 'rx_bytes', 'tx_bytes'] : array_merge(['time'], $attribs);
+        $json     = ['attrs' => $attribs, 'start' => $start, 'end' => $end, 'mac' => $mac];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/stat/report/daily.user', 'json='.$json);
+        return $this->process_response($response);
+    }
+
+    /**
+     * Method to fetch speed test results
+     * ----------------------------------
+     * returns an array of speed test result objects
+     * optional parameter <start> = Unix timestamp in milliseconds
+     * optional parameter <end>   = Unix timestamp in milliseconds
+     *
+     * NOTES:
+     * - defaults to the past 24 hours
+     * - requires a USG
+     */
+    public function stat_speedtest_results($start = null, $end = null)
+    {
+        if (!$this->is_loggedin) return false;
+        $end      = is_null($end) ? ((time())*1000) : intval($end);
+        $start    = is_null($start) ? $end-(24*3600*1000) : intval($start);
+        $json     = ['attrs' => ['xput_download','xput_upload','latency','time'], 'start' => $start, 'end' => $end];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/stat/report/archive.speedtest', 'json='.$json);
+        return $this->process_response($response);
+    }
+
     /**
      * Show all login sessions
      * -----------------------
@@ -655,18 +806,6 @@ class Client
         return $this->process_response($response);
     }
 
-    /**
-     * List user groups
-     * ----------------
-     * returns an array of user group objects
-     */
-    public function list_usergroups()
-    {
-        if (!$this->is_loggedin) return false;
-        $response = $this->exec_curl('/api/s/'.$this->site.'/list/usergroup');
-        return $this->process_response($response);
-    }
-
     /**
      * Assign client device to another group
      * -------------------------------------
@@ -683,22 +822,39 @@ class Client
     }
 
     /**
-     * Update user group (using REST)
+     * Update client fixedip (using REST)
      * ------------------------------
-     * returns an array containing a single object with attributes of the updated usergroup on success
-     * required parameter <group_id>   = id of the user group
-     * required parameter <site_id>    = id of the site
-     * required parameter <group_name> = name of the user group
-     * optional parameter <group_dn>   = limit download bandwidth in Kbps (default = -1, which sets bandwidth to unlimited)
-     * optional parameter <group_up>   = limit upload bandwidth in Kbps (default = -1, which sets bandwidth to unlimited)
+     * returns an array containing a single object with attributes of the updated client on success
+     * required parameter <client_id>   = id of the client
+     * required parameter <use_fixedip> = boolean defining whether if use_fixedip is true or false
+     * optional parameter <network_id>  = network id where the ip belongs to
+     * optional parameter <fixed_ip>    = value of client's fixed_ip field
      *
      */
-    public function edit_usergroup($group_id, $site_id, $group_name, $group_dn = -1, $group_up = -1)
+    public function edit_client_fixedip($client_id, $use_fixedip, $network_id = null, $fixed_ip = null)
     {
         if (!$this->is_loggedin) return false;
+        if (!is_bool($use_fixedip)) return false;
         $this->request_type = 'PUT';
-        $json     = json_encode(['_id' => $group_id, 'name' => $group_name, 'qos_rate_max_down' => intval($group_dn), 'qos_rate_max_up' => intval($group_up), 'site_id' => $site_id]);
-        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/usergroup/'.trim($group_id), $json);
+        $data = ['_id' => $client_id, 'use_fixedip' => $use_fixedip];
+        if($use_fixedip){
+            if($network_id){ $data["network_id"] = $network_id; }
+            if($fixed_ip){ $data["fixed_ip"] = $fixed_ip; }
+        }
+        $json     = json_encode($data);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/user/'.trim($client_id), $json);
+        return $this->process_response($response);
+    }
+
+    /**
+     * List user groups
+     * ----------------
+     * returns an array of user group objects
+     */
+    public function list_usergroups()
+    {
+        if (!$this->is_loggedin) return false;
+        $response = $this->exec_curl('/api/s/'.$this->site.'/list/usergroup');
         return $this->process_response($response);
     }
 
@@ -713,11 +869,31 @@ class Client
     public function create_usergroup($group_name, $group_dn = -1, $group_up = -1)
     {
         if (!$this->is_loggedin) return false;
+        $this->request_type = 'POST';
         $json     = json_encode(['name' => $group_name, 'qos_rate_max_down' => intval($group_dn), 'qos_rate_max_up' => intval($group_up)]);
         $response = $this->exec_curl('/api/s/'.$this->site.'/rest/usergroup', $json);
         return $this->process_response($response);
     }
 
+    /**
+     * Modify user group (using REST)
+     * ------------------------------
+     * returns an array containing a single object with attributes of the updated usergroup on success
+     * required parameter <group_id>   = id of the user group
+     * required parameter <site_id>    = id of the site
+     * required parameter <group_name> = name of the user group
+     * optional parameter <group_dn>   = limit download bandwidth in Kbps (default = -1, which sets bandwidth to unlimited)
+     * optional parameter <group_up>   = limit upload bandwidth in Kbps (default = -1, which sets bandwidth to unlimited)
+     */
+    public function edit_usergroup($group_id, $site_id, $group_name, $group_dn = -1, $group_up = -1)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'PUT';
+        $json     = json_encode(['_id' => $group_id, 'name' => $group_name, 'qos_rate_max_down' => intval($group_dn), 'qos_rate_max_up' => intval($group_up), 'site_id' => $site_id]);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/usergroup/'.trim($group_id), $json);
+        return $this->process_response($response);
+    }
+
     /**
      * Delete user group (using REST)
      * ------------------------------
@@ -732,6 +908,75 @@ class Client
         return $this->process_response_boolean($response);
     }
 
+    /**
+     * List firewall groups (using REST)
+     * ----------------------------------
+     * returns an array containing the current firewall groups on success
+     */
+    public function list_firewallgroups()
+    {
+        if (!$this->is_loggedin) return false;
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/firewallgroup');
+        return $this->process_response($response);
+    }
+
+    /**
+     * Create firewall group (using REST)
+     * ----------------------------------
+     * returns an array containing a single object with attributes of the new firewall group on success
+     * required parameter <group_name>    = name to assign to the firewall group
+     * required parameter <group_type>    = firewall group type; valid values are address-group, ipv6-address-group, port-group
+     * optional parameter <group_members> = array containing the members of the new group (IPv4 addresses, IPv6 addresses or port numbers)
+     *                                      (default is an empty array)
+     */
+    public function create_firewallgroup($group_name, $group_type, $group_members = [])
+    {
+        if (!$this->is_loggedin) return false;
+        if (!in_array($group_type, ['address-group', 'ipv6-address-group', 'port-group'])) return false;
+        $this->request_type = 'POST';
+        $json     = json_encode(['name' => $group_name, 'group_type' => $group_type, 'group_members' => $group_members]);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/firewallgroup', $json);
+        return $this->process_response($response);
+    }
+
+    /**
+     * Modify firewall group (using REST)
+     * ----------------------------------
+     * returns an array containing a single object with attributes of the updated firewall group on success
+     * required parameter <group_id>      = _id value of the firewall group
+     * required parameter <site_id>       = site_id value of the firewall group
+     * required parameter <group_name>    = name of the firewall group
+     * required parameter <group_type>    = firewall group type; valid values are address-group, ipv6-address-group, port-group,
+     *                                      group_type cannot be changed for an existing firewall group!
+     * optional parameter <group_members> = array containing the members of the group (IPv4 addresses, IPv6 addresses or port numbers)
+     *                                      which will overwrite the existing group_members (default is an empty array)
+     *
+     *
+     */
+    public function edit_firewallgroup($group_id, $site_id, $group_name, $group_type, $group_members = [])
+    {
+        if (!$this->is_loggedin) return false;
+        if (!in_array($group_type, ['address-group', 'ipv6-address-group', 'port-group'])) return false;
+        $this->request_type = 'PUT';
+        $json     = json_encode(['_id' => $group_id, 'name' => $group_name, 'group_type' => $group_type, 'group_members' => $group_members, 'site_id' => $site_id]);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/firewallgroup/'.trim($group_id), $json);
+        return $this->process_response($response);
+    }
+
+    /**
+     * Delete firewall group (using REST)
+     * ----------------------------------
+     * returns true on success
+     * required parameter <group_id> = id of the firewall group
+     */
+    public function delete_firewallgroup($group_id)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'DELETE';
+        $response           = $this->exec_curl('/api/s/'.$this->site.'/rest/firewallgroup/'.trim($group_id));
+        return $this->process_response_boolean($response);
+    }
+
     /**
      * List health metrics
      * -------------------
@@ -824,6 +1069,20 @@ class Client
         return $this->process_response($response);
     }
 
+    /**
+     * List auto backups
+     * ---------------------------
+     * return an array containing objects with backup details on success
+     */
+    public function list_backups()
+    {
+        if (!$this->is_loggedin) return false;
+        $mac      = strtolower($mac);
+        $json     = json_encode(['cmd' => 'list-backups']);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/backup', 'json='.$json);
+        return $this->process_response($response);
+    }
+
     /**
      * List sites
      * ----------
@@ -1041,6 +1300,77 @@ class Client
         return $this->process_response($response);
     }
 
+    /**
+     * Invite a new admin for access to the current site
+     * -------------------------------------------------
+     * returns true on success
+     * required parameter <name>           = string, name to assign to the new admin user
+     * required parameter <email>          = email address to assign to the new admin user
+     * optional parameter <enable_sso>     = boolean, whether or not SSO will be allowed for the new admin
+     *                                       default value is true which enables the SSO capability
+     * optional parameter <readonly>       = boolean, whether or not the new admin will have readonly
+     *                                       permissions, default value is true which gives the new admin
+     *                                       administrator permissions
+     * optional parameter <device_adopt>   = boolean, whether or not the new admin will have permissions to
+     *                                       adopt devices, default value is false. Only applies when readonly
+     *                                       is true.
+     * optional parameter <device_restart> = boolean, whether or not the new admin will have permissions to
+     *                                       restart devices, default value is false. Only applies when readonly
+     *                                       is true.
+     *
+     * NOTES:
+     * - after issuing a valid request, an invite will be sent to the email address provided
+     * - issuing this command against an existing admin will trigger a "re-invite"
+     */
+    public function invite_admin($name, $email, $enable_sso = true, $readonly = false, $device_adopt = false, $device_restart = false)
+    {
+        if (!$this->is_loggedin) return false;
+        $email_valid = filter_var(trim($email), FILTER_VALIDATE_EMAIL);
+        if (!$email_valid) {
+            trigger_error('The email address provided is invalid!');
+            return false;
+        }
+
+        $json = ['name' => trim($name), 'email' => trim($email), 'for_sso' => $enable_sso, 'cmd' => 'invite-admin'];
+        if ($readonly) {
+            $json['role'] = 'readonly';
+            $permissions = [];
+            if ($device_adopt) {
+                $permissions[] = "API_DEVICE_ADOPT";
+            }
+
+            if ($device_restart) {
+                $permissions[] = "API_DEVICE_RESTART";
+            }
+
+            if (count($permissions) > 0) {
+                $json['permissions'] = $permissions;
+            }
+        }
+
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/sitemgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Revoke an admin
+     * ---------------
+     * returns true on success
+     * required parameter <admin_id> = id of the admin to revoke which can be obtained using the
+     *                                 list_all_admins() method/function
+     *
+     * NOTES:
+     * only non-superadmins account can be revoked
+     */
+    public function revoke_admin($admin_id)
+    {
+        if (!$this->is_loggedin) return false;
+        $json     = json_encode(['admin' => $admin_id, 'cmd' => 'revoke-admin']);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/sitemgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
     /**
      * List wlan_groups
      * ----------------
@@ -1130,6 +1460,7 @@ class Client
     public function create_hotspotop($name, $x_password, $note = null)
     {
         if (!$this->is_loggedin) return false;
+        $this->request_type = 'POST';
         $json     = ['name' => $name, 'x_password' => $x_password];
         if (isset($note)) $json['note'] = trim($note);
         $json     = json_encode($json);
@@ -1245,6 +1576,10 @@ class Client
      * List country codes
      * ------------------
      * returns an array of available country codes
+     *
+     * NOTES:
+     * these codes following the ISO standard:
+     * https://en.wikipedia.org/wiki/ISO_3166-1_numeric
      */
     public function list_country_codes()
     {
@@ -1278,8 +1613,8 @@ class Client
     }
 
     /**
-     * List port configuration
-     * -----------------------
+     * List port configurations
+     * ------------------------
      * returns an array of port configurations
      */
     public function list_portconf()
@@ -1358,8 +1693,9 @@ class Client
     public function disable_ap($ap_id, $disable)
     {
         if (!$this->is_loggedin) return false;
+        if (!is_bool($disable)) return false;
         $this->request_type = 'PUT';
-        $json     = json_encode(['disabled' => (bool)$disable]);
+        $json     = json_encode(['disabled' => $disable]);
         $response = $this->exec_curl('/api/s/'.$this->site.'/rest/device/'.trim($ap_id), $json);
         return $this->process_response_boolean($response);
     }
@@ -1399,6 +1735,7 @@ class Client
     public function locate_ap($mac, $enable)
     {
         if (!$this->is_loggedin) return false;
+        if (!is_bool($enable)) return false;
         $mac      = strtolower($mac);
         $cmd      = (($enable) ? 'set-locate' : 'unset-locate');
         $json     = json_encode(['cmd' => $cmd, 'mac' => $mac]);
@@ -1415,7 +1752,8 @@ class Client
     public function site_leds($enable)
     {
         if (!$this->is_loggedin) return false;
-        $json     = json_encode(['led_enabled' => (bool)$enable]);
+        if (!is_bool($enable)) return false;
+        $json     = json_encode(['led_enabled' => $enable]);
         $response = $this->exec_curl('/api/s/'.$this->site.'/set/setting/mgmt', 'json='.$json);
         return $this->process_response_boolean($response);
     }
@@ -1565,11 +1903,12 @@ class Client
      * List network settings (using REST)
      * ----------------------------------
      * returns an array of (non-wireless) networks and their settings
+     * optional parameter <network_id> = string; network id to get specific network data for
      */
-    public function list_networkconf()
+    public function list_networkconf($network_id = '')
     {
         if (!$this->is_loggedin) return false;
-        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/networkconf');
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/networkconf/'.trim($network_id));
         return $this->process_response($response);
     }
 
@@ -1725,9 +2064,9 @@ class Client
      */
     public function set_wlansettings($wlan_id, $x_passphrase, $name = null)
     {
-        $payload = (object)[];
-        if (!is_null($x_passphrase)) $payload->x_passphrase = trim($x_passphrase);
-        if (!is_null($name)) $payload->name = trim($name);
+        $payload = [];
+        if (!is_null($x_passphrase)) $payload['x_passphrase'] = trim($x_passphrase);
+        if (!is_null($name)) $payload['name'] = trim($name);
         return $this->set_wlansettings_base($wlan_id, $payload);
     }
 
@@ -1740,9 +2079,9 @@ class Client
      */
     public function disable_wlan($wlan_id, $disable)
     {
-        $payload          = (object)[];
-        $action           = ($disable) ? false : true;
-        $payload->enabled = (bool)$action;
+        if (!is_bool($disable)) return false;
+        $action  = $disable ? false : true;
+        $payload = ['enabled' => $action];
         return $this->set_wlansettings_base($wlan_id, $payload);
     }
 
@@ -1773,11 +2112,9 @@ class Client
      */
     public function set_wlan_mac_filter($wlan_id, $mac_filter_policy, $mac_filter_enabled, array $macs)
     {
+        if (!is_bool($mac_filter_enabled)) return false;
         if (!in_array($mac_filter_policy, ['allow', 'deny'])) return false;
-        $payload                     = (object)[];
-        $payload->mac_filter_enabled = (bool)$mac_filter_enabled;
-        $payload->mac_filter_policy  = $mac_filter_policy;
-        $payload->mac_filter_list    = $macs;
+        $payload = ['mac_filter_enabled' => (bool)$mac_filter_enabled, 'mac_filter_policy' => $mac_filter_policy, 'mac_filter_list' => $macs];
         return $this->set_wlansettings_base($wlan_id, $payload);
     }
 
@@ -1879,6 +2216,38 @@ class Client
         return $this->process_response_boolean($response);
     }
 
+    /**
+     * Start rolling upgrade
+     * ---------------------
+     * return true on success
+     *
+     * NOTES:
+     * - updates all access points to the latest firmware known to the controller in a
+     *   staggered/rolling fashion
+     */
+    public function start_rolling_upgrade()
+    {
+        if (!$this->is_loggedin) return false;
+        $json     = ['cmd' => 'set-rollupgrade'];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/devmgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Cancel rolling upgrade
+     * ---------------------
+     * return true on success
+     */
+    public function cancel_rolling_upgrade()
+    {
+        if (!$this->is_loggedin) return false;
+        $json     = ['cmd' => 'unset-rollupgrade'];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/devmgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
     /**
      * Power-cycle the PoE output of a switch port
      * -------------------------------------------
@@ -1888,6 +2257,7 @@ class Client
      *
      * NOTES:
      * - only applies to switches and their PoE ports...
+     * - port must be actually providing power
      */
     public function power_cycle_switch_port($switch_mac, $port_idx)
     {
@@ -2424,4 +2794,4 @@ class Client
 
         return $ch;
     }
-}
+}