When deep diving more and more into vRA / vRO and learning about the REST API functionalities, I just had to test it! The question was, with what? Well, how about Home Assistant?
Current setup
My home is automated with Home Assistant. I’m currently running it on a Raspberry Pi with an AEOTEC ZWAVE USB Stick and Hassio to control the devices. It’s an Open Source solution and you don’t need much to get it up and running.
Feel free to find out more here: https://www.home-assistant.io/hassio/
My (borrowed 😉 ) VMware lab has vRealize Automation 7.4 HF11 running combined with the embedded vRO instance.
In short:
- Home Automation: Home Assistant – version 0.91.1
- vRealize Automation 7.4 with embedded vRO
What do you need?
- Home Assistant API URL (e.g.: https://hassio.local:8123/api)
- Home Assistant ‘Long-Lived Access Token‘ so you can authorize vRO to talk to Home Assistant’s API
- vRO HTTP REST host (adding your Home Assistant instance)
- vRO HTTP REST Operations (adding some API calls like ‘turn on / off light’)
- Some vRO workflows which call your vRO REST Operations
- vRA XaaS blueprints using these vRO Workflows so you can order it from the catalog
Let’s make vRO talk to Home Assistant!
REST API!
The Home Assistant RESTful API is pretty well documented, I’ll walk you through the setup. But be aware, it’s a journey…
Home Assistant’s API is reachable through the following link: https:// < your_home_assistant_hostname_or_ip >:<the_port_you_configured>/api
1. Gathering your API details
This is pretty simple, just note down the link you use to reach your Home Assistant instance and put /api behind it.
https://hassio.local:8123/api
If you’re not sure about your link, just open your ‘configuration.yaml’ file from your Home Assistant instance and locate the line stating ‘base_url:’ and add /api to it.
2. Home Assistant – Long-Lived Access Token
Logon to your Home Assistant instance and generate a ‘Long-Lived Access Token’. This token will be used in the Headers of the REST API calls to authorize vRO to access Home Assistant’s API.
Browse to your Home Assistant instance /profile , scroll all the way down until you reach ‘Long-Lived Access Tokens’ and generate a new one. Make sure to copy it!
Example URL: https://hassio.local:8123/profile
You’re all set on Home Assistant side! Want to test if your API calls are working? Use simple curl commands to test it out:
curl -X GET -H "Authorization: Bearer <your_long_HA_lived_access_token>" -H "Content-Type: application/json" https://<YOUR_HA_INSTANCE:8123>/api/services
With this command you request all the services from your Home Assistant instance. It’s just a GET command, we’re not setting anything here.
3. vRO – Adding a HTTP-REST Host
Let’s go to vRO and add a HTTP-REST host.
Go to Library – HTTP-REST – Configuration – Add a REST host and run the workflow.
Fill in the details and adjust them to your environment as shown below:
We will not be using any authentication mechanism here, our authorization will happen by adding the Long-Lived Access Token to the Headers of our REST API calls.
Run the workflow & wait for the workflow to complete.
Result:
If you go to the Inventory tab in vRO and expand HTTP-REST you should see your Home Assistant instance listed there.
4. vRO – Adding a HTTP-REST Operation to control your lights!
Now we will be adding some operations for our HTTP-REST Host in order to perform certain actions on it. Meaning we will be adding some GET & POST actions to execute against our Home Assistant instance.
Reading the Home Assistant API pages, you’ll find out that in order to turn_on / off switches, we’ll be needing the following information:
Headers:
"Authorization: Bearer <YOUR_LONG_LIVED_ACCESS_TOKEN_HERE>"
API Full URL:
https://<YOUR_HA_INSTANCE:8123>/api/services/switch/turn_off AND https://<YOUR_HA_INSTANCE:8123>/api/services/switch/turn_on
Only the part highlighted in bold is needed for the vRO HTTP-REST Operation.
HTTP Method:
POST
Content-Type:
application/json
Content:
{"entity_id": "<YOUR_ENTITY_ID_Here>"}
e.g.:{"entity_id": "switch.bureau_light_switch"}
In order to add a REST Operation to vRO we will only be needing the API URL, HTTP Method & the Content-Type in our case. However the other information listed above will be used by our vRO workflows calling this HTTP REST Operation.
To configure a HTTP-REST Operation in vRO browse to Library – HTTP-REST – Configuration – Add a REST operation and run the workflow
Workflow details:
Note that the ‘Template URL’ setting is only the part that comes after your Home Assistant HTTP-REST Host URL in vRO.
Submit the workflow and wait for it to finish. Repeat for the other REST Operation / Action (turn_off or turn_on in this case).
Result:
If you go to the Inventory tab in vRO and expand HTTP-REST you should see your Home Assistant instance listed with the REST Operations we just added.
5. Add a Configuration Element to vRO containing your Long-Lived Access Token
Head over to the Configurations tab in vRO, create a new configuration element in the folder you want, add an ‘Authorization‘ attribute with the Long-Lived Access Token as SecureString. For example:
6. Download & Import vRO workflows
Download & import the following vRO workflows:
Make sure to remove the ‘.doc’ extension in order to use it in vRO.
7. Point the attributes to the correct values
In the ‘vRA4U – Invoke a REST operation‘ workflow point the ‘HomeAutomationAttributes‘ attribute to your Configuration Element you’ve created in Step 5.
In the ‘vRA4U – Turn_On_Light’ workflow, point the ‘restOperation‘ attribute to the ‘Turn Light On’ REST Operation we’ve created in Step 4. Go to the ‘schema‘ tab, click on the ‘vRA4U – Invoke REST Operation‘ workflow and verify that the workflow can be found. If not, select ‘change workflow’ at the bottom of your screen and search for the ‘vRA4U – Invoke REST Operation’ workflow. Make sure the parameters are synchronized afterwards 🙂
In the ‘Presentation‘ tab of the ‘vRA4U – Turn_On_Light‘ workflow, you can adjust the values of the ‘lightBulb‘ Input Parameter to represent the entities of your lights in Home Assistant.
E.g.:
- Dropdown list with the entity_ids of your lights (switch.bureau_light_switch)
Your Entity_IDs can be found in Home Assistant’s UI or via a REST API call from vRO for example. This REST CALL can be coupled to an vRO Action which you can call to populate the Dropdown list of this Input Parameter.
You can repeat these steps for adding more workflows providing different operations / actions against your Home Assistant instance.
8. vRO – How does it all come together?
The ‘vRA4U – Turn_On_Light’ workflow will ask you for the Entity_ID of the lightbulb / switch you want to power on. In the first scriptable task ‘Set REST Parameters‘ it will add your lightbulb to the content in a JSON String format. This content variable is then being passed to the ‘vRA4U – Invoke a REST Operation‘ workflow which executes the ‘Turn Light On‘ REST Operation against your Home Assistant Instance with the given content (your entity_id) and the headers which you stored in the Configuration Element. 🙂
Run it in vRO to test it out! Make sure to perform the necessary modifications to adapt it to your situation.
Let’s publish it in vRA!
Now in vRA go ahead and create an XaaS blueprint! Assign it to the correct service, modify the icon to your likings, make sure it is entitled and… control your home!
vra4u.com 