Attention

This is the documentation stub to the upcoming TBD V2 release.

It is incomplete and subject to future changes.

Overview

This section goes into depth on how the TBD firmware is built and client libraries are generated. The information provided here is not relevant to ordinary contributors or developers. It is only intended for those wishing to extend the build system or implement custom sub-systems that require advanced code generation/analysis mechanics.

Build System Fundamentals

The TBD firmware is based on ESPHome, therefore all TBD Components are also ESPHome components, albeit quite often bypassing the ESPHome mindset. One of TBD’s core requirement is the ability to perform a multi-staged code/analysis and generation process, where components can utilize global registries to register specific features for later processing once all components have been collected and the core build initialization stage has completed.

On Components

Since TBD components are ESPHome components, the following core mechanics work just as any ESPHome build:

  • the esphome CLI or docker image can be used to build the firmware with no other prerequisites installed on the system.

  • a device firmware is described in a some-device.yaml esphome YAML spec

  • top level entries in the YAML dictionary are considered to be components

  • component search paths are the ESPHome defaults (components from the esphome repo and external paths specified in YAML using external components mechanism)

  • components are organised as folders, that contain both a python module (must contain a __init__.py) and C++ sources

  • root level files in a component will be copied to the build source directory

  • components need can provide ESPHome specific variables such as DEPENDENCIES, AUTO_LOAD, CONFIG_SCHEMA and a setup function to_code as well as ESPHome actions etc.

  • python helpers and additional setup functions etc can be imported via esphome.components.<component-name>

TBD adds many mechanism to these mechanics once the tbd_module component has been loaded. The most important part of any TBD firmware description YAML is adding the path of the TBD repo (URL or path to cloned copy) as an external component search paths and adding tbd_module to the list of modules in the YAML:

external_components:
  - source: <path-to-tbd>

tbd_module:

This will add additional module search paths to the ESPHome build and setup python import paths.

  • all the subdirectories of <tbd-repo>/components/<subdir> as component search paths

  • the tbd_core python module becomes globally available