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

Please accept the use of cookies on our site

At PEmicro we use web browser cookies in order to provide you with an enhanced experience and in order to be able to do things like shopping cart processing and identify you when you login to our website.

Click here to accept

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. 

; Automatically generated configuration file
; Silicon Manufacturer is ARM Based (All Manufacturers)
; Silicon Architecture is ARM Based (Kinetis, LPC, etc.)
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

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

[executable] This specifies the particular CSAP executable that is compatible with the user's device.

[?] 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):

csapacmpz.exe ? "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, 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.)
EN  ;Erase if not Blank
PT  ;Program Trim
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 (one continuous line):

csapacmpz.exe “/param0=KL25Z128 TEST IMAGE”  
/param2=C:\MyWorkspace\MyProjectApplicationBinary.s19 /param3=VC "C:\MyWorkspace\MyProject\KL25Z128_script.cfg"
/imagefile "C:\MyWorkspace\MyProject\" 

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

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 (34)
Cyclone FX (36)
Multilink (17)
Multilink FX (12)
GDB Server (10)
Prog ACMP (3)
Interface Library Routines (4)

ARM (31)
NXP (40)
Microchip (4)
Cypress (2)
Infineon (1)
Maxim (2)
Nordic Semiconductor (2)
Silicon Labs (3)
STMicroelectronics (4)
Texas Instruments (1)
Toshiba (2)
Renesas (6)

Production Programming (46)
Debug (22)
Automated Control (10)
Miscellaneous (35)

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