Announcement

Collapse
No announcement yet.

Unifi Custom API Call event action

Collapse
This topic is closed.
X
This is a sticky topic.
X
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

    Unifi Custom API Call event action

    Version 4.0.19.4 and higher supports a new event action: "Unifi Custom API Call". With this event action, it is possible to get and set virtually any setting on the Unifi Network. It might be extended to Protect later as well. However, it requires some basic knowledge of the Unifi API, and because of it's endless possibilities it is quite difficult to document it fully.

    Instead, the post below is an example on how to use it, created by d834758. Thanks David!

    I will update this post if there are any questions on this feature that might benefits others as well.
    stefxx

    #2
    Using the new Custom API call to enable/disable and check status of a Guest Network

    Background:

    I wanted a way to enable and disable my guest network via HS and view the status of the Guest Network.
    1. I created virtual device with an on/off state
      • I also made this discoverable via Alexa so I can say “Alexa, enable the guest network” and “Alexa, disable the guest network”
    2. I created 2 events to execute on virtual device change
      • When virtual device is enabled, enable the Guest Network
      • When virtual device is disabled, disable the Guest Network
    3. I created an event for status to run hourly and update the virtual device state if it is out of sync (if the network was enabled/disabled outside of HS). Unfortunately, the status information is only provided via pull, so it is necessary to obtain that on a periodic basis but it is a single REST call so the cost is low.
    Click image for larger version  Name:	UnifiAPI1.png Views:	0 Size:	24.4 KB ID:	1523196


    Preparation:

    Before creating an event to manage the network, you need to obtain the network id. The easiest way to do this is to log into your Cloud Key->Settings->WiFi->click on the network name. The URL will change to:
    https://<ipaddress>/network/default/settings/wifi/hotspot/form/<networkid>
    where <networkid> is an alphanumeric string

    If you want to assign the network to a specific AP Group, you will need that id as well. On the page above, expand the Advanced section, hover over the AP Group and “Edit” will appear. Click Edit and the URL will change to:
    https://<ipaddress>/network/default/settings/wifi/hotspot/form/<networkid>/ap-groups/<apgroupid>
    where <apgroupid> is an alphanumeric string

    Click image for larger version  Name:	UnifiAPI2.png Views:	0 Size:	42.2 KB ID:	1523195

    Obtaining Status:

    To obtain the status of the network (along with much other configuration information), a GET is executed against rest/wlanconf/<networkid>. Stefxx provides a convenient link to the list of available commands when editing the event.

    To parse out if the network is enabled or disabled, the relevant information is in the “enabled” property of the return value which can be isolated as data[0].enabled

    To assign that value (true or false) to a device, the device name and property are specified in the Result field of the event as
    <devicename>|<property>
    For example:
    GuestHotspotStatus|data[0].enabled

    There are two methods to view all of the information returned (rather than just the status of enabled)
    1. Run the event, then edit the action and click on the “Click here to open the last known return JSON” link which will open a new browser tab with the complete JSON
    2. Omit the pipe and property name after the device name and then run the event and then view the string of the device itself

    If you want to parse out other return values, an easy way to determine what to put after the pipe in the Result field is to copy the full return JSON from above and paste it into the JSONPath evaluator (link also provided in the event editor) and then experiment until you have isolated the desired data.

    When all put together, you have an event that looks like this where the blurred text at the red arrow is the alphanumeric string obtained above as <networkid>

    Click image for larger version  Name:	UnifiAPI3.png Views:	0 Size:	144.7 KB ID:	1523198

    When executed, a device will be created (or updated if it has already been created) and will hold the value true or false.

    Click image for larger version  Name:	UnifiAPI4.png Views:	0 Size:	16.8 KB ID:	1523197


    Enabling the Network:

    To enable the network, a PUT is executed against the same URL, rest/wlanconf/<networkid> and the JSON Data provided specifies that the network should be enabled and the AP Group/s to use.

    In this example, enabled is true to enable the network and a single AP Group id is specified (replace the <apgroupid> inside the quotes with the alphanumeric string obtained above):
    {
    "ap_group_ids": [
    "<apgroupid>"
    ],
    "_id": "default",
    "enabled": true
    }

    If the network is to be assigned to all APs, the first part of the above can be omitted.
    {
    "_id": "default",
    "enabled": true
    }

    It also may not be necessary to specify the id as the site information is specified in the event.

    When entered into the event action, it looks like this where the blurred text at the red arrow is the alphanumeric string obtained above as <networkid> and the blurred text at the blue arrow is the alphanumeric string obtained above as <apgroupid>:

    Click image for larger version  Name:	UnifiAPI5.png Views:	0 Size:	133.8 KB ID:	1523199

    Disabling the Network:

    To disable the network, a PUT is executed against the same URL, rest/wlanconf/<networkid> and the JSON Data provided specifies that the network should be disabled.

    The Data is simply:
    {"enabled": false}

    When entered into the event action, it looks like this where the blurred text at the red arrow is the alphanumeric string obtained above as <networkid>

    Click image for larger version  Name:	UnifiAPI6.png Views:	0 Size:	121.7 KB ID:	1523200

    Notes:
    • In my configuration, the desired data was always data[0], however, it may be necessary to view the full Result JSON and determine which data block contains your desired return values.
    • It’s also important to note that the JSON Result values are written to the “string” of the device specified in the Result field of the action (which makes perfect sense) but HS does not have a native way to trigger on the change of the string or on the string data itself. However, it is possible to do so with scripts or by using the EasyTrigger PI.
    stefxx

    Comment

    Working...
    X