Home Assistant Integration Requirements Document

1. Purpose & Scope

This document defines the requirements for deploying Home Assistant OS on a dedicated machine and integrating the following smart-home ecosystems:

• Ring
• Mysa
• TopGreener
• Tapo
• YoLink
• Carro
• SmartLife / Tuya
• SmartHQ
• MyQ
• SmartThings
• Cync

The objective is to establish a stable, local-first smart home platform that prioritizes reliability, predictable behavior, secure networking, and clean device onboarding—while accommodating unavoidable cloud-based integrations.

⸻

2. System Requirements

2.1 Hardware Requirements

Minimum

• 2 CPU cores
• 4 GB RAM
• 32 GB SSD
• Wired Ethernet
• UPS recommended

Recommended

• 4+ CPU cores
• 8–16 GB RAM
• 128 GB SSD or NVMe
• x86_64 platform (Intel/AMD)
• Optional dual NIC for network segmentation

⸻

2.2 Network Requirements

• Home Assistant must reside on a trusted LAN
• Static IP or DHCP reservation required
• 1 Gbps Ethernet recommended

Optional VLAN Segmentation

• VLAN 10 — Trusted LAN (Home Assistant, controllers)
• VLAN 20 — IoT devices
• VLAN 30 — Cameras
• VLAN 40 — Guest network

Firewall Rules

• Allow IoT VLAN → HA
• TCP 8123
• UDP mDNS / SSDP as required for discovery
• Block IoT VLAN → Internet except required cloud APIs
• Allow HA → Internet for integrations, updates, and backups
• Explicitly block inbound WAN access to HA

⸻

3. Software Requirements

3.1 Home Assistant OS

• Latest stable release
• Supervisor enabled
• Add-on store available
• Automated backups enabled
• OS and Core updates staged (not blind auto-apply)

Downloads

• Home Assistant OS images: https://www.home-assistant.io/installation/
• Generic x86_64 image: https://www.home-assistant.io/installation/generic-x86-64/

⸻

3.2 Required Add-ons

Add-ons provide supporting services. Vendor connections are implemented as integrations, not add-ons.

Required

• Mosquitto MQTT - https://www.home-assistant.io/integrations/mqtt/
• File Editor
• SSH & Web Terminal
• Backup solution
• Samba Backup
• Google Drive Backup

Optional / Conditional

• Bond: https://www.home-assistant.io/integrations/bond/
• Zigbee2MQTT: https://www.zigbee2mqtt.io/
• AdGuard Home: https://www.home-assistant.io/integrations/adguard/
• InfluxDB: https://www.home-assistant.io/integrations/influxdb/
• Grafana: https://www.home-assistant.io/integrations/grafana/
• Network UPS Tools (NUT): https://www.home-assistant.io/integrations/nut/

⸻

4. Integration Requirements (with Docs)

4.1 Ring

https://www.home-assistant.io/integrations/ring/

• Ring account + 2FA required
• Cloud-based
• Subject to API rate limits

⸻

4.2 Mysa

https://www.home-assistant.io/integrations/homekit_controller/

• HomeKit Controller integration
• Local control after pairing

⸻

4.3 TopGreener (Tuya-based)

https://www.home-assistant.io/integrations/tuya/

• Cloud-based
• Local mode not guaranteed

⸻

4.4 Tapo

https://www.home-assistant.io/integrations/tapo/

• Local control supported on many devices
• Requires Tapo credentials

⸻

4.5 YoLink

https://www.home-assistant.io/integrations/yolink/

• Requires YoLink Hub
• Developer API key required https://developer.yosmart.com/

⸻

4.6 Carro (via Bond)

https://www.home-assistant.io/integrations/bond/

• Requires Bond Bridge and API token
• Local control supported

⸻

4.7 SmartLife / Tuya

https://www.home-assistant.io/integrations/tuya/

• Cloud-based
• API keys required: https://iot.tuya.com/

⸻

4.8 SmartHQ

https://www.home-assistant.io/integrations/smarthq/

• Cloud-based
• GE appliances

⸻

4.9 MyQ

https://www.home-assistant.io/integrations/myq/

• Cloud-based
• API reliability varies
• Must not be used for safety-critical automations

⸻

4.10 SmartThings

https://www.home-assistant.io/integrations/smartthings/

• Cloud-based
• Zigbee/Z-Wave bridge support

⸻

4.11 Cync

https://www.home-assistant.io/integrations/cync/

• Cloud-based
• Bluetooth devices require Cync Wi-Fi bridge

⸻

5. Security Requirements

5.1 Authentication

• Strong passwords
• MFA enabled
• Least-privilege users
• Remove unused/default accounts

⸻

5.2 Network Security

• No public exposure of port 8123
• Use Nabu Casa for remote access: https://www.nabucasa.com/
• TLS for all external access
• Restrict SSH by IP

⸻

5.3 Backup Strategy

• Daily snapshots
• Weekly offsite backups
• Quarterly restore testing
• YAML, dashboards, and blueprints exported

⸻

6. Automation Requirements

6.1 Core Automations

• Presence detection
• Climate control
• Leak detection
• Garage door alerts
• Lighting automations
• Fan control

⸻

6.2 Notification Channels

• Home Assistant mobile app: https://www.home-assistant.io/integrations/mobile_app/
• Email
• Push notifications
• Optional: Telegram, Signal, Discord

⸻

7. Configuration Management with Ansible

7.1 Scope of Ansible Use

Ansible does not install Home Assistant OS itself, but is used to:

• Provision the host system (if using HA Supervised or Container)
• Manage:
  • Backups
  • Add-on configuration files
  • Secrets
  • Dashboards
  • YAML automations
• Enforce configuration drift control

⸻

7.2 Supported Deployment Models

Reference: https://www.home-assistant.io/installation/

⸻

7.3 Ansible Responsibilities

• Create and manage:
  • /config YAML files
  • secrets.yaml
• Dashboards
• Install required packages on host (Supervised/Container)
• Manage backups via HA API
• Validate configs before restart

⸻

7.4 Ansible Integration Pattern

• Use Home Assistant REST API: https://developers.home-assistant.io/docs/api/rest/
• Use long-lived access tokens Idempotent tasks only
• Changes applied via:
  • ha core check
  • ha core restart

⸻

7.5 Ansible Limitations

• UI-based onboarding (OAuth, MFA) must be completed manually
• Vendor cloud authentication cannot be automated
• Device pairing remains manual by design

⸻

8. Future Expansion

• Zigbee2MQTT
• Thread / Matter controller: https://www.home-assistant.io/integrations/matter/
• Local DNS (AdGuard Home, Pi-hole)
• UPS monitoring
• InfluxDB + Grafana
• Local voice assistant

⸻

9. Acceptance Criteria

A deployment is considered complete when:

• Home Assistant boots reliably after updates and power loss
• All integrations function as documented
• Automations execute predictably
• Backups are automated and restorable
• Remote access is secure and audited
• Dashboards are consistent and usable
• IoT devices are segmented but reachable