Introduction

This document describes the Wirepas Massive 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. 

This document first covers the Wirepas OTAP operation principle. It then describes the key components involved in OTAP operations.

What you’ll learn

• How Wirepas Massive OTAP works
• What are the key components involved and how they are linked together

What you’ll need

• Basic knowledge of Wirepas Massive is a plus. You can refer to the Wirepas Massive Concept document [1] for more details.

OTAP operation principle 

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

Wirepas Massive 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 both user applications and the Wirepas stack.

OTAP Features at a glance

Wirepas OTAP supports the following features:

• Multi-components: Possibility to update either the:
  • Wirepas 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

Because 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.

Note: OTAP needs to be done as fast and as efficiently as possible. To allow this, nodes use a special point-to-point communication mode with a high data rate to exchange Scratchpad images. This is why normal network operations are disrupted during the update process.

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, this new image is automatically exchanged using an optimized 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

Note: During this Scratchpad exchange the devices are disconnected from the network.

Note: Even if in most of the cases the update is started from the Sink, any device with a newer version will automatically share his new image hop-by-hop to all devices. 

Step2 - Trigger

During this phase the Backend (e.g. Wirepas Network Tool(WNT)) is used to:

1. Query the information from all devices via the Wirepas Massive 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. 

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

Step3 - Process and apply the Update

This step is 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: The solution does not include a fallback mechanism.

OTAP fail-safe

In addition to the previously described OTAP flow, a fail-safe mechanism is implemented. The fail-safe allows covering potential orphan devices to be updated in case they missed the update commands. For example, mobile devices, that might be outside of the network coverage when the process command is sent, are automatically updated after the safe period.

Key OTAP inputs parameters 

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

• The Scratchpad, which contains the images to be updated
• The AreaID used to identify a firmware to update
• The Sequence number 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 stack firmware AreaID (Stack AreaID): The Stack Area
• 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 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. Also, the stack is usually updated on all devices independently of their respective 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.

The sequence number

A sequence number determines which OTAP scratchpad is the latest. The latest OTAP scratchpad gets copied between nodes until all nodes have the same scratchpad sequence number. The sequence number has 8 bits and the value is selected between 1-254. 

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 Massive remote API
• Wirepas Gateway drivers
• Wirepas Gateway to Cloud API

Wirepas Massive 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 (Sequence number)
• Decide to exchange a scratchpad or not
• Send or receive the scratchpad with neighbors if needed.

Note: The scratchpad is exchanged using a special peer-to-peer communication protocol between the sender and the receiver allowing a fast exchange of the scratchpad. During this exchange, the nodes are not anymore part of the mesh network. That’s why normal network operations are disrupted during the update process. 

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 (see Scratchpad). 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 [2]) or remotely(Remote API [3]), to see if the bootloader was able to process the scratchpad successfully.

Scratchpad information and version number can be optionally be written in the memory. This is enabled by setting a flag in memory are configuration. This information can be retrieved with scratchpad status or remote status remote API queries. 

The bootloader contains a set of AES-128 keys for authenticating and decrypting the OTAP scratchpad. These keys should be used when generating the scratchpad so that the device’s bootloader keys match with the scratchpad keys.

More details of the flash memory organization and bootloader can be found in Wirepas Massive Flash structure and Bootloader application note [5]

The Wirepas Massive remote API

The Wirepas Massive Remote API is used to interact with the device Wirepas Stack from the Gateways. The Remote API is used to monitor and control the OTAP process from the Gateway. More details on the Remote API concept can be found in Wirepas Software and APIs Overview document [4]

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

References

[1] Wirepas Mesh Concepts
[2] Wirepas Single MCU API (SDK Documentation)
[3] Wirepas Mesh Remote API Reference Manual
[4] Wirepas Software and APIs Overview
[5] Wirepas Massive Flash structure and Bootloader application note

Revision History

Legal Notice

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

Copyright © 2021 Wirepas Oy