2018-06-01 18:10:00 +02:00
|
|
|
Contributing
|
|
|
|
============
|
|
|
|
|
2018-11-14 22:12:27 +01:00
|
|
|
.. seo::
|
2019-02-16 23:25:23 +01:00
|
|
|
:description: Getting started guide for contributing to the ESPHome project
|
2018-11-19 18:32:16 +01:00
|
|
|
:image: github-circle.png
|
2018-11-14 22:12:27 +01:00
|
|
|
|
2019-02-16 23:25:23 +01:00
|
|
|
Contributions to the ESPHome suite are very welcome! All the code for the projects
|
2018-06-01 18:10:00 +02:00
|
|
|
is hosted on GitHub and you can find the sources here:
|
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
- `ESPHome <https://github.com/esphome/ESPHome>`__ (Project Source Code)
|
2019-02-01 21:26:18 +01:00
|
|
|
- `ESPHome-Docs <https://github.com/esphome/ESPHome-Docs>`__ (The documentation which you're reading here)
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2018-10-20 15:10:26 +02:00
|
|
|
Just clone the repository locally, do the changes for your new feature/bug fix and submit
|
2019-05-12 22:44:59 +02:00
|
|
|
a pull request.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-11 18:20:49 +01:00
|
|
|
Contributing to ESPHome-Docs
|
|
|
|
----------------------------
|
|
|
|
|
|
|
|
.. figure:: /images/logo-docs.svg
|
|
|
|
:align: center
|
|
|
|
:width: 60.0%
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-16 23:25:23 +01:00
|
|
|
One of the areas of ESPHome that can always be improved is the documentation.
|
2018-06-01 18:10:00 +02:00
|
|
|
If you see an issue somewhere, or spelling mistakes or if you want to share your awesome
|
|
|
|
setup, please feel free to submit a pull request.
|
|
|
|
|
2019-02-16 23:25:23 +01:00
|
|
|
The ESPHome documentation is built using `sphinx <http://www.sphinx-doc.org/>`__ and uses
|
2018-06-01 18:10:00 +02:00
|
|
|
`reStructuredText <http://docutils.sourceforge.net/rst.html>`__ for all source files.
|
|
|
|
|
2019-02-01 22:27:05 +01:00
|
|
|
Syntax
|
|
|
|
******
|
|
|
|
|
2018-06-01 18:10:00 +02:00
|
|
|
In my opinion, markdown would have been the much better choice in hindsight, but at the time
|
|
|
|
I was setting up the documentation good doxygen integration was key to me. Anyway, here's a quick
|
|
|
|
RST primer:
|
|
|
|
|
|
|
|
- **Headers**: You can write titles like this:
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
My Title
|
|
|
|
========
|
|
|
|
|
2018-10-12 16:33:22 +02:00
|
|
|
and section headers like this:
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2018-10-12 16:33:22 +02:00
|
|
|
My Sub Section
|
|
|
|
--------------
|
|
|
|
|
|
|
|
and sub-section headers like this:
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-10-12 16:33:22 +02:00
|
|
|
|
2019-02-27 10:23:58 +01:00
|
|
|
My Sub-sub Section
|
2018-10-12 16:33:22 +02:00
|
|
|
******************
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-27 10:23:58 +01:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
The length of the bar below the text **must** match the title Text length.
|
|
|
|
Also, titles should be in Title Case
|
|
|
|
|
2018-06-01 18:10:00 +02:00
|
|
|
- **Links**: To create a link to an external resource (for example https://www.google.com), use
|
|
|
|
``\`Link text <link_url>\`__``. For example:
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
`Google.com <https://www.google.com>`__
|
|
|
|
|
|
|
|
`Google.com <https://www.google.com>`__
|
|
|
|
|
|
|
|
- **References**: To reference another document, use the ``:doc:`` and ``:ref:`` roles (references
|
|
|
|
are set up globally and can be used between documents):
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
.. _my-reference-label:
|
|
|
|
|
|
|
|
Section to cross-reference
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
2019-02-07 13:54:45 +01:00
|
|
|
See :ref:`my-reference-label`, also see :doc:`/components/switch/gpio`.
|
|
|
|
:doc:`Using custom text </components/switch/gpio>`.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-07 13:54:45 +01:00
|
|
|
See :ref:`devices`, also see :doc:`/components/switch/gpio`.
|
|
|
|
:doc:`Using custom text </components/switch/gpio>`.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
- **Inline code**: To have text appear ``like this``, use double backticks:
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
To have text appear ``like this``, use double backticks.
|
|
|
|
|
|
|
|
To have text appear ``like this``, use double backticks.
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
- **Code blocks**: To show a sample configuration file, use the ``code-block`` directive:
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: yaml
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
# Sample configuration entry
|
|
|
|
switch:
|
|
|
|
- platform: gpio
|
|
|
|
name: "Relay #42"
|
|
|
|
pin: GPIO13
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: yaml
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-27 18:32:47 +01:00
|
|
|
# Sample configuration entry
|
|
|
|
switch:
|
|
|
|
- platform: gpio
|
|
|
|
name: "Relay #42"
|
|
|
|
pin: GPIO13
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-15 09:30:38 +01:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
Please note the empty line after the ``code-block`` directive. That is necessary.
|
|
|
|
|
2018-06-01 18:10:00 +02:00
|
|
|
- **Images**: To show images, use the ``figure`` directive:
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
.. figure:: images/dashboard.png
|
|
|
|
:align: center
|
|
|
|
:width: 40.0%
|
|
|
|
|
|
|
|
Optional figure caption.
|
|
|
|
|
|
|
|
.. figure:: images/dashboard.png
|
2019-02-27 18:32:47 +01:00
|
|
|
:align: center
|
|
|
|
:width: 40.0%
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-27 18:32:47 +01:00
|
|
|
Optional figure caption.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-15 09:30:38 +01:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
All images in the documentation need to be as small as possible to ensure
|
|
|
|
fast page load times. For normal figures the maximum size should be at most
|
|
|
|
about 1000x800px or so. Additionally, please use online tools like
|
|
|
|
https://tinypng.com/ or https://tinyjpg.com/ to further compress images.
|
|
|
|
|
2018-06-01 18:10:00 +02:00
|
|
|
- **Notes and warnings**: You can create simple notes and warnings using the ``note`` and ``warning``
|
|
|
|
directives:
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
2019-02-27 18:32:47 +01:00
|
|
|
This is a note.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
2019-02-27 18:32:47 +01:00
|
|
|
This is a warning.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
2019-02-27 18:32:47 +01:00
|
|
|
This is a note.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
2019-02-27 18:32:47 +01:00
|
|
|
This is a warning.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
- **Italic and boldface font families**: To *italicize* text, use one asterisk around the text. To put
|
|
|
|
**a strong emphasis** on a piece of text, put two asterisks around it.
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
*This is italicized.* (A weird word...)
|
|
|
|
**This is very important.**
|
|
|
|
|
|
|
|
*This is italicized.* (A weird word...)
|
|
|
|
**This is very important.**
|
|
|
|
|
|
|
|
- **Ordered and unordered list**: The syntax for lists in RST is more or less the same as in markdown:
|
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: rst
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
- Unordered Item
|
|
|
|
|
|
|
|
- Unordered Sub-Item
|
|
|
|
|
|
|
|
- Item with a very long text so that it does not fully fit in a single line and
|
|
|
|
must be split up into multiple lines.
|
|
|
|
|
|
|
|
1. Ordered Item #1
|
|
|
|
2. Ordered Item #2
|
|
|
|
|
|
|
|
- Unordered Item
|
|
|
|
|
|
|
|
- Unordered Sub-Item
|
|
|
|
|
|
|
|
- Item with a very long text so that it does not fully fit in a single line and
|
|
|
|
must be split up into multiple lines.
|
|
|
|
|
|
|
|
1. Ordered Item #1
|
|
|
|
2. Ordered Item #2
|
|
|
|
|
2019-02-27 18:32:47 +01:00
|
|
|
- **imgtable**: ESPHome uses a custom RST directive to show the table on the front page (see
|
|
|
|
`index.rst <https://github.com/esphome/esphome-docs/blob/current/index.rst>`__).
|
2019-02-15 09:30:38 +01:00
|
|
|
New pages need to be added to the ``imgtable`` list. The syntax is CSV with <PAGE NAME>, <FILE NAME> (without RST),
|
|
|
|
<IMAGE> (in top-level images/ directory). The aspect ratio of these images should be 8:10 (or 10:8) but exceptions are possible.
|
|
|
|
|
|
|
|
Because these images are served on the main page, they need to be compressed heavily. SVGs are prefered over JPGs
|
|
|
|
and JPGs should be max. 300x300px.
|
|
|
|
If you have imagemagick installed, you can use this command to convert the thumbnail:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
convert -sampling-factor 4:2:0 -strip -interlace Plane -quality 80% -resize 300x300 in.jpg out.jpg
|
|
|
|
|
2018-06-01 18:10:00 +02:00
|
|
|
reStructured text can do a lot more than this, so if you're looking for a more complete guide
|
|
|
|
please have a look at the `Sphinx reStructuredText Primer <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__.
|
|
|
|
|
2019-02-01 22:27:05 +01:00
|
|
|
Build
|
|
|
|
*****
|
2019-02-27 18:32:47 +01:00
|
|
|
|
2018-10-12 16:33:22 +02:00
|
|
|
.. note::
|
|
|
|
|
2019-02-16 23:33:36 +01:00
|
|
|
The easiest way is to use the `esphome-docs docker image <https://hub.docker.com/r/esphome/esphome-docs/>`__:
|
2019-02-09 14:08:00 +01:00
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: bash
|
2018-10-12 16:33:22 +02:00
|
|
|
|
2019-02-16 23:33:36 +01:00
|
|
|
docker run --rm -v "${PWD}/":/data -p 8000:8000 -it esphome/esphome-docs
|
2019-02-01 22:27:05 +01:00
|
|
|
|
2018-10-12 16:33:22 +02:00
|
|
|
And then go to ``<CONTAINER_IP>:8000`` in your browser.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-01 22:27:05 +01:00
|
|
|
This way, you don't have to install the dependencies to build the documentation.
|
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
To check your documentation changes locally, you first need install sphinx (with **Python 3**).
|
2019-02-01 22:27:05 +01:00
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
# in ESPHome-Docs repo:
|
|
|
|
pip3 install -r requirements.txt
|
|
|
|
|
2018-06-03 12:50:44 +02:00
|
|
|
Then, use the provided Makefile to build the changes and start a simple web server:
|
2018-06-03 11:37:08 +02:00
|
|
|
|
2018-11-19 18:32:16 +01:00
|
|
|
.. code-block:: bash
|
2018-06-03 11:37:08 +02:00
|
|
|
|
2018-06-03 12:50:44 +02:00
|
|
|
# Start web server on port 8000
|
|
|
|
make webserver
|
|
|
|
|
|
|
|
# Updates then happen via:
|
2018-06-03 11:37:08 +02:00
|
|
|
make html
|
|
|
|
|
2019-02-01 22:27:05 +01:00
|
|
|
Notes
|
|
|
|
*****
|
|
|
|
|
2018-06-01 18:10:00 +02:00
|
|
|
Some notes about the docs:
|
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
- Use the english language (duh...)
|
|
|
|
- An image tells a thousand words, please use them wherever possible. But also don't forget to shrink them, for example
|
2018-06-03 12:50:44 +02:00
|
|
|
I often use https://tinypng.com/
|
2019-05-12 22:44:59 +02:00
|
|
|
- Try to use examples as often as possible (also while it's great to use highly accurate,
|
2018-06-01 18:10:00 +02:00
|
|
|
and domain-specific lingo, it should not interfere with new users understanding the content)
|
2019-05-12 22:44:59 +02:00
|
|
|
- Fixes/improvements for the docs themselves should go to the ``current`` branch of the
|
2018-06-04 08:17:22 +02:00
|
|
|
esphomedocs repository. New features should be added against the ``next`` branch.
|
2019-05-12 22:44:59 +02:00
|
|
|
- Always create new branches in your fork for each pull request.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-21 17:44:17 +01:00
|
|
|
Setting Up Development Environment
|
|
|
|
----------------------------------
|
|
|
|
|
|
|
|
For developing new features to ESPHome, you will first need to set up a development environment.
|
|
|
|
This is only possible for ``pip`` installs.
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
# Clone repos
|
|
|
|
git clone https://github.com/esphome/esphome.git
|
|
|
|
git clone https://github.com/esphome/esphome-docs.git
|
|
|
|
|
|
|
|
# Install esphome, python 2!
|
|
|
|
cd esphome/
|
2019-05-12 22:44:59 +02:00
|
|
|
script/setup
|
2019-02-21 17:44:17 +01:00
|
|
|
# Start a new feature branch
|
|
|
|
git checkout -b my-new-feature
|
|
|
|
cd ..
|
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
Now you can open esphome in your IDE of choice (mine is CLion) with the platformio
|
2019-02-21 17:44:17 +01:00
|
|
|
addons (see platformio docs for more info). Then develop the new feature with the
|
|
|
|
guidelines below.
|
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
All PRs are automatically checked for some basic formatting/code mistakes with travis.
|
|
|
|
These checks *must* pass for your PR to be mergable.
|
2019-02-21 17:44:17 +01:00
|
|
|
|
2019-03-11 11:14:22 +01:00
|
|
|
Setting Up Git Environment
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
ESPHome's code-base is hosted on GitHub, and contributing is done exclusively through
|
|
|
|
"Pull Requests" (PRs) in the GitHub interface. So you need to set up your git environment
|
|
|
|
first.
|
|
|
|
|
|
|
|
When you want to create a patch for ESPHome, first go to the repository you want to contribute to
|
2019-05-12 22:44:59 +02:00
|
|
|
(esphome, etc) and click fork in the top right corner. This will create
|
2019-03-11 11:14:22 +01:00
|
|
|
a fork of the repository that you can modify and create git branches on.
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
# Clone your fork
|
|
|
|
git clone https://github.com/<YOUR_GITHUB_USERNAME>/<REPO_NAME>.git
|
2019-05-12 22:44:59 +02:00
|
|
|
# For example: git clone https://github.com/OttoWinter/esphome.git
|
2019-03-11 11:14:22 +01:00
|
|
|
|
|
|
|
# Add "upstream" remote
|
|
|
|
git remote add upstream https://github.com/esphome/<REPO_NAME>.git
|
2019-05-12 22:44:59 +02:00
|
|
|
# For example: git clone https://github.com/esphome/esphome.git
|
2019-03-11 11:14:22 +01:00
|
|
|
|
|
|
|
# For each patch, create a new branch from latest dev
|
|
|
|
git checkout dev
|
|
|
|
git pull upstream dev
|
|
|
|
git checkout -b <MY_NEW_FEATURE>
|
|
|
|
# For example: git checkout -b gpio-switch-fix
|
|
|
|
|
|
|
|
# Make your modifications, then commit changes with message describing changes
|
|
|
|
git add .
|
|
|
|
git commit -m "<COMMIT_MESSAGE>"
|
|
|
|
# For example: git commit -m "Fix GPIO Switch Not Turning Off Interlocked Switches"
|
|
|
|
|
|
|
|
# Upload changes
|
|
|
|
git push -u origin <BRANCH_NAME>
|
|
|
|
# For example: git push -u origin gpio-switch-fix
|
|
|
|
|
|
|
|
Then go to your repository fork in GitHub and wait for a create pull request message to show
|
|
|
|
up in the top (alternatively go to branches and create it from there). Fill out the
|
|
|
|
Pull Request template outlining your changes; if your PR is not ready to merge yet please
|
|
|
|
mark it as a draft PR in the dropdown of the green "create PR" button.
|
|
|
|
|
|
|
|
**Review Process:** ESPHome's code base tries to have a high code standard. At the bottom
|
|
|
|
of the Pull Request you will be able to see the "Travis" continuous integration check which
|
|
|
|
will automatically go through your patch and try to spot errors. If the CI check fails,
|
|
|
|
please see the travis log and fix all errors that appear there. Only PRs that pass the automated
|
|
|
|
checks can be merged!
|
|
|
|
|
|
|
|
**Catching up with reality**: Sometimes other commits have been made to the same files
|
|
|
|
you edited. Then your changes need to be re-applied on top of the latest changes with
|
|
|
|
a "rebase". More info `here <https://developers.home-assistant.io/docs/en/development_catching_up.html>`__.
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
# Fetch the latest upstream changes and apply them
|
|
|
|
git fetch upstream dev
|
|
|
|
git rebase upstream/dev
|
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
Codebase Standards
|
|
|
|
------------------
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-16 23:25:23 +01:00
|
|
|
Standard for the esphome-core codebase:
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
- The C++ code style is based on the
|
|
|
|
`Google C++ Style Guide <https://google.github.io/styleguide/cppguide.html>`__ with a few modifications.
|
|
|
|
|
|
|
|
- function, method and variable names are ``lower_snake_case``
|
|
|
|
- class/struct/enum names should be ``UpperCamelCase``
|
|
|
|
- constants should be ``UPPER_SNAKE_CASE``
|
|
|
|
- fields should be ``protected`` and ``lowe_snake_case_with_trailing_underscore_`` (DO NOT use private)
|
|
|
|
- It's preferred to use long variable/function names over short and non-descriptive ones.
|
|
|
|
- All uses of class members and member functions should be prefixed with
|
|
|
|
``this->`` to distinguish them from global functions in code review.
|
|
|
|
- Use two spaces, not tabs.
|
|
|
|
- Using ``#define`` s is discouraged and should be replaced with constants.
|
|
|
|
- Use ``using type_t = int;`` instead of ``typedef int type_t;``
|
|
|
|
|
|
|
|
- New components should dump their configuration using ``ESP_LOGCONFIG``
|
|
|
|
at startup in ``dump_config()``
|
2018-06-01 18:10:00 +02:00
|
|
|
- The number of external libraries should be kept to a minimum. If the component you're developing has a simple
|
2019-02-16 23:25:23 +01:00
|
|
|
communication interface, please consider implementing the library natively in ESPHome.
|
2018-06-01 18:10:00 +02:00
|
|
|
- Implementations for new devices should contain reference links for the datasheet and other sample
|
|
|
|
implementations.
|
|
|
|
- Please test your changes :)
|
|
|
|
|
2019-02-11 18:20:49 +01:00
|
|
|
Contributing to ESPHome
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
.. figure:: /images/logo-text.svg
|
|
|
|
:align: center
|
|
|
|
:width: 60.0%
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-16 23:25:23 +01:00
|
|
|
ESPHome primarily does two things: It validates the configuration and creates C++ code.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
|
|
|
The configuration validation should always be very strict with validating user input - it's always
|
|
|
|
better to fail quickly if a configuration isn't right than to have the user find out the issue after
|
|
|
|
a few hours of debugging.
|
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
Preferably, the configuration validation messages should explain the exact validation issue
|
2018-06-01 18:10:00 +02:00
|
|
|
and try to suggest a possible fix.
|
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
The C++ code generation engine is 99% syntactic sugar.
|
2018-06-01 18:10:00 +02:00
|
|
|
Have a look around other components and you will hopefully quickly get the gist of how to interact with
|
|
|
|
the code generation engine.
|
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
All python modules have some magic symbols that will automatically be loaded by the ESPHome
|
|
|
|
loader. These are:
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
- ``CONFIG_SCHEMA``: The configuration schema to validate the user config against.
|
|
|
|
- ``to_code``: The function that will be called with the validated configuration and should
|
|
|
|
create the necessary C++ source code.
|
|
|
|
- ``DEPENDENCIES``: Mark the component to depend on other components. If the user hasn't explicitly
|
|
|
|
added these components in their configuration, a validation error will be generated.
|
|
|
|
- ``AUTO_LOAD``: Automatically load an integration if the user hasn't added it manually.
|
|
|
|
- ``MULTI_CONF``: Mark this component to accept an array of configurations.
|
|
|
|
- ``CONFLICTS_WITH``: Mark a list of components as conflicting with this integration. If the user
|
|
|
|
has one of them in the config, a validation error will be generated.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
- ``ESP_PLATFORMS``: Provide a whitelist of ESP types this integration works with.
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
TODO Phases:
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-05-12 22:44:59 +02:00
|
|
|
- Component loading (explain paths, directory structure)
|
|
|
|
- Validation (explain how to validate properly)
|
|
|
|
- Codegen (explain how code can be generated)
|
|
|
|
- Runtime setup phase
|
|
|
|
- Runtime loop/update phase
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-04-15 22:04:37 +02:00
|
|
|
ESPHome via Gitpod
|
|
|
|
******************
|
|
|
|
|
|
|
|
An alternative to a local checkout and build is doing so via `Gitpod <https://www.gitpod.io>`__.
|
|
|
|
ESPHome will be installed for you and the dashboard wizard will run on startup.
|
|
|
|
|
|
|
|
You can also run the steps manually.
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
python setup.py install
|
|
|
|
|
|
|
|
To start a command line wizard, run
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
python esphome my_configuration.yaml wizard
|
|
|
|
|
|
|
|
To get the web-based dashboard, use
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
python esphome my_configuration.yaml dashboard
|
|
|
|
|
|
|
|
and allow exposing the web app at port 6052.
|
|
|
|
|
2018-06-01 18:10:00 +02:00
|
|
|
See Also
|
2018-10-12 16:33:22 +02:00
|
|
|
--------
|
2018-06-01 18:10:00 +02:00
|
|
|
|
2019-02-07 13:54:45 +01:00
|
|
|
- :doc:`ESPHome index </index>`
|
2018-06-01 18:10:00 +02:00
|
|
|
- :doc:`faq`
|
2019-02-07 13:54:45 +01:00
|
|
|
- :ghedit:`Edit`
|