Getting Started with Home Assistant

Getting Started with Home Assistant

Home Assistant is a powerful, open-source home automation platform that runs locally on your own hardware. It gives you complete control over your smart home without relying on cloud services. This guide walks you through everything from initial setup to advanced features like automations and custom dashboards.

What is Home Assistant?

Home Assistant is:

• Local-first: Your data stays on your hardware, not in the cloud
• Privacy-focused: No tracking, no data mining
• Highly customizable: Thousands of integrations and add-ons
• Community-driven: Active development and extensive documentation

It serves as the central hub for all your smart devices, letting you create powerful automations and unified control dashboards.

---

Part 1: Choosing Your Hardware

Before installing Home Assistant, you'll need to decide what hardware to run it on.

Option 1: Home Assistant Green (Recommended for beginners)

The Home Assistant Green is a plug-and-play device designed specifically for Home Assistant. It's the easiest way to get started.

Pros:

• Pre-installed and ready to go
• Compact and energy-efficient
• Official support from the Home Assistant team
• No technical setup required

Cons:

• No built-in Z-Wave/Zigbee radio (USB stick required)
• Limited expandability

Price: ~$99 USD

Option 2: Home Assistant Yellow

The Home Assistant Yellow is a more advanced option with built-in Zigbee radio and expansion options.

Pros:

• Built-in Zigbee radio
• Expandable with NVMe storage
• Supports Power over Ethernet (PoE)
• More powerful hardware

Cons:

• Higher price point
• Requires some assembly
• Currently harder to obtain

Price: ~$125-175 USD (depending on configuration)

Option 3: Raspberry Pi or Mini PC (DIY)

For those who prefer flexibility, you can install Home Assistant on a Raspberry Pi 4/5 or a mini PC.

Pros:

• Most flexible option
• Can repurpose existing hardware
• Full control over hardware specs

Cons:

• Requires more technical knowledge
• Power supply and storage quality matters
• SD cards can fail (use SSD if possible)

Our Recommendation

For most users, especially those new to Home Assistant, we recommend the Home Assistant Green with a Zooz 800 Series Z-Wave USB stick. This combination offers the best balance of ease-of-use and smart home compatibility.

See our Hardware Requirements guide for detailed recommendations.

---

Part 2: Initial Setup

Once you have your hardware, it's time to set up Home Assistant.

Powering on for the first time

1. Connect your Home Assistant device to your router with an ethernet cable
2. Plug in the power adapter
3. Wait 5-10 minutes for the initial boot (the device needs to set up its operating system)

Accessing Home Assistant

1. Open a web browser on any device connected to your network
2. Navigate to http://homeassistant.local:8123
   • If that doesn't work, try http://homeassistant:8123
   • As a last resort, find the IP address in your router's admin page

Creating your account

1. Click Create my smart home
2. Enter your name and create a username
3. Create a strong password (you'll use this to log in)
4. Click Create Account

Setting your location

1. Enter your home address or click Detect to auto-locate
2. Adjust the pin on the map if needed
3. Set your time zone
4. Choose your unit system (Metric or Imperial)
5. Select your currency
6. Click Next

Your location is used for:

• Sunrise/sunset automations
• Weather information
• Local time display

Selecting data sharing preferences

Home Assistant asks if you'd like to share anonymous usage data to help improve the project. This is entirely optional and doesn't affect functionality.

Discovering devices

Home Assistant will automatically scan your network for compatible devices. You may see:

• Smart TVs
• Streaming devices (Chromecast, Roku)
• Smart speakers
• Network equipment

You can add these now or skip and add them later. Don't worry if nothing appears—most Z-Wave and Zigbee devices need to be added manually.

---

Part 3: Understanding the Dashboard

After setup, you'll land on the Home Assistant dashboard. Let's understand the interface.

The sidebar

The left sidebar is your main navigation:

• Overview: Your main dashboard with device controls
• Energy: Monitor your home's energy usage (requires compatible devices)
• Map: See the location of tracked devices
• Logbook: Activity log of events in your home
• History: Graphs showing device history over time
• To-do: Built-in task lists
• Media: Control media players
• Settings: Configure Home Assistant

The Overview dashboard

The Overview dashboard shows cards representing your devices and information. By default, it's automatically organized, but you can fully customize it.

Default cards include:

• Weather forecast
• Person/presence tracking
• Device controls

Quick actions

In the top-right corner, you'll find:

• Search (magnifying glass): Quickly find anything in Home Assistant
• Assist (chat bubble): Voice/text assistant for controlling devices
• Overflow menu (⋮): Additional options like Edit Dashboard

---

Part 4: Understanding Add-ons

Add-ons extend Home Assistant's functionality by running additional services on your device.

What are add-ons?

Add-ons are containerized applications that run alongside Home Assistant. They can provide:

• File management (File Editor, Samba share)
• System tools (Terminal & SSH, Git pull)
• Media services (Plex, Jellyfin)
• Network tools (AdGuard, WireGuard)
• Smart home hubs (Z-Wave JS, Zigbee2MQTT)
• And much more

Accessing the Add-on Store

1. Go to Settings in the sidebar
2. Click Add-ons
3. Click Add-on Store in the bottom-right

Essential add-ons to install

We recommend installing these add-ons right away:

Studio Code Server

A full Visual Studio Code editor running in your browser—perfect for editing configuration files, automations, and scripts.

1. Search for Studio Code Server in the Add-on Store
2. Click Install
3. After installation, toggle Show in sidebar
4. Click Start
5. Click Open Web UI to launch the editor

Terminal & SSH

Access the command line for advanced operations and installing tools like HACS.

1. Search for Terminal & SSH
2. Click Install
3. Go to Configuration tab
4. Set a password or add your SSH public key
5. Toggle Show in sidebar
6. Click Start

Z-Wave JS

Required if you're using Z-Wave devices (smart locks, thermostats, switches). This add-on runs the Z-Wave JS server that Home Assistant connects to.

1. Search for Z-Wave JS in the Add-on Store
2. Click Install
3. Go to Configuration tab
4. Select your Z-Wave USB stick from the device dropdown
5. Click Start
6. After starting, go to Settings → Devices & Services
7. Home Assistant should auto-discover Z-Wave JS—click Configure to set it up

Note: You'll need a Z-Wave USB stick plugged into your Home Assistant device. We recommend the Zooz 800 Series Z-Wave Long Range S2 USB Stick (ZST39 LR).

Managing add-ons

Each add-on has several tabs:

• Info: Start/stop, update, and see resource usage
• Documentation: How to use the add-on
• Configuration: Settings specific to the add-on
• Log: View add-on output for troubleshooting

---

Part 5: Setting Up HACS

HACS (Home Assistant Community Store) unlocks thousands of community-created integrations, themes, and frontend components.

What is HACS?

HACS is a community-driven store that provides:

• Custom integrations: Support for devices and services not in the official list
• Frontend cards: Custom dashboard cards with advanced features
• Themes: Change the look and feel of Home Assistant

Installing HACS

Step 1: Install Terminal & SSH

If you haven't already, install the Terminal & SSH add-on (see Part 4).

Step 2: Download HACS

1. Open Terminal from the sidebar
2. Run this command:

wget -O - https://get.hacs.xyz | bash -

3. Wait for the script to complete (you'll see "Installation complete")

Step 3: Restart Home Assistant

1. Go to Settings → System
2. Click Restart in the top-right
3. Click Restart to confirm
4. Wait 2-3 minutes for Home Assistant to restart

Step 4: Add the HACS integration

1. After restart, go to Settings → Devices & Services
2. Click Add Integration (bottom-right)
3. Search for HACS and select it
4. Check all the acknowledgment boxes (read them!)
5. Click Submit
6. A GitHub authorization window opens
7. Click the link to authorize with GitHub
8. Enter the code shown in Home Assistant
9. Authorize the HACS application

Step 5: Verify HACS is working

After authorization, HACS appears in your sidebar. Click on it to browse available content.

Installing items from HACS

To install something from HACS:

1. Open HACS from the sidebar
2. Choose a category: Integrations, Frontend, or browse All
3. Search for what you want
4. Click on the item
5. Click Download in the bottom-right
6. Select the version (usually latest)
7. Click Download
8. Restart Home Assistant if prompted (integrations always require restart)

Popular HACS items

Integrations:

• Staykey: Our plugin for enhanced lock activity tracking (keypad code usage)
• Local Tuya: Control Tuya devices locally without cloud
• Frigate: AI-powered camera NVR integration
• Adaptive Lighting: Automatically adjust lights based on time of day

Frontend cards:

• Mushroom Cards: Modern, minimalist card designs
• Button Card: Highly customizable button cards
• mini-graph-card: Beautiful sensor graphs
• Bubble Card: Create stunning mobile-first dashboards

---

Part 6: Creating Automations

Automations are the heart of a smart home—they make things happen automatically based on triggers and conditions.

Understanding automation components

Every automation has three parts:

1. Trigger: What starts the automation (motion detected, time of day, button pressed)
2. Condition: Optional rules that must be true (only at night, only when home)
3. Action: What happens (turn on light, send notification, lock door)

Creating your first automation

Let's create a simple automation: turn on a light when motion is detected.

Using the visual editor

1. Go to Settings → Automations & scenes
2. Click Create Automation
3. Click Create new automation

Adding a trigger

1. Click Add Trigger
2. Choose Device
3. Select your motion sensor
4. Choose the trigger (e.g., "Motion detected")

Adding a condition (optional)

To make the automation only run at night:

1. Click Add Condition
2. Choose Sun
3. Select Before: Sunrise or After: Sunset

Adding an action

1. Click Add Action
2. Choose Device
3. Select your light
4. Choose Turn on
5. Optionally set brightness or color

Saving and testing

1. Give your automation a name (e.g., "Motion light - Living room")
2. Click Save
3. Test it by triggering the motion sensor

Automation examples

Here are some useful automations for vacation rentals:

Welcome lighting:

• Trigger: 30 minutes before sunset
• Condition: A guest has an active stay
• Action: Turn on porch lights

Energy saver:

• Trigger: No motion for 30 minutes
• Action: Turn off all lights, set thermostat to eco mode

Tips for automations

• Start simple: Get basic automations working before adding complexity
• Use descriptive names: You'll thank yourself later
• Test thoroughly: Trigger automations manually to verify they work
• Check the trace: If something isn't working, click on the automation and view its trace to see what happened

---

Part 7: Building Custom Dashboards

While the default dashboard is functional, custom dashboards let you create exactly the interface you want.

Dashboard basics

Home Assistant dashboards consist of:

• Views: Tabs at the top (e.g., "Home", "Lights", "Climate")
• Cards: Individual components that display information or controls
• Sections: Group cards together (in newer dashboard layouts)

Creating a new dashboard

1. Go to Settings → Dashboards
2. Click Add Dashboard
3. Give it a name (e.g., "Custom Home")
4. Choose an icon
5. Toggle Show in sidebar
6. Click Create

Editing your dashboard

1. Open your new dashboard from the sidebar
2. Click the ⋮ menu in the top-right
3. Click Edit Dashboard
4. You're now in edit mode

Adding cards

1. In edit mode, click Add Card (bottom-right)
2. Choose a card type

Common card types:

• Button: Single device control
• Entities: List multiple entities in one card
• Thermostat: Climate control with a visual dial
• Light: Light control with brightness slider
• Media Control: Control media players
• Weather Forecast: Show weather conditions
• Gauge: Display sensor values visually

Organizing with views

Views are tabs that organize your dashboard:

1. In edit mode, click the + next to existing view tabs
2. Give the view a name and icon
3. Add cards specific to that view

Example structure:

• Home: Overview of everything
• Lights: All lighting controls
• Climate: Thermostats and fans
• Security: Locks and cameras
• Media: TV and speaker controls

Using HACS cards

HACS provides powerful custom cards. Here's how to use them:

1. Install a card from HACS (e.g., Mushroom Cards)
2. Restart Home Assistant
3. Edit your dashboard
4. Click Add Card
5. Scroll down to find HACS cards or click Manual to use YAML

Dashboard tips

• Mobile-first: Design for mobile so you can manage your property on the go
• Group logically: Put related controls together
• Use icons: Visual icons are faster to recognize than text
• Less is more: Don't overwhelm with every possible entity

---

Part 8: Setting Up Remote Access

To access Home Assistant from outside your home (required for Staykey), you need to set up remote access.

Why remote access matters

Remote access lets you:

• Control your property from anywhere
• Receive notifications on your phone
• Connect cloud services like Staykey

Remote access options

We have detailed guides for each option:

Option 1: Nabu Casa (Recommended)

The easiest method with the fastest setup. $6.50/month supports Home Assistant development.

→ Setting Up Nabu Casa

Best for: Most users, especially those who want simplicity and want to support the project.

Option 2: Tailscale Funnel

Free option that works through Tailscale's secure network. Requires more technical setup.

→ Setting Up Tailscale Funnel

Best for: Technical users who want a free solution.

After setting up remote access

Once you have a public URL for your Home Assistant:

1. Test it works from outside your network (turn off WiFi on your phone)
2. Create a Long-Lived Access Token for external services
3. You're ready to connect to Staykey!

---

Part 9: Next Steps with Staykey

Now that your Home Assistant is set up and accessible remotely, you're ready to connect it to Staykey for automated guest access management.

What Staykey adds

• Automatic access codes: Generate unique codes for each guest stay
• Guest portal: Beautiful interface for guests to control allowed devices
• Booking sync: Import reservations from Airbnb, VRBO, and more
• Activity logging: See when codes are used and devices are controlled

Getting started with Staykey

1. Connect your Home Assistant hub — Link your instance to Staykey
2. Install the Staykey plugin — Enable enhanced lock activity tracking
3. Set up Z-Wave devices — Add smart locks and other devices
4. Create your first property — Configure your rental in Staykey
5. Create your first guest link — Test the guest experience

---

Troubleshooting

Home Assistant won't boot

• Ensure the power supply provides adequate power
• Try a different ethernet cable
• Wait at least 20 minutes on first boot
• Check if the device shows activity lights

Can't access homeassistant.local

• Try the IP address directly (find it in your router)
• Ensure you're on the same network
• Some routers don't support .local addresses—use the IP instead

Devices not appearing

• Most devices (Z-Wave, Zigbee) need to be manually added
• Check that integrations are properly configured
• Restart Home Assistant after adding new integrations

Automations not running

• Check the automation is enabled (toggle is on)
• View the automation trace for errors
• Verify trigger conditions are being met
• Check entity IDs haven't changed

HACS not showing

• Ensure you restarted Home Assistant after installation
• Clear browser cache and reload
• Check the Home Assistant logs for errors

---

Resources

Official documentation

• Home Assistant Docs
• Home Assistant Community Forum

Staykey help articles

• Hardware Requirements
• Supported Smart Locks
• Connecting Your Home Assistant Hub
• Setting Up Z-Wave Devices

---

Questions? Our support team is here to help. Reach out through your Staykey dashboard or check our other help articles.