Skip to main content

Building from Source

Kamoji firmware builds with the standard ESPHome toolchain against one of the YAML configuration files described in the configuration files — for example:

esphome run kamoji-r7-production.yaml
Pin ESPHome to 2026.3.x

Kamoji's YAML only compiles against ESPHome 2026.3.x. Newer ESPHome releases throw syntax errors and won't compile it — the YAML hasn't been updated for changes in later ESPHome versions yet. Pin your esphome install to a 2026.3.x release before building. This is being worked on; until it's resolved, using a newer ESPHome version is not a supported path.

Source code​

All of Kamoji's YAML configuration and custom ESPHome components are open source, in the public GitLab repo kamoji-esphome. This is the same source the production firmware is built from — the top-level kamoji-core.yaml / kamoji-r7-production.yaml / kamoji-r8-production.yaml files described in Configuration files, plus all components under custom components/ folder.

Using your own ESPHome instance​

If you're running ESPHome yourself (CLI, Home Assistant add-on, or otherwise) rather than using this repo directly, there are two ways to pull in Kamoji's custom components:

  1. Copy the kamoji-xxxxx.yaml file you want to build (e.g. kamoji-r7-production.yaml) into your own ESPHome config folder.

  2. Then make the custom components available to it, either:

    • Copy the components in, or
    • Reference the GitLab repo directly

Option A: copy the components folder​

Copy the entire components/ folder from kamoji-esphome into your ESPHome config folder, alongside the YAML file. This matches how the repo is laid out already, so nothing else needs to change — kamoji-core.yaml's external_components: section already points at a local components path.

Option B: reference the GitLab repo directly​

Instead of copying files locally, point ESPHome at the GitLab repo and let it fetch the components remotely. This means changing the external_components: section in kamoji-core.yaml that currently reads from the local components/ folder:

# Load custom components from the GitLab repo instead of a local folder
external_components:
  - source:
      type: git
      url: https://gitlab.com/originallyus/kamoji-esphome
      ref: main
    refresh: 1d

ref can be a branch, tag, or commit — pin it to a known-good commit if you want reproducible builds instead of always tracking main. refresh controls how often ESPHome re-fetches the repo (refresh: 0s forces a fetch on every build, useful while actively tracking upstream changes).