PEmicro - P&E Microcomputer Systems: Over 30 years as an Industry leader in Embedded Systems Development Tools, debug probes, and production programmers
Cart New Account Login

HomeAbout usProductsSupportForumsBlogCustomer Service

by Johnny Ng

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 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 users goal, for instance, was to update a stand alone programming image each time a referenced binary application file changed, it is as simple as calling the CSAP utility with exactly the same configuration file specified (since when generating the programming image, the data included is sourced from the referenced binary file which changed).

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 a 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. Lines in the file that begin with semicolons are comment lines. 

; Automatically generated configuration file

; Silicon Manufacturer is NXP

; Silicon Architecture is ARM devices














CM  C:\PEMicro\cyclone\supportfiles\supportFiles_ARM\NXP\KL2x\freescale_kl25z128m4_1x32x32k_pflash.arp

SS   C:\MyWorkspace\MyProjectApplicationBinary.s19

EN  ;Erase if not Blank

PM  ;Program Module

VC  ;Verify Checksum

2. Script Commands

The top of the script file consists of setup commands preceded by a colon.

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

:SAPGUIVERSION Internal command. This is not required.

:USEPRORELAY Turns on Cyclone Relays.

:DEVICEPOWER Selects voltage generated by Cyclone. 5V = 2. 3V = 2. 2V =4.

:POWERDOWNDELAY This controls the delay after power off setting.

:POWERUPDELAY This controls the delay after power on setting.

:POWEROFFONEXIT 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 algorithm may support additional commands that are not listed here. A complete list can be found in the CPROGACMP user guide found in the Cyclone software 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. The values for the reset_delay and bdm_speed are shown in the comments of the previous configuration script. 

[reset_delay n] Specifies a delay after the Cyclone resets the KL25Z128 that we check to see if the target device has properly gone into background debug mode. This is useful if an external reset driver IC holds the target device in reset after the Cyclone releases the reset line. The n value is a delay in milliseconds.

[bdm_speed n] This option allows the user to set the BDM shift clock speed of the Cyclone. This integer value may be used to determine the speed of communications according to the following equation: Cyclone : (50000000/(2*n+5)) Hz
The value n should be between 0 and 31. This shift clocktakes effect after the commands in the top of the programming algorithm are executed so that these commands can increase the target device frequency and allow a faster shift clock. This clock can't generally exceed a div 4 of the processor bus frequency.

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.

Here is a command-line using the cfg script from the previous example:

csapacmpz.exe ? reset_delay 250 bdm_speed 5 "C:\MyWorkspace\MyProject\KL25Z128_script.cfg" /imagefile "C:\MyWorkspace\MyProject\"

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, 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 show 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 NXP

; Silicon Architecture is ARM devices
















EN  ;Erase if not Blank

PM  ;Program Module

/PARAM3  ;Verify Checksum

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"




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

csapacmpz.exe “/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 reset_delay 250 bdm_speed 5 "C:\MyWorkspace\MyProject\KL25Z128_script.cfg" /imagefile "C:\MyWorkspace\MyProject\"

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

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

CSAP command-line utility

Target Architectures


ARM DEVICES (All supported vendors)























search in blog posts


Product pages
Cyclone (31)
Cyclone FX (33)
Multilink (15)
Multilink FX (10)
GDB Server (9)
Prog ACMP (3)
Interface Library Routines (4)

ARM (29)
NXP (39)
Atmel (3)
Cypress (2)
Infineon (1)
Maxim (2)
Nordic Semiconductor (2)
Silicon Labs (2)
STMicroelectronics (3)
Texas Instruments (1)
Toshiba (2)
Renesas (6)

Production Programming (44)
Debug (20)
Automated Control (10)
Miscellaneous (35)

© 2018 P&E Microcomputer Systems Inc.
Website Terms of Use and Sales Agreement