homeassistant.adoc 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172
  1. [#hass]
  2. = Home Assistant (REST)
  3. [NOTE]
  4. The recommended way to integrate HomeAssistant and OliveTin is via the xref:integrations/homeassistant-integration.adoc[HACS integration].
  5. Home Assistant is able to call REST API endpoints, making integration with OliveTin possible without any custom plugins or integrations in Home Assistant. This does require modifying your Home Assistant configuration.yml file though.
  6. == Give you actions an ID
  7. First, you need to give your actions an ID. This is done by adding an `id` field to your action. This ID will be used by Home Assistant to call the correct action. Here is an example of an action with an ID:
  8. [source, yaml]
  9. ----
  10. actions:
  11. - id: "server_sleep"
  12. title: "Server Sleep"
  13. icon: ping
  14. shell: ssh user@server "sudo systemctl suspend"
  15. ----
  16. You then need to know the URL to call to trigger this action. This is the OliveTin API URL plus the method name, and the action is selected in a JSON body. For example, if your OliveTin is running at `http://yourserver:1337`, you would `POST` `{"bindingId": "server_sleep"}` to `http://yourserver:1337/api/StartAction`. (For a normal action, the `bindingId` is the same as the action `id`.)
  17. You can learn more about starting actions via the OliveTin API by reading the link xref:api/start_action.adoc[Starting Actions via the API] page, but the method "StartAction" is the one you will want to use for Home Assistant. It returns as soon as the action has started.
  18. [NOTE]
  19. ====
  20. Avoid `StartActionAndWait` for Home Assistant unless you need the action's output:
  21. * It only responds once the action has finished, and Home Assistant's `rest_command` gives up after 10 seconds by default, so longer actions are reported as failed even though they ran.
  22. * It checks that the caller can view the action's logs *after* the action has run. Without the `logs` permission, Home Assistant gets an error even though the action ran, and retrying runs it again.
  23. ====
  24. == Add the REST API call to Home Assistant
  25. Now that you have the URL to call to trigger your action, you can add this to your Home Assistant configuration. This is done by adding a `rest_command` to your configuration.yml file.
  26. * link:https://www.home-assistant.io/docs/configuration/[Home Assistant Configuration]
  27. That page assumes you will use the Home Assistant File Editor addon to edit your configuration.yaml. Install it from the Home Assistant addon store if you have not done so already;
  28. image::integrations/hass/hassFileEditor.png[]
  29. The addon is started and added to the sidebar;
  30. image::integrations/hass/hassFileEditorConfig.png[]
  31. Here is an example of a `rest_command` that calls the action above:
  32. From the file editor now in your sidebar, browse the filesystem to the configuration.yaml file and add the following to the file:
  33. [source, yaml]
  34. ----
  35. rest_command:
  36. olivetin_sleep_mindstorm:
  37. url: http://olivetin.example.com:1337/api/StartAction
  38. method: post
  39. content_type: "application/json"
  40. payload: '{"bindingId": "server_sleep"}'
  41. ----
  42. You save the file, and restart Home Assistant to pick up the changes.
  43. == Add a button to your HASS Dashboard
  44. Now that you have a `rest_command` set up to call your action, you can add a button to your Home Assistant dashboard to trigger the action. This is done by adding a `button` to your dashboard configuration.
  45. image::integrations/hass/hassButtonSetup.png[]
  46. Set the "Tap Action" to "Call Service" and select the `rest_command` you created earlier. You can also set the icon and name of the button to whatever you like.
  47. Good luck!