Skip to content

Device Software Update (SWU)

Firmware update in KNX IoT transfers a new firmware image from a Software Update Client to a KNX IoT device over CoAP/OSCORE. The process uses the PUSH transfer mode: the Software Update Client sends firmware chunks directly to the device via sequential CoAP PUT requests, then triggers activation after transferring all data.

The .knxfwp file packages the firmware image as a ZIP archive containing a signed Manifest.xml and one or more firmware BLOBs. The Software Update Client parses the package offline, verifies the hardware reference with the target device, and then streams the BLOB in chunks. The device buffers the data, verifies integrity, and reboots automatically after the trigger command.

Access Control and Token Provisioning

The MaC provisions if.swu access tokens on the device before a Software Update Client can perform updates. See Device Access Control for access token details and Device Bootstrapping for the commissioning workflow.

Overview

Phase Description Endpoints
Pre-flight Discover device, read SWU hardware reference and manufacturer ID, read SWU status resources. swu/mid, swu/hwref, swu/method, swu/state, swu/pkgbytes
BLOB Transfer Read resume offset, transfer firmware in chunks, poll until DOWNLOADED, read package version. swu/pkgbytes, /a/swu?po=<offset>&ps=<size>, swu/state, swu/pkgv
Activation Trigger update, wait for device reboot, verify firmware version. /swu/update, dev/fwv, swu/result

Any client with an if.swu access token (=Software Update Client) can perform all three phases. Only the MaC (Management Client), which holds if.sec scope, can provision if.swu tokens on the device.

Note

Each Software Update Client SHALL obtain its own access token with a unique OSCORE security context. Reusing the same token across multiple clients risks OSCORE nonce reuse, which breaks confidentiality protection. Every client must track its own Context ID and Sender Sequence Number. To grant SWU access to a new client after onboarding, a MaC with if.sec scope installs a separate access token for that client on the device.

Protocol Sequence

Software Update Client                   KNX IoT Device
     |
     |--- [NON] GET Query SN ----------------->| Discovery
     |<-- [NON] 2.05 Content (IA, SN) ---------|
     |                                         |
     |          ┌------ Pre-flight --------┐   |
     |          │                          │   |
     |--- [CON] GET /swu/mid ------------->|   | Read manufacturer ID
     |<-- [ACK] 2.05 Content (253) --------|   |
     |--- [CON] GET /swu/hwref ----------->|   | Read hardware reference
     |<-- [ACK] 2.05 Content (hwref) ------|   |
     |--- [CON] GET /swu/method ---------->|   | Confirm PUSH support (1 or 2)
     |<-- [ACK] 2.05 Content (1) ----------|   |
     |--- [CON] GET /swu/state ----------->|   | Confirm IDLE state (0)
     |<-- [ACK] 2.05 Content (0) ----------|   |
     |--- [CON] GET /swu/pkgbytes -------->|   | Read resume offset
     |<-- [ACK] 2.05 Content (0) ----------|   |
     |          └--------------------------┘   |
     |                                         |
     |          ┌------ BLOB Transfer -----┐   |
     |          │                          │   |
     |--- [CON] PUT /a/swu?po=0&ps=8192 -->|   | Chunk 0 (octet-stream)
     |<-- [ACK] 2.04 Changed  -------------|   |
     |--- [CON] PUT /a/swu?po=8192&ps=8192>|   | Chunk 1
     |<-- [ACK] 2.04 Changed  -------------|   |
     |          │  (... N chunks ...)      │   |
     |--- [CON] PUT /a/swu?po=<last> ----->|   | Final chunk
     |<-- [ACK] 2.04 Changed  -------------|   |
     |          │                          │   |
     |--- [CON] GET /swu/state ----------->|   | Poll until DOWNLOADED (state=2)
     |<-- [ACK] 2.05 Content (1) ----------|   | -> still DOWNLOADING
     |          │  (... poll ...)          │   |
     |--- [CON] GET /swu/state ----------->|   |
     |<-- [ACK] 2.05 Content (2) ----------|   | -> DOWNLOADED
     |          │                          │   |
     |--- [CON] GET /swu/pkgv ------------>|   | Read downloaded package version
     |<-- [ACK] 2.05 Content ([M,m,p]) ----|   |
     |          └--------------------------┘   |
     |                                         |
     |          ┌------ Activation --------┐   |
     |          │                          │   |
     |--- [CON] PUT /swu/update {1: 0} --->|   | Trigger activation
     |<-- [ACK] 2.04 Changed (Max-Age N) --|   |
     |          │  (device reboots)        │   |
     |          │  (sleep Max-Age seconds) │   |
     |          │                          │   |
     |--- [CON] GET /dev/fwv ------------->|   | Poll until device responds
     |<-- [ACK] 2.05 Content ([M,m,p]) ----|   |
     |--- [CON] GET /swu/result ---------->|   | Confirm SUCCESS result
     |<-- [ACK] 2.05 Content (1) ----------|   |
     |          └--------------------------┘   |
     |                                         |

Pre-flight Checks

Before transferring data, the Software Update Client validates that the package is appropriate for the target device and reads the current SWU state.

1. Device Discovery

The client discovers the target device via mDNS on the local network. As an alternative, a CoAP multicast resource discovery query can find the device by serial number.

Both methods return the device's individual address and serial number.

2. SWU Identity Check

The Software Update Client reads the manufacturer ID and hardware reference from the SWU interface object and compares the hardware reference with the HardwareReference attribute in the package Manifest.xml. A mismatch aborts the update early, avoiding a lengthy transfer of an incompatible package. The device always validates the package independently after receiving it.

Property Endpoint Manifest Attribute Example
Package manufacturer ID GET /swu/mid ProviderId 253
Hardware reference GET /swu/hwref HardwareReference 00FD000500000008
Package version GET /swu/pkgv FirmwareVersion [1, 0, 1]

Note

swu/mid returns the manufacturer ID of the entity that signed the firmware package, not the device manufacturer. In OEM scenarios this value can differ from dev/mid.

3. SWU Status Read

The Software Update Client reads the SWU status resources before starting:

Resource Key Meaning
swu/method {1: unsigned} Supported transfer mode; 1 = PUSH, 2 = PUSH and PULL
swu/state {1: unsigned} Current state (see state machine below)
swu/pkgbytes {1: unsigned} Bytes already received (resume offset)

All KNX IoT devices SHALL support PUSH (swu/method includes 1). If swu/state is not IDLE (0), a previous transfer may be in progress.

BLOB Transfer

4. Resume Offset

The Software Update Client reads swu/pkgbytes before the first PUT. A zero value means no prior data exists on the device, so the transfer starts from the beginning. A non-zero value indicates an interrupted transfer. The Software Update Client can resume from that byte offset only when it can confirm the same firmware package was in progress. Otherwise it resets to offset 0.

Stale-resume guard: if swu/pkgbytes >= total_firmware_bytes, the offset is invalid (the device may have reset or received a different package) and must be reset to 0.

5. Chunked PUT

The Software Update Client transfers the firmware BLOB by sending sequential PUT requests:

PUT /a/swu?po=<byte_offset>&ps=<chunk_size>
Content-Format: application/octet-stream (42)
Payload: up to <chunk_size> bytes of firmware data
  • The byte offset (po=) is the byte position in the firmware BLOB.
  • The page size (ps=) is the number of payload bytes in this chunk.
  • The Software Update Client sends each chunk as a single confirmable ([CON]) CoAP message. The device responds 2.04 Changed on success. The OS handles IP fragmentation for large packets, the Software Update Client sends the firmware as a single UDP packet per chunk, not CoAP Block1 fragments.

OSCORE note: All PUT requests are OSCORE-protected using the security context established by the if.swu access token. OSCORE encrypts the firmware payload and query parameters.

6. Poll for DOWNLOADED

After the last chunk, the Software Update Client polls swu/state until the device reports state 2 (DOWNLOADED). This confirms the device has received all data and passed its internal integrity check.

IDLE (0) → DOWNLOADING (1) → DOWNLOADED (2)

If the state does not reach DOWNLOADED within the poll timeout, the Software Update Client raises a timeout error.

7. Read Downloaded Package Version

Once the Software Update Client confirms DOWNLOADED, it reads swu/pkgv to verify the version of the firmware image the device has just received:

GET /swu/pkgv
Response: {1: [major, minor, patch]}   // version of the downloaded (not yet active) package

This is the version of the pending image—distinct from dev/fwv, which returns the version of the currently running firmware.

Note

The manifest FirmwareVersion attribute uses four parts (for example, 1.0.1.0). KNX IoT devices use only the first three parts (major.minor.patch). The fourth part is always 0 for KNX IoT devices. Software Update Clients can discard it when comparing versions.

Activation

8. Trigger Update

Once DOWNLOADED, the Software Update Client sends:

PUT /swu/update
Payload: CBOR {1: 0}   // 1 = trigger key; 0 = activate value

The device responds 2.04 Changed with a Max-Age option indicating the minimum time (in seconds) before it becomes reachable again (reboot duration). The Software Update Client waits for Max-Age seconds before polling.

9. Wait for Reboot and Verify

The device reboots and applies the firmware image. After the Max-Age wait, the Software Update Client reads dev/fwv to confirm that the device is back online and reports the expected firmware version.

The UPDATING state (3) may be visible during the reboot window. After the device comes back online, the device state returns to IDLE.

SWU State Machine

The device SWU state (swu/state) transitions through four states:

  ┌----------┐  first PUT  ┌-------------┐
  │  IDLE    │ ----------> │ DOWNLOADING │
  │  (0)     │             │    (1)      │
  └----------┘             └-------------┘
        ^                         │ all bytes
        │                         v received
        │                  ┌-------------┐
        │                  │ DOWNLOADED  │ <---┐
        │                  │    (2)      │     │
        │                  └-------------┘     │
        │                         │ PUT        │
        │                         v /swu/update│
        │                  ┌-------------┐     │
        │                  │  UPDATING   │-----┘
        │                  │    (3)      │ (failed)
        │                  └-------------┘
        │                         │
        └-------------------------┘ (success, device reboots)
State Value Description
IDLE 0 Ready; no transfer in progress
DOWNLOADING 1 Receiving firmware chunks via PUT
DOWNLOADED 2 All chunks received; integrity passed
UPDATING 3 Activation in progress; transitions to IDLE on success or DOWNLOADED on failure

SWU Resources Reference

All SWU resources return and accept CBOR with numeric key 1 for the value, matching the KNX IoT Point API convention.

Resource Methods CBOR Description
swu/mid GET {1: unsigned} KNX manufacturer ID of the firmware package provider
swu/hwref GET {1: text string} Hardware reference (16 hex chars)
swu/method GET {1: unsigned} Supported transfer methods; 1 = PUSH, 2 = PUSH and PULL
swu/state GET {1: unsigned} Current SWU state (0–3)
swu/result GET {1: unsigned} Result of last update (0–9)
swu/pkgbytes GET {1: unsigned} Bytes saved to non-volatile memory for the current package
swu/pkgv GET {1: [unsigned,unsigned,unsigned]} Version of the downloaded (not yet active) package
/a/swu PUT - Firmware data; query po=<byte_offset>&ps=<chunk_size>
swu/update PUT {1: unsigned} Trigger activation; {1: 0} to activate

Firmware Package Format

The .knxfwp file is a ZIP archive containing:

  • Manifest.xml: Signed XML with package metadata and BLOB references.
  • Firmware BLOB file (name defined in Manifest.xml).

Manifest Attributes

Attribute Description
ProviderId KNX manufacturer ID of the firmware provider
FirmwareVersion Package firmware version (see note in section Read Downloaded Package Version)
FriendlyName Human-readable package name
RestrictPayloadSize Optional: maximum bytes per PUT chunk

ApplicableTo Element

Contains the mandatory HardwareReference attribute (16 hex characters, 8 bytes) that the Software Update Client compares with the device swu/hwref property before transferring data.

FirmwareParts / FirmwarePart Element

Each FirmwarePart element describes one BLOB:

Attribute Description
Identifier 20-character hex firmware part ID
Version Part version string
FileName BLOB filename inside the ZIP
Hash SHA-256 hash of the BLOB content

See the detailed description of the ZIP archive in this KNX Support article. For this, log in to the KNX Support Portal with a registered KNX member account.