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:

The running application puts the firmware update data into the RAM of the
module.
If firmware update data was received a reboot of the running application is
performed. This step can be permitted by the application controller.
The bootloader starts and detects a pending firmware update.
The bootloader verifies the firmware signature, if passed the firmware is
flashed - the previously running firmware is still kept.
The bootloader starts the new firmware.
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.

SoM/iRJ45

002 - Firmware Update

Changelog

Introduction

Scope

Document structure

Firmware Update Methods

General procedure

Available Methods

Firmware Commit

Firmware update package

Firmware Update Method HTTP

Preconditions

Authentication

application control

Firmware transmission

Firmware Update Method FoE

Preconditions

Authentication

application control

Firmware transmission

Firmware Update Method SPI

Preconditions

Authentication

application control

Firmware transmission

Reset and Firmware Update