Skip to content
GrowAssistant.io GrowAssistant.io GrowAssistant.io Docs

Installation

This page is for readers who have never installed Home Assistant, set up MQTT, or paired a Zigbee device before. If you already run a Home Assistant instance with Zigbee2MQTT working, skip straight to Installing GrowAssistant below.

Everything in the beginner section points at the official Home Assistant, Zigbee2MQTT, and HACS documentation for every step — this page connects those official guides into one beginner-friendly path and explains which options this specific project (a native-Home-Assistant grow tent controller) actually needs. Source links are given throughout so you can always go to the original instructions for more detail.

1. Which Home Assistant installation to pick, and why

Home Assistant currently ships two supported installation methods: Home Assistant Operating System (HA OS) and Home Assistant Container (Docker). Two older methods, Home Assistant Core and Home Assistant Supervised, are being phased out — support for them ends with the 2025.12 release, and Home Assistant recommends migrating away from both (see the deprecation announcement).

This project is built and documented for Home Assistant OS. The reason is the Supervisor: HA OS is the only current option that gives you the Supervisor’s add-on store, and this project’s setup relies on several add-ons:

  • Mosquitto broker (MQTT, needed for Zigbee2MQTT, see step 5),
  • Zigbee2MQTT (see step 5),
  • File editor or Studio Code Server (to edit the YAML files this project ships, see step 3),
  • HACS (for the custom dashboard cards used across this project’s dashboards, see step 6),
  • optionally MotionEye (only if you add USB tent cameras, see Module M13 – Cameras).

Home Assistant Container can run all of this too, but without the Supervisor you would need to run MQTT/Zigbee2MQTT/HACS as separate Docker containers you manage yourself — more moving parts for a first-time setup. See Home Assistant’s own comparison of installation types and the HA OS vs. Container FAQ if you want the full picture before deciding.

2. Hardware and prerequisites

Before installing anything, make sure you have:

  • A dedicated host. A Raspberry Pi 4 or 5 (at least 2 GB of RAM), a small x86-64 mini PC, or a spare machine to run a VM on all work. Home Assistant’s official pre-built appliance, Home Assistant Green, is the least fiddly option if you would rather not assemble/flash anything yourself. See the official installation overview for every supported option and its hardware requirements.
  • Storage. For a Raspberry Pi: a 32 GB or larger microSD card, ideally “Application Class 2” (A2-rated) for better performance, per the official Raspberry Pi installation guide. An SD card reader (built into most laptops, or a cheap USB one).
  • A wired Ethernet connection for the initial setup. HA OS’s first boot needs Ethernet even if you plan to switch to Wi-Fi afterward (see the Raspberry Pi guide linked above).
  • A proper power supply — the official guide specifically warns against phone chargers or a computer’s USB port, which often cannot deliver stable power to a Raspberry Pi under load.
  • A USB Zigbee coordinator (dongle). This is what lets Home Assistant talk to your Zigbee sensors/plugs; see step 5 for adapter recommendations — decide on one now since it affects what you plug in later.
  • The Home Assistant sensors/actuators this project needs. GrowAssistant itself only requires a temperature sensor, a humidity sensor, and at least one of a dehumidifier or humidifier — everything else (lighting, CO2, irrigation, substrate sensors, energy metering, cameras) is optional and can be added later. See Core / Entity Mapping – Required vs. optional for the full list. You do not need to own all of this hardware before you start; Home Assistant, MQTT, and Zigbee2MQTT can all be fully installed and verified first, with real devices mapped in afterward as they arrive.

3. Install Home Assistant OS and do the initial setup

  1. Flash the image. Download and open Raspberry Pi Imager, choose Other specific-purpose OS -> Home automation -> Home Assistant, pick the image matching your Pi model, select your SD card, and write it. Full walkthrough, including x86-64/VM instructions: Home Assistant OS installation.

  2. First boot. Insert the card, connect Ethernet and power, and wait a few minutes for the first-boot setup to finish. Open http://homeassistant.local:8123 in a browser on the same network (use your router’s client list to find the device’s IP address if that hostname does not resolve on your network).

  3. Onboarding wizard. Home Assistant walks you through creating your owner account (username/password — there is no recovery for this account, so store it somewhere safe), setting your home’s location (used for time zone, unit system, and sunrise/sunset-based automations), and an optional analytics opt-in. Full details: Onboarding.

  4. Install a way to edit YAML files. This project is delivered as YAML files (packages/*.yaml, dashboards/*.yaml) that need to be copied into your Home Assistant config folder. From Settings -> Add-ons -> Add-on Store, install either:

    • File editor — a simple browser-based editor with YAML syntax checking, restricted to the config folder by default; or
    • Studio Code Server — a full web-based VS Code, including a terminal (more capable, slightly heavier); or
    • Samba share — mounts your config folder as a network drive (\\<your-ha-ip> on Windows, smb://<your-ha-ip> on Mac/Linux) so you can edit files with tools on your own computer instead.

    All three are official Home Assistant add-ons; see Common tasks – Home Assistant OS for the install steps and a comparison.

  5. Enable packages: support. This project ships as Home Assistant packages (one YAML file per module). Open configuration.yaml with whichever editor you installed and make sure there is exactly one homeassistant: block containing a packages: line:

    homeassistant:
      name: Home
      packages: !include_dir_named packages

    Then create the packages folder next to configuration.yaml if it does not exist yet. If you hit an Integration 'packages' not found error later, see Troubleshooting — it is almost always this block being duplicated or placed at the wrong indentation level.

4. Install and connect MQTT (Mosquitto)

Zigbee2MQTT needs an MQTT broker to talk to Home Assistant. The official, zero-configuration option is the Mosquitto broker add-on:

  1. From Settings -> Add-ons -> Add-on Store, search for Mosquitto broker (an official Home Assistant add-on — no repository URL needs to be added first) and install it.
  2. Start it, and enable “Start on boot”.
  3. Go to Settings -> Devices & Services -> Add Integration, search for MQTT, and add it. When the official Mosquitto add-on is running, Home Assistant auto-detects it and generates the login credentials for you automatically — no manual broker address/username/password entry is needed in the normal case.

Official references: the MQTT integration and the Mosquitto broker add-on.

5. Install, configure, and connect Zigbee2MQTT

This project uses Zigbee2MQTT rather than Home Assistant’s built-in ZHA integration as the Zigbee backend — practically, GrowAssistant does not care which backend you use, since every entity is referenced through the mapping helpers described in Core / Entity Mapping, but this page follows that choice for consistency with the rest of this documentation.

  1. Pick a coordinator adapter. Zigbee2MQTT’s own guidance is to prefer a zStack (Texas Instruments), EmberZNet (Silicon Labs), or deCONZ (Dresden Elektronik) based USB coordinator, connected by a wired USB extension cable rather than plugged directly into the host (USB 3.0 ports and the Pi’s own electronics are a known source of Zigbee interference). See the official adapter guide before buying one, and check the FAQ there first if you already own an adapter and are unsure it is supported.
  2. Add the add-on repository. From Settings -> Add-ons -> Add-on Store -> ⋮ (top right) -> Repositories, add https://github.com/zigbee2mqtt/hassio-zigbee2mqtt (the official Zigbee2MQTT Home Assistant add-on repository).
  3. Install and start Zigbee2MQTT. Find “Zigbee2MQTT” in the store, install it, then open its web UI. The onboarding flow detects your USB adapter and lets you select it; if it is not auto-detected, set the adapter type and serial port manually in the add-on configuration (a single USB device is usually /dev/ttyACM0 or /dev/ttyUSB0). Full steps: the official add-on repository README.
  4. Pair (join) your Zigbee devices. Open the Zigbee2MQTT web UI, click the join/“permit join” button (top right — opens the network for 254 seconds), and put your sensor/plug into pairing mode per its own manual (usually a factory reset or a long button press). Watch the Zigbee2MQTT log for a “successfully paired” message. Repeat for every sensor and actuator. Official guide: Pairing devices.
  5. Confirm the entities show up in Home Assistant. With the MQTT integration from step 4 installed, every paired Zigbee2MQTT device appears automatically as one or more Home Assistant entities (via MQTT discovery) — no extra configuration needed. You will map these entity IDs into GrowAssistant later, in Dashboard 1 – Configuration.

6. What GrowAssistant itself needs on top of a working Home Assistant

Once Home Assistant, MQTT, and Zigbee2MQTT are running, this project additionally needs:

  • HACS (Home Assistant Community Store), for the custom dashboard cards used across this project’s dashboards — apexcharts-card (charts), mushroom (compact status cards), card-mod (dynamic styling), and expander-card (collapsible explainer notes). Install HACS itself per the official HACS download guide, then install each card from HACS -> Frontend -> Explore & Add Repositories by name. None of Dashboard 1’s mapping fields or Setup Status card need HACS — only the more visual parts of Dashboard 2/3 do, so this step can wait until the functional setup is confirmed working.
  • The Home Assistant Companion mobile app (optional, only needed for push-notification alarms), installed from the App Store or Google Play, then logged into your instance. Once logged in, your device automatically gets a notify.mobile_app_<device> service Home Assistant can send alerts to. See the official Companion app documentation for details.
  • An SMTP integration (optional, only needed for email alarms) via Settings -> Devices & Services -> Add Integration -> Email, using your mail provider’s SMTP server, port, and credentials (Gmail and similar providers typically require an app-specific password rather than your normal account password). See the official SMTP integration docs.
  • Nothing special for history/graphs. Home Assistant’s built-in Recorder uses a local SQLite database by default, which is enough to start with — no separate database server is required for this project.

7. Verifying everything works before you install GrowAssistant

Work through this checklist before moving on — it isolates problems to the right layer (Home Assistant vs. MQTT vs. Zigbee2MQTT vs. an individual device) instead of debugging GrowAssistant’s own templates against a shaky foundation.

  1. Home Assistant itself is healthy. Settings -> System -> Logs shows no repeating errors, and Developer Tools -> YAML -> Check Configuration reports “Configuration valid!”.
  2. MQTT is connected. Settings -> Devices & Services lists an MQTT integration entry without a “not loaded”/“failed to connect” warning badge.
  3. Zigbee2MQTT’s bridge is online. Open the Zigbee2MQTT web UI — the dashboard shows the bridge as connected, and every paired device is listed with a recent “last seen” time and non-zero link quality.
  4. Paired devices report real values in Home Assistant. Go to Developer Tools -> States, filter for your device (e.g. by its Zigbee2MQTT friendly name), and confirm its sensor.*/switch.* entities show a live, changing value — not unavailable or unknown. For a plug/switch, toggle it from the States tab (or physically) and confirm the state updates within a few seconds.

8. Common setup issues for first-time users

  • homeassistant.local does not resolve. Not every router/network supports .local (mDNS) hostnames. Use the device’s IP address instead (check your router’s connected-devices list), or an mDNS-capable browser extension — see the Raspberry Pi installation guide.
  • New input_* helpers from a package do not appear. A first-time package deployment needs a full Home Assistant restart, not just a YAML reload — see Troubleshooting.
  • Zigbee2MQTT does not detect the USB adapter, or devices randomly drop off. Usually a serial-port/interference issue: use a wired USB extension cable to move the adapter away from the host and any USB 3.0 ports, and double-check the port path (/dev/ttyACM0//dev/ttyUSB0) in the add-on configuration. See the official adapter guide and that guide’s linked FAQ for adapter-specific quirks.
  • A device will not pair. Re-enable “permit join” (it only stays open 254 seconds), then factory-reset the device again per its manual — most join failures are the join window having already closed rather than a real fault. See Pairing devices for device-specific pairing instructions and its own troubleshooting section.
  • MQTT integration installed, but Zigbee2MQTT devices never appear in Home Assistant. Confirm Zigbee2MQTT’s own MQTT connection (its web UI shows a bridge-connected state) — if Zigbee2MQTT cannot reach the broker, entities are never published for Home Assistant to discover.
  • Still stuck? The official Home Assistant Community forum and the Zigbee2MQTT GitHub Discussions are the right places to ask — both are far more active and current than any single doc page can be, including this one.

Installing GrowAssistant

Once the checklist in section 7 passes — or immediately, if you already had a working Home Assistant/MQTT/Zigbee2MQTT setup — install the project itself:

  1. Make sure packages: is enabled as in step 3.5 above (nested inside your existing homeassistant: block, not as its own top-level key).
  2. Copy the contents of the repository’s packages/ folder into your HA config/packages/ folder (create it if it does not exist yet).
  3. Run Developer Tools -> YAML -> Check Configuration (or ha core check), then reload if valid — at minimum reload Template Entities and Automations. The very first time the packages: block or a new package file is added, a full restart is needed instead of a reload (new input_* helper definitions are only read in at startup; later value changes never need a restart).
  4. Import dashboards/dashboard_1_configuration.yaml as a new dashboard: Settings -> Dashboards -> Add Dashboard -> “Take control of the YAML”, then paste the file’s content in raw edit mode. Repeat for dashboards/dashboard_2_control_panel.yaml and dashboards/dashboard_3_log.yaml.
  5. On the new “Configuration” dashboard, fill in at least the required mappings (Temperature Sensor, Humidity Sensor, and at least one of Dehumidifier/Humidifier). You do not need to type/paste entity IDs by hand — use the search-based helper instead: Developer Tools -> Actions -> “Grow Assistant: Set Mapping”, pick the function and search for your device. See Mapping Tool for details. The “Setup Status” card at the top confirms once all required mappings are complete.
  6. Install HACS and the four dashboard cards listed in step 6 above if you have not already, for Dashboard 2/3’s full visual experience.

Next steps