Technical: Badges

This page is the canonical reference for badge-related sensor contracts.

Note

Dashboard surfaces may use kid-friendly labels such as Ranks for cumulative badge status and Quests for periodic badge progress. The runtime sensor contracts and configuration types still use cumulative and periodic terminology.

---

Sensor families

Badge functionality is exposed through three sensor families:

1. Badge status sensor (one per assignee profile)
2. Badge progress sensor (one per assignee + non-cumulative badge)
3. Badge definition sensor (one per badge definition)

Entity IDs are auto-generated by Home Assistant from unique IDs. Avoid hardcoding legacy sensor.kc_* patterns.

---

1) Badge status sensor

Intent

Represents cumulative rank/progression status for one profile.

State

• Primary state is the highest earned cumulative badge name.

Stable attributes

• current_badge_name
• highest_earned_badge_name
• next_higher_badge_name
• next_lower_badge_name
• points_to_next_badge
• badge_status (active, grace, demoted)
• cycle_points
• maintenance_points_required
• maintenance_points_remaining
• maintenance_end_date
• maintenance_grace_end_date
• last_awarded_date
• award_count

---

2) Badge progress sensor

Intent

Tracks progress for one non-cumulative badge assignment.

State

• Percentage progress (0 to 100)
• Unit: %

Stable attributes

• badge_name
• badge_type
• status (inactive, active, completed)
• target_type
• threshold_value
• recurring_frequency
• start_date
• end_date
• overall_progress
• criteria_met
• last_awarded
• award_count

---

3) Badge definition sensor

Intent

Represents badge metadata/configuration and aggregate earned count.

State

• Integer count of profiles that earned the badge.

Stable attributes

• badge_name
• description
• badge_type
• target
• reset_schedule
• required_chores
• badge_awards
• associated_achievement
• associated_challenge

Assignment attribute keys

The integration exposes the following attribution keys in the badge sensor attributes:

• assigned_user_ids (List of user UUIDs assigned to this badge)
• earned_by (List of user UUIDs who have earned this badge)

These keys are used for dashboard filtering and assignment tracking.

---

Dashboard consumption pattern

• Level/rank views read badge status sensor fields.
• Quest/progress lists read badge progress sensor fields.
• Catalog/admin views read badge definition sensor fields.

---

Automation guidance

• Match on explicit keys (badge_type, status, thresholds/progress), not display text.
• Build templates defensively for missing optional attributes.
• Prefer key-based logic over entity-id string assumptions.

---

Related docs

• Configuration: Badges overview
• Configuration: Cumulative Badges (Rank badges)
• Configuration: Periodic Badges (Quest badges)
• Advanced: Cumulative Badges (Rank badges)
• Advanced: Periodic Badges (Quest badges)

---

Last Updated: March 2026 (dashboard terminology bridge for Rank and Quest badge wording)