Amazon Web Services (AWS)
The aws
integration provides a single place to interact with Amazon Web Services
Setup
You have to have an AWS account to use Amazon Web Services, create one here
The lambda
, sns
, sqs
, and events
services, used in the aws
integration, all provide an Always Free tier for all users even after the 12-month period. The general usage in Home Automation will most likely not reach the free tier limit. Please read Lambda Pricing
The aws
integration is using botocoreaws
shares the same credential and profiles with awscli
tool. Please read Configuring the AWS CLI
Configuration
To use the aws
integration and the notify
platform in your installation, add the following to your configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file.
After changing the configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes. The integration is now shown on the integrations page under Settings > Devices & services. Its entities are listed on the integration card itself and on the Entities tab.
# Example configuration.yaml entry
aws:
credentials:
- name: My AWS Account
aws_access_key_id: AWS_ID
aws_secret_access_key: AWS_SECRET
notify:
# use the first credential defined in aws integration by default
- service: lambda
region_name: us-east-1
Configuration for credentials
Configuration Variables
Give your AWS credential a name, so that you can refer it in other AWS platforms.
Your AWS Access Key ID. If provided, you must also provide an aws_secret_access_key
and must not provide a profile_name
. Required if aws_secret_access_key
is provided.
Your AWS Secret Access Key. If provided, you must also provide an aws_access_key_id
and must not provide a profile_name
. Required if aws_access_key_id
is provided.
Configuration for notify
Configuration Variables
Amazon Web Services will be used for notification. You can choose from lambda
, sns
, or sqs
.
A reference to an aws
credential. Notify platform will use the default profile
defined in ~/.aws
if none of credential_name
, aws_access_key_id
, or profile_name
was given.
Your AWS Access Key ID. If provided, you must also provide an aws_secret_access_key
.
Your AWS Secret Access Key. If provided, you must also provide an aws_access_key_id
. Required if aws_access_key_id is provided.
Setting the optional parameter name
allows multiple notifiers to be created. The notifier will bind to the notify.NOTIFIER_NAME
action.
Lambda notify usage
AWS Lambda is a notification platform and thus can be controlled by calling the notify
action as described here. It will invoke a Lambda for all targets given in the notification payload. A target can be formatted as a function name, an entire ARN (Amazon Resource Name
The Lambda event payload will contain everything passed in the action payload. Here is an example payload that would be sent to Lambda:
{
"title": "Test message!",
"target": "arn:aws:lambda:us-east-1:123456789012:function:ProcessKinesisRecords",
"data": {
"test": "okay"
},
"message": "Hello world!"
}
The context will look like this:
{
"custom": {
"two": "three",
"test": "one"
}
}
SNS notify usage
AWS SNS is a notification platform and thus can be controlled by calling the notify
action as described here. It will publish a message to all targets given in the notification payload. A target must be a SNS topic or endpoint ARN (Amazon Resource Name
If one exists, the SNS Subject will be set to the title. All attributes from the payload, except the message, will be sent as stringified message attributes.
Setting up SNS within AWS
- Log into your AWS console and under “Security and Identity”, select “Identity & Access Management”.
- On the left-hand side, select “Users” then click “Create New Users”. Enter a name here and then click “Create”.
- You can either download the credentials or click the arrow to display them one time.
If you do not download them, you will lose them and will have to recreate a new user.
- Copy/Paste the two keys that are shown here in your
configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file. - On the left-hand side of the screen go back to “Users” and select the user you just created. On the “Permissions” tab click the “Attach Policy” icon. Search for “SNS” and attach the policy “AmazonSNSFullAccess”.
- Back to the AWS Console you now need to find “SNS” and click in to that service. It is under the Mobile Services group.
- On the left-hand side, select “Topics” then “Create new topic”.
- Choose a Topic Name and Display Name.
- Now check the box next to the Topic you just created and under Actions, select “Subscribe to topic”.
- In the box that pops up, select the Protocol = SMS and enter in the phone number next to “Endpoint” you wish to SMS. Now click “Create”.
- Repeat for additional numbers.
- Back in the “Users” section you will see a long alphanumeric line that starts with “arn:” and ends with the Topic Name you choose previously. This is what your “target” in Home Assistant will be.
SQS Notify Usage
AWS SQS is a notification platform and thus can be controlled by calling the notify
action as described here. It will publish a message to the queue for all targets given in the notification payload. A target must be a SQS topic URL. For more information, please see the SQS documentation
The SQS event payload will contain everything passed in the action payload. SQS payloads will be published as stringified JSON. All attributes from the payload, except message, will also be sent as stringified message attributes. Here is an example message that would be published to the SQS queue:
{
"title": "Test message!",
"target": "https://sqs.us-east-1.amazonaws.com/123456789012/queue2%22",
"data": {
"test": "okay"
},
"message": "Hello world!"
}
EventBridge Notify Usage
AWS EventBridge is a notification platform and thus can be controlled by calling the notify
action as described here. It will publish a message to the event bus for all targets given in the notification payload. A target must be a name of an event bus accessible by the given credentials. A target is not required, and the default event bus will be used if none are specified. For more information, please see the EventBridge documentation
There are two options for generating the event detail based on the action payload. If the detail
attribute is specified, then its value will be serialized as a JSON object and used for the event detail. If the attribute is not specified, then the value of the message
attribute is serialized as a simple JSON object with a single key named message
and the value of the message supplied to the action.
Here are a couple of examples showing the action input and corresponding API entry:
// Service call payload
{
"message": "Hello world!"
}
// Corresponding Entries
{
"Detail": "{\"message\": \"Hello world!\"}"
"DetailType": "",
"Source": "homeassistant",
"Resources": [],
}
// Service Call Payload:
{
"target": ["eventbus1", "eventbus2"]
"data": {
"detail_type": "test_event":
"detail": {
"key1", "value1",
"key2", "value2"
},
"resources": ["resource1", "resource2"],
"source": "example"
}
}
// Corresponding Entries
[
{
"Detail": "{\"key1\": \"value1\",\"key2\": \"key2\": \"value2\"}"
"DetailType": "test_event",
"EventBusName": "eventbus1",
"Resources": ["resource1", "resource2"],
"Source": "example"
},
{
"Detail": "{\"key1\": \"value1\",\"key2\": \"key2\": \"value2\"}"
"DetailType": "test_event",
"EventBusName": "eventbus2",
"Resources": ["resource1", "resource2"],
"Source": "example"
}
]