Quickstart Guide

Requirements

Install Cookiecutter:

$ pipx install cookiecutter

pipx is preferred, but you can also install with pip install --user.

It is recommended to set up Python 3.7, 3.8, or 3.9 using pyenv.

Creating a project

Generate a Home Assistant custom component project by using the following command:

$ cookiecutter gh:oncleben31/cookiecutter-homeassistant-custom-component --checkout=2021.1.1

Follow the instructions to customize the generated project

Setting

Definition

friendly_name

Integration name used in configuration UI.

project_name

Project name on GitHub.

domain_name

Integration domain name

class_name_prefix

Prefix to be use in classes name

github_user

GitHub user hosting the repository

version

Initial version of the component

Change to the root directory of your new project, and create a Git repository:

$ git init
$ git add .
$ git commit

Setup the development container

The development container allows to work in a local and dedicated Home Assitant instance to test your custom component. To launch it you need to have already installed Docker, Visual Studio Code (VSC) and the Visual Studio Code Remote - Containers extension.

Open your local copy of the repository with VSC:

$ code .

Visual Studio Code starts and you are asked to “Reopen in Container”, this will start the build of the container.

When done, you can launch the local instance of Home Assistant by running the task Run Home Assistant on port 9123.

Use your preferred browser to open the URL http://localhost:9123.

Initalize your Home Assistant local instance by following the onboarding workflow.

When setup, you can go to Configuration -> Integrations menu, clic the + button and search the name you have given to the custom component.

Follow the config flow of the custom component to integrate it in Home Assistant.

Now you are all set to modify the code and develop your ideas !

Advanced usages

Deploy with HACS

HACS is the community store. You can ease the installation of your custom component by making it compatible with HACS.

The template have already the tools do do that: hacs.json and info.md files. The Publish documentation explains how to set those files and the different options you have to integrate your custom component in the HACS network.

Step by step debugging

If you choose to use Visual Studio Code with the development container, you can test your custom component in Home Assistant with step by step debugging.

You need to modify the configuration.yaml file in .devcontainer folder by uncommenting the line:

# debugpy:

Then launch the task Run Home Assistant on port 9123, and launch the debbuger with the existing debugging configuration Python: Attach Local.

For more information, look at the Remote Python Debugger integration documentation.

Known limitations

  • If you plan to host the generated repository in a GitHub organization you will need manual modifications.

    Currently the template work well when the repostory is hosted in a GitHub individual account, where URL name and code owner are the same. If you want to use an organization, it is recommended to use the name of this organization for github_user settings and modify manually where it’s needed afer generation with Cookiecutter.