Severity on the pass.

What severity is

Patrimony is a monitor, not a control surface. Each mapped line on the boarding-pass document carries a severity: how seriously that line should read on the principal’s phone.

Severity is decided in the house, by the Patrimony Collection custom component, when it builds the presentation document. The iPhone does not re-guess severity from temperatures, lock states, or other values. If a cellar at 18 °C should look calm, Home Assistant must say so.

There are exactly three ranks:

Rank	Meaning on the pass	Typical feel
ok	Quiet	All right
attention	Needs a look	Something to check when convenient
alert	Alert	Needs attention now

Unknown ranks are never invented on the wire. The component only emits those three.

The house badge

The phone shows one house-level line — All secure, Needs a look, or Alert.

That badge is not a separate field from Home Assistant. It is the maximum severity across every item on every card:

• alert beats attention beats ok
• A card with no items counts as ok
• Empty house (no items) → All secure

Where it is decided

In the custom component, each mapping row becomes an item in mapping.py:

1. Read the Home Assistant entity (and optional attribute)
2. Shape the value (enum, number, bool, text — or null when unknown)
3. Call decide_severity with the row’s severity_mode (default auto)
4. Emit severity on the item; strip entity_id before anything leaves the house

Integrators set severity on the row in the mapping UI (or mapping file), not on the phone.

Default: auto

Leave severity_mode at auto unless the house needs a deliberate override. Auto uses the entity’s domain, and where useful its device_class, plus a few kind heuristics.

Alarm panel (alarm_control_panel)

HA state	Severity
armed_*	ok
disarmed	attention
pending / arming / disarming	attention
triggered	alert

Lock (lock)

HA state	Severity
locked	ok
unlocked	ok
jammed / locking / unlocking / other	attention (value may show as empty)

Locked and unlocked are both calm by default: the pass shows status, not “problem.” Use an override if this residence should treat an unlocked door as watchful.

Door / window / garage

binary_sensor with those device classes:

Sense	Severity
Closed (off)	ok
Open (on)	attention

Smoke, gas, CO, heat, safety, problem, tamper

Sense	Severity
Clear (off)	ok
Detected (on)	alert

Network / connectivity

Sense	Severity
Connected / on	ok
Down / off	attention

Weather

Severe conditions (for example lightning, hail, exceptional) → alert. Windy / heavy snow-type conditions → attention. Ordinary sunny / cloudy / clear → ok. Outdoor temperature as a bare number without ranges stays ok under auto.

Everything else with a real value → ok under auto.

Per-row overrides

Set severity_mode on a single mapping when auto is wrong for that house.

ok_when_on

Boolean (or lock polarity: unlocked counts as “on”).

• On → ok
• Off → attention

Use for: Guest Wi‑Fi that should stay up; a link that must be connected.

ok_when_off

Inverse of the above.

• Off → ok
• On → attention

Use for: A contact that should stay closed when auto’s door heuristic is not applied, or a “fault” binary you want calm only when clear.

binary_alert_on

• On → alert
• Off → ok

Use for: Smoke or panic-style binaries when you want the loudest rank on trip, even if auto would already do so; or any binary that must never look merely “watchful” when true.

enum_map

Map raw HA states into lists on the row:

• ok_states
• attention_states
• alert_states

First matching bucket wins (alert list is checked before attention before ok). Unlisted states → attention.

Use for: Alarm or mode entities whose state names are site-specific, or climate HVAC modes you care about by name.

number_range

For numeric values (indoor temperature, cellar humidity, and similar):

1. Inside [ok_min, ok_max] → ok
2. Else inside [attention_min, attention_max] → attention
3. Else, if an ok band was configured → alert
4. Non-numeric → attention

Use for: Climate and cellar bands tuned to that residence. Example: ok 18–24 °C, attention 10–28 °C, outside that → alert.

fixed

Always emit the chosen fixed_severity (ok, attention, or alert).

Use for: Static lines, notepad-style placeholders, or a line that must never change with the entity. Missing or unknown values do not force attention when mode is fixed.

Unknown and missing values

If the value cannot be shown (null), or Home Assistant reports unknown / unavailable (and similar):

• Severity becomes attention — fail visible, not silent green
• Exception: mode fixed, which keeps the integrator’s chosen rank

Broken or missing entity mappings still produce a line with an empty value and attention, so the principal sees that something is off the map.

Practical guidance for a new house

1. Map first, tune second. Add the lines the principal should see. Leave most rows on auto.
2. Walk the pass once. Armed house, closed doors, clear smoke, comfortable climate should read All secure. If one noisy sensor keeps the badge on Needs a look, fix that row — don’t train the principal to ignore the badge.
3. Prefer ranges on climate. Auto will not invent comfort bands. Set number_range for indoor (and cellar) temperatures that matter for this property.
4. Network lines want a polarity. Guest Wi‑Fi and WAN checks usually want ok_when_on.
5. Locks are status by default. Both Locked and Unlocked are ok under auto. Only override if this house’s brief says an unlocked entry should raise the badge.
6. Smoke and life-safety stay loud. Prefer auto or binary_alert_on. Do not fixed them to ok.
7. One bad line raises the house. Remember max-rank: a single alert item makes the whole house Alert.
8. Never put secrets on the pass. Severity is about status language. Do not map tokens, URLs with credentials, or entity ids onto labels or values.

When auto and a careful override still disagree with the brief, write to us with the entity type and the intended quiet / watchful / urgent behaviour — not with tunnel tokens or pairing material.

Privacy note

Live state stays on that residence’s Home Assistant. Severity travels only as ok / attention / alert on presentation items. Entity ids are stripped before the document is shown. See Privacy.

Short reference

Mode	When to use
auto	Default for almost every row
ok_when_on	Must be on / connected to be calm
ok_when_off	Must be off / closed to be calm
binary_alert_on	On must be urgent
enum_map	Named states → explicit ranks
number_range	Comfort / cellar numeric bands
fixed	Never changes with the entity

House badge = max item severity. Offline / Stale = connectivity clock, not a mapping mode.