diff --git a/README.md b/README.md index dacd18e..97883cd 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ All sample components can be found in the `custom_components` directory. The `te - Create a `custom_components` directory in your esphome configuration directory (the directory where your ```.yaml``` files are) -- Copy the directory of the empty component to `custom_components` in its entirety, so you end up with e.g. `custom_components/empty_sensor/` +- Copy the directory of an empty component to `custom_components` in its entirety, so you end up with e.g. `custom_components/empty_sensor/` - Find the configuration entry for the empty component in `test_empty.yaml` and copy it into your own `.yaml` file. @@ -16,3 +16,41 @@ All sample components can be found in the `custom_components` directory. The `te - No errors? Great! You can now start modifying the empty component into your own custom component. +## Basic structure of a custom component + +Let's start with the simplest custom component: + +``` +custom_components +├── empty_component +│ ├── __init.py__ +│ ├── empty_component.cpp +│ ├── empty_component.h +│ ... +``` + +The ```__init.py__``` file contains 2 main things: +- **configuration validation** or **cv** +- **code generation** or **cg** + +**cv** handles validation of user input in the `.yaml` configuration file for this particular component: defining the available configuration options, whether they are _required_ or _optional_, any constraints on the types and values of an option, etc. + +**cg** takes these validated configuration options and generates the code necessary to streamline them into your c++ code, as well as registering your component properly within the ESPHome runtime. + +The ```.cpp``` and ```.h``` files are the main source code files for your component. You're free to add to or modify the structure of the source code within the constraints of `c++`, but your code needs at least one `class` derived from `Component` that will be registered in the `__init__.py`. + +If your component yields a specific type of component, e.g. a `sensor` or a `switch`, ESPHome will instead look for a `sensor.py` or `switch.py`. +The structure of these is identical to that of `__init__.py`. + +See for example: + +``` +custom_components +├── empty_binary_sensor +│ ├── binary_sensor.py +│ ├── empty_binary_sensor.cpp +│ ├── empty_binary_sensor.h +│ ... +``` + +There is no `__init__.py` here, instead we have a `binary_sensor.py`.