First commit

.gitignore

@@ -0,0 +1,18 @@
+# Secrets — never commit Wi-Fi / API / OTA credentials
+secrets.yaml
+
+# ESPHome build cache & artifacts
+.esphome/
+*.bin
+
+# Demo recordings (host README/wiki videos via GitHub attachments, not in-repo)
+*.mp4
+
+# Python
+__pycache__/
+*.pyc
+
+# OS junk
+.DS_Store
+Thumbs.db
+desktop.ini

CHANGELOG.md

@@ -0,0 +1,190 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [2.2.6] - 2026-06-25
+
+### Fixed
+- Neon watchface: temperature degree sign showed as `º` (double-encoded in source); now renders `°` like Classic.
+
+## [2.2.5] - 2026-06-19
+
+### Added
+- New **Knobuss** game (optional carousel screen, a knob-steered tube shooter): your ship orbits the rim, you auto-fire inward, foes spiral out from a black-hole core. Turn the knob to aim; every foe that reaches the rim costs a life and bursts in an animated explosion. The ship is a pixel fighter pre-rotated into 16 frames so it always points inward, foes are glowing orbs, a rushing starfield + concentric rings give a cheap 3D-depth tube, and the menu has a "Knobuss" title screen. 3 lives, top-10 scores. Add it to your `screen_order` as `knobuss` (`gyruss` also works). (Art: Lunar Lander pack by Matt Walkden, CC0; see assets/sprites/knobuss/CREDITS.txt.)
+
+### Fixed
+- Cool Cars ran choppier than the other games: its per-tick position updates were 8 separate widget actions (now one batched lambda, like Snake/Knobuss), and it ticked at 12.5fps (now 20fps with speeds scaled to keep the same pace) - so the motion is much smoother.
+
+## [2.2.4] - 2026-06-19
+
+### Changed
+- Sensors screen: each glance now gets its own accent colour (icon + position dots).
+- Added a faint depth ring to the Sensors, Home (Classic) and Weather screens for a consistent framed look.
+
+## [2.2.3] - 2026-06-19
+
+### Changed
+- Thermostat screen polished: the whole arc is now colour-coded by action (heating / cooling / idle / off), a white head-dot marks the target on the gauge, and a faint depth ring was added.
+
+## [2.2.2] - 2026-06-19
+
+### Changed
+- Timer screen redesigned: colour-coded depleting ring (green → amber → red) with a head-dot, SET / RUNNING / PAUSED status, and tile-styled buttons with a soft glow.
+- Alarm screen redesigned: red scrim, a big pulsing bell, "TIME'S UP!" and a tap-to-stop hint.
+
+### Fixed
+- Returning to the home screen after music stops/pauses keeps the selected watchface (was forced to Classic).
+- The Minecraft watchface now shows the active-timer badge.
+
+## [2.2.1] - 2026-06-19
+
+### Added
+- **Minecraft watchface** - a blocky scene with a day/night cycle (sun by day, moon + stars by night), a textured grass/dirt ground, a pixel-font clock, and a heart bar for the battery. Optional, like the other faces.
+
+### Changed
+- Watchfaces redraw the clock only when the minute changes (not every second), so they stay light; faces slide in by swipe direction instead of cross-fading.
+
+### Fixed
+- Silenced the font "missing glyphs" warnings (pixel font uses an explicit glyph list; the Roboto faces use `ignore_missing_glyphs`).
+
+## [2.2.0] - 2026-06-19
+
+### Added
+- **Watchfaces** - the home screen now has selectable looks. Classic is built in; enable the optional **Neon** face (big two-tone digits + neon rings) or copy the heavily-commented **Demo** template to build your own. Pick one in Settings → Home → Watchface with a live full-screen preview (knob switches, tap keeps).
+
+### Changed
+- Settings: clearer names (Home screen, LED Ring, Voice Assistant, Show weather / Show climate, Screen auto-off) and the selected row is styled like the swipe-up control tiles.
+- The rotary knob now wakes the screen from sleep, just like a tap.
+
+## [2.1.6] - 2026-06-18
+
+### Changed
+- Control tiles: the lit tile now has a soft amber glow, and tile names get a little letter spacing.
+
+## [2.1.5] - 2026-06-18
+
+### Changed
+- Weather screen redesigned: animated condition icons, colour-coded temperature, and a glow that slides to the selected day.
+- Boot splash ring is now an azure comet instead of the rainbow.
+
+### Fixed
+- LED ring no longer flashes a stray pixel during screen transitions (RMT now uses DMA).
+
+## [2.1.4] - 2026-06-18
+
+### Added
+- **Snake 360** (optional carousel screen). Steer a 360-degree snake with the knob; eat fruit (up to 3 at once) to grow, avoid the ring, your tail and up to two skulls. Keeps a top-10.
+
+### Changed
+- In games the knob only changes volume on the menu/scores/how-to screens; while playing and on game-over it steers (no accidental volume changes).
+
+### Fixed
+- Clock could stay on UTC: the `timezone` substitution now maps common IANA names (e.g. `Europe/Warsaw`) to the POSIX form the device needs. Use a POSIX string for unlisted zones.
+
+## [2.1.3] - 2026-06-17
+
+### Added
+- **Boot splash**. A short "HELLO!" greeting on startup (~5 s) with a spinning arc on the screen
+  and the LED ring animating, then it cross-fades to the clock. Touch is ignored until it hands off.
+- **Hold to talk** toggle (Settings -> Assistant). Press and hold anywhere on the screen to start
+  the assistant; this can now be turned off (the wake word keeps working regardless).
+
+### Fixed
+- Clock could show UTC (off by the timezone offset) after a restart until the next time sync. The
+  device now re-applies its resolved timezone every second, so the clock never drifts to UTC.
+- OTA updates could roll back to the previous firmware if the device was restarted shortly after
+  flashing (on esp-idf the bootloader only keeps a new image once the boot is marked good). The
+  image is now committed as soon as the boot splash finishes, and the safe-mode window is shortened.
+
+## [2.1.2] - 2026-06-17
+
+### Changed
+- Per-screen settings are now declared in each screen's own package via a generic Widgets
+  options registry, so a screen is fully self-contained (its options, globals and reset
+  logic live in its file). Adding a screen with settings no longer touches the core.
+- The games' "Reset scores" is now under separate **Cool Cars** and **Space Wars** groups
+  in Settings -> Widgets (previously a single "Games" group); each game owns its high scores.
+
+## [2.1.1] - 2026-06-17
+
+### Added
+- **Sensors screen** (optional). A glance of 1-6 configurable Home Assistant entities, shown
+  one at a time big and readable; turn the knob to cycle (slider dots show the position).
+  Pulls straight from HA (no helper), auto-skips unconfigured slots, and units with a micro
+  sign / superscripts are sanitized so they don't render as boxes. New `glanceN_entity` /
+  `glanceN_name` / `glanceN_icon` substitutions, plus the icons `air`, `plant`, `plex`,
+  `server` and `shield`.
+
+## [2.1.0] - 2026-06-17
+
+### Added
+- **Thermostat screen** (optional). A round dial for a Home Assistant `climate.*` entity:
+  the knob sets the target temperature (committed ~0.6 s after you stop turning), tap toggles
+  on/off, and the accent colour follows the action (heating / cooling / idle). Shows the
+  current temperature, humidity and HVAC mode. Set it with the `climate_entity` substitution.
+- **Configurable wake word** via a `wake_word` substitution (default `alexa`; built-in:
+  `okay_nabu`, `hey_jarvis`, `hey_mycroft`).
+
+## [2.0.0] - 2026-06-17
+
+Modular screens release. The firmware is now split into an always-on core plus optional
+screen packages, and you keep a single thin config locally that pulls everything else
+from GitHub at compile time.
+
+### Added
+- **Modular screens.** Optional carousel screens live as separate packages under
+  `base/screens/`. Pick which ones compile in via the `files:` list and set their
+  left-to-right order with the `screen_order` substitution, all from one file.
+- **Thin local config.** The root `guition-va.yaml` is the only firmware file you keep;
+  it pulls `base/core.yaml` and the selected `base/screens/*.yaml` as a remote package.
+- **Weather screen.** Today plus a 7-day radial dial (Apple-Watch style); the knob
+  highlights a day, the centre shows the day name, temperatures and condition. Includes a
+  Celsius/Fahrenheit toggle and a Home Assistant helper sensor that feeds the forecast.
+- **Example "demo" screen.** A small, heavily commented screen (TAP ME!) you can copy as a
+  starting point for your own screen.
+- **Configurable control tiles.** The swipe-up page is now four tiles, each with its own HA
+  entity, icon (chosen by name from a 20-icon set, repeatable) and label. Works on any HA
+  domain via `homeassistant.toggle`.
+- **Configurable clock timezone** via a `timezone` substitution (DST automatic).
+
+### Changed
+- **Repository layout.** The core and screens moved into `base/`; the root holds the thin
+  `guition-va.yaml` you copy and edit.
+- **Settings menu.** "Widgets" is now a per-screen group menu (Widgets -> Demo / Games /
+  Weather), each opening that screen's own options. A separate "Home" submenu owns the
+  home-screen widget toggles; "Display" keeps global brightness / night / screen-off.
+  "System" is always last, and device Restart lives only inside it.
+
+### Fixed
+- Clock showing UTC: the timezone is now set explicitly (the Home Assistant time platform
+  does not sync the zone to the device).
+- Control-tile icons rendering empty, and the "led" icon pointing at map-marker-outline
+  (now `led-strip`).
+- Settings list collapsing "Restart" and "System" into one entry (a folded YAML newline).
+- Demo LED ring staying lit on the home screen after a reboot.
+
+## [1.0.0] - 2026-06-16
+
+### Added
+- Initial release: ESPHome voice assistant for the Guition JC3636K718C round knob display.
+  Clock, music player (album art + transport), timer, two games (Cool Cars, Space Wars),
+  settings menu, WS2812 LED ring, on-device wake word and the Assist voice pipeline.
+- Fonts, images and sounds fetched from GitHub at compile time (nothing to copy locally
+  except the config and the partition table).
+
+[2.2.5]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.2.5
+[2.2.4]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.2.4
+[2.2.3]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.2.3
+[2.2.2]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.2.2
+[2.2.1]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.2.1
+[2.2.0]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.2.0
+[2.1.6]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.1.6
+[2.1.5]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.1.5
+[2.1.4]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.1.4
+[2.1.3]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.1.3
+[2.1.2]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.1.2
+[2.1.1]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.1.1
+[2.1.0]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.1.0
+[2.0.0]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v2.0.0
+[1.0.0]: https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/releases/tag/v1.0.0

README.md

@@ -0,0 +1,177 @@
+
+
+![ESPHome + Home Assistant Voice Assistant on the Guition JC3636K718C](assets/header.jpg)
+
+# ESPHome Voice Assistant for the Guition JC3636K718C (round knob display)
+
+A full-featured **Home Assistant Voice Assistant** running on the **Guition
+JC3636K718C** - a 1.8" round 360×360 touch display with a rotary knob, speaker,
+microphone and an **addressable LED ring**. It's pure ESPHome (no custom C firmware):
+an always-on core plus optional screen packages you pick from one thin config.
+
+It started as "my kid needs a physical timer" and turned into a whole puck. 🙂
+
+## Demo
+
+<div align="center">
+  <video src="https://github.com/user-attachments/assets/e945f4ec-b80f-4740-9130-ed93bd2ab31b" controls width="400"></video>
+</div>
+
+## What it does
+
+- **Voice assistant** - on-device wake word ("Alexa") via `micro_wake_word`, full
+  Home Assistant Assist pipeline (STT / LLM / TTS), wake beep + music ducking. You can also
+  press and hold the screen to talk (toggleable in Settings).
+- **Boot splash** - a short "HELLO!" greeting with a spinning ring on startup, then the clock.
+- **Music player** - `speaker` media player visible in HA / Music Assistant, with
+  album art, title/artist, transport buttons and a progress bar.
+- **Timers** - set by knob or by voice; big countdown with a depleting ring,
+  pause/stop, and an alarm (sound + on-screen + LED) when it finishes.
+- **Device control** - a tiles screen toggling your lights/switches.
+- **Home screen** - clock, date, battery, weather + room temp/humidity, with a **selectable watchface** look (Classic, Neon, or your own).
+- **More screens** (all optional, knob-driven) - a weather forecast dial, a thermostat for
+  any `climate` entity, and a configurable multi-sensor glance.
+- **LED ring** - controllable from HA *and* reactive: assistant (comet/spinner/wave),
+  timer countdown, alarm flash, volume bar - each reaction toggleable in Settings.
+- **Four built-in arcade games** (a lane racer, a vertical shooter, a 360-degree snake and a Gyruss-style tube shooter) for the kid.
+
+Everything is navigated with **swipes + taps on the screen** and the **rotary knob**.
+
+## Screens
+
+| Screen | View |
+|:---:|---|
+| <img src="assets/screens/home.png" width="170"> | **Home / Clock**<br>Time, date, battery (a bolt while charging), outdoor weather and room temperature + humidity. Pick the watchface look in Settings → Home - see [Watchfaces](#watchfaces) below. |
+| <img src="assets/screens/player.png" width="170"> | **Player**<br>Album art, title & artist, prev / play-pause / next and a progress bar. Auto-shows when playback starts. |
+| <img src="assets/screens/controls.png" width="170"> | **Control tiles** (swipe up)<br>Four configurable tiles toggling any HA entity; each has its own icon and label, and the colour follows the live on/off state. |
+| <img src="assets/screens/weather.png" width="170"> | **Weather**<br>A 7-day dial; turn the knob to scroll days. Animated condition icon, colour-coded temperature, and a glow that slides to the selected day. |
+| <img src="assets/screens/thermostat.png" width="170"> | **Thermostat**<br>A dial for a `climate.*` entity; the knob sets the target (a head-dot rides the gauge), tap toggles on/off. The whole arc is colour-coded by action - heating / cooling / idle / off. |
+| <img src="assets/screens/sensors.png" width="170"> | **Sensors**<br>A glance of 1-6 configurable Home Assistant entities, shown big one at a time; turn the knob to cycle (dots show the position). Each gets its own accent colour. Any entity, pulled straight from HA. |
+| <img src="assets/screens/timer.png" width="170"> | **Timer**<br>Set by knob or voice; big countdown with a colour-coded depleting ring (green → amber → red) and a head-dot, SET / RUNNING / PAUSED status, pause/stop, and a fancy alarm screen when it finishes. |
+| <img src="assets/screens/cool-cars.png" width="170"> | **Cool Cars**<br>A lane-racing arcade game - the knob steers, dodge traffic and grab coins. |
+| <img src="assets/screens/space-wars.png" width="170"> | **Space Wars**<br>A vertical space shooter - the knob steers, auto-fire, survive the waves. |
+| <img src="assets/screens/snake.png" width="170"> | **Snake 360**<br>A smooth-steering 360-degree snake - turn the knob to steer the head and the body trails behind, across the whole round screen. |
+| <img src="assets/screens/knobuss.png" width="170"> | **Knobuss**<br>A **Gyruss clone**: your ship orbits the rim and auto-fires inward while foes spiral out of a black-hole core - turn the knob to aim and shoot them down. **Every foe that reaches the rim costs a life** (it bursts in an explosion). 3 lives, top-10 scores. |
+| <img src="assets/screens/settings.png" width="170"> | **Settings** (swipe down)<br>Display, Home screen, Widgets, LED Ring, Voice Assistant, System; turn the knob to scroll, tap to enter. |
+| <img src="assets/screens/demo.png" width="170"> | **Demo**<br>A small, heavily commented example screen (tap flips black ↔ white) to copy when building your own. |
+
+> Optional screens (player, timer, games, weather, thermostat, sensors, demo) are pickable - choose which compile in and their order; see [Configuration](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki/Configuration).
+
+## Watchfaces
+
+The home screen has a **selectable look**. Open **Settings → Home → Watchface** and the knob previews each face live, full-screen - tap to keep. **Classic** is built in; **Neon** (big neon digits), **Minecraft** (a blocky day/night scene) and a heavily-commented **Demo** template are optional files you switch on in your config, and you can copy Demo to build your own (see [Configuration](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki/Configuration)).
+
+| Classic (built-in) | Neon | Minecraft | Demo (template) |
+|:---:|:---:|:---:|:---:|
+| <img src="assets/screens/home.png" width="150"> | <img src="assets/screens/watchface-neon.png" width="150"> | <img src="assets/screens/watchface-minecraft.png" width="150"> | <img src="assets/screens/watchface-demo.png" width="150"> |
+
+## Documentation
+
+Full docs live in the **[wiki](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki)**:
+
+| Page | What's inside |
+|---|---|
+| [Hardware](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki/Hardware) | Board specs, full pinout, what to buy on AliExpress |
+| [Installation](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki/Installation) | Requirements, first flash (USB), OTA, the bundled sounds |
+| [Usage](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki/Usage) | Gestures, screens, the settings menu, the LED ring |
+| [Configuration](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki/Configuration) | Change entities, tiles, wake word, run without Music Assistant |
+| [Troubleshooting](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki/Troubleshooting) | Known issues (battery %, GPIO0 strapping, performance, the knob) |
+
+Release history: [CHANGELOG.md](CHANGELOG.md).
+
+## Buying one (AliExpress)
+
+Search for the exact model number and verify the listing matches:
+
+- Model: **Guition JC3636K718** (look for this in the title/photos)
+- ESP32-S3, **16 MB flash**, **octal PSRAM**
+- 1.8" round **360×360**, driver **ST77916**
+- touch **CST816**, rotary **knob**, speaker + mic, **LED ring**
+
+⚠️ **Heads-up:** there's a near-identical board, the **JC3636W518**, with a *different
+pinout*. Make sure the listing says **K718**, not W518. More detail on the
+[Hardware](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki/Hardware) wiki page.
+
+## Quick start
+
+> **Requires ESPHome 2025.5.0+** - the LED ring uses `use_dma`, added in that release. Older versions fail to compile with `[use_dma] is an invalid option for [light.esp32_rmt_led_strip]`.
+
+1. Copy `secrets.example.yaml` → `secrets.yaml` and fill in your Wi-Fi.
+2. Copy **`guition-va.yaml`** and **`partitions.csv`** so they sit together with `secrets.yaml`. Edit the `substitutions:` at the top of `guition-va.yaml` (HA URL + your entity IDs + the four control tiles). That thin file is the only firmware file you keep - the core and all screens are **pulled from GitHub at compile time** (see its `packages:` block), as are the fonts, images and sounds.
+3. Choose which screens compile in via the `files:` list and their left-to-right order via `screen_order`, both in `guition-va.yaml`.
+4. **First flash over USB** - easiest via the **ESPHome dashboard** (GUI) or the CLI; the 16 MB partition table can't be set over OTA, so the first flash is USB, then updates go wireless.
+5. In Home Assistant: open the new ESPHome device → assign an Assist pipeline.
+
+To pull the latest changes later: `esphome clean guition-va.yaml` (clears the package cache) then `esphome run guition-va.yaml`.
+
+Full details on the [Installation](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki/Installation) wiki page.
+
+## Repository layout
+
+```
+guition-va.yaml            # YOUR config: copy + edit this (pulls everything else from GitHub)
+partitions.csv             # 16 MB partition table (keep next to guition-va.yaml)
+secrets.example.yaml       # copy to secrets.yaml
+base/                      # pulled as a remote package at compile time (no need to copy)
+  core.yaml                # always-on core: clock, controls (swipe-up tiles), settings menu
+  screens/                 # optional carousel screens (toggle each in guition-va.yaml)
+    player.yaml            #   music player (album art + transport)
+    timer.yaml             #   timer screen in the carousel
+    cool-cars.yaml         #   "Cool Cars" game
+    space-wars.yaml        #   "Space Wars" game
+    snake.yaml             #   "Snake 360" game (knob steers)
+    knobuss.yaml           #   "Knobuss" game (Gyruss-style tube shooter, knob aims)
+    weather.yaml           #   weather (today + 7-day radial dial)
+    thermostat.yaml        #   thermostat (climate.* dial; knob sets target, tap on/off)
+    sensors.yaml           #   sensors glance (1-6 HA entities, knob cycles)
+    demo.yaml              #   commented example screen
+    weather.ha-helper.yaml #   HA template sensor that feeds the weather screen
+  watchfaces/              # optional home-screen looks (Classic is built into core)
+    neon.yaml              #   "Neon" watchface - big two-tone digits + neon rings
+    minecraft.yaml         #   "Minecraft" watchface - blocky day/night scene + pixel clock
+    demo.yaml              #   "Demo" watchface - minimal, heavily-commented template to copy
+assets/                    # fetched from GitHub at compile time (no need to copy locally)
+  header.jpg               # banner
+  fonts/pixel-font.ttf     # pixel font (Minecraft watchface)
+  sounds/                  # wake.wav + alarm.wav
+  sprites/cool-cars/       # "Cool Cars" game graphics
+  sprites/space-wars/      # "Space Wars" game graphics
+  sprites/snake/           # "Snake" menu logo
+  sprites/knobuss/         # "Knobuss" game graphics (ship/foes/explosion/core/logo)
+  sprites/minecraft/       # "Minecraft" watchface graphics (sun/moon/ground/flower)
+  sprites/weather/         # animated weather icon frames
+scripts/
+  make_sounds.py           # (re)generate the wav sounds
+  gen_weather.py           # (re)generate the animated weather icon frames
+  gen_snake.py             # (re)generate the snake sprites
+  esplog.py                # stream device logs over the native API
+skill/                     # Claude Code skill: hardware spec + gotchas
+```
+
+## Claude Code skill
+
+This repo ships a [Claude Code](https://claude.com/claude-code) skill at
+[`skill/guition-jc3636k718c/`](skill/guition-jc3636k718c/SKILL.md). It gives the
+assistant the correct pinout, ESPHome component choices, and the hard-won gotchas
+(the knob isn't quadrature, GPIO0 ring strapping, 16 MB partitions need a USB flash,
+LVGL performance limits, lambda/string pitfalls, the battery heuristic).
+
+### Install it
+
+So Claude can use it on any project:
+
+- **User-wide** - copy the folder into `~/.claude/skills/`:
+  ```bash
+  cp -r skill/guition-jc3636k718c ~/.claude/skills/
+  ```
+- **Per-project** - copy it into that project's `.claude/skills/`.
+
+Start a new Claude Code session and ask anything about this board; the skill loads
+automatically. See the [wiki](https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va/wiki/Claude-Code-Skill) for details.
+
+## Credits / notes
+
+- Pinout and the display `init_sequence` come from the **official manufacturer demo**
+  (`JC3636K718_knob_EN`) - this is the correct pinout for the **K718C** board, which
+  differs from the otherwise-similar **JC3636W518**.
+- Built with [ESPHome](https://esphome.io/) + Home Assistant.

assets/sprites/knobuss/CREDITS.txt

@@ -0,0 +1,20 @@
+Gyruss sprite credits
+=====================
+
+ship0..15.png, life.png, expl0..7.png
+  Derived from the "Lunar Lander" asset pack by Matt Walkden
+  (mattwalkden.itch.io / mattwalkden.com), released into the Public Domain
+  under the Creative Commons CC0 dedication. No attribution required; credited
+  here with thanks. Ship sprite pre-rotated into 16 frames (+ an upright life
+  icon); explosion sliced from the 8-frame sheet.
+
+knobuss-logo.png (menu title screen)
+  "KNOBUSS by Zan" - made by the project owner (Zan).
+
+core.png (black-hole portal), enemy0..3.png (glowing orbs)
+  Cropped/scaled from a "celestial objects" pixel-art set. Used with the
+  project owner's confirmation that its license permits redistribution.
+  TODO(owner): fill in the exact source/author + license for this set.
+
+bullet.png
+  Original to this project.