Introduction

This document describes the Wirepas Over-The-Air-Programming (OTAP) feature. It is targeted for developers and users and contains the concepts associated with OTAP as well as the key components.

What you’ll learn

• How Wirepas OTAP works
• What are the key components involved and how they are linked together
• A deeper dive on how to make an OTAP in a Wirepas network

What you’ll need

• Basic knowledge of Wirepas 5G Mesh is a plus. You can refer to the Wirepas 5G Mesh document for more details.

OTAP operation principle

In this chapter, the high-level concepts of Wirepas OTAP are presented.

Wirepas OTAP allows updating the software running in a device via the mesh network. OTAP uses an optimized, secure, and reliable way to spread a new software version to an existing network and to update devices. OTAP can be used to update user applications, the Wirepas 5G Mesh stack and the Modem Firmware.

OTAP Features at a glance

Wirepas OTAP supports the following features:

• Multi-components: Possibility to update either the:
  • Wirepas 5G Mesh stack
  • Radio Modem Firmware (provided by Wirepas with the Wirepas 5G Mesh stack)
  • Application sitting in the same radio chipset.
  • Other user memory areas
• Multi-application: Capability to update the network containing different devices running different applications via multi-application updates
• Secure: Encrypted update image with integrity verification
• Optimized: An optimized and efficient mechanism to propagate new images into the network to minimize network downtime.
• Reliable: OTAP supports mechanisms to control and ensure high reliability for this process.

OTAP Operation principle

As a network may consist of multiple devices with different features, and as a consequence, different firmware, the Wirepas OTAP mechanism relies on 3 main steps:

• Step1 - Propagate to spread a new update image (called a Scratchpad) to all devices in a given network
• Step2 - Trigger: to send an update command to a network
• Step3 - Process and apply the Update: When all devices process the update image and move to the new version

In order for the OTAP to operate some flash memory must be reserved in each device to store the update image called Scratchpad.

Step1 - Propagate

The first step of an OTAP starts by pushing a new Scratchpad to the Sink(s) (the Wirepas device in the Gateway) together with some parameters used to identify a newer version for the network.

Please note that in the below description we use versions e.g. v1.0 & v2.0 to identify newer versions only for a conceptual purpose. Other parameters are used to identify a newer scratchpad and are described in the next chapters.

As soon as a newer Scratchpad is seen by a device and parameters are properly set, the new image is automatically exchanged using an peer-to-peer communication between devices and stored in the device's scratchpad memory (which can be either in internal or external flash).

This mechanism ensures that all devices will receive the new image when the image is present in the network.

At the end of the propagation process, all devices have a running version ie: v1.0 and a stored version ie: v2.0

Identification of new available Firmware is based on a CRC provided explicitly.

The Wirepas 5G Mesh OTAP propagation process takes advantage of the regular data plane. To ensure the correct propagation of the scratchpad over the complete network, here are some insights on the propagation:

• sending the scratchpad is done per hop. Hence, it is propagated, solely after a node has received the complete. As long as a node does not have the complete scratchpad, it does not propagate it.
• sending the scratchpad is set at the lowest priority on the network data packet transmission. Whenever a network is overloaded with data to be sent, Scratchpad may be sent extremely slowly.

Step2 - Trigger

During this phase the Backend is used to:

1. Query the information from all devices via the Wirepas network to ensure they all have the proper Scratchpad in memory
2. When all information is correct, trigger the OTAP by sending a command to all devices from all Gateways' sinks

At the end of this step, all devices have the Scratchpad and are ready to process it.

Step3 - Process and apply the Update

This step is either automatically triggered at the end of the Activation Delay set previously and will trigger the following actions:

• The device reboots and transfers execution to the Bootloader
• The Bootloader verifies the integrity of the scratchpad images
• The Bootloader checks if the scratchpad contains some valid binaries to be processed (checking Area ID)
• If yes, the Bootloader decrypts, decompresses, and writes the binary to the device’s flash, otherwise it just ignore the scratchpad and set it as processed.
• At the end of the process, the Bootloader reboots the device and the new version is executed.

Note 1: The Wirepas OTAP does not include a fallback mechanism.

Note 2: The device may reboot two times in case the DECT-2020 NR Modem Firmware is updated.

Key OTAP inputs parameters

In this section, the key parameters related to OTAP are described:

• The Scratchpad, which contains the image(s) to be updated
• The AreaID used to identify a firmware to update
• The Sequence number and CRC used to identify a newer scratchpad in the network.

Scratchpad

An OTAP Scratchpad is binary data that gets copied from one node to another. A scratchpad is a collection of binaries transmitted via the OTAP. Each binary in a scratchpad has (among others) an Identifier to define the targeted component to be updated. This identifier is called AreaID and is a specific software component (a specific area in Flash memory to be accurate).

Area ID

Area ID can be defined for example as:

• Wirepas 5G Mesh stack firmware AreaID (Stack AreaID): The Stack Area
• Modem Firmware AreaID.
• Application Area ID (App Area ID): The Application Area
• User-defined Area ID, that can also be defined to store specific data related to the user application or system and which can be updated via the Wirepas OTAP mechanism.

Each binary part of the scratchpad is encrypted and the entire scratchpad integrity is guaranteed.

For example:

Stack Area ID

The Stack Area is used to store the Wirepas 5G Mesh stack. The Area ID is always the same for all devices having the same chipset as the stack is tightly linked to a given chipset.

Modem Firmware AreaID

The Modem Firmware AreaID defines the memory area in which the modem firmware is stored and executed. This a specific area, since it is not located the same flash area as the Stack and the Application.

The application Area ID and other User Area ID(s)

Each application or user area shall have a unique 32-bit AreaID that is stored in the device’s memory. Because this ID is used by the Bootloader to identify if a scratchpad update shall be applied or not, it shall be different for all different application firmware or user areas. The device starts the update process only if the scratchpad includes a binary that has the same AreaID that is stored in the device’s memory. The AreaID corresponding to the application is named AppAreaID.

Note: AreaID is defined during the device firmware build process. Hence they should be carefully selected as AreaID’s cannot be changed afterward. Wirepas recommandation is: 16-bit endpoint defined by DECT-2020 NR standard and administered by ETSI is used. Alignment with the new standard enables technology roadmap towards new connectivity standard and use cases. The assigned company specific endpoint values are used to derive company specific Application Area ID. For further details, please refer to this document.

Network Persistent Data

Network Persistent Data is used to control the OTAP. Thanks to this Wirepas 5G Mesh stack feature it is possible to set a network wide OTAP action and configuration which nodes will use to trigger and control OTAP.

Key components involved during OTAP

In this section, the key components involved during the OTAP process are listed:

• The Wirepas Stack
• The Bootloader
• The Wirepas Mesh remote API
• Wirepas Gateway drivers
• Wirepas Gateway to Cloud API

Wirepas Stack

The Wirepas stack is responsible to spread a new scratchpad to the network. The Stack has the logic to:

• Advertise to the other devices its stored scratchpad information
• Decide to exchange a scratchpad or not
• Send or receive the scratchpad with neighbors if needed.

Note: The scratchpad is exchanged using peer-to-peer communication protocol between the sender and the receiver allowing a fast exchange of the scratchpad. During this exchange, the nodes are using normal data plane, hence the network is not disrupted during the propagation of the scratchpads in the devices. The disruption occurs when devices need to reboot after having triggered the execution of the OTAP.

The Bootloader

The bootloader is responsible for processing the OTAP scratchpad. Whenever a new OTAP scratchpad is found in memory, the bootloader authenticates it and iterates through the OTAP files. If any of the data files have a matching AreaID, the bootloader erases the referenced memory areas and then writes file contents there.

There is no local, external interface for the bootloader. All interaction with the bootloader happens via data in program memory.

After iterating through all files in the scratchpad, the bootloader writes a status word in program memory to mark the scratchpad as processed. This prevents the bootloader from processing the scratchpad again when the node boots up. If there is an error, the status word will be written with an error code. In this case, the processing can be retried later.

Wirepas stack supports querying the bootloader status word locally (Single-MCU API) or remotely(Remote API), to see if the bootloader was able to process the scratchpad successfully.

The bootloader uses asymmetric key of 256 bits for authenticating and an additional key (128bits) to decrypt the OTAP scratchpad. These keys should be used when generating the scratchpad so that the device’s bootloader keys match with the keys which served to generate the scratchpad.

The Wirepas Remote API

The Wirepas Remote API is used to interact with the device Wirepas 5G Mesh stack from the Gateways. The Remote API is used to monitor the OTAP process from the Gateway. More details on the Remote API concept can be found in Wirepas Software and APIs Overview document.

Wirepas Gateway drivers

The Wirepas Gateway drivers are responsible to receive and download a scratchpad to a Sink node via the Dual-MCU API.

Wirepas Gateway to Cloud API

The Wirepas Gateway to Cloud API over MQTT is used to:

• Download scratchpad and set the sequence number to all gateways using the Gateway OTAP Module
• Send and receive commands to control and monitor the update process via Remote API

Revision History

Legal Notice

Use of this document is strictly subject to Wirepas’ Terms of Use and Legal Notice.

Copyright © 2024 Wirepas Oy