project overhaul: introduce kegboard v4, an esp32 + esphome based device

.clang-format

@@ -0,0 +1,137 @@
+Language:        Cpp
+AccessModifierOffset: -1
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: DontAlign
+AlignOperands:   true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: MultiLine
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+  AfterClass:      false
+  AfterControlStatement: false
+  AfterEnum:       false
+  AfterFunction:   false
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     false
+  AfterUnion:      false
+  AfterExternBlock: false
+  BeforeCatch:     false
+  BeforeElse:      false
+  IndentBraces:    false
+  SplitEmptyFunction: true
+  SplitEmptyRecord: true
+  SplitEmptyNamespace: true
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Attach
+BreakBeforeInheritanceComma: false
+BreakInheritanceList: BeforeColon
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+BreakConstructorInitializers: BeforeColon
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: true
+ColumnLimit:     120
+CommentPragmas:  '^ IWYU pragma:'
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+IncludeBlocks:   Preserve
+IncludeCategories:
+  - Regex:           '^<ext/.*\.h>'
+    Priority:        2
+  - Regex:           '^<.*\.h>'
+    Priority:        1
+  - Regex:           '^<.*'
+    Priority:        2
+  - Regex:           '.*'
+    Priority:        3
+IncludeIsMainRegex: '([-_](test|unittest))?$'
+IndentCaseLabels: true
+IndentPPDirectives: None
+IndentWidth:     2
+IndentWrappedFunctionNames: false
+KeepEmptyLinesAtTheStartOfBlocks: false
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+PenaltyBreakAssignment: 2
+PenaltyBreakBeforeFirstCallParameter: 1
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyBreakTemplateDeclaration: 10
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 2000
+PointerAlignment: Right
+RawStringFormats:
+  - Language:        Cpp
+    Delimiters:
+      - cc
+      - CC
+      - cpp
+      - Cpp
+      - CPP
+      - 'c++'
+      - 'C++'
+    CanonicalDelimiter: ''
+    BasedOnStyle:    google
+  - Language:        TextProto
+    Delimiters:
+      - pb
+      - PB
+      - proto
+      - PROTO
+    EnclosingFunctions:
+      - EqualsProto
+      - EquivToProto
+      - PARSE_PARTIAL_TEXT_PROTO
+      - PARSE_TEST_PROTO
+      - PARSE_TEXT_PROTO
+      - ParseTextOrDie
+      - ParseTextProtoOrDie
+    CanonicalDelimiter: ''
+    BasedOnStyle:    google
+ReflowComments:  true
+SortIncludes:    false
+SortUsingDeclarations: false
+SpaceAfterCStyleCast: true
+SpaceAfterTemplateKeyword: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 2
+SpacesInAngles:  false
+SpacesInContainerLiterals: false
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard:        Auto
+TabWidth:        2
+UseTab:          Never

.github/workflows/ci.yaml

@@ -0,0 +1,136 @@
+---
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Pinned deliberately. ESPHome makes breaking changes to its external
+  # component API on a regular cadence, so contributors should not have a
+  # release land on them mid-PR. The nightly job in dev.yaml tracks upstream.
+  ESPHOME_VERSION: "2026.6.5"
+
+jobs:
+  core-tests:
+    name: Core unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Check core purity
+        run: python3 script/check-core-purity.py
+
+      - name: Run tests
+        run: make -C tests/core STRICT=1
+
+      - name: Install jsonschema
+        run: pip install jsonschema
+
+      # The firmware's serialized output must validate against the normative
+      # protocol schemas, and the schema files must match the doc appendices.
+      - name: Check protocol schema conformance
+        run: python3 script/check-events-schema.py
+
+  lint:
+    name: Lint and format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - uses: pre-commit/action@v3.0.1
+
+  host-compile:
+    name: Host smoke compile
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install ESPHome
+        run: pip install "esphome==${ESPHOME_VERSION}"
+
+      # Compiles the components natively with the system compiler: a full
+      # type-check of the C++ in seconds, no ESP toolchain download. The ESP32
+      # matrix below still proves the real targets.
+      - name: Compile host smoke test
+        run: esphome compile tests/host/smoke.yaml
+
+  config:
+    name: Validate configs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install ESPHome
+        run: pip install "esphome==${ESPHOME_VERSION}"
+
+      - name: Provide dummy secrets
+        run: cp examples/secrets.yaml.example examples/secrets.yaml
+
+      - name: Validate
+        run: |
+          for config in examples/*.yaml; do
+            case "$config" in *secrets*) continue;; esac
+            echo "::group::$config"
+            esphome config "$config"
+            echo "::endgroup::"
+          done
+
+  compile:
+    name: Compile ${{ matrix.board }}
+    runs-on: ubuntu-latest
+    needs: [core-tests, config, host-compile]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - board: esp32-s3-devkitc-1
+            config: examples/kegbot-2tap.yaml
+          - board: esp32-devkit
+            config: examples/home-assistant-2tap.yaml
+          # Widest surface: relays, buzzer, LEDs, rfid, ibutton, and auth.
+          - board: esp32-s3-full
+            config: examples/kegbot-full.yaml
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Cache PlatformIO and ESP-IDF toolchains
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.platformio
+            ~/.espressif
+          key: pio-${{ matrix.board }}-${{ env.ESPHOME_VERSION }}-${{ hashFiles('boards/*.yaml') }}
+          restore-keys: |
+            pio-${{ matrix.board }}-${{ env.ESPHOME_VERSION }}-
+
+      - name: Install ESPHome
+        run: pip install "esphome==${ESPHOME_VERSION}"
+
+      - name: Provide dummy secrets
+        run: cp examples/secrets.yaml.example examples/secrets.yaml
+
+      - name: Compile
+        run: esphome compile ${{ matrix.config }}

.github/workflows/esphome-dev.yaml

@@ -0,0 +1,35 @@
+---
+# Tracks ESPHome's dev branch so their breaking changes surface here as a
+# failing scheduled build rather than as a user bug report weeks later.
+#
+# This job is expected to break occasionally. It does not gate PRs.
+name: ESPHome dev
+
+on:
+  schedule:
+    # Weekly, Monday early UTC.
+    - cron: "0 5 * * 1"
+  workflow_dispatch:
+
+jobs:
+  compile-against-dev:
+    name: Compile against ESPHome dev
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install ESPHome from dev
+        run: pip install git+https://github.com/esphome/esphome.git@dev
+
+      - name: Report version under test
+        run: esphome version
+
+      - name: Provide dummy secrets
+        run: cp examples/secrets.yaml.example examples/secrets.yaml
+
+      - name: Compile
+        run: esphome compile examples/kegbot-full.yaml

.gitignore

@@ -1,13 +1,19 @@
-### global stuff
-*.DS_Store
+# Python / tooling
+.venv/
+__pycache__/
 *.pyc
-*.egg
-*.o
-*.hex
 
-python/dist/*
-python/distribute-*
-python/*egg-info
+# ESPHome build output
+.esphome/
+secrets.yaml
 
-arduino/kegboard/.dep
-arduino/kegboard/.lib
+# Host test build output
+tests/core/build/
+
+# Sphinx build output
+docs/_build/
+
+# Editors / OS
+.DS_Store
+compile_commands.json
+uv.lock

.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+---
+# Formatting and lint hooks. Install with: pre-commit install
+#
+# The C++ and Python conventions here deliberately mirror ESPHome's own, since
+# our components are compiled into their tree and most contributors will be
+# coming from that codebase. clang-format is pinned to the same v13 they pin.
+repos:
+  - repo: https://github.com/pre-commit/mirrors-clang-format
+    rev: v13.0.1
+    hooks:
+      - id: clang-format
+        types_or: [c, c++]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.1
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/adrienverge/yamllint.git
+    rev: v1.37.1
+    hooks:
+      - id: yamllint
+        exclude: ^\.clang-format$
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Install the docs toolchain with uv from docs/uv.lock and build with
+# sphinx. docs/ is a self-contained uv project; the firmware repo itself
+# contains nothing to install.
+build:
+  os: ubuntu-24.04
+  tools:
+    python: '3.13'
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv sync --project docs --frozen
+    - uv run --project docs --no-sync sphinx-build -T -b html docs $READTHEDOCS_OUTPUT/html