User Guide¶
This is the user guide for the Home Assistant Custom Component Cookiecutter, a Python template for Home Assistant based on the Integration Blueprint repository.
If you’re in a hurry, check out the quickstart guide.
Introduction¶
In progress
About this project¶
Features¶
Here is a detailed list of features for this Python template:
Ready to use Home Assistant custom component
UI configuration with config Flow
Translations
Development, testing and step by step debugging in Visual Studio Code development container
HACS ready
Continuous integration with GitHub Actions
Settings for pre-commit
Optional tests suite with pytest and code coverage
You can find a repository created with this cookiecutter template in the cookiecutter-homeassistant-custom-component-instance example.
Release cadence¶
In progress
Installation¶
In progress
Project creation¶
In progress
Project overview¶
This repository contains multiple files, here is a overview:
|
Used for development/testing with VSCODE, more info in the readme file in that dir |
|
Template for Feature Requests |
|
Template for issues |
|
Probot settings to control the repository settings. |
|
Tasks for the devcontainer |
|
|
|
The component file for the integration |
|
This is a sample API client |
|
Binary sensor platform for the integration |
|
Config flow file, this adds the UI configuration possibilities |
|
A file to hold shared variables/constants for the entire integration |
|
A manifest file for Home Assistant |
|
Sensor platform for the integration |
|
Switch sensor platform for the integration |
|
Makes the tests folder a Python package |
|
|
|
Tests for custom_components/[DOMAIN NAME]/api.py |
|
Tests for custom_components/[DOMAIN NAME]/config_flow.py |
|
Tests for custom_components/[DOMAIN NAME]/__init__.py |
|
Tests for custom_components/[DOMAIN NAME]/switch.py |
|
Guidelines on how to contribute |
|
Screenshot that demonstrate how it might look in the UI |
|
An example on a info file (used by HACS) |
|
The license file for the project |
|
The file you are reading now, should contain info about the integration, installation and configuration instructions |
|
Python packages used to provide IntelliSense/code hints during development of this integration, typically includes packages in |
|
Python packages required to run the tests for this integration, typically includes packages in |
If you want to use all the potential and features of this blueprint template you
should use Visual Studio Code to develop in a container. In this container you
will have all the tools to ease your python development and a dedicated Home
Assistant core instance to run your integration. See .devcontainer/README.md
for more information.
If you need to work on a Python library in parallel of this integration, there are different options. The following one seems easy to implement:
Create a dedicated branch for your python library on a public git repository (example: branch dev)
Update in the
manifest.json
file therequirements
key to point on your development branch ( example:"requirements": ["git+https://github.com/ludeeus/sampleclient.git@dev#devp==0.0.1beta1"]
)Each time you need to make a modification to your Python library, push it to your development branch and increase the number of the Python library version in
manifest.json
file to ensure Home Assistant update the code of the python library. (example"requirements": ["git+https://...==0.0.1beta2"]
).
Developing in Visual Studio Code with a development container¶
The easiest way to get started with custom integration development is to use Visual Studio Code with development containers. This approach will create a preconfigured development environment with all the tools you need.
In the container you will have a dedicated Home Assistant core instance running with your custom component code.
You can configure this instance by updating the ./devcontainer/configuration.yaml
file.
Prerequisites¶
git installed
Docker - For Linux, macOS, or Windows 10 Pro/Enterprise/Education use the current release version of Docker - Windows 10 Home requires WSL 2 and the current Edge version of Docker Desktop (see instructions here). This can also be used for Windows Pro/Enterprise/Education.
Getting started¶
Clone the repository to your computer.
Open the repository using Visual Studio code.
When you open this repository with Visual Studio code you are asked to “Reopen in Container”, this will start the build of the container.
If you don’t see this notification, open the command palette and select ``Remote-Containers: Reopen Folder in Container``.
Tasks¶
The devcontainer comes with some useful tasks to help you with development.
You can start these tasks by opening the command palette
and select Tasks: Run Task
then select the one you want to run.
When a task is currently running, it can be restarted by opening the command palette
and selecting Tasks: Restart Running Task
, then select the task you want to restart.
The available tasks are:
Task |
Description |
---|---|
Run Home Assistant on port 9123 |
Launch Home Assistant with your custom component code and the configuration defined in |
Run Home Assistant configuration against /config |
Check the configuration. |
Upgrade Home Assistant to latest dev |
Upgrade the Home Assistant core version in the container to the latest version of the |
Install a specific version of Home Assistant |
Install a specific version of Home Assistant core in the container. |
Step by Step debugging¶
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.
Linting¶
In progress
GitHub Actions Workflows¶
In progress
Add a logo¶
In progress
Deploy on HACS¶
In progress