Home Security device and routine integration

Home Security device and routine integration is not released. This page describes the current developer-facing behavior for device modeling, household API use, lock-driven arming and disarming, outputs, and routines. In Home Security, protection depends on reported capabilities, confirmed state, current authorization, and recoverable output changes. Local functions can keep working during a cloud outage; cloud-dependent connectors require the provider and network.

Model devices by what they report

Security enrollment is based on capabilities and explicitly supported feature aliases, not a device name, room name, manufacturer name, or IP address.

Eligible families are cameras, motion sensors, contact sensors, vibration sensors, locks, and sirens. Important distinctions:

• A camera without a detection signal remains a camera. It does not imply motion detection.
• A lock is an access device, not an intrusion detector.
• A siren is an output, not an input that independently triggers an incident.
• Preserve every capability on a combined device. A thermostat can also report motion, and a device can report both vibration and temperature.
• Preserve sensor.vibration as a distinct capability. Do not translate a generic detected boolean into motion.

Security membership is separate from normal room membership. Household selection supports auto, include, and exclude.

• auto follows recognized capabilities.
• include is the homeowner’s manual fallback.
• exclude persists through rediscovery.

If your connector refreshes features, preserve endpoint identity and do not overwrite the household’s security selection.

Security exclusion or security being OFF does not disable ordinary routine triggers. Newly discovered devices are considered for the next arming decision, while the current active generation stays frozen until the next arm cycle. Disabled, unknown, and unavailable sensors must be shown honestly before arming.

Use stable tenant, property, integration, and endpoint identity in reports and commands. An address is transport information, never authority. An unassigned endpoint needs an unambiguous current home before it can participate.

Modes and confirmed state

Clients should treat requested state and confirmed state separately.

Mode	Detection
Away	All selected supported detection signals
Home	Selected contact and vibration perimeter signals
Sleep	Selected signals outside explicitly chosen sleeping rooms
OFF	No zones detect an intrusion

Rules that matter:

• The configured exit countdown for Away applies only when arming from OFF.
• Changing an already armed mode to Away commits coverage immediately.
• Failed arming checks leave the previous mode and configuration unchanged.
• requestedMode does not mean protection is active.
• Clients display requested and confirmed modes separately, including OFF.
• A repeated mode request must reuse the same body and UUID. Reusing that UUID for another action is rejected.
• A stale generation cannot turn off a newer armed period.
• OFF does not wait for device inventory or runtime readiness.

A responding process does not prove protection. The household view can retain its confirmed mode while reporting degraded or runtime unavailable when processing or frozen sensor coverage cannot be confirmed. Unconfirmed signals are not counted as confirmed armed coverage.

Household API workflow

Household APIs are under /home-security/:propertyId and require explicit tenantId.

Available operations include:

• read status
• POST /mode
• PATCH /settings
• PUT /devices/:kind/:id
• incident history
• POST /incidents/:id/acknowledge

Use the published typed contract for exact request and response shapes.

Arming uses the reviewed revision and generation, a UUID request ID, and explicit detector bypasses. A bypass lasts only for that armed period.

Permissions and access boundaries:

• Ordinary household members can control the mode.
• Configuration changes require an owner, OFF, and completed restoration.
• Current household access is checked again when actions execute.
• Developer DEV/LIVE keys, installer access, ordinary device grants, and connector service credentials do not grant Home Security control.
• TV access requires explicit current security delegation.
• A phone widget cannot acquire security authority through a generic device command or nested routine.

Lock events, prompts, and disarming

Only a verified external-keypad lock creates the prompt to arm. It never arms automatically.

Disarming behavior:

• A successful verified keypad-code unlock on any lock in the home turns all zones OFF, even if that lock is excluded from detection.
• A confirmed mechanical unlock from inside also turns all zones OFF whenever perimeter detectors are armed.
• This applies according to effective coverage in Away, Home, and Sleep.

Do not promote ambiguous events into stronger ones. Ambiguous manual unlocking, an outside mechanical key, remote commands, and failed codes do not become inside or keypad events.

For ingestion, use the current raw event and documented installed-model semantics. Do not infer a security edge from retained MQTT state, replayed discovery, merged stale attributes, or a command acknowledgement.

Event reporting requirements

Verify actual event delivery, not only discovery.

Use stable event identity, source occurrence time, and arrival time. Deduplicate safely. Out-of-order contact and unlock handling belongs to the evaluator, not the client.

Never store:

• PIN values
• raw credential-bearing bodies
• private media URLs

Newly enabled signals start fresh. Equal-time or earlier events cannot trigger them. Turning security OFF and rearming resets the period.

Outputs, acknowledgement, and restoration

Alarm outputs are recoverable state changes.

Before changing a light, speaker, or siren, ALYT preserves its native original state and requires later restoration. Each actual transport write rechecks current ownership. An old alarm command must be refused after OFF. Timeout is not success, and unknown outcomes still keep a recovery obligation.

acknowledgement is separate from turning the system OFF and belongs to one resident.

Sonos alarm output uses eligible rooms at 50% volume, alternating a siren with a fixed deterrent recording. Existing grouping, volume, mute, source, transport, and position remain subject to restoration. If source recovery is unsupported, it must not be reported as restored.

Night lights flash at full intensity only after sunset and before sunrise for the home’s location and timezone. OFF restores native color, intensity, and original on or off state.

A stopped alarm can still own an unrestored original. Mutations that would strand an outstanding original return HTTP 409 with an actionable recovery message. Preserve the target and connection, resolve restoration, then retry. Do not automate delete and reconnect as recovery.

Routines and security authority

Route UI and routine mode requests through the same Home Security authority. Do not write an alarm mode directly from a connector, client, or generic HTTP routine action.

A typed security routine action exists as {kind:"security",mode}.

Rules to keep:

• One authority controls a home.
• Activating a dedicated security-system connector must first turn off built-in evaluation, stop its effects, and complete restoration before control transfers.
• Connector failure cannot silently reactivate built-in arming.
• Two alarm engines must not run at once.
• Switching back requires an explicit reviewed choice.

Ordinary room and device behavior remains available under its usual permissions.

Hosted and local runtime boundaries

A hosted home does not gain protection because an API request succeeded. Arming requires the assigned hub’s current connection, acknowledged configuration, matching generation, and protection state.

Pending output restoration blocks a new arming claim.

There is no automatic local or cloud fallback for selected connectors. A selected local connector still requires that exact home’s available binding. A paused Sonos connector is unavailable for voice and Sonos alarm output. Never claim a cloud connector works when its cloud path is unavailable.

Limits and validation

Key Home Security hub configuration limits:

Limit	Value
Maximum size	24 KiB
Chunk size	1024 bytes
Maximum chunks	24
Detectors	200
Outputs	64
Disarmers	64

When integrating, test real ingestion, real event delivery, physical keypad behavior, confirmed mechanical unlock from inside, and complete output restoration. Synthetic UI-only checks are not enough.

This feature has no emergency dispatch or evidence-sharing integration in its current release candidate.