• Instagram
• YouTube
• TikTok

Introduction

This guide shows you exactly how to set up Home Assistant on a Raspberry Pi 4B and connect it to UniFi Access running on a UniFi Console

🧰 What You Need

Hardware

• Raspberry Pi 4B (4GB recommended)
• MicroSD card:
  • Minimum: 32GB
  • Recommended: 64GB+ (high endurance)
• Raspberry Pi power supply (official recommended)
• Ethernet connection (strongly recommended)

💾 Step 1 — Download the Raspberry Pi Imager

Download from:
👉 https://www.raspberrypi.com/software/

Install it on your computer.

💿 SteP  2 — Write Home Assistant to the SD Card

1. Insert your microSD card into your computer
2. Open Raspberry Pi Imager

Select Device

• Click Choose Device
• Select Raspberry Pi 4 (or whatever Raspberry Pi model you are using)

Select Operating System

• Click Choose OS
• Scroll to:
  • Other specific-purpose OS
  • → Home assistants and home automation
  • → Home Assistant

Select Storage

• Click Choose Storage
• Select your SD card

⚙️ Optional (Recommended Settings)

Before writing, configure:

• Hostname (e.g. homeassistant.local)
• Enable SSH (optional but useful)
• Set WiFi (only if not using Ethernet)

Write the Image

• Click Next
• Click Write
• Wait for completion

⚡ Step 3 — Boot the Raspberry Pi

1. Insert the SD card into the Raspberry Pi
2. C onnect Ethernet
3. Power it on

⏳ Important: First Boot Time

The first boot takes:

👉 10–20 minutes

During this time:

• Home Assistant is installing
• Services are being configured

 Do not power off the device

🌐 Step 4 — Access Home Assistant

Open a browser and go to:

http://homeassistant.local:8123

If that does not work, use the IP address:

http://<raspberry-pi-ip>:8123

🧑‍💻 Step 5 — Complete Initial Setup

You will be prompted to:

• Create a user account
• Set your location
• Choose units

Complete the onboarding process.

🔑 Step 6 — Create a UniFi Access API Token

On your UniFi Dream Machine SE:

1. Open:https://<your-udm-ip>
2. Launch the UniFi Access application
3. Go to:
   Settings → API / Integrations
4. Click:
   Create API Token

Important

• Name it something like: homeassistant
• Copy the token immediately (you will not be able to see it again)

🔗 Step 7 — Add UniFi Access to Home Assistant

1. In Home Assistant, go to:
   Settings → Device & Services
2. Click:
   Add Integration
3. Search for:
   UniFi Access

Enter Connection Details

• Host:<your-udm-ip> (enter only the IP — no https unless required)
• API Token:
  Paste the token you created

✅ Step 8 — Verify the Integration

Once connected, Home Assistant will automatically discover:

• Doors
• Locks (unlock controls)
• Door status sensors

Go to:
Settings → Devices & Services → UniFi Access

Confirm your devices are listed.

🧪 Step 9 — Test Door Control

1. Go to:
   Developer Tools → Services
2. Find a service such as:
   • lock.unlock
3. Select your door
4. Run the service

👉 If the door unlocks, your setup is working correctly

⚠️ Troubleshooting

Cannot access Home Assistant

• Ensure you included :8123
• Wait the full 20 minutes on first boot
• Check your router for the correct IP

UniFi Access shows “invalid authentication”

• Ensure the API token was created inside UniFi Access
• Not in UniFi Network or UniFi OS
• Recreate the token if unsure

Integration will not connect

• Try host with and wi thout:https://
• Ensure your UDM and Home Assistant are on the same network

🧠 Final Notes

• This setup uses only official integrations
• No third-party plugins or custom repositories are required
• Home Assistant runs best on reliable storage — consider SSD in future

🚀 What’s Next

You now have:

• Home Assistant running on Raspberry Pi
• UniFi Access fully integrated

In our blog below we explore using Home Assistant to connect one intercom to two outputs on a Gate Hub.

This completes the core setup for a Home Assistant UniFi Access setup.

FAQs — Home Assistant UniFi Access Setup

These frequently asked questions cover the most common issues and decisions when setting up Home Assistant with UniFi Access.

❓ Do I need HACS  to use UniFi Access with Home Assistant?

No — HACS is no longer required.

UniFi Access is now an official integration i  Home Assistant (from 2026 onwards). This means:

• ✅ You can install it directly via Settings → Devices & Services
• ❌ No need for HACS (Home Assistant Community Store)
• ❌ No terminal commands or GitHub setup required

Why you might still see HACS in older guides

Previously, UniFi Access was only available via custom integrations. Many guides still include HACS out of date.

👉 For a clean, modern  setup:do not  include HACS

❓ What UniFi hardware do I need?

At minimum, you need:

Core Cont roller

ou need a UniFi console capable of running the UniFi Access application.

This can be any UniFi OS device that supports Access, including:

• UniFi Dream Machine SE
• UniFi Network Video Recorders (NVRs) that support Access
• UniFi Cloud Gateways (only models that support the Access app)
• UniFi Cloud Key (Gen2+)

⚠️ Important

• Not all UniFi devices support UniFi Access
• Always check that the device can install and run the Access application

👉 If the device can ot run UniFi Access, it will not work with Home Assistant for this setup

Access Control Hardware

Depending on your use case:

🚪 Door Access

• UniFi Access Hub
• UniFi Door Hub Mini (your current device)

🚧 Gate Control (your upcoming setup)

• UniFi Gate Hub (for vehicle gates)

🔐 Entry Devices

• UniFi Access Reader (Pro / Lite)
• PIN entry / NFC / mobile unlock devices

Optional (but highly recommended)

• UniFi Protect cameras
  → Enables smart automations (person detection, vehicle detection, etc.)

❓ Is the UniFi Access integration in Home Assistant stable?

Yes — but with an important caveat.

The UniFi Access integration in Home Assistant is official, but it is still relatively new and currently rated at “Silver” quality level.

🧠 What “Silver” means

Home Assistant ranks integrations by quality. A Silver rating typically means:

• ✅ Core features are working reliably
• ✅ Setup is straightforward
• ⚠️ Some advanced features may still be incomplete
• ⚠️ Occasional bugs or edge cases may exist

🔍 What works well

• Connecting to UniFi Access via API token
• Door status (open/closed)
• Lock/unlock controls
• Basic device visibility

⚠️ What may still be evolving

• Real-time access events (PIN entry, NFC scans, user identification)
• Granular user-level data for automations
• Some edge-case behaviours depending on firmware versions

🧠 Real-world expectation

For most setups, the integration is stable enough for real use, especially for:

• Manual control (unlocking doors/gates)
• Basic automations
• Device monitoring

However, if your setup relies on advanced logic such as:

• Identifying specific users from PIN entry
• Triggering automations from access events

👉 You may find s ome features still improving over time.

✅ Recommen dation 

• Use the official integration first
• Keep Home Assistant and UniFi firmware up to date
• Test your specific use case (especially event-based automations)

📌 Bottom line

The integration is:

• ✔️ O fficial
• ✔️ Stable for core functionality
• ⚠️ Still evolving for advanced automation use cases

❓ Can I run Home Assistant on something other than a Raspberry Pi?

Yes. While this guide uses a Raspberry Pi 4B, Home Assistant can also run on:

• Mini PCs (recommended for long-term use)
• Virtual machines
• NAS devices

👉 Raspberry Pi is perfect for testing and light usage.

❓ What size SD card should I use?

• Minimum: 32GB
• Recommended: 64GB or larger
• Use high-quality cards (SanDisk Extreme, Samsung EVO)

👉 Poor-quality cards are the #1 cause of instability.

❓ Can I use WiFi instead of Ethernet?

Yes, but it is not recommended.

• Ethernet = more reliable
• Faster startup and integration discovery
• Fewer connection issues with UniFi devices

❓ Why can’t I access Home Assistant after boot?

C ommon reasons:

• You didn’t include :8123 in the URL
• The system is still booting (wait up to 20 minutes)
• You’re using the wrong IP address

Try:

http://homeassistant.local:8123

or

http://<your-ip>:8123

❓ What does “invalid authentication” mean when adding UniFi Access?

This usually means:

• The API token was created in the wrong place
  (must be inside UniFi Access, not UniFi Network)
• The token was copied incorrectly (extra spaces)
• The user does not have Access permissions

👉 Fix: create a new token inside the Access app and try again

❓ Should I include “https://” in the host field?

Start with:

<your-udm-ip>

If it fails, try:

https://<your-udm-ip>

👉 This varies slightly depending on firmware versions

❓ What can Home Assistant actually control in UniFi Access?

Once connected, Home Assis>

ant can expose:

• Door lock/unlock controls
• Door open/closed status
• Access devices

Newer versions are improving support for:

• Access events (PIN, NFC, etc.)

❓ Can I trigger automations based on PIN entry?

Yes — this is one of the most powerful use cases.

For example:

• User A enters PIN → open main gate
• User B enters PIN → open passenger gate

⚠️ Support for detailed event data depends on the current integration version and is still evolving.

❓ Do I need UniFi Protect for this to work?

No — UniFi Access works on its own.

However, adding UniFi Protect enables:

• Person/vehicle detection
• Camera-triggered automations
• Visual notifications

👉 Strongly recommended for advanced setups

❓ Is  this setuP  reliable?

Yes — with a few best practices:

• Use Ethernet instead of WiFi
• Use a good-quality SD card (or SSD upgrade later)
• Keep Home Assistant updated

❓ What should I do next?

Once setup is complete, you can move on to:

• Gate automation (user-based control)
• Smart entry workflows
• Security automations

🧠 Summary

• UniFi Access is now officially supported in Home Assistant
• No HACS or custom integrations are required
• Setup is straightforward with the right hardware
• You now have a strong foundation for advanced automations

Author: Huw Jones – Home Network Solutions Berkshire
Huw is a UniFi specialist and the owner of Home Network Solutions Berkshire, providing professional networking, CCTV, gate automation and smart home installations across the UK. With years of hands-on experience and a growing YouTube audience at @home.network.solutions, Huw creates practical, no-nonsense guides to help homeowners and installers get the best out of their UniFi systems.