Understand the Home Assistant KNX entity model

Chapter overview

Bottom line: Use label cards only to distinguish the roles of a Home Assistant entity, a KNX individual address, and a group address. Each card only records field roles and categories, not values, mappings, payloads, service calls, or control examples.

Purpose

Use record cards to distinguish the roles of entities, individual addresses and group addresses, without recording values or mappings.

Prepare

A few blank cards and the offline worksheet for Chapter 14; no Home Assistant or KNX material required.

Time

About 20 minutes

System change

No Home Assistant entities or group settings are created; only entity models are organized offline.

Expected result

Explain why entities, individual addresses, and group addresses are not interchangeable while recording only field roles and categories, never values or mappings.

Stop conditions

• The task requires providing or guessing a real individual address, group address, or home-device identifier.
• Creating entities, reading or writing groups, transmitting telegrams, and controlling physical equipment are prohibited.

Scope and safety boundaries

Cards only hold concept tags. Do not include identification strings, address values, corresponding values, mappings, data contents, payloads, configurations, control or service calls, nor any control context of the physical equipment.

Do not add the repository or install or start the Add-on. Work outside this chapter may be evaluated only with complete isolation, written approval, an approved immutable artifact/image digest, and source-to-build attestation; this chapter grants no authorization.

Group reads must not be automated. Group writes, telegram transmission, ETS programming or downloads, and physical control are prohibited. Cards do not certify any behavior or result for a Home Assistant entity, integration, KNX bus, ETS project, or device.

Core concepts

Even if the label text is clear, the field value, mapping, data direction, type, or state cannot be guessed from the name. In the absence of authorization evidence, always leave "pending confirmation".

Preparation and prerequisites

Draw only four spaces on each blank card. Don't imitate the settings screen of Home Assistant or KNX.

• Purpose label: write only general software usage.
• Data semantics: Just write "pending source confirmation".
• Field role: Record only the entity, device-identity, or shared-communication-topic classification; do not record any mapping.
• Evidence status: Use only “supported by a pinned source,” “pending confirmation,” or “not applicable.”
• At the end of the card page: write "Cannot be imported, cannot be called, and cannot be controlled".

If the general purpose also reveals home, room, person, or device information, switch to a more abstract label. You do not need to add examples to make the card look complete.

Steps

The finished product is an offline classification card, not an entity list.

1. Create purpose cards. Put only one general purpose per card and avoid family, room, equipment or person names.
2. Add data semantics. Record the type of meaning needed for the model; if there is no support from the pinned source, write "to be confirmed by the source".
3. Add the field-role section. Only classify as entity, device identity or shared communication topic role, do not write any value, mapping, direction, content or format.
4. Add the evidence-status field. Mark the file concept and Core version metadata separately, and do not write the two as execution evidence.
5. Do a de-identification check. Remove identification strings, home contexts, payloads, calls, configuration structures, and any control hints.
6. Close the card set. Write "Only for paper review; physical, integration, and bus status unknown" on the entire stack of cards.

Verification and evidence

Once you can distinguish the entity and device identities, shared communication topics and evidence at a glance, you are done. Any fields that require guesswork should remain pending confirmation.

• I can explain that the entity is the user-facing record card/semantic object, the individual address is the identity of a KNX device, and the group address is the shared communication topic that KNX is designed to use.
• I know that the three are not interchangeable. Each card only records the purpose, data semantics, field role and evidence status.
• All purposes use de-identified generic labels.
• Cards have no address values, mappings, identifiers, payloads, service calls, configuration structures, or control examples.
• Names are not to be relied upon as evidence of data direction, type, or site status.
• I didn't create the entity. I'm not allowed to perform group actions, send telegrams, or control devices.

Next step: Go to Chapter 16, perform safety classification before any action occurs.

Troubleshooting

• A label resembles a live field name: Change to general use, removing family, space, equipment and people clues.
• Someone wants to infer data meaning from a name: Replace the inference with "pending source confirmation." Names are not evidence of type.
• A value appears in the field-role section, mapping, or direction: Remove immediately, leaving only categories for entities, device identities, or shared communication topics.
• The card looks ready to import: Remove the setting shape and order, and add the unexecutable mark.
• Someone requests a service call or control example: Refuse. This chapter only deals with offline models.
• Screen status is treated as bus evidence: Limit the conclusion to a software observation; this chapter provides no live-environment results.

FAQ