-
Notifications
You must be signed in to change notification settings - Fork 5
Troubleshooting
The battery reading is approximate - treat it as a rough gauge, not a precise %.
- It's an ADC on GPIO6 (
BAT_ADC) with a ~10k/10k divider (×2 in the config), 64-sample hardware oversampling + a moving average to fight switching ripple from the ETA6003 converter (there's no capacitor on BAT_ADC). - The voltage→% curve (
vt[]/st[]arrays in theadcon_valuelambda) was calibrated on a real under-load discharge: starts ~4.10 V (≈90%), nearly linear, brownout ~3.20 V. Calibration is not finished - tune those arrays for your unit. - Charging detection is a heuristic (rising voltage or ≥4.13 V), because there's no STAT pin wired to a GPIO. While "charging" the icon shows a bolt + animation and hides the % (the rail voltage reads high under USB).
The WS2812 ring is on GPIO0, which is also the BOOT/strapping pin. ESPHome may warn about using a strapping pin as output - this is expected and harmless here; it's exactly what the manufacturer's own demo does. The ring works after boot.
This knob is not standard A/B quadrature, so a PCNT rotary_encoder reads zero.
Direction is encoded by which pin pulses: left → GPIO2, right → GPIO1. The config
reads two independent binary_sensor (inverted + pullup, on_press). If your unit is
reversed, swap the GPIO2/GPIO1 handling in the binary_sensor section.
The device uses a custom 16 MB partition table (partitions.csv). A partition
change must be flashed over USB the first time - OTA can't repartition. Flash once
over USB, then OTA works for subsequent updates.
Almost always the wrong board variant. This config is for the JC3636K718C (K/Knob series). The JC3636W518 has a different pinout (display, backlight, touch), so the screen stays black and I²C won't see the touch. Confirm you have the K718.
The homeassistant time platform syncs the clock value but not the timezone, so without
an explicit zone the clock falls back to the build host's zone (often UTC). Set the
timezone substitution in guition-va.yaml to your IANA zone (e.g. Europe/Warsaw,
America/New_York); DST is automatic. Re-flash after changing it.
ESPHome can also reset the device's zone to UTC at runtime (e.g. after a restart or when a
log/API client reconnects), so the clock briefly read 1-2 h off until the next sync. The core
now captures the resolved zone at boot and re-applies it every second, so it no longer drifts.
If you still see UTC, the timezone substitution itself is missing or wrong.
On esp-idf the bootloader rolls back to the previous firmware if the device resets before the new boot is marked "good" (a safety feature). Restarting from the menu within ~1 minute of an OTA update would therefore boot the old build again. The firmware now marks itself good as soon as the boot splash finishes (~5 s) and shortens the safe-mode window, so a normal restart keeps the new build. Just let the boot splash complete once after flashing before restarting.
The firmware (core + screens) is pulled as a remote packages: entry. If a rebuild still
uses the old version, clear the cached package and rebuild:
esphome clean guition-va.yaml
esphome run guition-va.yamlTo pin a known-good version instead of tracking a branch, set ref: in the packages:
block to a release tag rather than main/beta.
wake.wav and alarm.wav are pulled from the GitHub repo at compile time, so it builds
out of the box. To use your own, point the two file: entries under media_player: at
your files (16-bit/mono/16 kHz) or regenerate the originals with
python scripts/make_sounds.py.
Fonts (Google Fonts Roboto, MaterialDesign icon TTF), the game sprites
(assets/sprites/cool-cars/, assets/sprites/space-wars/) and the sounds
(assets/sounds/) are all fetched at compile time from the GitHub repo, so the build
machine needs internet during the build. They are baked into the firmware, so at runtime
nothing depends on any server.
The cover is fetched via online_image from the player's entity_picture. ESPHome
needs an explicit lvgl.image.update in on_download_finished (already in the
config) or the widget won't redraw. http_request uses verify_ssl: false for
self-signed HA certs. Same-URL covers are skipped to reduce flicker.
By design: the clock↔player auto-switch only fires when you're already on the clock or
player screen and the assistant isn't active. On a game/timer/menu it won't yank you
away. (See the media_state text sensor.)
The ring volume value comes from HA (vol_sensor → g_vol), so it updates after the
HA round-trip (~100-300 ms), same as the on-screen volume arc.
If the UI stutters, keep lvgl: buffer_size: 24% (fast internal RAM) and
display: data_rate: 80MHz. Avoid heavy full-screen redraws - a rotating full-screen
HUD and an animated radial equalizer were both removed for being too slow on this
S3 + QSPI panel.
The native API has no encryption in this config, so you can stream logs without the dashboard:
python scripts/esplog.py <seconds> # edit the device host inside the script