Task card for this chapter
Think of the KNXD Add-on as a translation desk ready to move into your building. Before opening it, confirm administrative permissions, backups, sources, artifact provenance, and the stop procedure. This chapter covers checks only: it does not add the repository, install or start the Add-on, or collect live-environment values.
- Purpose
- Complete a pre-installation checklist that does not include environmental data, and obtain a judgment of "can enter Chapter 4" or "stop and obtain the missing evidence first."
- Prepare
- Be able to sign in to Home Assistant and know who has Add-on management rights.
- Time
- About 15 minutes
- System change
- Do not modify Home Assistant; perform only a preflight review without live values.
- Expected result
- Classify all eight checks and clearly conclude that installation remains blocked while this site lacks an approved artifact digest.
- Stop conditions
- A usable backup cannot be created or confirmed.
- The task requires disclosure of a host, address, USB serial number, credential, or device path.
First keep the boundaries between data and operations
The checklist only records categories and placeholder marks, such as "Administrative permissions: Compliant" or "Network planning: Unknown". Don't replace live values with abbreviations that appear anonymous but can still be traced back to the environment.
May not be copied or shared: Host name, IP, KNX individual address, group address, USB serial number, account, password, token, certificate and device path. When you see these contents, just mark them as "masked" or "unknown" and do not post them to documents, screenshots, chats or issues.
This chapter does not send a KNX telegram or perform group writes. Group reads, ETS programming or downloads that write engineering designs to devices, and physical control are also prohibited. Any check that requires wiring, powering on a device, or testing equipment response is outside this chapter.
Understanding preflight with the door opening checklist
The building counter will not open the door just because the sign is up. It first needs to confirm who is responsible, whether it can be returned to its original condition, and which type of entrance the delivery will take. The same goes for KNXD Add-on.
Source, Archive and Delivery Route
Think of it this way: Repository is the designated library, commit is the exact archive number, and artifact digest is the fingerprint of the sealed box sent to the site; the three must be connected with a source-to-build attestation. The interface type only states which entrance the goods will go through, without writing the house number and key number.
Formal term:software repository, Git commit, artifact/image digest, source-to-build attestation and interface class.
How this chapter uses it: Only the approval certificate and the interface category's respective compliant/non-compliant/unknown status are recorded; the device path, serial number, IP or any address is not recorded. Store version text cannot replace immutable artifact digest and source-to-build attestation.
Prepare a value-free checklist
Create an eight-row checklist: Home Assistant installation type, administrative rights, Home Assistant backup, source and version, interface category, network planning, stop conditions, and restore decision. For each row, select only "Met", "Not met", or "Unknown", and add a description that contains no live values. The source and version columns must both check the source lock, the approved artifact/image digest, and the source-to-build attestation that ties that digest to the pinned commit.
- The installation type only records "Supports Add-on management" or "Pending confirmation", but does not record the host information.
- The permissions only record whether the role can manage Add-on, not the account number or login information.
- The backup only records whether the time range and coverage have been verified, and no files or names are attached.
- The interface and network only record the solution type and whether it has been confirmed by the person in charge, but do not record any endpoint or identification value.
Complete safety preflight item by item
- Confirm the Home Assistant installation type. Only determine whether the current environment provides an Add-on management interface. If you are not sure or the screen is different, mark "Unknown" and stop. Do not use other host methods to bypass it.
- Confirm administrative rights. Have an authorized administrator manually verify that you can install, start, and stop the Add-on. Stop if the permissions are unclear and do not borrow or share credentials.
- Confirm the backup or recovery point. Manually verify the timing, coverage, and restore responsibility of Home Assistant backups. Do not proceed with the installation without a backup that illustrates the scope.
- Check the source and version. The expected repository (specified software library) identity is
da-anda/hass-io-addons, the site source lock is fixed at commit (exact source revision) 60d4a702e2011e75c90a0f1012dfbd916eb24ce0, the source version boundary is Add-on 0.6.1. You must also obtain approved artifact/image digest and source-to-build attestation to prove that the image to be installed was built from this pinned source. The store shows that 0.6.1 cannot complete this proof. This site currently has no approved digest, so this column should be recorded as "Unknown", and the installation is still blocked.
- Confirm the interface category. Only the responsible person may select a category such as "USB, serial, network, or undecided." Do not select a driver (interface communication method); leave the device, endpoint, and KNX-address fields blank.
- Confirm the isolation plan. Record only whether there is a non-production Home Assistant test instance, no KNX/USB/device mapping, a disconnected physical bus, limited network exposure, assigned backup/restore roles, and an authorized administrator present. If anything is unknown, stop before adding to the repository and installing; do not scan the network, test endpoints, or log IPs to fill in forms.
- Write down the stopping condition. At a minimum, this includes version inconsistencies, unclear backups, identification values, unexpected interface connections, unexpected program behavior, and any physical equipment reactions.
- Write down the restore decision. Distinguish between "Stop Add-on" and "Restore Home Assistant Backup". Specify who will make the decision and what scope of change will be handled; don’t assume stopping equals restoring.
Completion check
Only when all eight rows are marked “met” may you proceed to Chapter 4’s conditional section. If any column is "Unknown" or "Not Compliant", stop. Do not add the repository or attempt installation merely to find the answer. Since this site currently has no approved artifact/image digest, the “source and version” item must remain unknown at this stage; you can read Chapter 4, but cannot perform lifecycle actions.
- The installation type and administrative rights are clearly classified, but the host or account information is not recorded.
- I've checked the timing and coverage of the backup and know that stopping does not equal restoring.
- I've separated the source version boundaries, artifact/image digest, and source-to-build attestation for Add-on 0.6.1; leaving it "unknown" without an approved digest.
- I only recorded the interface and network solution categories and did not copy any live values.
- I have written down the stop condition, operator and restore decision maker.
Next step: When every item is met, go to Chapter 4. If anything is missing, first review Check readiness before starting and When to stop and how to restore.
What to do when preflight is stuck
- Don't know the installation type: Please ask Home Assistant administrators to only reply whether they have Add-on management capabilities; do not ask for system screens or host information.
- Backup not found: Stop subsequent actions. First create and check the backup according to the official interface of the current Home Assistant version; this chapter does not involve guessing the button locations.
- Source or version different: Keep the "Not Conforming" category and stop. Do not apply settings declared in 0.6.1 to other versions.
- Someone asked for connection information: Refuse to copy and use categories such as "Network type, pending approval"; if you still need to provide actual values to continue, end this chapter.
- The stopping method is unclear: Read first Stop and restore entries, the manager will confirm the responsibility before repeating the preflight.
Advanced notes and FAQ
Advanced note: What judgments can be supported by fixed config.yaml?
Chapter 3 cites knxd/config.yaml from the pinned KNXD Add-on 0.6.1 commit. It supports the declared version, nine options, the interface enumeration, and field shapes. It does not support the location of controls in the current Home Assistant interface or prove the state of any local interface, network endpoint, or KNX bus.
The plain-language checklist therefore reviews the source version, the artifact to be installed, and the classification separately. The pinned config.yaml cannot prove the build source of a store image. Detailed options, INI content, and drivers are left to later chapters and are not entered during preflight.
Why don't you even copy the backup name?
The backup name may contain host or home clues. Recording only “Time and coverage checked” is enough to complete this chapter.
Do you need to know IP to do network planning?
No. In this chapter, confirm only whether there is an approved isolation plan; the actual value is not entered into the tutorial record.
Can the default interface be used directly?
No inference of field applicability can be made from the source. The interface type must be confirmed separately by the person in charge based on the hardware and security plan.
If every check passes, is KNX ready?
No. It only indicates that you can enter the Add-on lifecycle exercise without connecting to the bus, and does not demonstrate ETS, integration, group operation or physical equipment state.
Evidence and sources
Evidence class: source-bounded
Feature crosswalk: addon-options-schema
Pinned sources support only the documented scope. This page does not represent validation of any local environment, hardware, network, or KNX bus.