Zones

A zone records which lights FLARE has set, usually for one room. FLARE uses it to tell its own changes from anyone else’s, so it can leave alone a light you’ve changed yourself. Zones are under Settings → Devices & Services → FLARE → Zones.

On this page

A zone’s entities
Override protection
The zone’s events
Inspecting tracked state
When zones tick

A zone’s entities

Entity	Description
`sensor.<name>_flare_claims`	Where FLARE stores the zone’s claims. The state is the number of lights tracked; the `claims` attribute has each light’s claims. Don’t disable it: without it the zone can’t record anything.
`sensor.<name>_flare_controlled`	The number of the zone’s lights FLARE is setting. For information only.
`sensor.<name>_flare_overridden`	The number of the zone’s lights something else has changed. For information only.
`button.<name>_flare_clear`	Discards every claim in the zone.

The two counts are recorded in history, with long-term statistics, but the claims attribute isn’t. A light that’s unavailable or has no claim isn’t included in either count.

Clear discards every claim in the zone, not only for the overridden lights. FLARE then sets all of the zone’s lights again on their next update.

Override protection

When flare.apply_lighting or flare.turn_off changes a light, it records a claim on the light in the zone the call names. On the next update, FLARE compares the light with its claim. If the light still shows what FLARE set, FLARE carries on setting it. If it doesn’t, something else has changed it, and FLARE leaves it alone.

A light that’s on, has no claim, and already shows what flare.apply_lighting would set isn’t changed, so FLARE claims it as it is. After a Clear, for example, the zone’s lights are claimed again on their next update even if none of them needs changing.

The blueprint passes its Zone input with every call. If you call the services yourself, pass the zone as zone_device_id:

action: flare.apply_lighting
data:
  entities: [light.kitchen_1, light.kitchen_2]
  brightness: 200
  color_temp_kelvin: 3200
  transition: 2
  zone_device_id: "{{ device_id('sensor.kitchen_flare_claims') }}"

Without zone_device_id, apply_lighting, turn_off and compute_lighting_groups set the lights but record nothing, and don’t leave any light alone.
claims_check, claims_record, claims_clear and claims_override require zone_device_id.
A zone_device_id that isn’t one of your zones is an error.
Calls naming the same zone share its claims. To keep two automations’ lights separate, give them different zones.
force: true sets lights even if something else has changed them, and records the claim.
A light FLARE has no claim on is free for FLARE to set, so a change your own automation makes to one isn’t left alone unless you mark it with flare.claims_override.

The two claims

Each tracked light has two claims:

latest: the last change FLARE sent to the light.
observed: a change FLARE has seen the light report. On its next update, if the light reports latest’s context, FLARE promotes latest to observed.

A light matching either claim is FLARE’s. So a change that never reaches the light, such as a dropped Zigbee command, doesn’t make FLARE treat the light as changed by someone else; the light still matches observed.

A light matches a claim if it reports the context of that claim’s change, or the values in it. Values are needed because Home Assistant drops a change’s context after five seconds, and some bulbs take longer than that to report back.

Claims are kept across a restart. After a restart every light has a new context, so restored claims are matched by values only: a light still showing what FLARE set is FLARE’s, and any other light is left alone.

Turning a light off counts

Turning a light off yourself counts as changing it, so FLARE doesn’t turn it back on. FLARE’s own turn-offs record a claim of {"state": "off"}, which is how FLARE tells them apart from yours.

When FLARE sets a light again

A zone discards all its claims when none of its lights are on. This is what normally ends an override: once the room is dark, FLARE sets every light in it again.

A light that isn’t in the zone doesn’t count.
A light that’s unavailable counts as off, so one dead bulb can’t keep the zone’s claims.

A light also loses its claim when it goes unavailable, and you can discard a zone’s claims by hand with its Clear button.

A light that has just come back online, say switched on at the wall, starts at whatever it powers up as, and may miss a command sent while it boots. That isn’t counted as someone changing it: FLARE sends it again until it takes. Something changing it afterwards is.

One zone per light

If two zones set the same light, each treats the other’s changes as someone else’s, and the light stops following either. When this happens, FLARE shows a notification naming the light and the zones. It shows this once for each light, and doesn’t show it again for that light until Home Assistant restarts.

The zone’s events

A zone says when it takes its lights, when it lets them go, and when something else changes one of them. Each event is filed under the zone: entity_id is one of the zone’s entities (its Controlled or Overridden count, or Clear for a release) and device_id its device, so they appear in the zone’s Activity, on its device page. FLARE adjusting lights it already has isn’t announced.

When a zone starts controlling lights it wasn’t, such as when a room comes on, FLARE fires flare_lights_controlled once for them all, a few seconds after the first, since the bulbs report back one by one:

lights: [light.kitchen_1, light.kitchen_2]   # the lights it took
controlled: 6                                # how many it's controlling now
entity_id: sensor.kitchen_flare_controlled
zone: Kitchen
device_id: ...                               # the zone's device

Kitchen now controlling 6 lights

When a zone lets its lights go, because the room went dark or you pressed Clear, FLARE fires flare_lights_released:

lights: [light.kitchen_1, light.kitchen_2]
entity_id: button.kitchen_flare_clear
zone: Kitchen
device_id: ...

Kitchen cleared 6 lights

When something else changes one of a zone’s lights, and it stays changed for 30 seconds, FLARE fires flare_light_overridden for that light:

light: light.kitchen_1
entity_id: sensor.kitchen_flare_overridden
zone: Kitchen                        # the zone that lost the light
device_id: ...
previous_status: controlled
live_context_id: 01M11...
live: { state: on, brightness: 12, color_temp_kelvin: 6500 }   # or rgb_color, for a colour
observed: { context_id: ..., target: {...}, recorded_at: ... }
latest:   { context_id: ..., target: {...}, recorded_at: ... }

Kitchen released Kitchen 1 to something else (last asked for 255/6667, found 12/6500)

live is what the light was showing: its brightness and colour temperature, or its rgb_color if it wasn’t showing a white. A light reporting its colour as xy that’s showing a white has its colour temperature worked out from it.

It fires once when the light changes hands, not again while the light stays overridden, and not for lights that were already overridden before a restart. To trigger an automation on it:

triggers:
  - trigger: event
    event_type: flare_light_overridden

Inspecting tracked state

flare.claims_check returns each light’s status:

Status	Meaning
`controlled`	FLARE is setting it: it matches one of its claims.
`overridden`	It has matched neither claim for at least 30 seconds, so something else has changed it.
`mismatched`	It has matched neither claim for less than 30 seconds. Usually it’s FLARE’s own change still arriving, or a light just back online reporting late, so it isn’t counted or announced as overridden yet. It’s left alone meanwhile, the same as an overridden light.
`untracked`	It’s on, and has no claim, or only one FLARE hasn’t seen the light report yet. FLARE sets it as usual.
`off`	It’s off and has no claim. A light FLARE turned off is `controlled`; one someone else turned off is `overridden`.
`unavailable`	Home Assistant can’t reach it, so its claims aren’t checked. It isn’t blocked.

matched_via says which claim matched, and how: latest-context, latest-value, observed-context or observed-value.

Each claim has a recorded_at time and a context_id, which you can use to find the change in Home Assistant’s logbook. Claims that haven’t changed for a day are discarded, so a light deleted from Home Assistant stops being tracked.

When zones tick

Each zone fires a flare_tick event once per update interval, carrying the zone’s device as device_id. Zones fire one after another, in name order, a gap apart, so rooms don’t all send commands at the same time. A tick is a plain event, not an entity, so it never appears in Activity, history or the logbook. You can set the interval and the gap under FLARE → Zones → Configure:

Option	Default	Description
Update interval	1 minute	How often each zone ticks, from 1 to 60 minutes.
Gap between zones	1 second	Reduced automatically when the zones wouldn’t otherwise fit in the interval.

To run an automation on a zone’s tick:

triggers:
  - trigger: event
    event_type: flare_tick
    event_data:
      device_id: "<the zone's device ID>"

The zone’s device ID is in the address of its device page, or {{ device_id('sensor.kitchen_flare_claims') }} in the template editor.