373 lines
19 KiB
YAML
373 lines
19 KiB
YAML
# OpenCode decision notes
|
||
#
|
||
# Decisions and constraints about this Home Assistant installation, recorded by
|
||
# the OpenCode add-on only when you approve them. OpenCode reads a short digest
|
||
# of the active notes at the start of every session.
|
||
#
|
||
# Safe to edit or delete by hand. Keep the shape below; OpenCode refuses to add
|
||
# notes while the file cannot be parsed, so nothing is silently overwritten.
|
||
#
|
||
# Set a note's status to "superseded" (or delete it) to drop it from the digest.
|
||
# Add "pin: true" to a note to keep it in the digest when older notes no longer
|
||
# fit — use it for the decisions that must never be reversed by accident.
|
||
|
||
version: 1
|
||
notes:
|
||
- id: 2026-07-29-nest-snapshot-custom-integration
|
||
date: 2026-07-29
|
||
title: nest_snapshot custom integration abandoned
|
||
decision: nest_snapshot integration is abandoned. WebRTC SDP parsing was fixed but ICE
|
||
connection to Google Nest's ice-lite candidates never establishes (30s timeout). Do
|
||
not revisit.
|
||
rationale: After resolving SDP candidate format issues (missing component-id), aiortc
|
||
could parse Google's answer but ICE connectivity checks timed out every time across
|
||
multiple restarts. Track handler fires but recv() never gets a frame. Root cause
|
||
undetermined — likely aiortc STUN connectivity or ice-lite compatibility issue. Not
|
||
worth further effort.
|
||
files:
|
||
- custom_components/nest_snapshot/__init__.py
|
||
- custom_components/nest_snapshot/manifest.json
|
||
- custom_components/nest_snapshot/services.yaml
|
||
integrations:
|
||
- nest_snapshot
|
||
pin: true
|
||
status: active
|
||
- id: 2026-08-06-octoprint-automation-playroom-light
|
||
date: 2026-08-06
|
||
title: OctoPrint automation (playroom light + basement heat) pending — via MQTT/OctoMQTT
|
||
decision: "Built-in OctoPrint integration is broken here (AssertionError device_id is not
|
||
None; no printer entities). Chosen route: OctoMQTT plugin, trigger on
|
||
octoPrint/event/PrintStarted. Pending automation: when print starts, turn on
|
||
light.playroom_light and set climate.basement to 22C."
|
||
rationale: Completed the built-in OctoPrint integration setup flow but HA logs show setup
|
||
errors for sensor/binary_sensor/button/camera/number platforms, so there is nothing
|
||
to trigger on. User chose the MQTT route and will configure the OctoMQTT plugin
|
||
later (printer is currently busy). Leave the broken OctoPrint entry alone until this
|
||
is resolved.
|
||
entities:
|
||
- light.playroom_light
|
||
- climate.basement
|
||
integrations:
|
||
- octoprint
|
||
- mqtt
|
||
status: superseded
|
||
superseded_by: 2026-08-06-3d-printer-automation-runs-on-helper
|
||
- id: 2026-08-06-3d-printer-automation-runs-on-helper
|
||
date: 2026-08-06
|
||
title: 3D printer automation runs on helper, not MQTT
|
||
decision: "When the OctoPrint HA plugin toggles input_boolean.3d_printer_running: ON ->
|
||
playroom + bedroom lamps on, basement 22C heat; OFF -> playroom light off after 10
|
||
min, thermostat untouched. Mode restart cancels pending off on a new print. Old MQTT
|
||
automation stays disabled."
|
||
rationale: Built-in OctoPrint integration is broken here (AssertionError device_id is not
|
||
None; no printer entities). The OctoMQTT event trigger was replaced by a
|
||
helper-based design so OctoPrint can toggle a HA entity directly (plugin pointed at
|
||
the helper) and print-end handling (delayed light off) becomes possible. Built,
|
||
tested, and working 2026-08-06.
|
||
entities:
|
||
- input_boolean.3d_printer_running
|
||
- light.playroom_light
|
||
- light.bedroom_lamp
|
||
- climate.basement
|
||
integrations:
|
||
- octoprint
|
||
- mqtt
|
||
status: active
|
||
- id: 2026-08-06-octomqtt-still-enabled-for-future
|
||
date: 2026-08-06
|
||
title: OctoMQTT still enabled for future automations
|
||
decision: OctoMQTT plugin remains enabled on the OctoPrint side and keeps publishing to
|
||
octoPrint/event/... topics. The current print-start automation uses the
|
||
input_boolean helper, but this MQTT stream stays available for future, more complex
|
||
automations (print progress, job done, errors, etc.).
|
||
rationale: The helper-based automation only covers start/end. Keeping OctoMQTT running
|
||
preserves richer OctoPrint events for later automation without reconfiguring the
|
||
printer. No conflict with the helper automation — they are complementary.
|
||
integrations:
|
||
- octoprint
|
||
- mqtt
|
||
status: active
|
||
- id: 2026-08-07-printer-totals-history-stats-via-config
|
||
date: 2026-08-07
|
||
title: "Printer totals: history_stats via config flow (HA 2026.8: no YAML)"
|
||
decision: Print totals (print time + counts, today/week/7d) are history_stats config-flow
|
||
helpers (sensor.octoprint_printer_*), shown in the Totals section of the
|
||
printer-stats/print dashboard. history_stats no longer supports YAML in HA 2026.8 —
|
||
create helpers via config flow/UI only, never a configuration.yaml entry.
|
||
rationale: Session paused 2026-08-06 to continue later. YAML history_stats was rejected by
|
||
core with "history_stats does not support YAML setup", so all six sensors were
|
||
created via config flow and verified live; the Totals dashboard section is committed
|
||
(config hash 57e4ba20d169bbf3, render path printer-stats/print). Config-flow helpers
|
||
need no restart.
|
||
entities:
|
||
- sensor.octoprint_printer_print_time_today
|
||
- sensor.octoprint_printer_print_time_this_week
|
||
- sensor.octoprint_printer_print_time_last_7_days
|
||
- sensor.octoprint_printer_prints_today
|
||
- sensor.octoprint_printer_prints_this_week
|
||
- sensor.octoprint_printer_prints_last_7_days
|
||
integrations:
|
||
- history_stats
|
||
- octoprint
|
||
- mqtt
|
||
status: active
|
||
- id: 2026-08-07-octoprint-controls-are-mqtt-via
|
||
date: 2026-08-07
|
||
title: OctoPrint controls are MQTT via OctoMQTT plugin
|
||
decision: OctoPrint controls are MQTT entities from the installed OctoMQTT/Discovery
|
||
plugin v3.7.0, publishing to octoPrint/hassControl/*. Cancel/pause show unavailable
|
||
while idle by design (availability tied to octoPrint/hass/is_printing). No native
|
||
octoprint integration needed.
|
||
rationale: "Verified via mqtt/device/debug_info on device
|
||
9b0fd332d68cc7010c998450c00d49f2: each entity carries a command_topic on
|
||
octoPrint/hassControl/* (cancel, pause, stop, camera_snapshot, connect) that the
|
||
plugin subscribes to inside OctoPrint. The command path was proven working - a
|
||
camera_snapshot toggle earlier today transmitted True to the broker. Commands are
|
||
fire-and-forget; confirm landing by watching sensor.octoprint_print_status."
|
||
entities:
|
||
- button.octoprint_cancel_print
|
||
- switch.octoprint_pause_print
|
||
- switch.octoprint_camera_snapshot
|
||
- switch.octoprint_connect_to_printer
|
||
integrations:
|
||
- mqtt
|
||
- octoprint
|
||
status: active
|
||
- id: 2026-08-07-octoprint-frozen-sensors-shown-via-idle
|
||
date: 2026-08-07
|
||
title: OctoPrint frozen sensors shown via idle-zero template helpers
|
||
decision: OctoPrint sensors freeze at last-print values when idle. The /printer-stats
|
||
dashboard uses template helpers (sensor.octoprint_elapsed,
|
||
sensor.octoprint_time_left, sensor.octoprint_current_z_2) reporting 0 while printing
|
||
is off. Keep cards on helpers; raw sensors stay intact.
|
||
rationale: "While idle the raw sensors freeze at end-of-print values (elapsed 6661s,
|
||
current Z 26.8mm), looking like a mid-print and producing stale charts. Helper
|
||
template: {{ 0 if not is_state('binary_sensor.octoprint_printing','on') else
|
||
states('<source>')|float }}. The Current Z helper got _2 suffix because its friendly
|
||
name collided with the raw sensor's slug."
|
||
entities:
|
||
- sensor.octoprint_elapsed
|
||
- sensor.octoprint_time_left
|
||
- sensor.octoprint_current_z_2
|
||
- binary_sensor.octoprint_printing
|
||
- sensor.octoprint_print_time
|
||
- sensor.octoprint_print_time_left
|
||
- sensor.octoprint_current_z
|
||
integrations:
|
||
- octoprint
|
||
- template
|
||
status: superseded
|
||
superseded_by: 2026-08-07-octoprint-frozen-sensors-shown-via-idle-2
|
||
- id: 2026-08-07-octoprint-frozen-sensors-shown-via-idle-2
|
||
date: 2026-08-07
|
||
title: OctoPrint frozen sensors shown via idle-zero template helpers
|
||
decision: "OctoPrint duration sensors freeze when idle. The /printer-stats dashboard uses
|
||
template helpers (sensor.octoprint_elapsed, sensor.octoprint_time_left) reporting 0
|
||
while printing is off. Current Z stays on the raw sensor: the nozzle physically
|
||
remains at its height when idle."
|
||
rationale: "Elapsed and time-left are durations tied to a running print, so 0 while idle
|
||
is correct. Current Z is a physical position that persists — zeroing it would
|
||
falsely claim the nozzle is at the build plate. Helper template: {{ 0 if not
|
||
is_state('binary_sensor.octoprint_printing','on') else states('<source>')|float }}.
|
||
An earlier Z helper (octoprint_current_z_2) was created then deleted after this
|
||
distinction was realized."
|
||
entities:
|
||
- sensor.octoprint_elapsed
|
||
- sensor.octoprint_time_left
|
||
- binary_sensor.octoprint_printing
|
||
- sensor.octoprint_print_time
|
||
- sensor.octoprint_print_time_left
|
||
- sensor.octoprint_current_z
|
||
integrations:
|
||
- octoprint
|
||
- template
|
||
status: active
|
||
- id: 2026-08-07-octoprint-camera-go2rtc-h264-transcode
|
||
date: 2026-08-07
|
||
title: "OctoPrint camera: go2rtc H264 transcode required for WebRTC"
|
||
decision: Ender camera (endercamera.duckdns.org) streams MJPEG only; go2rtc serves it
|
||
transcoded to H264 (ffmpeg:...#video=h264) because WebRTC cannot negotiate MJPEG.
|
||
Keep this transcode. The printer-stats dashboard webrtc card uses go2rtc's named
|
||
'octoprint' stream, never a raw URL.
|
||
rationale: "Fixed the webrtc-camera card's DESCRIBE error (dead
|
||
rtsp://127.0.0.1:18554/octoprint) and 'codec not matched' error (MJPEG over WebRTC).
|
||
Operational trap discovered: do NOT POST to go2rtc /api/config - it persists its
|
||
JSON body into go2rtc.yaml, silently overwriting config. To change streams, edit
|
||
/homeassistant/go2rtc.yaml and reload the webrtc integration (entry
|
||
01KWT295KFJ9V0N6ZXG88JM3GA); the embedded go2rtc reads that file on reload."
|
||
entities:
|
||
- camera.endercamera_duckdns_org
|
||
files:
|
||
- go2rtc.yaml
|
||
integrations:
|
||
- webrtc
|
||
- octoprint
|
||
pin: true
|
||
status: active
|
||
- id: 2026-08-08-printjobhistory-external-db-settings
|
||
date: 2026-08-08
|
||
title: PrintJobHistory external-DB settings are inert defaults
|
||
decision: The PrintJobHistory plugin's datbaseSettings (useExternal=true, type=postgres,
|
||
user=Olli, etc.) are hardcoded defaults in get_settings_defaults(), never read by
|
||
plugin code. The plugin always uses a local SQLite DB in its plugin data folder. Do
|
||
not set up Postgres.
|
||
rationale: "Confirmed from OllisGit/OctoPrint-PrintJobHistory source: 'useExternal'
|
||
appears only in the defaults dict; DatabaseManager.py uses sqlite3.connect()
|
||
exclusively; the lone 'postgres' string is in testConnection(), invoked only from
|
||
the settings-UI test button. The API already serves valid JSON from SQLite
|
||
(totalItemCount=0) proving the store works."
|
||
entities:
|
||
- sensor.octoprint_filament_used_total
|
||
- sensor.octoprint_last_print_filament
|
||
files:
|
||
- configuration.yaml
|
||
integrations:
|
||
- octoprint
|
||
status: active
|
||
- id: 2026-08-08-midea-dishwasher-has-dhcp-reservation
|
||
date: 2026-08-08
|
||
title: Midea dishwasher has DHCP reservation
|
||
decision: The Midea dishwasher (MAC c0:88:40:53:27:7c) has a DHCP reservation at
|
||
192.168.1.84. The midea_ac_lan "Dishwasher" config entry must keep this IP; if
|
||
entities go unavailable, verify the IP before anything else.
|
||
rationale: On 2026-08-08 the dishwasher dropped offline at the old IP (192.168.1.83) after
|
||
a DHCP lease change; it moved to .84 and the reservation was added to prevent
|
||
recurrence.
|
||
entities:
|
||
- binary_sensor.150633095332665_door
|
||
integrations:
|
||
- midea_ac_lan
|
||
status: active
|
||
- id: 2026-08-14-octoprint-progress-never-reinstall-m73
|
||
date: 2026-08-14
|
||
title: "OctoPrint progress: never reinstall M73-injecting plugins"
|
||
decision: Never reinstall M73-injecting OctoPrint plugins (old "M73 plugin", Detailed
|
||
Progress with use_M73). They inject M73 P0 which overrides file-position progress
|
||
via serial.trustM73, freezing completion at 0%. If LCD M73 progress is wanted later,
|
||
set plugins.serial_connector.trustM73=false and keep the plugin.
|
||
rationale: "Diagnosed 2026-08-14: progress froze at 0% while /api/job filepos reached
|
||
100%. OctoPrint 2.0.0rc4 adopts any streamed M73 P value as authoritative progress
|
||
once trustM73 is true; the file had no M73 lines, so P0 came from plugin injection
|
||
and was never updated (file uses M117 DASHBOARD_LAYER_INDICATOR, not ;LAYER:
|
||
comments). Uninstalling the plugins restored correct progress immediately."
|
||
entities:
|
||
- sensor.octoprint_print_progress
|
||
- sensor.octoprint_print_status
|
||
- binary_sensor.octoprint_printing
|
||
integrations:
|
||
- octoprint
|
||
pin: true
|
||
status: active
|
||
- id: 2026-08-14-octoprint-live-rest-sensors-are-the
|
||
date: 2026-08-14
|
||
title: "OctoPrint: `_live` REST sensors are the accurate source, MQTT push lags"
|
||
decision: OctoPrint MQTT push progress events are throttled (~5-13 min gaps), so MQTT
|
||
sensors lag. The `_live` REST sensors (/api/job every 30s) are the accurate source.
|
||
Keep dashboards and helpers on `_live` sensors; do not swap MQTT sensors back in for
|
||
display.
|
||
rationale: "2026-08-14: throttled PrintProgress push left MQTT sensor.octoprint_print_time
|
||
~18 min stale vs live REST. Switched sensor.octoprint_elapsed helper to live REST
|
||
printTime attribute and History graph to sensor.octoprint_print_progress_live.
|
||
Rounded progress to 2 decimals so slow prints visibly advance (2.4 -> 2.45). Elapsed
|
||
2611s matched wall-clock printTime exactly."
|
||
entities:
|
||
- sensor.octoprint_print_progress_live
|
||
- sensor.octoprint_print_time_left_live
|
||
- sensor.octoprint_print_state_live
|
||
- sensor.octoprint_elapsed
|
||
- sensor.octoprint_print_progress
|
||
- sensor.octoprint_print_time
|
||
files:
|
||
- configuration.yaml
|
||
integrations:
|
||
- octoprint
|
||
- rest
|
||
- mqtt
|
||
- template
|
||
status: superseded
|
||
superseded_by: 2026-08-14-octoprint-live-rest-sensors-are-the-2
|
||
- id: 2026-08-14-octoprint-live-rest-sensors-are-the-2
|
||
date: 2026-08-14
|
||
title: "OctoPrint: `_live` REST sensors are the accurate source, MQTT push lags"
|
||
decision: OctoPrint MQTT push progress events are throttled (~5-13 min gaps), so MQTT
|
||
sensors lag. The `_live` REST sensors (/api/job every 30s) are the accurate source.
|
||
Keep dashboards and helpers on `_live` sensors; do not swap MQTT sensors back in for
|
||
display.
|
||
rationale: "2026-08-14: throttled PrintProgress push left MQTT sensor.octoprint_print_time
|
||
~18 min stale vs live REST. Switched sensor.octoprint_elapsed helper to live REST
|
||
printTime attribute and History graph to sensor.octoprint_print_progress_live.
|
||
Rounded progress to 2 decimals so slow prints visibly advance (2.4 -> 2.45). Elapsed
|
||
2611s matched wall-clock printTime exactly."
|
||
entities:
|
||
- sensor.octoprint_print_progress_live
|
||
- sensor.octoprint_print_time_left_live
|
||
- sensor.octoprint_print_state_live
|
||
- sensor.octoprint_elapsed
|
||
- sensor.octoprint_print_progress
|
||
- sensor.octoprint_print_time
|
||
files:
|
||
- configuration.yaml
|
||
integrations:
|
||
- octoprint
|
||
- rest
|
||
- mqtt
|
||
- template
|
||
pin: true
|
||
status: active
|
||
- id: 2026-08-14-octoprint-printjobhistory-set-to
|
||
date: 2026-08-14
|
||
title: OctoPrint PrintJobHistory set to capture all jobs (not just successful)
|
||
decision: OctoPrint's PrintJobHistory plugin is set to capture ALL jobs (success +
|
||
failed/cancelled), not "success jobs only". Failed/cancelled prints are now recorded
|
||
so their filament usage flows into sensor.octoprint_filament_used_total and the
|
||
daily/weekly/monthly filament meters. Do not revert to success-only.
|
||
rationale: With "capture successful jobs only", cancelled/failed prints (e.g. 2026-08-14
|
||
11:09 and 16:32) never entered OctoPrint's history, so no filament usage reached HA
|
||
at all — the gap was OctoPrint-side, not an HA integration issue.
|
||
Sensor.octoprint_filament_used_total only updates on prints OctoPrint records.
|
||
entities:
|
||
- sensor.octoprint_filament_used_total
|
||
- sensor.octoprint_filament_daily
|
||
- sensor.octoprint_filament_weekly
|
||
- sensor.octoprint_filament_monthly
|
||
integrations:
|
||
- octoprint
|
||
status: superseded
|
||
superseded_by: 2026-08-14-octoprint-printjobhistory-set-to-2
|
||
- id: 2026-08-14-octoprint-printjobhistory-set-to-2
|
||
date: 2026-08-14
|
||
title: OctoPrint PrintJobHistory set to capture all jobs (not just successful)
|
||
decision: OctoPrint's PrintJobHistory plugin is set to capture ALL jobs (success +
|
||
failed/cancelled), not "success jobs only". Failed/cancelled prints are now recorded
|
||
so their filament usage flows into sensor.octoprint_filament_used_total and the
|
||
daily/weekly/monthly filament meters. Do not revert to success-only.
|
||
rationale: With "capture successful jobs only", cancelled/failed prints (e.g. 2026-08-14
|
||
11:09 and 16:32) never entered OctoPrint's history, so no filament usage reached HA
|
||
at all — the gap was OctoPrint-side, not an HA integration issue.
|
||
Sensor.octoprint_filament_used_total only updates on prints OctoPrint records.
|
||
entities:
|
||
- sensor.octoprint_filament_used_total
|
||
- sensor.octoprint_filament_daily
|
||
- sensor.octoprint_filament_weekly
|
||
- sensor.octoprint_filament_monthly
|
||
integrations:
|
||
- octoprint
|
||
pin: true
|
||
status: active
|
||
- id: 2026-08-16-matter-outage-2026-08-16-was-thread
|
||
date: 2026-08-16
|
||
title: Matter outage 2026-08-16 was Thread mesh re-forming, not host firewall
|
||
decision: The 2026-08-16 Matter node outages were traced to the external Thread border
|
||
router's mesh re-forming (mesh prefix rotated fdfb:c653:60c7 → fd25:f6c0:5149). NOT
|
||
a host routing/firewall issue. Devices self-heal once the matter server re-learns
|
||
the new operational addresses; a per-device forced reconnect accelerates it.
|
||
rationale: "Evidence: all 7 nodes rotated to the new fd25 prefix between 03:28–03:36; the
|
||
host routed live Matter traffic fine throughout (office button session, scroll-wheel
|
||
button events); Thread integration shows 0 border routers and no OTBR add-on exists,
|
||
so routing depends on an external border router. Do not chase firewall/iptables
|
||
theories for this failure signature."
|
||
integrations:
|
||
- matter
|
||
- thread
|
||
status: active
|