Home Assistant is an open-source home automation solution.
This repository packages Home Assistant into an AWS IoT Greengrass V2 component named aws.greengrass.labs.HomeAssistant. This enables use cases where you requre Home Assistant for local control, but also require integration with AWS services at the edge and in the cloud.
Using the Home Assistant MQTT Integration, Home Assistant can publish and subscribe to topics on AWS IoT Core and/or on the Greengrass local EMQX MQTT broker or Moquette MQTT broker. This allows integration with the cloud, with other Greengrass components on the same device and/or with other devices on the local network. Home Assistant can therefore leverage AWS-managed Greengrass components, custom Greengrass components, community Greengrass components and AWS services to deliver powerful home automation solutions that extend Home Assistant's capabilities.
- Architecture
- Repository Contents
- Requirements and Prerequisites
- Getting Started
- Home Assistant Configuration Tips
- Operations
- Troubleshooting
- Development
An overview of the system architecture is presented below.
The aws.greengrass.labs.HomeAssistant component is a thin wrapper around a conventional Home Assistant Container deployment.
Home Assistant Container is delivered as a Docker image on Docker Hub and on GitHub. This Greengrass component downloads the selected Docker image from Docker Hub or GitHub with the help of the Docker application manager component.
Home Assistant configuration files are designed to be split as the solution scales. By convention, secrets are typically separated from the rest of the configuration and stored in a file named secrets.yaml. This Greengrass component handles secrets.yaml by storing it as a secret in AWS Secrets Manager in the cloud. At the edge, this component retrieves the secrets.yaml file from Secrets Manager with the help of the Secret manager managed component. From the developer machine, the contents of the secrets directory are placed into the Secrets Manager secret by calling create_config_secret.py.
As shown in blue on the architecture diagram, Home Assistant can use its MQTT integration to connect directly to AWS IoT Core. Alternatively, and more powerfully, Home Assistant can instead connect to the local Greengrass EMQX MQTT broker or Moquette MQTT broker. This is option is shown in red. If Home Assistant and other devices on the local network are registered as Local Client Devices with Greengrass, this architecture allows Home Assistant to communicate with those other devices via the broker and with AWS IoT Core and other Greengrass components via the MQTT bridge and Greengrass Interprocess Communication.
| Item | Description |
|---|---|
| /artifacts | Greengrass V2 component artifacts that run on the Greengrass edge runtime. |
| /cicd | CDK Typescript app for a CodePipeline CI/CD pipeline. |
| /images | Images for README files. |
| /libs | Python libraries shared by Python scripts. |
| /secrets | Home Assistant secrets (secrets.yaml and other optional files). |
| /tests | Pytest unit tests. |
| create_config_secret.py | Creates or updates the Home Assistant configuration secret in Secrets Manager. |
| deploy_component_version.py | Deploys a component version to the Greengrass core device target. |
| gdk_build.py | Custom build script for the Greengrass Development Kit (GDK) - Command Line Interface. |
| gdk-config.json | Configuration for the Greengrass Development Kit (GDK) - Command Line Interface. |
| quickstart.sh | Creates a secret, and creates and deploys a component version in a single operation. |
| recipe.yaml | Greengrass V2 component recipe template. |
This component requires that the Greengrass device be running a Linux operating system. It supports all architectures supported by Greengrass itself.
The Greengrass edge runtime needs to be deployed to a suitable machine, virtual machine or EC2 instance. Please see the Home Assistant installation guide for information on the resources required.
Your core device must meet the requirements to run Docker containers using Docker Compose and Docker Hub.
This component requires both python3 and pip3 to be installed on the core device.
Assuming the bucket name in gdk-config.json is left unchanged, this component downloads artifacts from an S3 bucket named greengrass-home-assistant-REGION-ACCOUNT. Therefore your Greengrass core device role must allow the s3:GetObject permission for this bucket. For more information: https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html#device-service-role-access-s3-bucket
Additionally, this component downloads sensitive Home Assistant configuration from Secrets Manager. Therefore your Greengrass core device role must also allow the secretsmanager:GetSecretValue permission for the greengrass=home-assistant-ID secret.
Policy template to add to your device role (substituting correct values for ACCOUNT, REGION and ID):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::greengrass-home-assistant-REGION-ACCOUNT/*"
},
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:greengrass-home-assistant-ID"
}
]
}
The AWS CLI should be installed.
Most of the scripts in this repository are Python scripts. They are Python 3 scripts and hence python3 and pip3 are required.
Package dependencies can be resolved as follows:
pip3 install -r requirements.txt
Please consider to use a virtual environment.
Boto3 is included in the package dependencies and therefore your machine requires appropriate credentials.
This component makes use of the Greengrass Development Kit (GDK) - Command Line Interface (CLI). This can be installed as follows:
pip3 install git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git
The quickstart.sh script is a Bash script. If using a Windows machine, you will need a Bash environment. Alternatively you can run the Python scripts individually.
The jq utility is used by quickstart.sh. Release packages for Linux, OS X and Windows are available on the jq site.
Alternatively, Ubuntu includes a jq package:
sudo apt update
sudo apt install jq
You can choose between two ways to get started: Quickstart or Slowstart.
All scripts are compatible with Linux, Mac or Windows operating systems, provided a Bash environment is available.
The quickstart.sh bash script is supplied to help you get going fast. It rolls the constituent steps up into a single command.
Before running the script, users must deploy Greengrass V2 to a physical machine, virtual machine or EC2 instance, meeting all of the prerequisites including the requirements to run Docker containers using Docker Compose and Docker Hub. Addtionally, users must set the AWS region in gdk-config.json.
It is not necessary to perform any Home Assistant configuration changes. Out of the box, Home Assistant will be deployed with default configuration.
The Quickstart script will:
- Install required Python packages on your developer machine.
- Upload the default (null) secret configuration (secrets.yaml) to a secret in Secrets Manager, creating the secret.
- Use GDK to build the component.
- Use GDK to publish a new component version to Greengrass cloud services and upload artifacts to an S3 bucket.
- Prompt you to add permissions for the configuration secret and artifacts bucket to the Greengrass core device role.
- Deploy the new component version to the Greengrass core.
The script accepts 1 argument: the Greengrass Core device name.
Example execution:
bash quickstart.sh MyCoreDeviceThingName
For any serious use of the component, Quickstart shall not be appropriate.
If not using Quickstart, you must perform the following steps:
- Deploy the Greengrass runtime to your machine, virtual machine or EC2 instance, meeting all of the prerequisites.
- Select your desired Home Assistant Container image and tag by modifying artifacts/docker-compose.yml.
- Configure Home Assistant by modifying the configuration YAML files in artifacts/config and secrets as desired.
- Set the AWS region and component version in gdk-config.json.
- Run create_config_secret.py to create the configuration secret in Secrets Manager.
- Run gdk component build to build the component.
- Run gdk component publish to create a component version in Greengrass cloud service, and upload artifacts to S3.
- Add permissions for the configuration secret and artifacts bucket to the Greengrass core device role.
- The component can then be deployed using the console or using the AWS CLI in the normal way. Alternatively it can be deployed using the supplied deploy_component_version.py script.
For iterative configuration changes, repeat steps as appropriate.
Example of steps 5, 6, 7 and 9:
python3 create_config_secret.py
gdk component build
gdk component publish
python3 deploy_component_version.py 1.1.0 MyCoreDeviceThingName
This example:
- Creates a Secrets Manager secret in your account in the region specified in gdk-config.json.
- Builds the component and publishes it to your account in the region specified in gdk-config.json.
- Deploys the new component version to Greengrass core device MyCoreDeviceThingName.
This repository offers a CodePipeline CI/CD pipeline as a CDK application. This can be optionally deployed to the same account as the Greengrass core.
This CI/CD pipeline automates steps 6, 7 and 9. With the pipeline deployed, users can make iterative configuration changes, update the configuration secret using create_config_secret.py, and then trigger the CI/CD pipeline to handle the rest.
Configuration of Home Assistant can be done predominantly through its user interface. However, it can also be configured using the YAML files in artifacts/config and secrets. Please consult the Home Assistant configuration documentation for details.
The configuration files in this projects are merely skeleton files. Home Assistant can be deployed with these files, yielding a greenfields installation.
Docker images from Home Assistant's GitHub releases can be used directly as the image in artifacts/docker-compose.yml.
You can use the Home Assistant MQTT Integration to integrate your devices and Home Assistant with AWS IoT services, by configuring your MQTT broker as being AWS IoT Core or one of the AWS IoT Greengrass brokers.
Install the MQTT integration and use the Home Assistant UI to configure the integration. You will need to enable Advanced mode in your Home Assistant user settings to be able to setup a TLS connection to your preferred broker.
To connect Home Assistant directly to AWS IoT Core, firstly create a Thing representing Home Assistant, and obtain the device certificate, private key and Amazon Root CA certificate.
Obtain the AWS IoT Core endpoint:
aws iot describe-endpoint --endpoint-type iot:Data-ATS
{
"endpointAddress": "ENDPOINTID-ats.iot.REGION.amazonaws.com"
}Then configure the MQTT integration through the UI with the following settings.
| Configuration Item | Description |
|---|---|
| Broker | ENDPOINTID-ats.iot.REGION.amazonaws.com |
| Port | 8883 |
| Client ID | The AWS IoT Core thing name |
| Client certificate | FINGERPRINT-certificate.pem.crt |
| Private key | FINGERPRINT-private.pem.key |
| Broker certificate validation | Custom |
| CA certificate | AmazonRootCA1.pem |
| MQTT protocol | 3.1.1 or 5 |
| MQTT transport | TCP |
Greengrass V2 includes two AWS-managed brokers, the EMQX MQTT broker component and the Moquette MQTT broker component. Either of these can be deployed to Greengrass to allow Greengrass components and devices on your local network to communicate with each other, without relying on an internet connection to AWS IoT Core.
Using the MQTT Integration, Home Assistant can be a "local IoT device" that connects to the EMQX or Moquette broker. Additionally, Greengrass V2 includes an AWS-managed MQTT Bridge component. When this is also deployed, Home Assistant can use its MQTT Integration to communicate with local devices, Greengrass components and AWS IoT Core; the best of all worlds.
To begin, update the Greengrass deployment to add the necessary components to your Greengrass core device:
You will then need to:
- Create a Thing representing Home Assistant, and obtain the device certificate and private key.
- Associate this Thing with your Greengrass core device.
- Configure the Client device auth component to define what Home Assistant is authorized to do.
- Configure the MQTT Bridge component to define the desired message relaying.
You can then configure the MQTT integration broker settings as described above for AWS IoT Core, but with the following adjustments:
- The broker should be
localhostbecause the broker is on the same machine as Home Assistant. - Use your own certificate authority (CA), configure the Client device auth component to use it, and configure the MQTT integration to use that as the CA certificate to validate the broker. Alternatively, disable broker certificate validation in the MQTT integration.
Removing this component from your deployment will not remove all vestiges from your Greengrass core device. Additional steps:
- Remove any Home Assistant Docker images that have persisted.
- Remove the working directory: /greengrass/v2/work/aws.greengrass.labs.HomeAssistant. This also deletes persistent data and settings.
If this component is deployed with default settings, persistent data and settings are located in /greengrass/v2/work/aws.greengrass.labs.HomeAssistant/config.
Tips for investigating failed deployments, or deployments that succeed but Home Assistant is still not working as expected.
Detailed component logs can be found on the Core Device in /greengrass/v2/logs/aws.greengrass.labs.HomeAssistant.log.
The Greengrass Core log file can be found at /greengrass/v2/logs/greengrass.log.
For more information please refer to the Greengrass V2 documentation: https://docs.aws.amazon.com/greengrass/v2/developerguide/monitor-logs.html
Consider to install the Greengrass Command Line Interface component to obtain greater visibility into the state of your core device.
The logs within the Docker container can be inspected as follows:
docker logs homeassistant
If a Docker image of the wrong architecture is deployed, it will fail to start. A message similar to the following indicates that the wrong architecture is being used:
standard_init_linux.go:228: exec user process caused: exec format error
This message will appear in /greengrass/v2/logs/aws.greengrass.labs.HomeAssistant.log.
To resolve incorrect architecture, please check the available architectures for the image tag. Image tags on DockerHub do not always support all architectures. Update docker-compose.yml and deploy a new version of the component.
The Greengrass Secret Manager component fetches the configuration secret from the cloud when the component starts up. If you change the value of the secret, you need to deploy a new component version, restart Greengrass, or reboot the core device to refresh the value.
The deployed secrets.yaml can be found at /greengrass/v2/work/aws.greengrass.labs.HomeAssistant/secrets.yaml.
Static analysis is performed using Pylint. Example execution:
pylint artifacts libs tests *.py
Unit tests are performed using pytest.
Example execution:
pytest --cov=artifacts --cov=.
Producing an HTML coverage report into the htmlcov directory:
pytest --cov=artifacts --cov=. --cov-report=html
Producing a coverage report for just the on-device artifacts (100% coverage):
pytest --cov=artifacts