Page tree
Skip to end of metadata
Go to start of metadata
Q

How is a running loadable firmware on COM-side (LFW - .nxi file) or APP-side (*.nai file) replaced by a newer version in the field?

A


The following steps are necessary

1) Transfer of the new firmware to netX 90

The new firmware may be
a) a COM-side firmware (*.nxi file)
b) an APP-side firmware (*.nai file)
c) fwupdate.zip (both *.nxi and *.nai files)

In case of c)  *.nxi and *.nai files are put into a ZIP archive.
It is even possible to store several *.nxi files (variants) into one ZIP archive.

Note: Please see the ZIP Archive section and using LZMA compression method with 64 KB dictionary size.

Depending on the flash layout use case A, B or C, either the COM-side Firmware (LFW) or the APP-side is responsible for the subsequent storage of the new firmware im flash memory (step 2)

The new firmware binary can be transferred through

Use case A, C:

  1. HTTP protocol over the network (Ethernet), using the basic webserver functionality of a running LFW
  2. Custom TCP/IP based protocol over the network (Ethernet), using the socket interface functionality of a running LFW
    In this case, the APP-side Firmware transfers the received fimware update image to the COM-side by using
    the cifX API function xChannelDownload() or the underlaying mailbox packet service "HIL_FILE_DOWNLOAD_REQ"
  3. From an external Host-Controller, via the host interface - HIF: parallel DPM or serial SPM (SPI)
    using the cifX API function xChannelDownload() or the underlaying mailbox packet service "HIL_FILE_DOWNLOAD_REQ"
    in this case the host application communicates with a running LFW or the MFW on COM-side
    use case c: location of the fwupdate.zip file or *.nxi, *.nai files in the filesystem: directory /FWUPDATE
  4. From the APP-side of netX 90 via the internal DPM
    using the cifX API function xChannelDownload() or the underlaying mailbox packet service "HIL_FILE_DOWNLOAD_REQ"
    in this case the host application communicates with a running LFW or the MFW on COM-side
    use case c: location of the fwupdate.zip file or *.nxi, *.nai files in the filesystem: directory /FWUPDATE
  5. The UART Marshaller and the PC Utility netHOST.exe(2019-08-1 (NXDIAG)\Windows Executable\netHost\x64\netHost.exe)

Use Case B

  1. HTTP protocol over the network (Ethernet), using the basic webserver functionality of a running LFW
    In this case, the COM-side LFW transfers the received fimware update image to the APP-side firmeware via mailbox packets
  2. Custom TCP/IP based protocol over the network (Ethernet), using the socket interface functionality of a running LFW
  3. Any communication interface (UART, I2C, SPI, etc.) and custom protocol to the APP side of netX 90

2) Store the new fimware binary in a flash memory

Depending on the flash layout use case A, B or C, either the COM-side Firmware (LFW) or the APP-side is responsible for the flash programming

Use Case A and C:

The flash programming is performed by the running LFW or MFW on COM side. The user application on APP-side or an external host is not responsible for flash programming.
The new firmware is stored in the so called "update area". I.e. after flash programming there are two firmware files inside the flash: a) the active firmware, b) the new firmware

Use Case B:

The APP-side firmware is responsible to program the new firmware file into the external flash memory update area.
The new firmware is stored in the so called "update area". I.e. after flash programming there are two firmware files inside the flash: a) the active firmeare, b) the new firmware


3) Trigger the start of the maintenance firmware

The maintenance firmware - MFW - is responsible for the actual installation of the new firmware. It erases the old firmware in flash and copies the new firmware into the firmware location.

The MFW can be started

  1. By pulling the RUN-pin to GND and performa a hardware reset
  2. By Software:
    1.  Sending the mailbox packet HIL_FIRMWARE_RESET_REQ → refer to documentation Packet-based services (netX 90/4000/4100) manual
    2. Using the cifX API Function xSysDeviceResetEx → refer to documentation cifX API manual
  3. By PC Utility netHost, command Device→Reset with "Update Start" reset mode
    The "Update Start" reset mode is only visible when the System Channel is opened (and not a Communication Channel)


  4. By basic webserver, directly click Reset button, after a new firmware is loaded


The firmware reset request (HIL_FIRMWARE_RESET_REQ → 0x00001E00) has two parameters:

  • ulTimeToReset (unused)
  • ulResetMode

By changing the ulResetMode parameter in the reset request packet, a running LFW is able to execute a reset and jump to the MFW to start the update process.

 
31...9Unused
8

Delete complete remanent data area

1 = Delete the complete remanent data area.

0 = Do not delete the remanent data area.

If this bit is set to 1 and the MFW is started using mode HIL_RESET_MODE_UPDATESTART, the complete remanent data area is deleted after a successful firmware update and the MFW will automatically restart to the LFW.

If this bit is set to 1 and the MFW is started using mode HIL_RESET_MODE_BOOTSTART, the complete remanent data area is deleted during the startup of the MFW and the MFW will not restart to the LFW.

This parameter is not supported for HIL_RESET_MODE_COLDSTART.

7...4

Reset Parameter

for HIL_RESET_MODE_COLDSTART

  • Does not support reset parameters.

for HIL_RESET_MODE_BOOTSTART

  • Does not support reset parameters.

for HIL_RESET_MODE_UPDATESTART

  • 0x0...0xF: If a ZIP file is used for the update, this option specifies the firmware that should be installed (Multi-Protocol Firmware).
3...0

Reset Mode

0 = HIL_RESET_MODE_COLDSTART
1 = HIL_RESET_MODE_WARMSTART (unused)
2 = HIL_RESET_MODE_BOOTSTART
3 = HIL_RESET_MODE_UPDATESTART

The cold start will perform a reset of the device and start the installed LFW again.

The boot start will perform a reset of the device and start the MFW. The boot start can be used to jump to the MFW without starting an update process (idle mode).

The update start will perform a reset of the device and start the MFW. If an update file is available, it will be automatically processed and installed.

4) The maintenance firmware installs the new loadable firmware

The maintenance firmware - MFW - is responsible for the actual installation of the new firmware. It erases the old firmware in flash and copies the new firmware into the firmware location.
The desitination is determined by the file type *.nxi, *.nai
It automatically detects the file type *.nxi, *.nai or *.zip by evaluation of the binary file headers.

Before the installation, checksums are calculated/compared and device and manufacturer IDs are checked to avoid installation of corrupt or wrong firmware images.

5) The maintenance firmware reboot the netX90

After completion of the installation process, the MFW performs a reboot of the system. Now the newly installed  loadable firmware is started.
In case of a hardware triggered MFW start (RUN-pin pulled to GND) the RUN-pin must be released before the system reboot.

Further info

ZIP Container Format:

File System Root
├───VAR0
    ├───SYSTEM
    ├───PORT_0
    ├───PORT_1
    ...
    ├───PORT_5
    └───XIP
├───VAR1
    ├───SYSTEM
    ├───PORT_0
    ├───PORT_1
    ...
    ├───PORT_5
    └───XIP
...

By using this layout, multiple firmware files can be placed in a single update container and installed by specifying the variant in the reset parameter described below.

The XIP directories hold the firmware file (with an 8.3 name format) that will be installed to the device (NXI/NXE/NAI/NAE).

The directory and filenames must contain capital letters only.

Files located in the SYSTEM and PORT_X directories will be installed to the corresponding directories on the file system (only use case C).

Firmware update area

The location used for firmware update files depends on the use case.

FLASH (use case A & B)

If a flash area is used for the firmware update, the location for the update area is defined in the FDL with the ID: HIL_PRODUCT_DATA_FLASH_LAYOUT_CONTENT_TYPE_FWUPDATE. Only one file can reside in this area at a time.

The FWUPDATE area is reserved for firmware files or an update container. Therefore other files will not be accepted by the download request.

The download request will only support files with the suffix's:

  • NAI
  • NXI

Or the update container "FWUPDATE.ZIP".

File system (use case C)

If a target has file system support, firmware, configurations, files, as well as the update container, are stored in a default file system layout. The location used for storing update files is the /FWUPDATE directory.

The file system location itself is defined in the FDL with the ID: HIL_PRODUCT_DATA_FLASH_LAYOUT_CONTENT_TYPE_FILESYSTEM.

Contrary to use case A/C, use case C supports all possible files (as long as the 8.3 file format is followed).

The download request will treat the following file types differently:

  • NAI
  • NXI

Or the update container with the name "FWUPDATE.ZIP".

If one of those files is received using the download request on PORT_0 (ulChannelNo set to 0), the file is automatically transferred to the /FWUPDATE directory (it will not be visible on /PORT_0). Other files residing in the FWUPDATE directory will be deleted before the download of the new file starts.

The contents of the /FWUPDATE directory are only deleted if a new firmware file or update container is downloaded. They are not deleted during or after a firmware installation. This way, the firmware can be installed again (without an additional download) if, for some reason, the original firmware is destroyed.

The default file system layout is:

File System Layout

File System Root
├───SYSTEM
├───PORT_0
├───PORT_1
...
├───PORT_5
└───FWUPDATE

6) ZIP Archive

Requirements (windows):

  • Program on Host PC to create LZMA compressed ZIP files (e.g. 7zip)
    • The following directions expect 7zip with shortcuts install in the context menu
  • Firmware to update (+ additional configuration files etc.)

Steps:

  1. Create the directory layout of the ZIP file as described above.
    1. If only one variant is used, create only the VAR0 directory.
    2. Create the XIP and PORT_X sub-directories as needed.
    3. use capital letters only
  2. Place all firmware binaries in the XIP directory (e.g. NXI/NXE files).
    • FIRMWARE.NXI
    • FIRMWARE.NAI
  3. Place additional files (e.g. configuration files) in the matching PORT_X directories (replace X with the COM channel number)
  4. If all files have been placed in the directory layout, mark all required variant directories in Windows Explorer and <right click/context menu> → "7Zip" → "add to archive...".
  5. Use the following settings:
    1. LZMA compression
    2. 64KB dictionary size
    3. Set the archive name to 'fwupdate.zip' (alternatively, rename zip file later in file manager)

  6. Make sure by opening the created 'fwupdate.zip' file, that the first directory level has the 'VAR' directories listed.

The 7zip version used in the screenshot is 19.00 (2019-02-21).

Limitations

  • Supported Compression Modes.
    • LZMA compression only. Requires ZIP version 6.3 or above.
  • Smallest LZMA dictionary size (64K).
    • As additional memory on netX (COM) is needed to hold the LZMA dictionary (its size is specified in the ZIP file), 64KB should always be possible.
  • ZIP file is scanning (front to back), the following simplifications/limitations apply:
    • No additional data descriptor (zip files should not be created using 'stream' mode, where storage size in local header is set to '0')
    • No encryption
  • Additional/New files should not be added to an existing archive, instead a new container should be created.

7) Error Codes

On an error during the update process, the MFW will set the system error (ulSystemError) field in the system status block of the DPM.

Code
Define
Description
0xC0001150ERR_HIL_INVALID_HEADER

File header information don't match.

Possible causes:

  • Invalid firmware cookie or signature in file header.
  • Invalid header version in file header.
  • Invalid CRC32 checksum in file header.
0xC0001151ERR_HIL_INCOMPATIBLE

Firmware file is incompatible with device.

Possible causes:

  • Invalid manufacturer ID in file header.
  • Invalid device class in file header.
  • Invalid compatibility options in file header.
  • Invalid hardware options in file header.
0xC0001152ERR_HIL_NOT_AVAILABLE

Firmware not available.

Possible causes:

  • No update .ZIP, .NXI, etc. file was found.
  • Update destination area was not found.
0xC0001153ERR_HIL_READCould not read from file or flash area.
0xC0001154ERR_HIL_WRITECould not write to file system or destination area.
0xC0001155ERR_HIL_IDENTICAL

Update firmware is identical to installed firmware.

  • File header matches the file header of the installed firmware.
  • Installed firmware is still valid (correct MD5 checksum).
0xC0001156ERR_HIL_INSTALLATION

Error during installation of

  • firmware file.
  • additional (configuration) files.
0xC0001157ERR_HIL_VERIFICATION

Failed to verify installed firmware file.

Possible causes:

  • Header verification of installed firmware failed.
  • CRC32/MD5 verification of installed firmware failed.
  • The firmware is not installed because the external flash is read-only for some reason.
0xC0001176ERR_HIL_UPDATE_ERROR

The ROM Loader couldn't start up the installed firmware and one firmware installation process was already performed.

A second installation is not started automatically.

0xC0001178ERR_HIL_MANUFACTURER_INVALIDManufacturer in file header does not match target.
0xC0001179ERR_HIL_DEVICE_CLASS_INVALIDDevice class in file header does not match target.
0xC000117AERR_HIL_HW_COMPATIBILITY_INVALIDHardware compatibility index in file header does not match target.
0xC000117BERR_HIL_HW_OPTIONS_INVALIDHardware options in file header does not match target.