hatchling 1.31.0 ships only .gitignore in the sdist; older releases also
bundled .hgignore. check_sdist required an exact member set including
.hgignore, so the Validate workflow's package job failed on main once CI
resolved the newer hatchling.
Require the tracked source set plus the fixed metadata files, and accept
.gitignore/.hgignore as optional members either way.
- Note the Fedora/RHEL SHA-1 crypto-policy block in Part 2 and how
setup_cert.py auto-retries / the manual update-crypto-policies remedy.
- Add dtls_probe.py to the repo-layout tree (it was referenced in three
places but missing from the file listing).
- Drop the .venv/ prefix from the Part 1 probe command so it runs against
the pip-installed package before the Part 4 venv exists.
- Expand the tests parenthetical to name the probe, port-resolution, and
cert-signing suites.
* fix(setup_cert): surface openssl errors and work around SHA-1 crypto policy
The signing step forces -sha1 (the AC14K_M chain requires SHA-1-signed
leaves), which Fedora/RHEL's default crypto policy rejects on OpenSSL
3.x. run() also swallowed stderr, so the failure surfaced as an opaque
non-zero-exit traceback with no diagnostic.
- run() now raises CommandError carrying the command and openssl stderr
- mint_cert retries signing with a scoped OPENSSL_CONF enabling
rh-allow-sha1-signatures when the first attempt fails
- main() prints the update-crypto-policies fallback on failure
Fixes#15
* test(setup_cert): cover SHA-1 signing, error surfacing, and crypto-policy retry
Regression tests for the #15 fix:
- full mint_cert flow (SHA-1 leaf, UUID SAN, custom OIDs, chain assembly)
- CommandError surfaces openssl stderr on a genuine signing failure
- signing retries via the SHA-1 override when the plain attempt is blocked
- run() raises CommandError with detail
GitHub is deprecating the Node 20 action runtime; checkout@v4,
setup-python@v5, and upload/download-artifact@v4 all run on it and
were being auto-forced to Node 24 with a warning. Bump each to its
current major (checkout@v7, setup-python@v7, upload-artifact@v7,
download-artifact@v8), all of which run natively on Node 24.
Convert em-dash prose splices to varied punctuation (periods, colons,
semicolons, commas, parens), turn **Label.**-period bullets into
**Label:** colons, drop sentence-spanning bold in "Traps to avoid", and
cut a couple of hollow intensifiers.
No content, facts, tables, code, or links changed (50/50 line diff). Left
as-is: the `## Part N —` headings (heading-anchor stability), everything
inside code/log fences, table N/A cells, and numbered-list
`**Bold** — desc` carve-outs.
A stateless-by-default DTLS ClientHello probe that classifies a host:port
as DEAD/LIVE/COMPLETED/REJECTED in ~1 RTT off the server's first flight,
sitting in front of the full handshake.
Probe (smartthings_local/protocol/dtls_probe.py):
- Stateless liveness mode (default): stops at HelloVerifyRequest and never
sends the cookie'd second ClientHello, so by RFC 6347 §4.2.1 it leaves
no association on the device — safe to run before a real connect.
- Diagnostic mode (stateless=False): drives the handshake further to
capture cipher/cert-chain/CertificateRequest or a fatal Alert, for
OCF-PKI-wall characterization (#16). Kept out of hot reconnect paths.
- Retransmit + retries: services OpenSSL's DTLS retransmit timer so a
single dropped ClientHello no longer reads as a false DEAD.
MQTT bridge (mqtt_demo):
- Stateless pre-flight gate in session_once() rejects a silent/rebooting
device or wrong port in ~3s (retries=1) instead of eating the 12s
HANDSHAKE_TIMEOUT_S per reconnect.
- OCF-band port autodiscovery when OCF_PORT is unset: races the band in
parallel and returns on the first port to answer LIVE (~1 RTT, abandoning
the dead-port probes), cached across reconnects; the stateless gate
leaves no orphan, preserving the fixed-source-port §4.2.8 invariant.
Validated on real hardware (dryer 49155 / oven 49154): parallel discovery
resolves both ports in <1s, connect with no orphan cooldown, and a wrong
pinned port rejected in ~3s.
Tests: probe behaviour (retransmit recovery, stateless single-flight
guard, silent-port flight budget, diagnostic continuation) and bridge
port-resolution (pinned gate, parallel discovery early-exit, cache).
Root-cause fix for the stale-session stall on always-on appliances (#14).
When the client dies without close_notify (crash, SIGKILL), the device
keeps an orphaned DTLS association keyed to the old 5-tuple; a reconnect
from a fresh ephemeral port presents as a brand-new peer, so the orphan
lingers until the device's own timer reaps it (observed 5-15 min).
RFC 6347 §4.2.8 covers exactly this: a ClientHello arriving on an existing
association's 5-tuple means the peer rebooted, and the server must complete
the new handshake and discard the old association. Add an optional
local_port to DtlsCoapSession that binds the UDP source port, and have the
bridge bind base+appliance-index, so every reconnect re-handshakes over the
same 5-tuple and the orphan is evicted instead of waited out.
Bench-verified on live hardware (2026-07-26): RT-OCF accepts the
same-5-tuple rehandshake (oven, dryer: handshake completes over a
crash-orphaned association, reads work immediately). The oven does not
reproduce the fridge stall even with 11 crash-orphaned OBSERVE
registrations, so fridge-side confirmation of the eviction is still needed.
Co-authored-by: vmvarga <garrysuchiy@gmail.com>
- credit @indykoning + note localthings test path for the washer row
- soften DV90T mnid grouping (mnid=0AJT confirmed on DV5000T only)
- de-speculate the same-family note now that a washer is confirmed
- Lead with the pip-installable library; frame the MQTT bridge as a
reference demo. Add a library quick-start (install, DtlsCoapSession
example, in-memory cert_pem/key_pem variant).
- Fix stale protocol/ + ocf/ references to smartthings_local/*; update
the repo-layout tree (nested package, ocf_root_ca.pem, pyproject.toml,
tests/, publish.yml); drop the non-existent auth.py.
- Correct the write-surface trap: reconciliation is a deferred poll, not
a post-write fetch-back (which itself triggered Samsung's revert).
Distinguish hardware-gated parity (power/child-lock/RC-enable) from
the open oven remote-start problem.
- Note the few write surfaces the cloud HA integration doesn't expose
(dryer course, oven setpoint). Drop the achieved collaborators-wanted
callout.
localthings mints its client cert at runtime through the HA config flow
and never writes it to disk. DtlsCoapSession only accepted cert_path/
key_path (file-based), which would have forced localthings to write its
in-memory cert/key to disk on every connect just to migrate off its
vendored copy of this transport layer.
Adds an alternate cert_pem/key_pem constructor path (ported from
localthings' own _load_pem_chain), validated so exactly one cert source
(file pair or PEM pair) is required. Existing file-path callers
(mqtt_demo, setup_cert.py) are unaffected — verified against both real
appliances with each constructor path.
Nest the two library packages under a single import namespace so they
can ship as one distribution:
protocol/ -> smartthings_local/protocol/
ocf/ -> smartthings_local/ocf/ (git mv, history preserved)
- Rewrite all imports protocol.* -> smartthings_local.protocol.*,
ocf.* -> smartthings_local.ocf.* across the ocf modules, mqtt_demo/
(bridge, descriptor, samples), and tests.
- Add pyproject.toml: dist name `smartthings-local`, hatch-vcs versioning
from v* tags, wheel ships only smartthings_local/.
- Add .github/workflows/publish.yml: build + PyPI Trusted Publishing on
v* tags (OIDC, no stored token).
- Force-include protocol/ocf_root_ca.pem via [tool.hatch.build] artifacts:
it is tracked but matches .gitignore's *.pem, so hatchling's VCS file
selection would drop it — and dtls_session.py loads it at runtime.
- Update mqtt_demo Dockerfile COPY and deploy.sh tar allowlist to the
single smartthings_local/ package.
- .gitignore: build artifacts (_version.py, dist/, *.egg-info/).
Validated: pytest tests/ (11 passed), python -m build produces sdist +
wheel with the pem bundled, fresh pip install resolves all nested imports
with the pem readable from site-packages.
Task 8's port of retry/retransmit from localthings dropped the per-attempt
timeout/retry log lines (present in coap_dtls.py) — found while gathering
real-device pacing evidence, where the missing logs made retry frequency
impossible to see. Restores both the retry and final-timeout log lines.
pace() slept the entire rate-limit interval every call regardless of how
much of it had already elapsed since the last real send (e.g. spent
processing the previous block's response). Track the last send timestamp
and only sleep the remainder, recovering time already spent between
requests without changing the enforced minimum interval.
Verified against 10.0.0.129/10.0.0.254: multi-block /device/0 fetches
still complete cleanly, faster per sweep, with the same request spacing
guarantee (patch and measurement from QuiteYellow, PR #8 review).
Ported from localthings fork: bounded per-block retransmission
(_BLOCK_MAX_ATTEMPTS/_BLOCK_ACK_TIMEOUT) instead of a single attempt
per block, SZX renegotiation tracking, and a bugfix moving
conn.send(datagram) inside the try that catches its own SSL errors.
- Add test_import_isolation.py: isolation test that copies protocol/ and ocf/
to a temp directory without mqtt_demo/ and verifies all modules import
- Add conftest.py: pytest configuration to add repo root to sys.path,
enabling tests to import protocol/ and ocf/ packages
- Add ARTIK051_REF_17K row to the tested-combinations table with a
link to aminorjourney's PR.
- New 'Firmware families — a limitation' section under Part 1
explaining that descriptors are firmware-family-specific with no
runtime feature detection, so the wrong descriptor produces
half-broken sensors rather than a clean error.
- New 'Fridge (ARTIK051)' section under Per-appliance notes with the
capability table + firmware-specific observations (port 49155,
minimal /oic/res, vestigial /hass paths, collection-resource door
model vs newer per-instance-resource fridges).
- Update config-keys reference: CLASS list gains 'fridge',
OCF_PORT defaults list gains fridge=49155.
- Suppress ConnectionError log noise from in-flight requests draining
after a session close (poll_scheduler + keepalive log at DEBUG).
- Null KeepaliveTask.on_unreachable during a forced reconnect so the
dying session's keepalive can't flip HA availability offline after
the new session is already healthy. Ported into PR #5's
_maybe_force_reconnect flow.
Drops the _session_stop / publish-health force-close mechanism from
the original PR — PR #5's last_success_ts + _maybe_force_reconnect
already covers the 'session dead, restart it' goal via a different
path, and running both means two paths force-closing the same session
on the same failure.
- Full resource map discovered via live CoAP-DTLS session against
ARTIK051_REF_17K fridge-freezer (firmware DA-REF-ART-COMMON-1_20201124)
- seed_path: /device/0 (returns 32 links including hidden appliance resources)
- Entities: fridge/freezer temp + setpoints, 3x door sensors (fridge,
freezer, convertible zone), power (W), energy (kWh, total_increasing),
water filter usage/status, ice maker, rapid fridge/freeze, sabbath mode
- Port: 49155 (not 49154)
First known public documentation of this firmware's local CoAP-DTLS
resource layout.
Jason Morcos