Use Zigbee knowledge and bounded acquisition

ALYT lets developers inspect Zigbee knowledge for a selected home, then request bounded acquisition when the known model and acquisition category match the current home state. Catalogue access is read-only: it can show supported routes, model identity, constraints, and guidance, but it never grants physical access or execution permission. Acquisition is separate, time-bound, and rechecked against the live home before the hub starts discovery. The full brands and device catalogue, frozen converters, search indexes, and model guides stay in the existing platform knowledge service. The full-acquisition home cohort is PHYSICAL_AI_ZIGBEE_FULL_ACQUISITION_PROPERTY_IDS; it complements the existing PHYSICAL_AI_ZIGBEE_CATALOGUE_PROPERTY_IDS read cohort. Both default to empty.

Catalogue access

Use GET /integrations/device-types with tenantId, propertyId, and optional clientId for the explicit selected home. The response reads the current selected-home /integrations/device-types catalogue. Its server-composed Protocol and Device type selectors filter acquisition routes. These items describe existing routes by category, protocol, integrationId, via, and flow. A disabled home returns an empty additive catalogue. Ordinary devices and integrations still work. The ordinary property-view permission applies, including current client scope. The displayed library totals identify the current catalogue version.

Use GET /integrations/{integrationId}/supported with tenantId, propertyId, catalogue=1, and optional type, sensorKind, vendor, search, cursor, limit, modelId, and revision. The server searches the whole library before paging. limit is at most 50, and pages are bounded to 384 KiB. Canonical modelCount and brandCount come from one pinned library artifact. Aliases and white-label names are searchable without changing canonical counts. A cursor binds revision and filters; if the revision or filter changes, browsing restarts. Unsupported fields and malformed queries are refused. Existing exact guide-vendor requests keep items and nextCursor. The browser includes every brand and model in ALYT’s pinned Zigbee library on web, iOS, and Android. Web and native clients use the same catalogueConstraintLabel projection for access, original units/range/grid and enumerated values; they never infer control authority from that label. The full library picker appears directly in the acquisition flow, and there is no separate catalogue-opening link or duplicate short picker inside acquisition.

What each supported row shows

Each row includes model identity, categories, sensorKinds, declaration constraints, dynamic or interview uncertainty, supportDepth, and acquisition fields: acquisitionAllowed, acquisitionCategories, and acquisitionReason. Identification, actual interview, reporting, usable controls, UI, and physical qualification are separate depths. A library match never establishes physical qualification.

A model can expose up to 64 constraints. When there are more retained constraints, constraintsTruncated makes that explicit. Constraint data includes access, endpoint, range, step, unit, and values. Unknown runtime fields remain unknown. Writable declarations never substitute for a working capability adapter.

Guidance

Guidance is either MANUFACTURER, with the exact sourced family/model and source, or labelled CLASS guidance. CLASS guidance follows the manufacturer’s instructions and never fabricates a reset gesture. Source selection belongs to ALYT.

Starting bounded acquisition

A model selection is read-only. To acquire, send POST /integrations/{integrationId}/discover with tenantId, propertyId, mode=start, and catalogue:{revision,modelId,category}. Do not combine catalogue with pairing. The server rechecks the exact current model, home, and acquisition category, then uses the existing hub discovery owner. It refuses stale knowledge or an unavailable family before sending. On a selected Zigbee route, choose Zigbee, then a type, then the home’s Zigbee route; the existing brand/model browser opens with that type selected. The enabled acquisition category uses the existing resident MG24/CPC hub flow.

Opening requested is distinct from confirmed open. The confirmed window lasts two minutes, and mode=status never extends it. mode=stop closes through the same owner even if the catalogue is unavailable. If a start response is lost, do not queue or retry automatically. Read status and choose the next action.

Session and scope rules

Web and iOS/Android bind account, session, tenant, client, home, and integration. If the account or home changes, selection is discarded. A response from another scope is refused. Knowledge reads do not add endpoints, change rooms, or open a radio.

Successful association and actual interview remain necessary before ordinary controls appear. Corrupt artifacts keep the last valid knowledge with stale=true and acquisition disabled. A cold-start failure reports unavailable; retry reading, not acquisition.

Access boundaries

Household permissions are narrower than staff permissions. DEV credentials act in the developer sandbox. LIVE credentials work only for their own installed connector. Cloud-dependent connectors require the provider and network; local functions can keep working during a cloud outage. Never claim a cloud connector works when its cloud path is unavailable. The hub receives bounded mappings for installed household devices through its existing configuration path; it loads neither the global catalogue nor converter library into internal SRAM or PSRAM.

The A9MEM1570 and EKO01825 rows carry acquisitionTransport: "green-power". This is platform-owned pinned model knowledge, not a discover-request override. The existing discover owner resolves the exact current model, revision, and category, verifies the selected home’s cohort and permission, and derives the transport. The existing hub connector checks fresh reported Zigbee readiness and greenPowerProtocol: 1 on that selected home hub before enqueueing {seconds:120,greenPower:true}. Ordinary acquisitions keep their existing payload. Status and Stop pairing use the same discovery owner without requiring a fresh catalogue; a cancelled or expired window grants no admission.

Green Power retains the 32-bit GP Source ID as its stable padded identity and actual virtual endpoint242/profile0xa1e0/cluster0x0021. It is not an ordinary endpoint1 or a short-address alias. Exact original reader identity and the observed GP interview gate read-only capability mappings. Native commissioning/reporting uses the current MG24/CPC proxy table and bounded radio job queue; it does not instantiate the retired tenant radio service, allocate a catalogue, or increase existing table capacities. Keys remain inside radio/security jobs and never enter public capabilities, context, catalogue responses, or guides. Transport acknowledgement is not acquisition readback or a physical measurement.