1. Configuration Script File

The Cyclone Image Creation utility that comes with your Cyclone software is shown in the following image. The utility allows you to interactively choose the settings for creating a stand alone programming image. This includes device settings, flash settings, binary data to program, power settings, scripted programming commands, and more. When the user is ready to create the stand along programming image, the Image Creation utility saves the settings into a .CFG file and launches the command-line CSAP utility. The CSAP utility generates a stand-along programming image (.SAP extension) based upon the settings in the .CFG file as well as data from any binary files (Elf, S-Rec, etc) referenced in the .CFG file. The generated stand alone programming image can be dropped directly into a Cyclone programmer and contains all information necessary for programming. 

The user can also call the command-line CSAP utility directly from the command-line to generate a stand alone programming image. It picks up the latest settings specified in the .CFG file as well as the latest programming data in any referenced binary files (Elf, S19, etc) when generating the image. If the user's goal, for instance, was to update a stand alone programming image each time a referenced binary data file changed, it is as simple as calling the CSAP utility with exactly the same configuration file (when generating the updated stand alone programming image, the data included in the image is sourced from the updated binary file).

A standalone configuration (.CFG) file is easy to generate on disk: 

1. Use the Cyclone Image Creation Utility to choose all the appropriate options to generate a stand alone programming image and then select the main menu option "File -> Save Cyclone Configuration" to save the configuration as a .CFG file. 

2. If you have an existing Stand Alone Programming image (SAP), in the Cyclone Image Creation Utility select the main menu option "File -> Load Configuration from Image". This will load the configuration into the Image Creation Utility. Select the main menu option "File -> Save Cyclone Configuration" to save it as a .CFG file.

Below is an example of a configuration file for programming a NXP Kinetis KL25Z128 device.

Note that the first three auto-generated comments are used by the Cyclone Image Creation Utility and cannot be modified unless you are only calling CSAP. 

; Automatically generated configuration file
; Silicon Manufacturer is ARM Based (All Manufacturers)
; Silicon Architecture is ARM Based (Kinetis, LPC, etc.)
;
:RESETDELAY 0
:DEVICE NXP_KL2x_KL25Z128M4
:USESWD 1
:DEBUGFREQUENCY 3330
:SAPGUIVERSION 362E3935
:PROVIDEPOWER
:POWERVOLTAGE 3.3
:POWERDOWNDELAY 250
:POWERUPDELAY 250
:KEEPPOWERON 0
:NEWIMAGE
:DESCRIBEIMAGE KL25Z128 Test Image
CM C:\PEMicro\cyclone\supportfiles\supportFiles_ARM\NXP\KL2x\freescale_kl25z128m4_1x32x32k_pflash.arp
SS C:\Products\DevOps\test\test_cases\cyclonefirmwaretest\srecords\KL25Z128.s19
EN ;Erase if not Blank
PT ;Program Trim
PM ;Program Module
VC ;Verify Checksum
SD  ;SECURE DEVICE

2. Script Commands

The lines that begin with a semicolon are comments. Setup commands are preceded by a colon.

:RESETDELAY Specifies the delay in milliseconds after a target reset before contacting target. 

:DEVICE Used to specify the device initialization string. Not required for all architectures.

:USESWD Used to indicate JTAG(=0) or SWD(=1). Only required for ARM architecture.

:DEBUGFREQUENCY Specifies the debug shift frequency

:SAPGUIVERSION Internal command. This is not required.

:PROVIDEPOWER Turns on Cyclone Relays.

:POWERVOLTAGE Specifies voltage generated by the Cyclone's power relays

:POWERDOWNDELAY This controls the delay after power off setting.

:POWERUPDELAY This controls the delay after power on setting.

:KEEPPOWERON Controls whether power is turned off to the target after SAP operations True(=1) or False(=0).

:NEWIMAGE Internal command. This is not required.

:DESCRIBEIMAGE This is the image description string.

The two letter script commands that go after the setup section are listed here.

CM Choose module .arp file. Note: Certain modules may require a base address to be specified

EN Blank check and erase

PT Program trim 

SS Specify binary data file (S19/Elf/Hex)

PM Program the binary data file to the module

VC Verify the programmed device using a checksum

SD Secure device

These are the most commonly used commands. The script may support additional commands that are not listed here. A complete list can be found in the CYCLONE and CYCLONE FX user manual found in the Cyclone install documentation folder.

3. Invoking Via Command-line And Parameters

The next step is to invoke the appropriate CSAP executable on the command-line to create the SAP file. 

[executable] This specifies the particular CSAP executable that is compatible with the user's device. See the table below in Appendix A. 

[?] The '?' character option causes the utility to wait and display the result of the configuration in the CSAP window. The '!' character option causes the utility to display the result only if the file fails to generate or there is an error.

[filename] A file containing the configuration commands.

[hideapp] This option will minimize the CSAP window to the taskbar while it is running.

[/logfile logfilename] This option opens a logfile of the name "logfilename" which will cause any information which is written to the status window to also be written to this file. The "logfilename" should be a full path name such as c:\mydir\mysub-dir\mylog.log.

[/imagefile imagefilename] This option specifies the name of the SAP file and the path where it should be saved to on your hard disk. A user may later update a Cyclone with this image file.  

[imagecontent] This option is a string that can be used to describe the SAP image, whether it is stored in a file or on the Cyclone. If the configuration command :DESCRIBEIMAGE is also present in the .CFG file, this will be overwritten.

[paramn=s] See Section 4 below

Here is a command-line using the cfg script from the previous example (one continuous line):

4. Leveraging Command-line Parameters In The Configuration Script

A CSAP command-line parameter in the form of /PARAMn=s inserts text into the script file in place of special tags. This replaces any part of the script, including: programming commands, header commands, comments, filenames, and parameters. Valid values of n are from 0-9. The string s replaces any occurrences of /PARAMn in the script file.

Following is an example of using command-line parameters to affect the generation of a programming image by overriding script/configuration settings with command-line specified options. The following example shows how several options specified in the configuration file previously shown can be overridden. Specifically this example overrides:

1. The string describing the programming image (shown on LCD/Console) [/PARAM0]
2. The programming algorithm to use [/PARAM1]
3. The binary data file (S19/Elf/Hex) to programming to the device [/PARAM2]
4. One of the programming commands (VC) which can now be specified on the command-line [/PARAM3]

; Automatically generated configuration file
; Silicon Manufacturer is ARM Based (All Manufacturers)
; Silicon Architecture is ARM Based (Kinetis, LPC, etc.)
;
:RESETDELAY 0
:DEVICE NXP_KL2x_KL25Z128M4
:USESWD 1
:DEBUGFREQUENCY 3330
:SAPGUIVERSION 362E3935
:PROVIDEPOWER
:POWERVOLTAGE 3.3
:POWERDOWNDELAY 250
:POWERUPDELAY 250
:KEEPPOWERON 0
:NEWIMAGE
:DESCRIBEIMAGE /PARAM0
CM /PARAM1
SS /PARAM2
EN ;Erase if not Blank
PT ;Program Trim
PM ;Program Module
/PARAM3 ;Verify Checksum
SD  ;SECURE DEVICE

These parameters are added to the command-line call to make this more generic configuration file act like the original configuration file when generating an image :

"/param0=KL25Z128 TEST IMAGE"

/param1=C:\PEMicro\cyclone\supportfiles\supportFiles_ARM\NXP\KL2x\freescale_kl25z128m4_1x32x32k_pflash.arp

/param2=C:\MyWorkspace\MyProjectApplicationBinary.s19

/param3=VC

NOTE: In the Windows OS, if a parameter has a space in its value, the entire parameter (including the /PARAMn=) should be enclosed in double quotations. This indicates to Windows and CSAP that it is a single parameter.

NOTE: An algorithm's base address can be a separate parameter or you can include it as part of the algorithm string.

“/param1=C:\PEMicro\cyclone\supportfiles\supportFiles_ARM\NXP\KL2x\freescale_kl25z128m4_1x32x32k_pflash.arp 0”

Below is the complete command-line using my example with all parameters (one continuous line):

Similar to most commandline applications, the system %ErrorLevel% environment variable returns the error code from the CSAP application.

5. SAP Image Comparison

CSAP includes a small amount of unique identifying data such as an ID and timestamp when it generates a SAP image. Due to the encoding format that we use, the inclusion of this unique data makes the final output very different each time even if you do not change the settings and configuration. 

If you use the CycloneControl SDK to compare a new SAP image that you just generated against an existing image on the Cyclone, such as the CompareImageInCycloneWithFile function, this will always return a mismatch. You can only compare an existing image on the Cyclone against the same file that was used to load it.

If you want to verify that two SAP images used the same settings and configuration, CSAP calculates a checksum which excludes the unique data. This checksum does not change if everything else is the same. 

6. Automatically Loading The Generated SAP Image To a Cyclone

Please refer to the section "Launching a programming image on a Cyclone" in our comprehensive guide to using the Cyclone Control Console here : Cyclone Control Console

7. Automatically Installing the Cyclone Software

The installation of the Cyclone software package can also be automated. Type the following commands exactly as shown from the command-line prompt or your batch file.

Silent installation:

start /w cyclone_install.exe /S /D=C:\PEMicro\cyclone

Silent un-installation:

start /w C:\PEMicro\cyclone\uninstall.exe /S

NOTE: /S and /D should be uppercase.

/S runs the installer or uninstaller silently.

/D sets the installation directory. It must be the last parameter used in the command line and must not contain any quotes, even if the path contains spaces. Only absolute paths are supported.

8. Conclusion

Using the procedure described in this document, your production team can fully automate generation of stand alone programming images, reduce errors, and increase production output.

Appendix A

The CSAP executables, which generate the SAP files, are currently found within the Cyclone installation folder in the ImageCreationSupportFiles sub-folder.