📖 Overview

This document provides a comprehensive guide on how to install Home Assistant using a Docker container on Robustel Edge Gateways (EG Series) running RobustOS Pro. Additionally, it covers the necessary steps to download and configure the Home Assistant Community Store (HACS) component.

Running Home Assistant on a Robustel Edge Gateway transforms your device into a powerful, locally-controlled hub for smart home and industrial IoT automation. Integrating HACS further extends its functionality by allowing you to easily install community-developed plugins, custom cards, and integrations.

🛠 What You'll Need

Hardware Requirements:

• A Robustel Edge Gateway (e.g., EG5100, EG5120, EG5200).

Software/Firmware Requirements:

• RobustOS Pro: v2.3.0 or newer.
• SSH Client (e.g., PuTTY, macOS/Linux Terminal) to access the gateway's command line.

Other Requirements:

• Internet Access: The gateway must have an active internet connection to pull the Docker image.

• Sudo User Account: A user with sudo privileges must be created in the device configuration page.

• Docker runtime environment: Installed and running on the gateway.

• A valid GitHub account: Required for the HACS configuration phase).

🚀 Step-by-Step Configuration Guide

1️⃣ Step 1: Install and Run Home Assistant

First, you will deploy the Home Assistant container using the command line.

1. Open your SSH client and connect to the gateway.
2. Run the following Docker command to pull the image, create the container, and start Home Assistant.

sudo docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=Asia/Shanghai \
  -v /usr/local/HAconfig:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

2️⃣ Step 2: Download and Prepare HACS

Once the container is deployed, you need to manually download and extract the HACS component into the Home Assistant configuration directory.

1. Navigate to the newly created Home Assistant configuration directory:

cd /usr/local/HAconfig

2. Create a folder for custom components and navigate into it:

sudo mkdir custom_components
cd custom_components

3. Download the HACS installation package:

sudo wget https://github.com/hacs/integration/releases/download/2.0.5/hacs.zip

4. Create a dedicated folder for HACS and extract the downloaded zip file into it:

sudo mkdir hacs
sudo unzip hacs.zip -d hacs

✅ Verification & Testing

Test 1: Verify the Docker Container is Running

Run the following command in your SSH terminal to ensure the Home Assistant container is active:

sudo docker ps

Test 2: Access the Home Assistant Web UI

1. Open a web browser on a computer connected to the same local network as the gateway.
2. Navigate to http://192.168.0.1:8123 (Replace 192.168.0.1 with the actual IP address of your gateway's LAN or WAN interface, depending on how you are accessing it).

Test 3: Verify and Install HACS via the UI

1. Restart Home Assistant:  In the Home Assistant sidebar, click on Developer Tools.
   
1. Under the YAML tab, click the RESTART button. This ensures Home Assistant detects the new custom_components folder.
   

2. Add Integration: Navigate to Settings > Devices & Services.

1. Click Add Integration in the bottom right and search for HACS.

3. Authentication: Follow the prompts to link your GitHub account using the provided activation code.

❓ Troubleshooting / FAQ

• Q: What if the wget or unzip commands are not recognized in the terminal?
• A: Your Debian environment may not have these basic utilities installed by default. You can install them by executing sudo apt update followed by sudo apt install wget unzip.

• Q: I cannot access the Home Assistant Web UI at port 8123. What is wrong?
• A: Verify the IP address of your gateway. If you are trying to access the UI from an external network, ensure that the gateway's Firewall rules allow inbound traffic on port 8123. Also, verify via sudo docker ps that the container is running.

• Q: The HACS integration is not showing up when I search for it in "Add Integration".
• A: This usually means the files were extracted into the wrong directory, or Home Assistant hasn't loaded them yet. Ensure the files are exactly in /usr/local/HAconfig/custom_components/hacs. After confirming the path, fully restart the Home Assistant Docker container by running sudo docker restart homeassistant.

📜 Revision History