Quickstart

Prerequisites

Homeassistant

Before using this library, you need to have Home Assistant running on a device. Something like a Raspberry Pi 3 or 4 or spare laptop. If you don’t want to do that you can setup a Home Assistant container on your laptop or desktop with docker. See here for how to install the installation right for you.

Configuring the REST API Server in Homeassistant

Enable the `api` integration in Homeassistant

This library requires that the api integration on your Home Assistant is enabled. It is enabled by default with the default_config integration. But if by chance you have disabled default_config you need to enable api. Which requires the http integration as well. (Again most likely already enabled on most installations of Home Assistant.) If you are not sure if it is enabled or not, chances are if your frontend is enabled, so is your API Server.

Access Token

Then once you have done that you need to head over to your profile and set up a “Long Lived Access Token” to use in your code later. A good guide on how to do that is here Also if you are building a website and want to integrate Home Assistant you can use a refresh token instead. See their Authentication API docs for more information. Every time you refresh your token you will need to update the Client.token attribute of your Client instance.

Exposing Home Assistant to the Web

You may want to setup remote access through a Dynamic DNS server like DuckDNS (a good youtube tutorial on how to do that here, keep in mind you will need to port forward to set that up.) If you do pursue this your API URL will be something like https://yourhomeassistant.duckdns.org:8123/api. Which is different than what it could have looked like before. Which might have been something like http://homeassistant.local:8123/api or http://localhost:8123/api

Installation

Installing with `pip`

Installation with pip is really easy and will install the dependencies this project needs.

# To install the latest stable version from PyPI
$ pip install homeassistant_api

# To install the latest dev version (you'll need to use poetry because pip, by itself, does not understand poetry dependencies.)
$ poetry add git+https://github.com/GrandMoff100/HomeassistantAPI

Installing with `git`

To install with git we’re going to clone the repository and then run $ poetry install like so.

# Clone with git
git clone https://github.com/GrandMoff100/HomeassistantAPI

# CD into your project
cd <path/to/my/awesome/homeassistant/project>

# Install poetry
python -m pip install poetry

# Run poetry install
python -m poetry install ~/HomeAssistantAPI

Then you should be all set to start using the library! If run into any problems open an issue on our github issue tracker

Example Usages

Some examples applications of this project include integrating it into a another library, flask application or just a regular python script. Maybe you want to start a project that allows you to use your Home Assistant from your command line but some sassy responses. Or maybe add it to a discord bot to manage your Home Assistant from inside discord. In any event, the possibilities are endless, so go make some cool stuff and share it with us on the repository! We hope to see your project soon!