1. Configuration Script File

The Cyclone Image Creation Utility that is included with the Cyclone software allows the user 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 is stored inside a Cyclone programmer and contains all information necessary for programming. 

The user can also call the 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. Configure all appropriate settings with the Cyclone Image Creation Utility. Then select the main menu option "File -> Save Configuration Script" to save the configuration as a .CFG file. 

2. If the user has an existing Stand Alone Programming image (SAP), in the Cyclone Image Creation Utility they should select the main menu option "File ->Import Configuration From Image". This will load the configuration into the Image Creation Utility. Select the main menu option "File -> Save Configuration Script" 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 the user is only calling CSAP. 

; Automatically generated configuration file
; Silicon Manufacturer is Generic
; Silicon Architecture is ARM devices
; Do not modify the comments above this line if using Cyclone Image Creation Utility
:RESETDELAY 2500
:ARCHTYPE 1
:DEVICE NXP_KL2x_KL25Z128M4
:USESWD 1
:DEBUGFREQUENCY 3330
:SAPGUIVERSION 392E3439
:PROVIDEPOWER
:POWERVOLTAGE 3.3
:POWERDOWNDELAY 250
:POWERUPDELAY   250
:KEEPPOWERON 0
:IMGOPTIONS {"pesettings":{"create_image_settings":{"image_settings_version":946,"allow_overlay_data_to_overwrite_image_data":false}}}
:NEWIMAGE
:DESCRIBEIMAGE Widget Firmware v1.1
CM  C:\PEMicro\cyclone\supportfiles\supportFiles_ARM\NXP\KL2x\freescale_kl25z128m4_1x32x32k_pflash.arp
QO  C:\PEMicro\cyclone\workspace\KL25Z128.s19
EN   ;Erase if not Blank
PT   ;Program Trim
PM   ;Program Module
VC   ;Verify Checksum
SD   ;SECURE DEVICE

2. Script Commands

Comments are preceded by a semicolon ;. 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).

:IMGOPTIONS - Shows the settings on the Image Settings tab.

: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

QO - Queue object file (S19/Elf/Hex)

EN - Blank check and erase

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 LC and Cyclone FX user manuals 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 SAPOBJ file.

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

csapacmpz.exe ? -inputcfg="C:\\MyProject\KL25Z128_script.cfg"-outputsapobj="C:\MyProject\cyclone.sapobj"

Then we will pass the SAPOBJ back again to CSAPACMPZ to generate the final SAP or eSAP file that is stored onto the Cyclone. This is where you can pass additional encryption or image restriction parameters that are configured with the Deployment Manager.

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

csapacmpz.exe ? -inputsapobj="C:\MyProject\cyclone.sapobj"-deploysapfile="C:\MyProject\KL25Z128_image.sap"

Note that you may find additional parameters used by the Deployment Manager in the generated log file located at:

 C:\PEMicro\cyclone\imageCreation\ImageCreationSupportFiles\*.deploylog

The following is a list of deprecated parameters. These should no longer be used with CSAP but are still supported for compatibility with legacy setups.

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 Generic
; Silicon Architecture is ARM devices
; Do not modify the comments above this line if using Cyclone Image Creation Utility
:RESETDELAY 2500
:ARCHTYPE 1
:DEVICE NXP_KL2x_KL25Z128M4
:USESWD 1
:DEBUGFREQUENCY 3330
:SAPGUIVERSION 392E3439
:PROVIDEPOWER
:POWERVOLTAGE 3.3
:POWERDOWNDELAY 250
:POWERUPDELAY   250
:KEEPPOWERON 0
:IMGOPTIONS {"pesettings":{"create_image_settings":{"image_settings_version":946,"allow_overlay_data_to_overwrite_image_data":false}}}
:NEWIMAGE
:DESCRIBEIMAGE /PARAM0
CM  /PARAM1
QO  /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 generic configuration file act like the original configuration file when generating an image :

"/param0=Widget Firmware v1.1"
/param1=C:\PEMicro\cyclone\supportfiles\supportFiles_ARM\NXP\KL2x\freescale_kl25z128m4_1x32x32k_pflash.arp
/param2= C:\PEMicro\cyclone\workspace\KL25Z128.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 (note: this is one continuous line):

csapacmpz.exe "/param0=Widget Firmware v1.1" /param1=C:\PEmicro\cyclone\supportFiles\ supportFiles_ARM\NXP\freescale_kl25z128m4_1x32x32k_pflash.arp   /param2=C:\PEmicro\cyclone\workspace\KL25Z128.s19 /param3=VC 
-inputcfg="C:\MyProject\KL25Z128_script.cfg" -outputsapobj="C:\MyProject\cyclone.sapobj"

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 SAP image 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.