Hub LED night mode

Hub LED night mode is a device setting on hubs that expose the hub capability with the ledNightMode control. It is off by default. When enabled, it dims hub lights after sunset while mute and fault indicators remain visible. This setting is part of the hub’s own configuration, not the home alarm mode or room lighting, and support must be detected from capability descriptors for the selected tenant and home, not from a product name.

What the setting does

ledNightMode is a settings-bound toggle under the hub capability.

When true, the hub dims its lights after sunset. Mute and fault indicators remain visible.

When false, the hub uses its normal light behavior.

This is the hub light preference, not the home alarm mode or room lighting.

Who can change it

Only authorized users can update hub settings.

Caller type	Can change ledNightMode
Household OWNER	Yes
Household MEMBER	No
Household GUEST	No
Tenant staff with INSTALLER or ADMIN	Yes
Other tenant staff	No

Respect server-returned permissions rather than assuming access from the client role alone.

Detecting support

Do not infer support from a product name.

A client should show this control only when the selected device’s capability descriptors include the hub capability and declare a writable settings control with key ledNightMode.

If the control is missing, this device has not exposed the capability. Missing controls mean this device has not exposed the capability; do not infer support from a product name.

Device-type settings are shared across brands exposing the required capabilities.

Read the current value

Use the authenticated API to fetch the selected device in the current tenant and home scope. The device’s settings document is the source for the saved preference.

Read the current value from:

• settings.hub.ledNightMode

If the field is absent, treat it as disabled by default.

Also respect:

• descriptor availability
• writable
• unavailableReason
• descriptor versions
• current reported state and operation results where relevant

Public clients must not call internal transport endpoints or bypass home authorization.

Update the setting

Update hub settings with:

• PATCH /devices/:id/settings?tenantId=...

Send a capability document containing only the setting being edited:

{ "hub": { "ledNightMode": true } }

To disable it:

{ "hub": { "ledNightMode": false } }

Send only the preference being edited. Preserve settings fields the client does not edit.

The settings endpoint merges capability documents, so you should patch only hub.ledNightMode here rather than sending a full copy of unrelated settings.

Do not substitute an endpoint command for device configuration.

Save flow and source of truth

After a successful settings update, use the returned device as the saved source of truth.

Recommended client flow:

1. Read the selected device and its capability descriptors.
2. Confirm that hub.ledNightMode exists and is writable for this device.
3. Send PATCH /devices/:id/settings?tenantId=... with only { "hub": { "ledNightMode": ... } }.
4. Wait for the saved setting.
5. Replace local state with the returned device from the response.
6. If the save fails, keep or restore the previous confirmed preference.

A failed save retains the previous preference.

Do not infer a supported action from brand, model, cached state or a successful request acknowledgement. Follow correlated operation results and current reported state.

Pending and confirmed results

Clients should distinguish pending UI from confirmed saved state.

While a save is in progress, it is valid to show a temporary pending value. If the request succeeds, update from the returned device. If it fails, revert to the last confirmed saved value.

Respect server-returned permissions, availability, versions and pending versus confirmed results.

A saved preference does not confirm that an offline hub has applied the change yet.

This matters because device settings are saved to ALYT even when the hub is not currently reachable. Local functions can keep working during a cloud outage; cloud-dependent connectors require the provider and network. For this setting, treat the API response as confirmation that the preference was saved, not proof that the hub has already applied it.

UI behavior across surfaces

The control appears only on surfaces that support hub configuration:

• Web: under hub capability settings
• iOS and Android: under device Configuration
• TV: does not change it

If your app deep-links from a notification or another device view, keep actionable notification navigation scoped to the identified device and home.

Error handling

When the update fails:

• keep the prior confirmed value
• show that the setting was not saved
• refresh the current device state if needed

Do not assume that an accepted request means the preference changed. The returned device is authoritative.

Typical client rules:

• Disable editing when the descriptor is not writable.
• Hide the control when the capability or control is absent.
• If the server rejects the update, show the previous confirmed state.
• Preserve unrelated settings fields.

Example request

PATCH /devices/123e4567-e89b-12d3-a456-426614174000/settings?tenantId=6f9d... HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "hub": {
    "ledNightMode": true
  }
}

Example response handling

On success, read the updated setting from the returned device:

{
  "thing": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "kind": "device",
    "settings": {
      "hub": {
        "ledNightMode": true
      }
    }
  }
}

Use that returned value as the confirmed state shown to the user.