> For the complete documentation index, see [llms.txt](https://docs.kpnthings.com/kpn-things/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kpnthings.com/kpn-things/kpn-firmware-over-the-air/getting-started/firmware-update-service.md).

# Firmware Update Service

### Device Type Requirements

The Firmware Update Service can be used to manage the firmware of your KPN Things M2M devices. Before you can use this service, your device types must be configured by a KPN support employee. 

Your device type may consist of multiple modules, for which the firmware can be managed in the Firmware Update Service seperately. The names of the modules must correspond with SenML attributes reported by the devices of this type. The SenML attribute values indicate the current versions of the firmware for each of the modules.

### Device Requirements

It is required that your devices are configured in a flow, with a decoder and encoder enabled, so the uplink messages from your device will be forwarded to the Firmware Update Service and the downlink SenML messages coming from the Firmware Update Service can be forwarded to your devices. 

### Firmware Update Process

The firmware update process is depicted below, and consists of the steps described in following sections.

<figure><img src="/files/dTIRBgjeZFNbiM71rQNi" alt=""><figcaption></figcaption></figure>

#### 1 - Uploading and activation of firmware

Via the Things Portal, you can create firmware packages for the modules of your device type. A firmware package has a version that corresponds to the SenML attribute value reported by the device when this firmware package is activated. A firmware file must be uploaded before the package can be activated on devices. Release notes can optionally be added for your convenience.

Using the portal, you can select a group of devices, and configure the target firmware for one or more modules for your selection of devices. This initiates the firmware update process.

#### 2 - Send downlink to devices

The firmware service monitors the reported firmware version for each of the modules and if the target firmware version differs from the reported version, the service sends a downlink to your device. The downlink has the SenML format and contains the URL indicating where the new firmware can be downloaded, and a Bearer token, that is required for the download:

```
[
  {
    "bn": "urn:dev:IMEI:866421234567890:"
  },
  {
    "n": "url",
    "vs": "http://prod.dm.kpnthings.com/f/v1/12345678-1234-5678-1234-123456789012"
  },
  {
    "n": "token",
    "vs": "eyJhbGciOiJIUzUxMiJ9..."
  }
]
```

The downlink messages will be delivered to the device in the response of an uplink message.

The firmware update service will periodically send new downlinks if the update process takes more time than expected by the service. The devices must be able to process those downlinks correctly.

#### 3 - Download new firmware

Upon receipt of the downlink with the firmware update information, the device shall download the firmware from the specified location using the provided token. HTTP Range may be used to download the firmware in multiple smaller parts.

```
> GET /f/v1/12345678-1234-5678-1234-123456789012 HTTP/1.1
> Host: m.m
> User-Agent: curl/8.7.1
> Accept: */*
> Authorization: eyJhbGciOiJIUzUxMiJ9...
> Range: bytes=0-10
> 
* Request completely sent off
< HTTP/1.1 200 
< Digest: crc32=9a165d01
< Content-Range: bytes 0-10/74000000
< ETag: 1782140572045
< Date: Wed, 24 Jun 2026 12:34:52 GMT
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: 0
< Content-Type: text/plain
< Content-Length: 11

0123456789a%
```

After downloading the file, the CRC32 in the Digest HTTP response header can be used by the device to confirm successful file(-part) transfer.

#### 4 - Apply new firmware

After downloading the firmware, the device will activate the new firmware.

#### 5 - Report new firmware version

The device with the new firmware will now send new uplinks that contain the updated version information in the SenML. The firmware update service that receives the uplink message will update the current firmware version for the device that completes the firmware update process.

### Limitations

<table><thead><tr><th width="236.625">Limit</th><th width="116.0625">Value</th><th>Notes</th></tr></thead><tbody><tr><td>max firmware file size</td><td>100MiB</td><td></td></tr><tr><td>max number of download attempts</td><td>19999</td><td>The complete file must be downloaded using max 19999 HTTP requests, or the file may be downloaded up to 19999 times using one request.</td></tr><tr><td>token validity</td><td>48h</td><td>The period the firmware can be downloaded by the device using the provided token.  A new token will be provided by the service, if needed, in a new downlink message.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kpnthings.com/kpn-things/kpn-firmware-over-the-air/getting-started/firmware-update-service.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.