PEmicro | Experts in Embedded tools for Flash Programming and Development
Cart New Account Login

HomeAbout usProductsSupportForumsBlogCustomer Service


by Keith McNeil & Kevin Perreault


Note: This blog post was updated in July 2019 with information regarding Cyclone image encryption (part of the ProCryption Security License).

The Cyclone Control Console is a powerful command-line application that allows simultaneous control of one or more Cyclones. Programming images can be added/removed, settings read/set, programming operations launched, and dynamic data programmed. The command-line application displays comprehensive status messages and also returns an error code indicating success or failure. The application can be launched from a script, a console, or another application. It is one of the three main components of the Cyclone Control Suite including : the Cyclone Control Console, the Cyclone Control GUI, and the Cyclone Control SDK.

This blog post demonstrates many common Cyclone programming operations which can easily be performed with the Cyclone Control Console application, including:

Getting Started

Cyclone Connection Examples

Image Management Examples (Adding/Removing)

Programming Launch Examples

Reading/Writing Cyclone/Image Properties

Managing Encrypted SAP Images

Additional Notes/Features

Conclusion

Getting Started

The Cyclone User Manual has information on different command-line parameters available on the Cyclone. The Cyclone Control Console can also present a condensed listing of the available parameters when using the -help command-line parameter.

Listing available Cyclone Control Console command-line parameters

The current list of commands may always be fetched from the console application with the -help command-line parameter. Available options are displayed:


Cyclone Connection Examples

Listing auto-detected Cyclones

Cyclones may be connected to the PC via USB, Ethernet, and Serial port connections. Cyclones connected via USB and Ethernet connections may be auto-detected. For Ethernet, only Cyclones on the local subnet will be automatically detected (remote cyclones may be controlled from the console but not auto-detected). The Cyclone’s Name, IP, and Port number are listed and any of these identifiers may be used to open a Cyclone. The Name and IP address are recommended for opening a Cyclone since the port number may change depending upon how many Cyclones are connected.

This example shows three cyclones being detected, with each Cyclone being connected to the PC via both USB and Ethernet connections.

Note: When a Cyclone is connected both via USB and Ethernet, it will be listed twice. 

Opening a Cyclone by name (and listing images)

Opening a Cyclone by name is the most common way of specifying a Cyclone. It will work regardless of whether it is connected via USB or Ethernet. The identifier chosen is specified by the -cyclone=[identifier] command-line parameter where the [identifier] is the name, IP, or port of the Cyclone. Most command-line operations (such as Launch Programming) will use the -cyclone parameter to specify the cyclone(s) to open and then include other parameters to indicate what functions to execute. Multiple Cyclones can be specified in a comma-delimited list or by using multiple -cyclone command-line parameters.

In this example, we also have a -listimages command-line parameter, which indicates that the utility should display the list of images found in both internal and external memory of the specified Cyclone. 

Here is an example of opening the cyclone ‘Ada’ by name and listing the images in it.

Image Listing Format

The programming images are listed by number. Each image will also specify "eSAP" if the image is encrypted, or "SAP" if the image is not encrypted. The image's storage location is also designated: "Internal" for images stored on the Cyclone's internal memory, or "External" for images stored on an SD memory card in the Cyclone's SDHC Port (Cyclone FX or SDHC Port Activation License required). Finally, the image description is listed (this may differ from the filename).

Note : The name of a Cyclone can be set from the LCD touchscreen or from any of the Cyclone Control Suite components (GUI, Console, and SDK). Once the name is set, it is stored in non-volatile memory in the Cyclone and will be remembered until changed. Other ways to open a Cyclone are by the IP address or port number.

Opening a Cyclone by port (and listing images)

In addition to the Name and IP number, a Cyclone may be specified by port name. This can be useful if there is only one Cyclone connected on the USB/Ethernet buses or if the Cyclone is connected via a COM port. To open a Cyclone attached to a specific COM port, use the appropriate COM port number (COM1...COM8). To open the first USB Cyclone detected, use USB1 (USB ports range from USB1..USB39). To open the first Ethernet Cyclone, use Ethernet1 (Ethernet ports range from Ethernet1..Ethernet99). Note that the Cyclones are listed in a sorted order to determine the port number, so port numbers may change with the number of Cyclones detected. That is the reason we recommend using the Cyclone Name or IP address to specify the appropriate Cyclone(s) when using multiple Cyclones simultaneously. When using a single Cyclone, however, the port number can be a simple way of opening any Cyclone attached to the PC without knowing its IP or Name.

An example of opening the first Cyclone detected on the USB bus:

Below is an example of opening a Cyclone by its IP address. The Cyclone can be remotely situated from the PC. In this case the Cyclone’s IP address, Gateway Address, and Netmask should be properly set for the network it is connected to. Example opening by IP address:

Opening multiple Cyclones (and listing images)

Opening multiple Cyclones is simple. Either pass a comma-delimited list of Cyclone names to the -cyclone= parameter (such as -cyclone=ada,colossus,hal9000) or use multiple -cyclone parameters (such as -cyclone=ada -cyclone=colossus -cyclone=hal9000). The other operations on the command-line will be executed on all open Cyclones, including programming launch, with the exception of dynamic data programming (where the Cyclone to which to apply the dynamic data is specified as part of the parameter). Here is an example of listing images on two Cyclones:

Image Management Examples (Adding/Removing) 

Adding a programming image to a Cyclone

Images can be added to a Cyclone by using the -addimage= command-line parameter and specifying the filename of the programming image to add. Multiple cyclones may be specified as well as multiple images on the same command-line. In this example, we add a single image to a single Cyclone:

Note that you will not be able to load an encrypted programming image (eSAP file) onto a Cyclone unless the ImageKey associated with that encrypted image resides on the Cyclone. See the Encrypted SAP Images section for more information.

Removing a programming image from a Cyclone

Specific images can be removed from a Cyclone by number, description, or a condensed description. A condensed description is the image description with all spaces removed (which makes using command-line parameters easier when the description has spaces). The identifier specified is not case-sensitive. The HAL9000 Cyclone in this example currently has the following programming images:


Images on Cyclone HAL9000

   Image 1 (SAP-Internal) : Red Image v1.0

   Image 2 (SAP-Internal) : Green Image v1.0

   Image 3 (SAP-Internal) : Blue Image v1.0

   Image 4 (SAP-Internal) : Red Image Barcode v1.0

   Image 5 (SAP-Internal) : Green Image Barcode v1.0

   Image 6 (SAP-Internal) : Blue Image Barcode v1.0

   Image 7 (SAP-Internal) : Run Test Application v1.02

   Image 8 (SAP-Internal) : Green


In the following example, we remove an image by its full description (including spaces). Because this example is on Windows, we surround a parameter with double quotations to signify that it is one parameter even though it contains spaces:




In the following example, we remove an image by its condensed description. This works on all operating systems even though the actual description has spaces (we omit them on the command line). For this reason, we recommend using condensed descriptions. Notice that there are no quotation marks needed in this example:


In the following example, we remove an image by its number:


Note that as images are deleted, the image numbers will change. If there are 5 images, and image 4 is deleted, image 5 becomes image 4.

Erasing all images in a Cyclone

There are two command-line parameters which can be used to delete groups of images in the Cyclone so that you don't have to remove them individually:


   -eraseallinternalimages : Erase all internal images from open Cyclones

   -eraseallexternalimages : Erase all external images from open Cyclones


Internal images reside within the encrypted internal memory of the Cyclone while external images reside in an encrypted SDCard optionally plugged into the Cyclone. Images can be erased from multiple Cyclones by specifying more than one Cyclone on the command-line. In this example, we are erasing all images residing internally within the HAL9000 Cyclone:


Adding multiple images into multiple Cyclones

Below is an example of how to combine different image management techniques together. We'll open two Cyclones (Agnes and Colossus), erase all internal images, and then add six programming images to each Cyclone, all with one command:  



Programming Launch Examples

Launching a programming image on a Cyclone

Images in the Cyclone may be selected and launched by specifying either the image number in the Cyclone, the image description, or the condensed version of the image description (with spaces removed). 

This example shows how to launch programming of an image that is specified by its condensed description: 


This example shows how to launch programming of an image that is specified by the image number in the Cyclone:

Note that programming cannot be launched for an encrypted (eSAP) image if the ImageKey for that file has been removed from the Cyclone. See the Encrypted SAP Images section for more information. 

Launching the same image simultaneously on different Cyclones, selected by name

The same image can be launched on multiple Cyclones simultaneously simply by specifying multiple Cyclones on the command-line. If different image sets exist on each Cyclone, using the condensed image descriptions is a good way to guarantee the appropriate programming image is launched. If the image set on each Cyclone is the same, the image number will match, and as such the image number is another way to launch the same image on multiple Cyclones. This example uses the condensed image description to launch programming:



Launching different images simultaneously on different Cyclones, selected by number

Sometimes a board will have multiple microcontrollers on it which need to be programmed simultaneously. It is often advantageous to use multiple Cyclones which each program a different image simultaneously. The approach is to make sure each Cyclone is loaded with a different image such that they have the same number in each Cyclone. An easy way to do this is to erase all images in both Cyclones and then to add a different image to each Cyclone. In this case, image 1 in each Cyclone would be different but could be launched at the same time :




Programming dynamic data after image programming

In addition to programming the data specified as part of a programming image, additional data can also be programmed into each target device. This data can be specified each time a programming image is launched and as such can be customized on a target-by-target basis. Dynamic data has many use cases: customer driven serialization, configuration, tracking, date coding, etc. Multiple sets of dynamic data can be specified on the command-line. Data can be provided as an array of bytes or as a null terminated string. 


As part of the dynamic data programming parameter, the Cyclone handle number must be specified. This allows different dynamic data to be programmed into targets connected to each opened Cyclone. If only one Cyclone is being launched, the value used would be 1. If three Cyclones were specified on the command-line, they would be numbered in order from left to right on the command-line as 1, 2, and 3.


The syntax for programming dynamic data as an array of bytes is:


   -putdynamicdata=[cyclone number],[address],[data] 


In the following example, we program a user-generated 4-byte serial number array into the target after the main image programming is complete:




Note: When programming dynamic data, image programming must first be launched in that command line.


The syntax for programming dynamic data as a null terminated string is:


   -putdynamicstring=[cyclone number],[address],[string] 


In the following example, we program a user-generated IP address string into the target after the main image programming is complete:




Note: Image programming must be launched as part of the command line when programming dynamic data. The examples given are for serial numbers and IP strings generated by the customer. The Cyclone also supports the automatic count of serial numbers to be stored as part of the image.

Programming different dynamic data into multiple targets from different Cyclones

In the following example we program both a unique user-generated serial number and a unique user-generated IP address string into two different targets connected to two different Cyclones:




Note: Image programming must be launched as part of the command line when programming dynamic data. The examples given are for serial numbers and IP strings generated by the customer. The Cyclone also supports the automatic counting of serial numbers stored as part of the image.

Reading/Writing Cyclone/Image Properties

There are many properties in the Cyclone and its resident images which may be useful to view and in some cases modify.

Fetching a list of property categories from the Cyclone

Properties are stored in different categories in the Cyclone, including system settings, network settings, image specific settings, and others. A list of the categories available can be displayed by using the -showproperties= command-line parameter without anything following the equals sign.




Reading the list of property names/values in a category

In the following example, we display the properties in the “cycloneproperties” category. This includes the name of the Cyclone as well as the number of images in the Cyclone. The syntax of the -showproperties command-line parameter is:


   -showproperties=[category],[image name or #] 


This will show all properties in the category. Leave blank after the = for the entire category list. In this case, since we are not accessing the properties of an image, we can set the image name or number to 0 or leave it blank: 

Reading image properties such as next serial number and CRC

Properties of images stored in the Cyclone can be read by accessing the “imageproperties” category and specifying the image name or number. The syntax of the -showproperties command-line parameter is:


   -showproperties=[category],[image name or #] 


This will show all properties in the category. Leave blank after the = for the entire category list. In this case, we are reading the properties of image “green_serial”. Note that information such as the image’s CRC and serial number are displayed:

The image has a single serial number which is currently “PE-00b”. The next time programming is launched, the target will be programmed with serial number “PE-00b” and because the serial file increments by 2, the Cyclone will automatically increment the serial number to “PE-00d”. This serial number is an example of the automatically counting serial number capability of the Cyclone. PEmicro has a serial number definition utility which allows the user to create automatically counting serial numbers.


To demonstrate, we will launch programming and display the serial number in a single console command. As part of the programming process, ‘PE-00b’ is programmed into the target and the serial number stored for the the image changes to ‘PE-00d’:


Setting a Cyclone’s name by writing the ‘cyclonename’ property

Some settings in the Cyclone are writeable, such as the network settings and the Cyclone’s name. In this example we are going to set the Cyclone’s name. Setting a Cyclone’s name can be useful since we can use to name to specify a specific Cyclone for other commands. It could be as simple as declaring the unit's function “JuliesCycloneDoNotTouch” or choosing a name that implies location such as “ProductXFixtureSlot3”. 


Let’s start by listing auto-detected Cyclones:

The Cyclone called Ada is listed on both on the USB and Ethernet Buses of the PC. Let’s query the “cycloneproperties” category of the Cyclone named Ada:

As expected, the “cyclonename” property is Ada. We know this because that is how we have been connecting to it. Let’s say we wanted to change the name to Skynet instead. We would use the -setproperty= command to modify the value. The syntax of the command is:


   -setproperty=[category],[image name or #],[property],[value] 


Since the name is not in the “imageproperties” category, we can set the image number to 0. Here we change the name from Colossus to Skynet:



Now if we query the Cyclones found on the USB and Ethernet buses, we can see that the Cyclone name has been changed from Ada, to Skynet: 

Managing Encrypted SAP Images

The Cyclone Control Console provides commands that are used to help manage encrypted (eSAP) programming images. These commands allow you to list, add, and delete ImageKeys, which are files used to encrypt a programming image. An eSAP image cannot be loaded onto a Cyclone or, once loaded, launched for programming, unless the ImageKey used to encrypt that eSAP image resides on the Cyclone.

Determining A Programming Image's Encryption Status

The -listimages command is used to list the programming images on a particular Cyclone. This image listing will indicate whether each image is encrypted or not. Images listed as "eSAP" are encrypted, images listed as "SAP" are not. The first two programming images listed in the screen below are encrypted.

Specific information about an individual programming image's encryption status can be viewed by using the -showproperties=imageproperties command for that specific image. There are three values relevant to image encryption:

1) The imageEncryptionStatus property displays the encryption status of a programming image as one of three values:

  • Encrypted. Ready For Execution.
  • Encrypted. Locked - No Key Found.
  • Not Encrypted. Ready For Execution

2) The imageKeyDescription property displays the name of the ImageKey, if any, that is associated with the programming image.

3) The imageKeyID property displays the unique ID of the ImageKey, if any, that is associated with the programming image. 

The screen below shows all of the -imageproperites for the image "K64 Encrypted BB 16K":

These properties indicate that this is an encrypted image, but the ImageKey is missing. The image is therefore locked and cannot be programmed. The ImageKey needed to unlock this image so that it can be programmed is called "Kevin BB" and its ID# is "pei-6D479B42-51D84364-5CA47697".

Using ImageKey Commands

What follows is an example, using the image above, of how to use Cyclone Control Console ImageKey commands to determine which ImageKey is missing, load that ImageKey onto the Cyclone so that the image may be programmed, and then delete the ImageKey, which once again locks the encrypted image.

The console provides commands to list, add, and remove ImageKeys: 

  • -listEncryptionKeys
  • -addEncryptionKey=[file path]
  • -deleteEncryptionKey=[objectID or display index]

List ImageKeys

First, the -listEncryptionKeys command shows that there is an ImageKey on the Cyclone (whose display index is 1) but it is not the key named "Kevin BB" that we need to unlock the image:

Add An ImageKey

The -addEncryptionKey command is then used to add the missing ImageKey to the Cyclone. The file path for the ImageKey is required:

The -listEncryptionKeys command now shows that the required ImageKey has been added, at display index 2:

Another look at the image properties shows the encrypted image is now ready for programming:

Delete An ImageKey

The user may wish to later remove this ImageKey so that the eSAP file "K64 Encrypted BB 16K" cannot be programmed. This is done by using the -deleteEncryptionKey command, with either the ImageKey's ID or (as in the example below) the ImageKey's display index:

Listing the ImageKeys once more with the -listEncryptionKeys command shows that the ImageKey has been removed.

More information on Cyclone image encryption is available in the blog post "Cyclone Adds RSA/AES Encryption for Production Programming."

Additional Notes/Features

Recovering success/error result from python/bash/batch/etc


In addition to displaying success and error information as strings written to the console, the Cyclone Control Console also returns an appropriate error code to the operating system on the PC. This error code can be tested for from an application or from various scripting languages. A zero error code indicates successful operation and a non-zero error code indicates a failure.


Here is an example of a Windows Batch file which can successfully recover success/error information from the Cyclone Control Console:


cyclonecontrolconsole -cyclone=Agnes -launchimage=green_serial

if ERRORLEVEL 1 goto errorOccurred

echo Successfully programmed!

goto done

:errorOccurred

echo Programming FAILED!!!!!

:done


Here is an example of a bash shell script which can successfully recover success/error information from the Cyclone Control Console:


#!/bin/bash  

cyclonecontrolconsole -cyclone=Agnes -launchimage=green_serial

errorReturn=$?

if [ $errorReturn == 0 ]; then

  echo 'Successfully programmed!'

else

  echo 'Programming FAILED!!!!! with error code '$errorReturn

  exit 1

fi


Here is an example of a python script which can successfully recover success/error information from the Cyclone Control Console:


import subprocess

import sys


P = subprocess.run("cyclonecontrolconsole -cyclone=Agnes -launchimage=green_serial", shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)

print("Printing STDOUT:")

print(P.stdout.decode())

if P.returncode == 0:

print("Successfully programmed!")

else:

print("Programming FAILED!!! with error code " + str(P.returncode))

sys.exit(1)


Order of execution of command-line parameters


Command-line parameters are all evaluated before any are executed. If there is an invalid parameter, the Cyclone Control Console will generate an error and will indicate which parameter is not understood. Parameters are executed in a priority order. Multiple parameters of the same priority are executed in the order that they appear on the command-line (from left to right). The priorities of the parameters shown in the blog post are (from highest to lowest):


 10 -help

 9  -listcyclones

 7  -cyclone

 5  -eraseallinternalimages

 5  -eraseallexternalimages

 5  -eraseimage

 4  -addimageinternal

 4  -addimageexternal

 4  -listimages

 3  -launchimage

 2  -putdynamicdata

 2  -putdynamicstring

 2  -setproperty

 1  -showproperties


Cyclone Control Suite - Download and Licensing

The latest Cyclone installation software includes the Cyclone Control Suite. The Cyclone Control Console is one of the components of the Cyclone Control Suite.

 The standard features of the Cyclone Control Suite work with any Cyclone unit, regardless of model or purchase date (no license required).

 The advanced automation features of the Cyclone Control Suite require either:

Encrypted programming images require either:

The blog post examples above use a mixture of standard and advanced features.


Conclusion

The Cyclone Control Console is a command-line tool which allows the user to read/set Cyclone settings, add/remove images and imagekeys,  launch images, and even add dynamic data via the command line.  It's one of the three powerful components that comprise PEmicro's Cyclone Control Suite, which is included with both CYCLONE and CYCLONE FX programmers.





search in blog posts

Tags

Product pages
Cyclone (51)
Cyclone FX (52)
Multilink (26)
Multilink FX (21)
GDB Server (12)
Prog ACMP (10)
Interface Library Routines (5)


Manufacturer
ARM (47)
NXP (52)
Microchip (6)
Cypress (6)
Infineon (2)
Maxim (3)
Nordic Semiconductor (3)
Silicon Labs (5)
Silergy Teridian (1)
STMicroelectronics (7)
Texas Instruments (2)
Toshiba (3)
Renesas (6)


Categories
Production Programming (61)
Debug (31)
Automated Control (17)
Miscellaneous (36)



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