Confirm the KNXD add-on lifecycle safety gates

Task card for this chapter

This chapter considers the lifecycle of KNXD Add-on as "arrival, duty, shift change, and off duty". But the counter cannot be moved into the production building first: complete isolation, written approval, and proof of immutable build must be completed before being added to the repository or installed. This site currently has no approved artifact/image digest, so you can only read the conditional interface tour, but cannot actually install or start or stop it.

Purpose

Distinguish between installed, running, stopped and anonymous log evidence, and know when lifecycle operations are still blocked.

Prepare

All eight preflight checks in Chapter 3 are satisfied; the six isolation conditions, approval records and artifact provenance have been verified by authorized managers.

Time

About 20 minutes

System change

This site currently lacks an approved artifact digest, so no repository is added and the Add-on is not installed, started, or stopped. Any future exercise must first pass the complete isolated-test gate.

Expected result

Distinguish source, artifact, and process evidence, and stop before the first change whenever proof is incomplete.

Stop conditions

• Telegram transmission, group reads or writes, and physical control are prohibited.
• Unable to describe the impact of the change or how to revert it.

First confirm this chapter makes no changes

The evidence in this chapter is limited to process status and logs. In a future approved exercise, you could observe only that the Add-on is installed, the process is running or stopped, or a category of de-identified message appears in the log. A running Add-on does not prove that the KNX bus is connected and cannot establish results for ETS, the Home Assistant KNX integration, group operations, or physical control.

Do not connect to a KNX interface or bus or transmit a KNX telegram. Group reads and writes, ETS programming or downloads, and physical control are prohibited. Do not copy, collect, share or publish real hosts, IPs, addresses, USB serial numbers, credentials, tokens or device paths.

Adding repository, installing, starting, restarting, stopping, removing and restoring are all environment changes. Full isolated-test gate, written approval and immutable artifact provenance must be completed first. All actions are manually confirmed step by step only by the administrator present, without the use of shells, APIs, scripts or automation.

Understand status with a staffed desk

Complete gate before all actions

Interface navigation note: Home Assistant's add-on store, repository management, and backup interface can change between versions. Use the official Home Assistant add-on documentation to identify the controls and process for the current version. If a name or location differs, return to the official documentation; do not guess which control to use.

Before adding the repository or installing the Add-on, the administrator present must verify each of the following six conditions. Only a non-production Home Assistant test instance is eligible to continue:

• This is a non-production Home Assistant test instance, not a system providing services in a home, office, or customer site.
• The system has no KNX, USB or other device paths mapped.
• The physical interface and bus remain disconnected, and there are no alternative connections that would allow the test program to touch the field device.
• Any services that may be enabled remain within the bounded network test scope approved by the administrator and cannot be reached inadvertently from a general local network or the public internet.
• Pre-installation Home Assistant backups, minimal recovery methods, and roles responsible for stopping, removing, or restoring have been reviewed.
• Administrators with Add-on management rights are present throughout the process and can stop immediately in case of abnormalities.

If any of these cannot be proven, stop before adding the repository and installing. Home Assistant in production use cannot install Add-ons that have not passed the above gate.

Written approval record

A privacy-safe change record must be established before operation. Only IDs without environmental clues are placed in public or educational records; private approval records, precise operational scope, and six isolation evidence remain in access-controlled records. If one of the following fields is missing, we will not continue.

Change/Approval Record ID

Use an organization-issued privacy-safe ID with no name, host, address or time clue; this site does not provide sample values that could be misused as real records.

Controlled record reference

Only controlled references that can be retrieved by authorized personnel are recorded; it must be tied to a private approval record, precise operating scope, and six items of isolation evidence, but no name, system path, or link to a public page.

Approver role

Record only the role, not a person's name—for example, "Home Assistant administrator." Evidence of the private approval remains in a controlled record.

Approval actions and scope

List item by item whether this includes adding repository, installing, starting once, restarting once, stopping, removing, or backup and restore; the precise operation scope does not include KNX interface, bus, telegram, ETS or physical equipment.

Isolation evidence reference

The controlled records linked to the six isolation checks above only disclose the conforming/non-conforming/unknown classifications and do not disclose the environmental values.

Approval date and time

Time is kept in a controlled record; the public guide displays only the "recorded" status to avoid cascading live-environment activities.

Stop conditions

Bind the applicable stop conditions this time; if the isolation fails, the status is unknown, the proof is inconsistent, or the unexpected behavior occurs, it must be stopped immediately.

Privacy boundaries

Do not record the host name, host ID, IP, KNX address, USB serial number, device path, account, password, token, certificate or other secret.

Immutable build/artifact provenance gate

The source lock pins da-anda/hass-io-addons at commit 60d4a702e2011e75c90a0f1012dfbd916eb24ce0, which declares Add-on version 0.6.1. This only proves the source content.The 0.6.1 shown in the store does not prove that the image to be installed is built from the pinned commit.

• The controlled record has an artifact/image digest approved by the administrator, and the algorithm has been checked against the full digest.
• There is verifiable source-to-build attestation, and the digest is tied to the above pinned commit and build process.
• The operator can verify that the artifact Home Assistant will retrieve is the approved digest; not just the name or version text.

Conditional interface navigation

The following items describe only interface landmarks, expected observable states, and stop points that accommodate version differences. An administrator may perform them manually, using the then-current Home Assistant documentation, only after controlled records satisfy every gate.

1. Add the repository. When the approval record and artifact/image digest evidence are both valid, find the Add-on management landmark from the Home Assistant configuration area, and then follow the official documents to enter the repository management. After joining, only accept the list of approved repository identities; stop if the items are different, the source is unrecognizable, or the interface requires guessing. This site currently lacks an approved digest, so do not execute it.
2. Manual installation. When the approval record and artifact/image digest evidence are both valid, find the KNXD details page for the approved source from the add-on store. After the installation is completed, the expected page can distinguish between the "installed" status and the lifecycle control area; do not use the store version to infer commits. If started automatically or if real KNX values are requested, stop immediately. This site currently lacks an approved digest, so do not execute it.
3. Manual start. While the approval record and artifact/image digest evidence remain valid, the administrator present may use the start control on the details page once. The expected observation is only that the Add-on process changes from a stopped state to a running state; wording varies by version. This does not prove that the bus is operational. This site currently lacks an approved digest, so do not perform this step.
4. Manual restart, once. Use the restart control on the details page only once, while the approval record and artifact/image digest evidence remain valid and the previous state can be explained. The expected observation is only a brief transition followed by a return to the running state. Stop rather than retry if the state is unclear. This site currently lacks an approved digest, so do not perform this step.
5. Manual stop. Use the stop control of the detail page when the controlled approval scope includes a stop and the preceding certificate is still valid. The expected state is no longer running, but a stopped state. Do not repeat operations when the screen has not changed, stay isolated and return Stop and restore. No operation has been performed on this site, so there is nothing to stop.
6. Manual removal. Only when the controlled approval scope includes removal and the Add-on has been stopped, the removal/uninstallation lifecycle action is identified from the details page. Expect the installed state and lifecycle controls for the instance to disappear, or the page to return to the installable state; this does not prove that Home Assistant as a whole has been restored. Nothing has been installed through this site, so there is nothing to remove.
7. Manual restoration. Only when the backup coverage is fully consistent with the controlled approval, the administrator can select the pre-verified recovery point from the Home Assistant backup management landmark, first review the scope of impact, and then confirm. Expect to return only to the state covered by this backup; recheck Add-ons with other affected items after restoring. This site currently has no lifecycle changes that need to be restored.

Complete examination and evidence interpretation

The correct result at present is "stopped before first change due to lack of artifact provenance". If all gates are satisfied in future, the log will only be viewed briefly in the Home Assistant screen. Follow safe log guidance to complete the de-identification and only record the time range, component and error category; remove the host, IP, address, account, token, session, certificate, device name, path and serial number, and do not publish the complete log.

• I know pinned commits only attest to sources, store versions cannot replace artifact/image digest with source-to-build attestation.
• I have checked six isolation conditions and complete approval records before adding the repository and installing; currently the digest is missing, so no changes have been made.
• I can explain the observable scope of installed, running, stopped, removed and restored respectively, without cross-layer inference.
• I don't connect to the interface or bus; I don't send telegrams; I don't perform group operations; I don't perform ETS programming or downloads; and I don't perform physical control.

Next step: Keep all KNX interfaces, device mappings, and buses disconnected. When you need to interpret process status, see Interpret Add-on status. Without artifact provenance, retain only a "blocked" record.

Stop, remove and restore decisions

1. Start by narrowing the scope of the change. If the problem in the future only involves this Add-on, stop the Add-on first, and then remove the Add-on. Afterward, confirm only that the process is not running and the Add-on instance has been removed; do not refer to the removal as all of Home Assistant has been restored.
2. Consider a broader restoration only when its scope matches. If changes other than Add-on have occurred, and the pre-approved backup does cover this scope, the administrator must first check the backup time, content and other changes that may be covered, and then manually confirm using the Home Assistant official backup and restore process. The interface and wording vary depending on the version. This chapter does not make up buttons.
3. Verify again after restoring. It is up to the administrator to confirm that Home Assistant is back in the expected range, that the KNXD Add-on is in the expected stopped or removed state, and that there are no unintended effects. If any result is unclear, remain in isolation and stop further operations.

• Missing digest or attestation: Remain blocked, do not add other repositories, and do not install similar versions.
• Process status unknown: Record only the de-identified error category and stop; do not fill in the bus value, change the driver, or connect to the interface to try.
• The log contains environmental information: Stop sharing and delete the copy; if the secret has been revealed, have it revoked or rotated by the administrator.

Advanced notes and FAQ