PEmicro Blog

How To Automate Cyclone Stand-Alone Programming Image Generation

April 2021 - Updated with steps to perform an automated silent install of the Cyclone software package. See Section 7 below.

April 2024 - Updated Section 3 with a list of new commands for CSAP.

PEMicro has released the  Cyclone Control Suite which offers a powerful yet flexible set of utilities to automate control of the Cyclones on your production line. 

Many of our users have to work with a very large number of stand-alone programming (SAP) image files and have to continually regenerate these images with new binaries.

This blog post shows how they can also fully automate the process of generating stand-alone programming (SAP) image files to remove the chance of errors that could occur when the process is done manually.

1. Configuration Script File

The Cyclone Image Creation Utility that comes with your Cyclone software 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 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).

Image Script tab

Power and Communication tab

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 you have an existing Stand Alone Programming image (SAP), in the Cyclone Image Creation Utility 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 you are 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.

 

3a. 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.

[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.

[-inputcfg="cfgfilename"] This parameter passes the name or path to the configuration script.

[-outputsapobj="objfilename"] This parameter passes the name or path of the intermediate SAPOBJ file that is generated.

[/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.

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

[paramn=s] See Section 4 below

 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"


CSAPACMP

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.

[inputsapobj="sapobjfilename"] This parameter passes the name or path of the intermediate SAPOBJ file.

[-restrictmaxprograms=100] This is the 'Maximum Programming Successes' parameter in the Deployment Manager.

[-restrictmaxerrors=100] This is the 'Maximum Programming Failures' parameter in the Deployment Manager.

[-restrictdatefrom=mm/dd/yyyy] This is the start date of the 'Limit Image Usage between dates' parameter in the Deployment Manager.

[-restrictdateto=mm/dd/yyyy] This is the end date of the 'Limit Image Usage between dates' parameter in the Deployment Manager.

[-peimagekeyfile="peimagekeyname"] This parameter passes path to the peimagekey private key that will encrypt your image.

[-deploysapfile="sapfilename"] This parameter passes the name of the SAP or eSAP output.

[-deploydescription="Image Description"] This parameter is a string that shows up as the description of the image.

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.

[filename] A file containing the configuration commands.

[/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.


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.

CSAP command-line utility

Target Architectures

CSAPACMPZ

ARM DEVICES (All supported vendors)

CSAPARMZ

MAC71XX, MAC72XX

CSAPBDM12Z

HC(S)12(x)

CSAPBDMCFV1Z

COLDFIRE V1

CSAPBDMCFZ

COLDFIRE V2, V3, V4

CSAPBDMPPCZ

POWERPC 5XX

CSAPDSCZ

DSC

CSAPHCS08Z

HCS08

CSAPMON08Z

HC08

CSAPPPCNEXUSZ

MPC55XX, MPC56XX, MPC57XX

CSAPRS08Z

RS08

CSAPS12ZZ

S12ZZ

CSAPTRICORE
TRICORE
CSAPWIZ00
RENESAS
CSAPWIZ01
STM8


Tags related to this Blog Post

Cyclone     Cyclone FX     ARM     NXP     Production Programming     Automated Control