Integrate endpoint-qualified Zigbee controls and physical observations

ALYT exposes endpoint-qualified Zigbee controls and physical observations through normalized capability descriptors, governed proposals, and reviewed mappings. For a developer, the key rule is that the canonical Zigbee device keeps its IEEE identity, while each additional endpoint-qualified target is an additive identity scoped to that home and integration. You work against the platform target ID and its reviewed mapping revision, not a display label, first endpoint assumption, manufacturer name, or raw radio address. The full 4478 canonical original definitions are imported into platform knowledge, and the web, iOS, and Android browsers use the existing server search, facets, and paging across all brands and models. Catalogue totals are dynamic for the pinned version and are not limited to featured devices. The full library picker is part of the existing acquisition flow, so choose the model there rather than opening a separate catalogue browser.

Identity and mapping

A mapped target binds three things: the component identity, the actual observed application endpoint, and the exact mapping revision. That mapping is what can authorize writes. If the mapping is changed, ambiguous, unobserved, or unreviewed, it does not grant any new write capability. Network repair or removal belongs to the canonical device, not the additive endpoint target. The enabled acquisition category uses the existing resident MG24/CPC hub flow, while original controls and guides remain available. The whole catalogue, converters, and guides never load into hub SRAM or PSRAM; only bounded installed-device mappings use the existing configuration path. The full 4478 canonical original definitions are imported into platform knowledge, and the web, iOS, and Android browsers use the existing server search, facets, and paging across all brands and models.

ALYT keeps the platform-owned PHYSICAL_AI_ZIGBEE_GUARDED_FIRMWARE_REVISIONS allowlist in the platform configuration environment. The allowlist is not stored in hub status; hub status carries the reported revision that is compared against it. Set the allowlist to the exact reviewed clean firmware revisions, in comma-separated 7–40 character lowercase hexadecimal form. The empty default rejects every new component write. Protocol 2 alone is insufficient. Manual admission, routine packing, and governed owner use check the same current reported snapshot and platform-owned list. Model, operator, or request payloads do not supply receiver qualification. Ordinary unguarded mappings keep their existing admission rules. Withdraw the guarded cohort before removing a qualified firmware revision; preserve mappings, readings, physical IEEE identities, and existing routine history. This contract adds no hub status field, native storage, service, or database migration.

Removal impact returns the reviewed endpointIds, affected routines, securityMembership, and consent token. The token pins validated sibling identities and their security membership. If discovery or reference data changes, a new review is required before removal. Cleanup cancels queued sibling commands and removes their active routine, dashboard, widget, and security references in the same transaction.

Capability descriptors and controls

Always read the target’s capability descriptors first. A declared property keeps its access, unit, range, step, and enum values. Writable properties require both a completed mapping and current authority. Read-only properties remain observations. Only declared controls and modes are exposed through the existing command API and the shared web and phone renderers.

Do not infer a write from a sensor value or a catalog entry. Default-off household cohorts and exact mapping revisions govern additive family activation. Existing device control, routines, voice, and cloud behavior continue independently. Catalogue presence, acquisition, controls, and physical qualification remain separate.

Cover behavior

Cover position is normalized percent open. Reported position is separate from motor movement. OPEN, CLOSE, STOP, and percentage writes use the selected mapped endpoint and the model polarity.

Acknowledgement is not completion. A report may establish requested position without establishing motor stop. Preserve partial, failed, and unknown outcomes, original request deadlines, and the action/outcome ledger. Do not replay an uncertain write.

For confirmation, OPEN and CLOSE require reported 100 or 0 percent position. STOP requires actual movement-false evidence.

Thermostat behavior

Thermostat measurements and targets use normalized Celsius. Keep measured room temperature separate from setpoint. Validate the selected supported target, range, step, and mode, including ambiguity between heating and cooling targets. A reported setpoint is evidence about that setting, never proof of heating or cooling.

Standard dual occupied heating/cooling exposes become separate stable Heating target and Cooling target controls on the same actual endpoint. The heating control keeps the old component ID, while the cooling control adds a stable sourced ID; no fake endpoint is synthesized. Mode changes do not switch the page target. The original bounds and grids stay on the same actual endpoint, and the native finite query reads the opposite occupied target as signed16 plus the minimum deadband as INT8 tenths Celsius before dispatch. The query must match the typed query sequence, use the 10–25 tenths-degrees-Celsius gap, and return a fresh complete actual response. Missing, partial, duplicate, malformed, wrong-namespace, changed-guard, unsafe-target, authority, map, or expiry evidence is refused. The platform does not clamp or write the opposite setting. The original 4.5-second query/write/readback/final APS fence remains in force. Target physical reports after dispatch confirm the setting, not HVAC operation.

Library-exposed limits are declared constraints, not measured hardware preferences. The platform keeps its conservative thermostat policy until actual device limits are available. Declared thermostat ranges narrow the existing 18–27 Celsius policy on the device’s original step grid. Web, phone, context validation, operator admission, and the native receiver use that same grid. Source source16–45/1 is narrowed to 18–27 whole degrees, with available Off, Heat, Dry, and Fan modes only.

Changing Celsius or Fahrenheit presentation does not change the normalized Celsius contract. Mapped thermostat display conversion preserves the exact step origin: a Celsius range of 18.25–26.75 with a 0.5 step becomes 64.85–80.15 Fahrenheit with a 0.9 step. Convert the selected value back to normalized Celsius before admission.

A reported setpoint is confirmation only when it matches the requested setpoint or mode. Thermostat confirmation never uses room temperature. Current preset limits reject without clamping; unknown, duplicate, wrong type, preset change, current-map, permission withdrawal, or expiry reject. The full 4478 canonical original definitions are imported into platform knowledge, and the web, iOS, and Android browsers use the existing server search, facets, and paging across all brands and models.

Measurements and observations

Measurement fields keep separate units: temperature Celsius, humidity percent, light level lux, CO2 ppm, and PM2.5 micrograms per cubic metre. VOC needs its own declared and verified conversion; do not substitute an ambiguous pollutant number. Fan presets confirm reported settings, not measured airflow; meter W/kWh/V/A and phase/cumulative fields retain their original meanings.

Attribute sentinels, non-finite values, and unverified unit conversions remain unknown. Field observations keep their own provenance and freshness. Partial and battery-only updates do not refresh unrelated measurements. Replay and retained state are not fresh physical evidence. DP5 signed temperature and W100 measured temperature are actual reports; W100 display and cache defaults are not connected-heater evidence.

Alarm inputs

IAS water, smoke, and carbon-monoxide inputs are read-only alarm facts. Alarm1, Alarm2, tamper, and low battery are distinct bits. A mapper must prove the exact converter semantics rather than combining unused alarm bits.

Do not manufacture an alarm-clear timestamp or a siren output. Existing security authority remains with ALYT’s explicit enrolment and deterministic policies.

Testing and recipe generation

Test integrations with model-independent library, interview, report, and execution adapters. Bind fixture evidence to the converter version, mapping revision, adapter, and actual source inputs. Keep software tests, signed native installation, deployed hub image, and observed device qualification separate.

An AI client proposes bounded normalized intent. It cannot select byte encodings, bypass fences, alter permissions, or declare a physical result. New conditional AR331 and AR331Pro target writes require a newly received typed preset after actual query transmission; receive-order freshness, not device timestamp or sequence proof, is required.

ALYT compiles the pinned converter library into versioned native recipes. Modern factories retain their actual captured arguments and source identity; equal JavaScript function bodies do not imply equal closure settings. Standard recipes prove the exact unit, cluster, alarm bit, and model. Whole catalogue, converters, and guides stay outside hub SRAM or PSRAM, with only bounded installed-device mappings stored through existing configuration.

Tuya datapoints retain their exact declared id, converter, scale, datatype, enum, and cover polarity. Derived or null ids, ambiguous properties, and unknown custom closures do not grant native write. Tuya Zigbee datapoints use the existing Zigbee frame owner, separately from cloud or LAN Tuya connections. Regenerate and check recipe artifacts with the pinned library; changes alter the reviewed mapping identity.

Proposals, approval, and authority

Governed cover and thermostat actions use the existing proposal, approval, effect ledger, owner fence, and outcome interfaces. The native receiver advertises agent-fence protocol 2 for these families; protocol 1 retains existing light compatibility. Yuba light and climate stay separate, with original private UINT64 target and mode masks and readback using the existing decoder and job.

A lease binds current household scope, selected component, physical parent, reviewed revision, declared access, exact normalized capability, command, value, and finite authority. Preparation, publish, and final send recheck the current owner. A changed mapping, recovery operation, withdrawn cohort, or newer operator action withdraws unsent work. Query and target ACK do not confirm the result.

The existing finite query/write/readback window and the final-send plus physical-confirmation owner remain in force for all governed control paths. Household review displays the original capability and command; momentary actions carry no setting value and stay fixed during value correction. Saving any correction captures fresh context and requires new approval.

Command completion and read behavior

New component commands require the current recorded physical hub’s protocol-2 receiver report. Native packing and manual admission check that owner; no different hub in the household substitutes for it. The existing read and poll owners ask a reviewed new family target only when its actual interview reports Router. EndDevice and unknown roles retain the existing wake-hold behavior; a mains label supplies no authority.

Tuya reads use the existing bounded Zigbee query path and never replay a write to obtain a result. When a mapping revision, endpoint, tuple recipe, or declared capability changes, the native table invalidates affected family readings rather than treating retained values as current translation evidence. Unchanged mappings retain their evidence.

Room and unassigned projections withdraw new writable descriptors when their household cohort or reviewed revision is withdrawn. Stable identities and historical observations remain intact. A manual component command completes only from its fresh report delta; battery-only changes, cached merged position, and transport acknowledgement cannot confirm it. The original finite query/write/readback window and the existing final-send and physical-confirmation owner remain in force.

The same fresh-read rule applies to standard dual-target thermostat writes and calibration-dependent cover mappings: physical reports after dispatch confirm the setting, not device motion or HVAC operation. Acquisition does not calibrate or move a motor.

Correction workflow

Household proposal correction uses the target’s normalized declared constraints for numeric bounds, original step, and permitted options. Those hints grant no execution authority. Saving re-captures current context, validates the entire unchanged target manifest, and produces a new unapproved plan.

Current cohort or mapping withdrawal denies new writes while retaining readings and history. For developers, this means you can continue to inspect state and historical evidence after a withdrawal, but you cannot use withdrawn context to authorize a new physical action.

The Aqara ZNMHLDJ01LM, ZNCLDJ01LM, and C200 percentage writer binds zigbee.cover.calibration.lumi to the exact original calibration reader and the actual interviewed FCC0 private cluster. The finite query reads attribute 0426 as UINT8 under manufacturer 115F and requires status 2 for fully calibrated. SONOFF MINI-ZBRBS binds zigbee.cover.calibration.sonoff to the exact original reader, the actual interviewed FC11 cluster, and standard-header attribute 5012 as UINT8, requiring status 1. Missing private-cluster evidence or removed source readers withdraw the percentage writer. Calibration toggles, settings, and travel-time values do not qualify as calibrated-state evidence. The same finite-job fields, live guard, send, deadline, and qualification list apply; no new native RAM member, scalar table, database service, status field, catalogue allocation, or hub SRAM/PSRAM is introduced.