002 - Firmware Update

Changelog

Version

Remark

Version

Remark

1.0

Initial Release

Table: Changelog

Introduction

Scope

This document describes the process of updating the firmware of the ccm module.

Document structure

Chapter

Content

Chapter

Content

Introduction

Introduction of this document

Update Methods

Overview over firmware update methods

Update Method HTTP

Firmware update method HTTP

Update Method FoE

Firmware update method EtherCAT/FoE

Update Method SPI

Firmware update method SPI

Reset

Reset and Firmware update

Table: Content of this document

Firmware Update Methods

General procedure

The ccm module provides multiple ways to update the firmware. On the module two firmware objects are present. Those are the bootloader and the application. The bootloader is immutable by the user. It contains the basic startup code, firmware flashing routines and signature verification code for firmware
update.

All shown firmware update methods have a basic procedure in common:

  1. The running application puts the firmware update data into the RAM of the
    module.

  2. If firmware update data was received a reboot of the running application is
    performed. This step can be permitted by the application controller.

  3. The bootloader starts and detects a pending firmware update.

  4. The bootloader verifies the firmware signature, if passed the firmware is
    flashed - the previously running firmware is still kept.

  5. The bootloader starts the new firmware.

  6. If configured, commits the running firmware during bootup - else this
    commit process is triggered from external.

Depending on the commit execution the bootloader then starts the new firmware
or the previously run firmware.

Available Methods

Following methods for firmware update are available:

Method

Description

Method

Description

HTTP

Firmware upload using an HTTP-POST Request, used by the Industrial Communication Explorer

FoE

Firmware upload using an EtherCAT FoE transfer, used by the communication explorer tool for EtherCAT devices

SPI

Firmware upload using RPC functions by the application controller

Table: Firmware update methods

Firmware Commit

The following table shows the default behaviour for firmware update regarding commit:

Method

Firmware Commit configuration

Method

Firmware Commit configuration

HTTP

by default commit is required, thus a specific URL has to be requested after firmware update which triggers the commit

FoE

commit is automatically done after booting of the updated firmware

SPI

commit is automatically done after booting of the updated firmware

Table: Firmware update commit configuration

Firmware update commit step is configure using the CM variable:

  • module id: GOAL_ID_CCM (72)

  • variable id: CCM_CM_VAR_FW_UPDATE_COMMIT_DISABLE (8)

By default (value 0) commit is enabled.

The mentioned methods FoE and SPI set this variable implicitly, however after firmware update the variable is reset to the default value of 0.

Firmware update package

Firmware is delivered as a firmware package. This file, e.g. irj45_1.2.0.35_ci1243.pfw, is basically a zip archive which contains the following files:

File

Description

File

Description

bundle/bundle.xml

bundle description

irj45_2port.dat

firmware update file for HTTP method

irj45_2port.bin

firmware update file for FoE/SPI method

Table: firmware update bundle content

Both data files are signed by the author of this firmware and thus must not be manipulated.

Firmware Update Method HTTP

Preconditions

A valid IP configuration of the device must be configured to support update over HTTP. The application controller needs to permit firmware update in general. This is the case by default, but can be configured using an RPC function:

GOAL_STATUS_T appl_ccmUpdateAllow( void ); GOAL_STATUS_T appl_ccmUpdateDeny( void );

Authentication

Firmware update over HTTP supports basic authentication. Authentication credentials are compared against CM variables:

All variables are associated to module id GOAL_CM_HTTP_MOD_ID (25).

Level

varId

Level

varId

0

HTTP_CM_VAR_USERLEVEL0 (2)

1

HTTP_CM_VAR_USERLEVEL1 (3)

2

HTTP_CM_VAR_USERLEVEL2 (4)

3

HTTP_CM_VAR_USERLEVEL3 (5)

Table: HTTP Authentication credentials

Firmware update over HTTP uses HTTP authentication level 0.

application control

The application can register an optional callback function to take control of some aspects during firmware update.

Following an example implementation of the callback function:

/****************************************************************************/ /** firmware update callback * */ static void appl_fwUpdateCb( FW_UPDATE_SOURCE_T source, /**< fw update source */ FW_UPDATE_STATUS_T state, /**< fw update status */ uint8_t progress /**< fw update progress */ ) { switch (state) { default: case FW_UPDATE_IDLE: goal_logInfo("fw update state : IDLE"); break; case FW_UPDATE_TRANSFER_INIT: goal_logInfo("fw update state : INIT"); switch (source) { case FW_UPDATE_SOURCE_RPC: goal_logInfo(" fw update source : RPC"); break; case FW_UPDATE_SOURCE_HTTP: goal_logInfo(" fw update source : HTTP"); break; case FW_UPDATE_SOURCE_FOE: goal_logInfo(" fw update source : FOE"); break; } break; case FW_UPDATE_TRANSFER: goal_logInfo("fw update state : TRANSFER, progress = %d", progress); break; case FW_UPDATE_TRANSFER_DONE: goal_logInfo("fw update state : DONE"); goal_logInfo("performing update and rebooting CCM module"); /* * this function call will reboot the communication controller. * it will be accepting communication after firmware update is * done. * * a reboot of the application controller ist required before * the communication module is available again. By default * this is performed, see * plat/board/<board name>/goal_target_board.c, function * goal_miMctcCbRegReset() function, which registers a reset * callback function */ appl_ccmFwUpdateExecute(); break; case FW_UPDATE_ABORT: goal_logInfo("fw update state : ABORT"); break; default: goal_logErr("unknown callback id"); break; } }

If the application does not register a callback function, the communication module will reboot when firmware reception is done. If the application does register a callback function, the communication module will reboot only when appl_ccmFwUpdateExecute() is called by the application controller.

Firmware transmission

Firmware transmission is done using a HTTP Post Request:

# default values for firmware update IP = 192.168.0.100 LOGIN = admin:password curl -v <http://$(IP):8080/fw/firmware.html> -F file=@firmware/bundle/irj45_2port.dat --basic -u $(LOGIN)

If successful, this transmission will perform a reboot of the device. Startup takes a long time since the bootloader will verify and flash the new update. The updated firmware will restart after this process, which may take up to 2 minutes.

If the updated firmware is running, a commit step is required to permanently enable the updated firmware. Firmware update commit is done using a HTTP Post Request:

If successfull, this step will also trigger a reboot of the firmware.

Firmware Update Method FoE

Preconditions

The device must operate within a EtherCAT network.

The application controller needs to permit firmware update in general. This is the case by default, but can be configured using an RPC function:

Please note if you are using uGOAL: Please consider increasing available RPC handles (e.g. per define CONFIG_UGOAL_RPC_HANDLES (3)), as the execution of the firmware must be triggered trough RPC.

Authentication

Firmware update over FoE supports authentication. Authentication credentials are compared against CM variables:

All variables are associated to module id GOAL_CM_CCM_MOD_ID (72).

Property

varId

Property

varId

FoE filename

CCM_CM_VAR_FOE_FILENAME (9)

FoE filename match length

CCM_CM_VAR_FOE_FILENAME_MATCH_LENGTH (12)

FoE password

CCM_CM_VAR_FOE_PASSWORD (10)

FoE state

CCM_CM_VAR_FOE_UPDATE_REQUIRES_BOOT (11)

Table: FoE Authentication credentials

A FoE firmware update is only done when FoE filename and FoE password match. If the configured match length is 0, the whole filename is matched. If a length is configured, only those number of characters are matched.

If the variable CCM_CM_VAR_FOE_UPDATE_REQUIRES_BOOT is set, then firmware update is only allowed in BOOTSTRAP mode.

application control

The application can register an optional callback function to take control of some aspects during firmware update.

Following an example implementation of the callback function:

If the application does not register a callback function, the communication module will reboot when firmware reception is done. If the application does register a callback function, the communication module will reboot only when appl_ccmFwUpdateExecute() is called by the application controller.

It is recommended to perform execution of the firmware update when leaving the BOOTSTRAP state.

Firmware transmission

Firmware transmission is done using a FoE download request.

Firmware Update Method SPI

Preconditions

An SPI communication between AC and CC must be established.

The application controller needs to permit firmware update in general. This is the case by default, but can be configured using an RPC function:

Authentication

There is no authentication required for firmware update over SPI.

application control

The application can register an optional callback function to take control of some aspects during firmware update. If the application does not register a callback function, the communication module will
reboot when firmware reception is done.

If the application does register a callback function, the communication module will
reboot only when appl_ccmFwUpdateExecute() is called by the application controller.

Firmware transmission

Firmware transmission is done using an RPC request.

It requires the address of the firmware data, which must be located in memory. This data must contain the data from the bundle file ir45_2port.bin.

Reset and Firmware Update

The ccm module can be reset by the application controller. During a firmware update process this reset must not be performed. During the performing of the firmware update by the bootloader and commit step by the application, the module will not be communicating over the SPI interface. Thus the communication from the application controller to the ccm module can only be established when the firmware update process is done.