Firmware update

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?

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 in 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 Firmware upload module of 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 firmware 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 WebIf module of the basic webserver functionality of a running LFW
   In this case, the COM-side LFW transfers the received firmware update image to the APP-side firmware 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 firmware 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 firmware, 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 perform 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.

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:

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

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.