Just a second...

UniFi LED API

Night mode scheduling for UniFi Access Points — the feature Ubiquiti never built. Now available on PyPI — install with a single command and start automating.

pip install GitHub Documentation

pip install unifi-led-api| PyPI ↗

Actively Maintained & on PyPI

Tested with UniFi OS 5.1.5, Network 10.2.97 on U7 Pro and U6+. Published on PyPI and GitHub Container Registry.

Features

Available on PyPI

Install with pip install unifi-led-api. The global unifi-led command is ready to use — no cloning or manual setup required.

Auto-Discovery

Finds all connected UniFi APs and checks LED toggle compatibility. Shows names, MAC addresses, models, and device IDs.

Webhook API Server

Built-in HTTP server designed for Node-RED, Home Assistant, and more. Control LEDs via GET/POST requests.

Device Groups

Create custom zones like "upstairs" or "downstairs" using groups.json. Control entire groups with a single command.

Auto-Config

Device configuration is fetched live on every run. Payloads are never stale — even after firmware updates or config changes.

Interactive Setup

The built-in wizard walks you through configuration: enter credentials, discover devices, and select targets — .env is generated automatically.

LED Status & Dry-Run

Check the current LED state without making changes, or use dry-run mode to preview payloads before they are sent.

Docker Ready

Pre-built images on GitHub Container Registry. Ready to run with Docker Compose and ofelia scheduler out of the box.

Automation Ready

Designed for cron jobs and unattended operation. The .env file loads automatically — no extra setup needed in schedulers.

Why REST, not SSH?

Many existing solutions rely on SSH access to the AP. That approach has serious drawbacks.

SSH-based control

• Firmware corruption and device instability
• Reprovisioning loops and unexpected reboots
• May require TFTP recovery after failure
• Breaks silently after firmware updates

REST API (this project)

• Uses the same API the controller uses internally
• No direct device access — safe and stable
• Auto-fetches config on every run — never stale
• Suitable for long-term unattended automation

Quick Start

Get up and running in under a minute. Install from PyPI (recommended), use Docker, or clone the source.

# Install from PyPI
pip install unifi-led-api

# Interactive setup wizard
unifi-led setup

# Control LEDs
unifi-led led on
unifi-led led off

# Check LED status
unifi-led status

# Schedule with cron (night mode off at 10 PM, on at 7 AM)
0 22 * * * cd /path/to/my/env_folder && unifi-led led off
0 7  * * * cd /path/to/my/env_folder && unifi-led led on

# Pull from GitHub Container Registry
docker pull ghcr.io/elnino0916/unifi-led-api:main

# Create your .env file with controller URL, credentials, and device ID

# Control LEDs
docker run --rm --env-file .env ghcr.io/elnino0916/unifi-led-api:main led off
docker run --rm --env-file .env ghcr.io/elnino0916/unifi-led-api:main led on

# Check LED status
docker run --rm --env-file .env ghcr.io/elnino0916/unifi-led-api:main status

# Schedule with cron (night mode off at 10 PM, on at 7 AM)
0 22 * * * docker run --rm --env-file /path/to/.env ghcr.io/elnino0916/unifi-led-api:main led off
0 7  * * * docker run --rm --env-file /path/to/.env ghcr.io/elnino0916/unifi-led-api:main led on

# Clone and install
git clone https://github.com/elNino0916/unifi-led-api.git
cd unifi-led-api
pip install -e ".[dev]"

# Interactive setup wizard
unifi-led setup

# Or configure manually
cp .env.example .env
# Edit .env with your controller URL, credentials, and device ID

# Control LEDs
unifi-led led on
unifi-led led off

# Preview config without making changes
unifi-led fetch-config

Usage

Here are the key commands at a glance. After installation, the global unifi-led command is available.

💡 Turn LEDs On / Off

unifi-led led on
unifi-led led off
unifi-led led on --color "#0000ff" --brightness 50

Color and brightness only supported on older APs.

🔍 Auto-Discovery

unifi-led discover

Finds all connected devices with names, MACs, models, and compatibility.

📊 Check LED Status

unifi-led status

Displays the current LED override state for each device.

🧪 Preview (Dry-Run)

unifi-led led on --dry-run

Shows the JSON payload without making any changes.

🌐 Webhook Server

unifi-led serve --port 8080

# Endpoints:
# GET /led/on
# GET /led/off?group=upstairs
# GET /led/on?device=id1,id2

Perfect for Node-RED, Home Assistant, and other platforms.

🏷️ Device Groups

unifi-led --group upstairs led on
unifi-led --device device_id_3 led off

Define groups in groups.json or use --device for specific targets.

Configuration

All settings live in a single .env. Copy .env.example and fill in your values.

Variable	Required	Default	Description
UNIFI_USER	Yes	—	Local UniFi username (no 2FA)
UNIFI_PASS	Yes	—	UniFi password
UNIFI_CONTROLLER	Yes	—	Controller URL (e.g. https://192.168.1.1)
UNIFI_DEVICE_ID	Yes	—	Device ID (comma-separated for multiple)
UNIFI_SITE	No	default	UniFi site name
UNIFI_VERIFY_SSL	No	false	Set to true for valid SSL certs
UNIFI_TIMEOUT	No	10	HTTP request timeout in seconds

For multiple devices, set UNIFI_DEVICE_ID to a comma-separated list. Each device gets its own config files.

Define device groups in a groups.json file and use --group upstairs.