Marc Billow
7086b134c0
CONTRIBUTING.md gains a "Code comments" section: comment the why not the what, keep it to a sentence or two with a pointer to the load-bearing evidence, don't re-derive a sibling's already-documented reasoning, and move failed-attempt investigation logs out of inline comments. Applied that policy across the codebase: condensed sprawling module docstrings, per-entity essays, and multi-paragraph rationale blocks down to their load-bearing conclusions, while preserving the actual "why" (issue numbers, calibration evidence, gotchas, don't-guess rationale). No functional code changed — verified via diff review, ruff, ty, and the full pytest suite (1211 passed). One inline investigation log (the AC filter-reset "tried and failed" notes) moved to docs/investigations/ac-filter-reset.md rather than being deleted, per the new guideline on where that kind of record belongs.
99 lines
4.0 KiB
Python
99 lines
4.0 KiB
Python
DOMAIN = "localthings"
|
|
|
|
PLATFORMS = [
|
|
"sensor",
|
|
"binary_sensor",
|
|
"switch",
|
|
"number",
|
|
"select",
|
|
"button",
|
|
"time",
|
|
"climate",
|
|
"fan",
|
|
"water_heater",
|
|
]
|
|
|
|
CONF_HOST = "host"
|
|
CONF_PORT = "port"
|
|
CONF_CA_CERT_PEM = "ca_cert_pem"
|
|
CONF_CA_KEY_PEM = "ca_key_pem"
|
|
CONF_LEAF_CERT_PEM = "leaf_cert_pem"
|
|
CONF_LEAF_KEY_PEM = "leaf_key_pem"
|
|
|
|
# Device identity, resolved once by the config flow's probe and persisted
|
|
# on the entry (issue #236) -- what the coordinator mints registry keys
|
|
# from at __init__ time, before any poll has happened. Without them,
|
|
# anything registering before the first poll (e.g. the connection-mode
|
|
# sensor) got keyed on the IP address permanently.
|
|
#
|
|
# CONF_SERIAL is the resolved serial (registry.identity.resolve_serial's
|
|
# output, the host itself for a placeholder-serial board -- issues
|
|
# #83/#189), so it matches what _run_discovery computes on the first poll.
|
|
CONF_SERIAL = "serial"
|
|
CONF_MODEL = "model"
|
|
CONF_MANUFACTURER = "manufacturer"
|
|
CONF_DEVICE_TYPE = "device_type"
|
|
|
|
# Options-flow key (entry.options, not entry.data): lets a user override
|
|
# the device-wide remote-control-off write block for a specific device
|
|
# (issue #54). Some devices accept certain writes even while reporting
|
|
# remote control off (e.g. a washer's default detergent dosing), so the
|
|
# blanket-block assumption doesn't hold everywhere. Defaults to False
|
|
# (block stays on).
|
|
CONF_BYPASS_REMOTE_CONTROL = "bypass_remote_control_lock"
|
|
|
|
# Options-flow key: minimum change (in minutes) required before a
|
|
# hysteresis-gated timestamp sensor (currently just finish_time) reports a
|
|
# new value. Devices commonly revise their remaining-time estimate by a
|
|
# minute or two throughout a cycle, and finish_time = now() + remaining
|
|
# drifts with the poll interval between revisions -- both push a fresh
|
|
# state far more often than the estimate is meaningfully different. 0
|
|
# disables the gate.
|
|
CONF_FINISH_TIME_HYSTERESIS_MINUTES = "finish_time_hysteresis_minutes"
|
|
DEFAULT_FINISH_TIME_HYSTERESIS_MINUTES = 3
|
|
|
|
# The DTLS/CoAP local API binds somewhere in this ephemeral range,
|
|
# depending on firmware (newer builds answer on 49154/49155, older ones as
|
|
# low as 49153) -- swept for a live UDP port before the expensive DTLS
|
|
# handshake.
|
|
PROBE_PORT_RANGE = list(range(49152, 49161))
|
|
|
|
# Ports we've historically seen complete a DTLS handshake; tried first when
|
|
# more than one port in the range looks live.
|
|
PREFERRED_PROBE_PORTS = [49154, 49155]
|
|
|
|
# Per-port timeout for the cheap UDP liveness sweep. Closed ports return an
|
|
# ICMP port-unreachable almost immediately; a live-but-silent port is only
|
|
# detected by this timeout elapsing, so keep it short. Only reached as the
|
|
# fallback for when the ClientHello probe below confirms nothing.
|
|
LIVENESS_PROBE_TIMEOUT_S = 1.5
|
|
|
|
# Per-port budget for the DTLS ClientHello probe (smartthings-local >=
|
|
# 0.1.2), the primary port-detection gate. A real server answers with a
|
|
# HelloVerifyRequest in ~1 RTT; the budget only bounds how long a silent
|
|
# port takes to give up. 3s covers two retransmits on a slow LAN.
|
|
CLIENTHELLO_PROBE_TIMEOUT_S = 3.0
|
|
CLIENTHELLO_PROBE_RETRIES = 2
|
|
|
|
# The whole port range is probed at once: each stateless probe is bounded
|
|
# by CLIENTHELLO_PROBE_TIMEOUT_S (unlike a full handshake's 12s), so the
|
|
# sweep costs one probe's wall clock, not the sum of the range. Capped so a
|
|
# widened PROBE_PORT_RANGE can't spawn an unbounded thread pool.
|
|
PROBE_MAX_WORKERS = 12
|
|
|
|
# Deadline for the blockwise /device/0 GET during the config-flow probe.
|
|
# The slowest device observed returns a full dump in ~8s.
|
|
PROBE_GET_TIMEOUT_S = 10.0
|
|
|
|
# Base for the local (client-side) DTLS source port, distinct from the
|
|
# destination probe ports above -- see coordinator._local_source_port for
|
|
# why a fixed per-device source port matters. Mirrors the upstream
|
|
# smartthings-local reference bridge. Requires smartthings-local >= 0.1.1.
|
|
DTLS_LOCAL_PORT_BASE = 49700
|
|
|
|
SUMMARY_INTERVAL_S = 30.0
|
|
|
|
DEVICE_SUPPORT_ISSUE_URL = (
|
|
"https://github.com/mbillow/localthings/issues/new?template=device-support.yml"
|
|
)
|