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="2020.11.16"

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

Step by step debugging

Step by step debugging is easy with Visual Studio Code. You have to install in Home Assistant the PTVSD integration and follow the documentation instructions to setup VSC. Then you will be able to connect the VSC debuger to the local Home Assistant instance.

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.

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.