unipyaccess

unipyaccess is a Python package designed to interface with the Unifi Access system. This package provides a simple and efficient way to manage users in Unifi Access, including authentication, retrieval, creation, activation, deactivation, deletion, and updating of user groups and hardware settings.

[!NOTE]
This implementation uses Unifi API endpoints with admin user authentication. It does not utilize the latest, in my opinion half-baked Unifi API.

[!WARNING]
🚧 This project is under active development, and breaking changes are expected in upcoming releases.

Features

• Authenticate with Unifi Access using admin credentials.
• Retrieve, create, activate, deactivate, and delete user accounts.
• Update user group assignments.
• Manage Unifi Access hardware, including access methods, display brightness, and device status.

Installation

Install the package via pip:

pip install unipyaccess

Requirements

• Python 3.x
• requests library

Install the requirements with:

pip install requests

Environment Setup

Store your configuration details in a .env file:

UNIFI_CONTROLLER_ADDRESS=https://unifi-controller.local
UNIFI_LOGIN=admin
UNIFI_PASSWORD=password123
VERIFY_SSL=False

Usage

Import unipyaccess and use it in your Python script:

from unipyaccess import UnipyAccess
from dotenv import load_dotenv
import os

load_dotenv()

# Initialize the UnipyAccess API client
unipy = UnipyAccess(
    base_url=os.getenv('UNIFI_CONTROLLER_ADDRESS'),
    username=os.getenv('UNIFI_LOGIN'),
    password=os.getenv('UNIFI_PASSWORD'),
    verify=os.getenv('VERIFY_SSL')
)

# Features
users = unipy.users.get_users()

new_user = {
    "first_name": "Python",
    "last_name": "Test",
    "PersonId": 98765,
}

unipy.users.create_user(new_user)
unipy.users.deactivate_user(uuid)
unipy.users.activate_user(uuid)
unipy.users.set_user_group(uuid, group_uuid)
unipy.users.delete_user(uuid)

# Hardware management
devices = unipy.hardware.get_devices()

unipy.hardware.get_device(device_id)
unipy.hardware.set_access_method(device_id, ["pin", "nfc", "mobile_tap", "mobile_button"])
unipy.hardware.set_doorbell_trigger(device_id, "tap")
unipy.hardware.set_status_light(device_id, "on")
unipy.hardware.set_display_brightness(device_id, 50)
unipy.hardware.set_status_sound("f4e2c6d3085d", 30)  # For models other than UA G2 Pro use "on" or "off"
unipy.hardware.get_device_capabilities(device_id)
unipy.hardware.get_device_model(device_id)
unipy.hardware.restart_device(device_id)

Methods

User Management

1. unipy.users.create_user(new_user)

Creates a new user.

Parameters:

• new_user (dict): Dictionary containing user details:
  • first_name (str): User's first name.
  • last_name (str): User's last name.
  • PersonId (str): Optional employee number.
  • group_ids (list): Optional list of group IDs.

Usage:

new_user = {
    "first_name": "Jane",
    "last_name": "Doe",
    "PersonId": "789",
    "group_ids": ["group-123"]
}
unipy.users.create_user(new_user)

2. unipy.users.deactivate_user(uuid)

Deactivates a user.

Parameters:

• uuid (str): User’s unique identifier.

Usage:

unipy.users.deactivate_user("user-123")

3. unipy.users.activate_user(uuid)

Activates a user.

Parameters:

• uuid (str): User’s unique identifier.

Usage:

unipy.users.activate_user("user-123")

4. unipy.users.set_user_group(uuid, group_uuid)

Updates the user group assignment.

Parameters:

• uuid (str): User’s unique identifier.
• group_uuid (str): Group’s unique identifier.

Usage:

unipy.users.set_user_group("user-123", "group-789")

5. unipy.users.delete_user(uuid)

Deletes a user.

Parameters:

• uuid (str): User’s unique identifier.

Usage:

unipy.users.delete_user("user-123")

Hardware Management

1. unipy.hardware.get_devices()

Fetches a list of hardware devices.

Usage:

devices = unipy.hardware.get_devices()

2. unipy.hardware.get_device(device_id)

Fetches details of a specific device.

Usage:

device = unipy.hardware.get_device("device-123")

3. unipy.hardware.set_access_method(device_id, enabled_methods)

Sets the access methods for a device.

Usage:

unipy.hardware.set_access_method("device-123", ["pin", "nfc"])

4. unipy.hardware.set_doorbell_trigger(device_id, doorbell_trigger)

Sets the doorbell trigger type for a device.

Usage:

unipy.hardware.set_doorbell_trigger("device-123", "tap")

5. unipy.hardware.set_status_light(device_id, status_light)

Sets the status light for a device.

Usage:

unipy.hardware.set_status_light("device-123", "on")

6. unipy.hardware.set_display_brightness(device_id, brightness)

Sets the display brightness for a device.

Usage:

unipy.hardware.set_display_brightness("device-123", 50)

7. unipy.hardware.set_status_sound(device_id, status_sound)

Sets the status sound for a device.

Usage:

unipy.hardware.set_status_sound("device-123", 30)

8. unipy.hardware.get_device_capabilities(device_id)

Fetches the capabilities of a device.

Usage:

capabilities = unipy.hardware.get_device_capabilities("device-123")

9. unipy.hardware.get_device_model(device_id)

Fetches the model of a device.

Usage:

model = unipy.hardware.get_device_model("device-123")

10. unipy.hardware.restart_device(device_id)

Restarts a device.

Usage:

unipy.hardware.restart_device("device-123")

Example Code

from unipyaccess import UnipyAccess
from dotenv import load_dotenv
import os

load_dotenv()

unipy = UnipyAccess(
    base_url=os.getenv('UNIFI_CONTROLLER_ADDRESS'),
    username=os.getenv('UNIFI_LOGIN'),
    password=os.getenv('UNIFI_PASSWORD'),
    verify=os.getenv('VERIFY_SSL')
)

# Retrieve users
users = unipy.users.get_users()
print(users)

# Create a user
new_user = {
    "first_name": "Alice",
    "last_name": "Smith",
    "PersonId": "125"
}
unipy.users.create_user(new_user)

# Activate a user
unipy.users.activate_user("user-123")

# Deactivate a user
unipy.users.deactivate_user("user-123")

# Delete a user
unipy.users.delete_user("user-123")

# Update user group
unipy.users.set_user_group("user-123", "group-789")

# Hardware Management
# Get devices
devices = unipy.hardware.get_devices()
print(devices)

# Set device configurations
unipy.hardware.set_access_method("device-123", ["pin", "nfc"])
unipy.hardware.set_display_brightness("device-123", 50)
unipy.hardware.set_status_sound("device-123", "on")

License

This project is licensed under the MIT License. See the LICENSE file for more details.