Flasher - Project Management

Flasher supports storing multiple projects on its file system, making it possible to switch between projects purely in standalone mode without needing to update any files.
A project consists of one or more jobs. Each job is one of the following:

• Debug interface programming configuration (*.CFG)
• Programming app configuration (*.UNI)
• Custom app (*.PEX)

Depending on the job type, additional files may be part of the job, e.g. data files (.DAT) for programming jobs (*.CFG as well as *.UNI).

Managed projects

The most recent firmware version of Flasher models with hardware revision >= V5 supports project management.
Note: A firmware provided with the Software and Documentation Pack V8.90 or newer is required to support project management.
The Legacy projects section describes how older models and firmware versions without project management handle projects.

With project management, each project is its own folder, stored inside a parent folder named "Projects" that is located on the root folder of the Flasher file system.
A project folder name consists of two parts:

07_MyProject

1. Numerical prefix
   • The numerical prefix is optional, so it can be omitted. Projects are sorted by their folder name, lexicographically descending. A numerical prefix allows users to define the order of projects, regardless of their name. This is useful for Flasher Portable Plus, which allows selecting projects by going to the next or previous one. If present, Flasher omits the prefix when displaying the project name. Additionally, selecting the project by name works both, with and without the numerical prefix.
2. Project name
   • The name identifies a project.

A project folder contains any project-specific files, such as Cntdown.txt (see Flasher - Limit programming cycles for more information), as well as one folder for each of its jobs.
Similar to the project folders, job folder names consist of two parts:

04_MyJob

1. Numerical prefix
   • The numerical prefix is optional, so it can be omitted. Jobs are sorted by their folder name, lexicographically descending. A numerical prefix allows users to define the order of jobs, regardless of their name. The order of jobs is crucial, as the jobs of a project are executed consecutively, one after another. Because of this, it's recommended to always provide a numerical prefix for job folders. Otherwise, the order of operations would depend on the name of the job. If present, Flasher omits the prefix when displaying the job name.
2. Job name
   • The name identifies a job.

A job folder contains any job-specific files, such as...

• Type-specific job file (i.e. *.CFG, *.UNI or *.PEX)
• Data file (.DAT, only required for *.CFG and *.UNI jobs)
• Optional serial number file(s) Serial.txt and SNList.txt (See Serial number programming for more information)
• Optional patch file Patches.txt (See Patch file support for more information)
• Optional key file Key.txt (See Device unlock key for more information)

Note:

For projects that consist of only a single job, it's possible to omit the job folder and store the job files directly inside the project folder. So instead of ...

• Projects
  • 03_SingleJobProject
    • 00_OnlyJob
      • [Job files]

The file system would look as follows:

• Projects
  • 03_SingleJobProject
    • [Job files]

When omitting the only job folder, there is no job name.

For that reason, Flasher will use the job's type-specific job file name (i.e. *.CFG, *.UNI or *.PEX), when displaying the identifier for such a job.

An example for a Flasher file system with managed projects looks as follows:

• Projects
  • 00_STM32
    • 00_Prepare
      • Prepare.pex
    • 01_Program
      • Firmware.CFG
      • Firmware.DAT
      • Patches.txt
    • 02_Restore
      • Restore.pex
  • 01_PIC16
    • Cntdown.txt
    • 00_Prepare
      • Prepare.pex
    • 01_Program
      • Firmware.UNI
      • Firmware.DAT
      • PIC16.PEX
      • Serial.txt
    • 02_Restore
      • Restore.pex
  • 02_HelloWorld
    • HelloWorld.pex

Naming and Path Length Restrictions

All folder names and filenames used within a managed project tree (project folders, job folders, and individual job files) must not exceed 80 characters including the terminating null character (\0). That is, the maximum usable length for the name string is 79 characters.

This 80-character limit applies to:

• The project folder name (including any optional numeric prefix).
• Each job folder name (including any optional numeric prefix).
• Filenames of job files (e.g. *.CFG, *.UNI, *.PEX, *.DAT, Serial.txt, etc.).

Prefix Handling

Numeric prefixes count toward the total length.
Example: 07_MyProductionProject
Here, 0, 7, _, and all characters of the project name contribute to the 79-character limit.

File Transfer

To transfer the created project structure to the Flasher, refer to Flasher file management for details on how to do this.

Migrating from legacy projects to managed projects

Flasher setups that make use of legacy projects can be migrated to make use of the new managed projects as follows.

Note:

Project files stored on Flasher's secure area cannot be read out.
As such, there is no way to migrate them to the new project management.

If not stored elsewhere, the projects would need to generated again, put into the new project management folder structure and then moved to Flasher's secure area.

Manual migration

If the Flasher software applications are not suitable for migrating projects stored on Flasher, they can be migrated manually, too.

1. Transfer all files stored on Flasher to a new, designated folder on a PC, from now on referred to as "Org"
   • See Flasher file management for details on how to do this
2. Create another new, designated folder on a PC, from now on referred to as "New"
   • Inside New, create an empty file called Flasher.ini
   • Inside New, create a folder called Projects
   • New
     • Flasher.ini
     • Projects
3. The following steps are done on the PC folder
4. Inspect your Org\Flasher.ini file. Depending on the contents, migration is done differently, as described below
5. One or more [BATCH<N>] sections present?

   [BATCH]
   ConfigFile  = "B0_Job0.cfg"
   DataFile    = "B0_Job0.dat"
   ConfigFile1 = "B0_Job1.cfg"
   DataFile1   = "B0_Job1.dat"
   [BATCH1]
   ConfigFile = "B1_Job0.cfg"
   DataFile   = "B1_Job0.dat"
   

   • A batch is a list of projects (*.CFG or *.UNI) executed one after another, in sequence. With the new project management, this is done by having one project that consists of a list of jobs (*.CFG, *.UNI, or *.PEX) that are executed one after another, in sequence.
   • Do the following for each [BATCH<N>] section
     1. Create a new folder in New\Projects. The name of the folder can be chosen freely. It determines the name of the new project that replaces the old batch. For simplicity, the new folder for [BATCH<N>] will be referred to as Batch_N
        • The order of the projects can be retained (i.e. to keep project rotation on Flasher Portable PLUS identical after migration), by using a numerical prefix in the folder name as described above.
        • New
          • Projects
            • Batch_N
     2. Do the following for each pair of ConfigFile<M> and DataFile<M> keys inside the [BATCH<N>] section
        1. Create a new folder in New\Projects\Batch_N. The name of the folder can be chosen freely. It determines the name of the respective job. Make sure to prefix the folder name with a numerical prefix (according <M> ) to ensure that the order of jobs is the same as the order of projects in the old batch. For simplicity, the new folder for [BATCH<N>] project <M> will be referred to as Job_M
        2. Copy both files, ConfigFile<M> and DataFile<M> from Org into New\Projects\Batch_N\Job_M\
           • New
             • Projects
               • Batch_N
                 • Job_M
                   • Job.cfg
                   • Job.dat
6. [FILES] section present?

   ConfigFile  = "Proj_0.cfg"
   DataFile    = "Proj_0.dat"
   ConfigFile1 = "Proj_1.cfg"
   DataFile1   = "Proj_1.dat"
   

   • Do the following for each pair of ConfigFile<N> and DataFile<N> keys inside the [FILES] section
     1. Create a new folder in New\Projects. The name of the folder can be chosen freely. It determines the name of the respective project. For simplicity, the new folder will be referred to as Proj_N
        • The order of the projects can be retained (i.e. to keep project rotation on Flasher Portable PLUS identical after migration), by using a numerical prefix in the folder name as described above.
     2. Copy both files, ConfigFile<N> and DataFile<N> from Org into New\Projects\Proj_N
7. If Org\Flasher.ini contains neither a [FILES] nor any [BATCH<N>] section, then legacy selection is used
   • File named Flasher.cfg present in Org\?
     1. Create a new folder in New\Projects. The name of the folder can be chosen freely. It determines the name of the respective project. For simplicity, the new folder will be referred to as Proj
     2. Copy Org\Flasher.cfg and Org\Flasher.dat into New\Projects\Proj
   • File named Flasher.UNI present in Org\?
     1. Create a new folder in New\Projects. The name of the folder can be chosen freely. It determines the name of the respective project. For simplicity, the new folder will be referred to as Proj
     2. Copy Org\Flasher.UNI and the respective *.DAT file into New\Projects\Proj
   • *.PEX file present in Org\?
     1. Create a new folder in New\Projects. The name of the folder can be chosen freely. It determines the name of the respective project. For simplicity, the new folder will be referred to as Proj
     2. Copy Org\*.PEX file into New\Projects\Proj
8. Migrate project selection as follows
   1. For models other than Flasher Portable PLUS, the ConfigFile and DataFile pair in the [FILES] section defines the currently selected project. Selection is done differently for managed projects. In New\Flasher.ini, add a section called [PROJECT] with a key called Name. The value for that key is the name of the selected project in quotation marks, e.g.

      [PROJECT]
      Name = "Proj_N"
      

   2. For Flasher Portable PLUS, the selected project was previously determined by the SelectedImage value in the [CONFIG] section. With managed projects, the SelectedImage value is no longer required for Flasher Portable PLUS. The Flasher Portable PLUS uses the same approach as all other Flashers and stores the currently selected project's name in the Name key of the [PROJECT] section.
9. Migrate Flasher.log file
   • Copy Org\Flasher.log to New\Flasher.log
10. Migrate Cntdown.txt file
    • Before, all projects shared the same Cntdown.txt. This made it impossible to have two projects with separate programming cycle limitations. Now, each project has its own, separate (and optional) Cntdown.txt, stored in its respective project folder.
11. Migrate Serial.txt file
    • Before, all projects shared the same Serial.txt. This made it impossible to have two projects with separate serial number programming configurations. Now, each job has its own, separate (and optional) Serial.txt, stored in its respective job folder.
12. Migrate SNList.txt file
    • Before, all projects shared the same SNList.txt. This made it impossible to have two projects with separate serial number lists. Now, each job has its own, separate (and optional) SNList.txt, stored in its respective job folder.
13. Migrate Patches.txt file
    • Before, all projects shared the same Patches.txt. This made it impossible to have two projects with separate patch lists. Now, each job has its own, separate (and optional) Patches.txt, stored in its respective job folder.
14. Migrate Key.txt file
    • Before, all projects shared the same Key.txt. This made it impossible to have two projects with separate programming keys. Now, each job has its own, separate (and optional) Key.txt, stored in its respective job folder.
15. Migrate other settings
    • If present, copy the [CONFIG] section from Org\Flasher.ini into New\Flasher.ini

      [CONFIG]
      AutoPowerOffOnIdle = "300"
      ShowDatCRCAfterProgramming = "1"
      SelectedImage = "2"
      

16. Replace the files on the Flasher with the content of the New\ directory

Legacy projects

Before the introduction of project management, projects needed to be stored on the Flasher file system in a different way.
Flasher determines which project was selected via Flasher.ini:

1. [BATCH] section present?
   • Each batch is a list of one or more jobs.
   • Each job is defined as a CFG+DAT file pair.
   • Multiple [BATCH<N>] sections can exist, where <N> is the selected project number (empty string for #0). Only Flasher Portable PLUS makes use of project numbers > 0.
   • All specified project files are expected to be stored in the root folder of Flasher.
   • Flasher.ini example:

     [BATCH]
     DataFile = "Proj0_Job0.dat"
     ConfigFile = "Proj0_Job0.cfg"
     [BATCH1]
     DataFile = "Proj1_Job0.dat"
     ConfigFile = "Proj1_Job0.cfg"
     DataFile1 = "Proj1_Job1.dat"
     ConfigFile1 = "Proj1_Job1.cfg"
     DataFile2 = "Proj1_Job2.dat"
     ConfigFile2 = "Proj1_Job2.cfg"
     

2. [FILES] section present?
   • "DataFile" and "ConfigFile" define the selected project
   • <N> is the selected project number (empty string for #0). Only Flasher Portable PLUS makes use of project numbers > 0.
   • All specified project files are expected to be stored in the root folder of Flasher.
   • Flasher.ini example:

     [FILES]
     DataFile<N> = "MySelectedProject.dat"
     ConfigFile<N> = "MySelectedProject.cfg"
     

3. None of the above (or Flasher.ini not present)?
   • Legacy mode. Flasher<N>.cfg and Flasher<N>.dat is selected as project files.
   • <N> is the selected project number (empty string for #0). Only Flasher Portable PLUS makes use of project numbers > 0.
     • Flasher<N>.cfg not present? → Use Flasher<N>.uni, instead.
       • Flasher<N>.uni not present? → Use *.pex, instead.

Note:

This legacy approach brings numerous disadvantages with it, e.g.:

1. Except for Flasher Portable PLUS, switching between batches was not possible. Effectively, one multi-job batch could be used at a time.
2. All projects would share the same Cntdown.txt, Serial.txt, SNList.txt, Patches.txt, Key.txt etc.
   • Effectively, multiple projects with separate programming cycle limits, serial number programming or separate keys were not supported.
   • Additionally, it was not possible to have multiple *.UNI projects that used separate versions of the same programming app (*.PEX).
3. All project files were stored inside the same folder, decreasing overview.
4. Flasher.ini's structure was quite complex, making it difficult to understand the setup just by looking at it.
5. Multiple, separate custom apps (*.PEX) could not be used.
6. Custom apps (*.PEX) as part of a multi-job project (or [BATCH]) were not supported.

Multiple File Support

It is also possible to have multiple data files and config files on Flasher, to make Flasher more easy to use in production environment. To choose the correct configuration file and data file pair, a FLASHER.INI file is used. This init file contains a [FILES] section which describes which configuration file and which data file should be used for programming. A sample content of a FLASHER.INI file is shown below:

[FILES]
DataFile = "Flasher1.dat"
ConfigFile = "Flasher1.cfg"

Using this method all configuration files and data files which are used in the production only have to be downloaded once. From there on a configuration file / data file pair can be switched by simply replacing the FLASHER.INI by a new one, which contains the new descriptions for the configuration file and data file. The FLASHER.INI can be replaced in two ways:

1. Boot Flasher in file access mode in order to replace the FLASHER.INI
2. If Flasher is already integrated into the production line, runs in standalone mode and can not be booted in other mode: Use the file I/O commands provided by the ASCII interface of Flasher, to replace the FLASHER.INI. For more information about the file I/O commands, please refer to File I/O commands.

Flasher Portable PLUS specifics

Flasher Portable PLUS allows to choose between 99 configuration and data file pairs during runtime by using the select button on the front of the Unit. A config / data file pair can be added to the [FILES] section with the ConfigFileX and DataFileX parameters, where X is the ID of the project. The sample below shows how to enable the user to select between five different images on the Flasher Portable PLUS:

[FILES]
DataFile = "First.dat"
ConfigFile = "First.cfg"
DataFile1 = "Second.dat"
ConfigFile1 = "Second.cfg"
DataFile2 = "Third.dat"
ConfigFile2 = "Third.cfg"

Using this method, all configuration files and data files which are used in the production only have to be stored on Flasher Portable PLUS (See File management). From there on, switching between the files can be done by simply using the selection and power buttons of Flasher Portable PLUS.

Note:

1. The Flasher Portable PLUS checks if the files exist on its file system. If a file is missing, the entry will be skipped and the selection jumps directly to the next entry in the list.
2. You may have gaps in the list. The missing entries will be skipped when selecting the next configuration.

Batch Programming in standalone mode

Batch programming allows the execution of different standalone mode jobs in batch to be executed in immediate succession, without any user interaction in between. This can be used for example to program multiple targets in a JTAG-Chain or multiple data files to a target.
A batch may contain an unlimited number of configurations which consist of a data file (*.DAT) and config file (*.CFG). For further information regarding config and data files, please refer to Preparing for standalone operation manually.
In order to specify the batch jobs, a FLASHER.INI file is used. This init file contains a [BATCH] section which describes which configuration pairs (*.DAT and *.CFG file) should be used for each batch job. A sample content of a FLASHER.INI file is shown below:

[BATCH]
DataFile = "Flasher0.dat"
ConfigFile = "Flasher0.cfg"
DataFile1 = "Flasher1.dat"
ConfigFile1 = "Flasher1.cfg"

The Flasher Portable PLUS screen will show that the number of jobs contained in the batch and the configuration file name of the first job.

The progress will be shown during the flashing action. The Flasher lists the current job of the batch, the current sector address and the percentage of the currently executed action.

The result of the programming will be shown on the screen after finishing all jobs.

Creating / Replacing of the FLASHER.INI file can be done in two ways:

1. Boot Flasher in file access mode in order to replace the FLASHER.INI
2. If Flasher is already integrated into the production line, runs in standalone mode and can not be booted in other mode: Use the file I/O commands provided by the ASCII interface of Flasher, to replace the FLASHER.INI . For more information about the file I/O commands, please refer to File I/O commands. In case of an error occurred during execution, the Flasher terminates the entire batch processing.

Note:

1. The batch programming feature can not be used with the multiple file support feature. Therefore, neither the #SELECT ASCII command nor the [FILES] tag in the FLASHER.INI file can be used.
2. For information on restrictions for file and directory names, refer to: File system.

Flasher Portable PLUS specifics

Flasher Portable PLUS allows the user to select between 99 batches (since V7.90) during runtime by using the select and power button on the front of Flasher Portable PLUS. Which batch configuration is used for which image selection position is specified in the FLASHER.INI. For this, the FLASHER.INI contents in the [BATCH] section have been extended. The sample below shows how to enable the user to select between four different batches on the Flasher Portable PLUS via the select / power button:

[BATCH]
DataFile = "Flasher0.dat"
ConfigFile = "Flasher0.cfg"
DataFile1 = "Flasher1.dat"
ConfigFile1 = "Flasher1.cfg"
DataFile2 = "Flasher2.dat"
ConfigFile2 = "Flasher2.cfg"
[BATCH1]
DataFile = "TEST.dat"
ConfigFile = "Test.cfg"
[BATCH2]
DataFile = "VALIDATE.dat"
ConfigFile = "Flasher0.cfg"

Using this method allows to have different batches for different setups used in the production to be stored once on the Flasher Portable PLUS via file access mode. From there on, switching between the batches can be done by simply using the selection and power button of Flasher Portable PLUS.

Examples

Example 1: Programming two Data files to the same target

• Open your J-Flash project.
• Use File -> Save Flasher config file... to save the .CFG file (in this example: STM32F4.CFG).
• Select the first binary and use File -> Save Flasher Data file... to save the first .DAT file (in this example: DATA0.DAT).
• Select the second binary and use File -> Save Flasher Data file... to save the second data file .DAT file (in this example: DATA1.DAT).
• Copy the Files to the Flasher e.g. by using file access mode.
• Create a FLASHER.INI file in the root directory of the Flasher.
• Exemplary content of FLASHER.INI:
  

[BATCH]
DataFile = "DATA0.dat"
ConfigFile = "emPower.cfg"
DataFile1 = "DATA1.dat"
ConfigFile1 = "emPower.cfg"

Example 2: Programming one Data file to the first target in a JTAG-Chain and then programming two data files to another device in the JTAG chain.
Example scenario: 2 Devices in a JTAG chain, a STM32F1 and a STM32F4.

• Follow the same as described before and additionally:
• Create one project file per target (and create a .CFG file of each one).
• Make sure each project file is configured correctly, especially the JTAG-Chain position (See UM08003_JFlash for more detailed info).
• Exemplary content of FLASHER.INI:
  

[BATCH]
DataFile = "F1DATA.dat"
ConfigFile = "STM32F1.cfg"
DataFile1 = "F4DATA0.dat"
ConfigFile1 = "STM32F4.cfg"
DataFile2 = "F4DATA1.dat"
ConfigFile2 = "STM32F4.cfg"

Example 3: Using multiple Batch sections with Flasher Portable PLUS.
Example scenario: 2 Devices in a JTAG chain, a STM32F1 and a STM32F4.
Selection 1 will program the STM32F1 target.
Selection 2 will program the STM32F4 target using "F4DATA0.dat".
Selection 3 will program the STM32F4 target using "F4DATA1.dat".
Selection 4 will execute 1, 2 and 3 in sequence.

• Exemplary content of FLASHER.INI:
  

[BATCH]
DataFile = "F1DATA.dat"
ConfigFile = "STM32F1.cfg"
[BATCH1]
DataFile = "F4DATA0.dat"
ConfigFile = "STM32F4.cfg"
[BATCH2]
DataFile = "F4DATA1.dat"
ConfigFile = "STM32F4.cfg"
[BATCH3]
DataFile = "F1DATA.dat"
ConfigFile = "STM32F1.cfg"
DataFile1 = "F4DATA0.dat"
ConfigFile1 = "STM32F4.cfg"
DataFile2 = "F4DATA1.dat"
ConfigFile2 = "STM32F4.cfg"

Programming multiple targets

It is possible to program multiple targets which are located in a JTAG chain. The targets will be programmed each with a configuration and a data file.
The configuration for the desired target must be selected before it can be programmed, this can be done with the #SELECT command. For more information how to use the #SELECT command please refer to the Flasher - Remote control.

Example
Three devices should be programmed.

JTAG Chain: TDI --> Device2 --> Device1 --> Device0 --> TDO

Three configurations would be stored on the flasher:

Config 0: Configured to program Device0 (DEVICE0.CFG, DEVICE0.DAT)
Config 1: Configured to program Device1 (DEVICE1.CFG, DEVICE1.DAT)
Config 2: Configured to program Device2 (DEVICE2.CFG, DEVICE2.DAT)

Selection and programming of the target will be done via the ASCII interface:

#SELECT DEVICE0
#AUTO
#SELECT DEVICE1
#AUTO
#SELECT DEVICE2
#AUTO

Programming multiple targets with J-Flash

Programming multiple targets can also be done via J-Flash using the command line interface. For this each target must be handled with its own project file.

Example

JFlash.exe -openprj"Device0.jflash" -open"Device0.hex" -auto -exit
JFlash.exe -openprj"Device1.jflash" -open"Device1.hex" -auto -exit
JFlash.exe -openprj"Device2.jflash" -open"Device2.hex" -auto -exit

Custom labels

Flasher supports to assign custom labels to configurations ("Project Display Text" in U-Flash) using the DisplayName parameter. This allows to specify easy to remember names for configurations that are stored on the Flasher. The maximum length of a custom label is 32 characters. If this length is exceeded, the label is ignored and Flasher switches back to default mode for the affected configuration.

Hardware and software requirements

This feature is supported by the following models:

• Flasher Portable PLUS

Other models will ignore the DisplayName parameter. This feature is supported since V6.30e of the software package and firmware.

Assigning labels for FILES projects

The configuration and data file pairs are specified in the FLASHER.INI file:

[FILES]
DataFile    = "IMAGE1.dat"
ConfigFile  = "IMAGE1.cfg"
DataFile1   = "IMAGE2.dat"
ConfigFile1 = "IMAGE2.cfg"

By default, Flasher will show the names of the configuration and data file:

By adding DisplayName, DisplayName1, ... keys to the FLASHER.INI, a custom label can be shown instead:

[FILES]
DisplayName  = "FW smartwatch"
DataFile     = "IMAGE1.dat"
ConfigFile   = "IMAGE1.cfg"
DisplayName1 = "FW smart meter"
DataFile1    = "IMAGE2.dat"
ConfigFile1  = "IMAGE2.cfg"

The images will now be shown as follows:

Assigning labels for BATCH projects

When projects are defined using the BATCH notation, each BATCH-project can have a custom label which is set with the DisplayName parameter. There can be one DisplayName per project.

It is matched to the project by the [BATCH] section it is placed in and must not end with the projects number (in contrast to the FILES notation).

[BATCH]
DisplayName  = "FW smartwatch"
DataFile     = "SW_IMAGE.dat"
ConfigFile   = "SW_IMAGE.cfg"

[BATCH1]
DisplayName  = "FW smart meter"
DataFile     = "BOOTLOADER.dat"
ConfigFile   = "BOOTLOADER.cfg"
DataFile1    = "SM_IMAGE.dat"
ConfigFile1  = "SM_IMAGE.cfg"

The custom label will be shown in the first line of the projects description. Projects with only one job will show the data file name and the timestamp of the configuration file in the second and third line. Multi-job projects will show the number of jobs in the second line.