Cyclone Control Suite: Cyclone Control Console
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: Image Management Examples (Adding/Removing) Reading/Writing Cyclone/Image Properties 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. The current list of commands may always be fetched from the console application with the -help command-line parameter. Available options are displayed: 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 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 FX's SDHC Port. 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. 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 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: Images can be added to a Cyclone by using the -addimageinternal= 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. 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. 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: 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: 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. 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: 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 : In addition to the data specified as part of a programming image, additional unique data can be programmed into each target device. This function has many use cases: customer driven serialization, configuration, tracking, date coding, calibration, etc. The unique data can be overlaid on top of the static so all data is programmed at once; please refer to this detailed description of how the overlay data process works. Note that the overlay data function, shown below, is most commonly used to program blank space not programmed by the static data in the image. However a setting in the Image Creation Utility can be set to allow the overlay data to overwrite the base image. An example of this could be, if the base image contains a default IP address at a certain memory location, and the overlay data is used to overwrite this on a board-by-board basis. There are two command-line parameters for specifying the data in either hexadecimal format or string format. Specifies overlay data to be programmed during program module operation. Must be issued together with the "-launchimage" command; order does not matter since prioroty is assigned. Specifies overlay data as NULL terminated string to be programmed during program module operation. Must be issued together with the "-launchimage" command; order does not matter since prioroty is assigned. This example shows the overlay data specified in hexadecimal format. This example shows the overlay data specified in string format. We can even specify the overlay data to two different targets connected to two different Cyclones. The command-line parameters would be (in one single line): Note: Image programming must be launched as part of the command line when programming overlay data or overlay string. The programming image must have a programming-related command such as PM, PB, PW, or PR. 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. 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 using the older -putdynamicdata command-line parameter. There are many properties in the Cyclone and its resident images which may be useful to view and in some cases modify. 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. 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: 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’: 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] Here we change the name from Ada 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: 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: 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". 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: 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." 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: Here is an example of a bash shell script which can successfully recover success/error information from the Cyclone Control Console: Here is an example of a python script which can successfully recover success/error information from the Cyclone Control Console: 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 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. 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 LC and Cyclone FX programmers.Getting Started
Listing available Cyclone Control Console command-line parameters
Cyclone Connection Examples
Listing auto-detected Cyclones
Opening a Cyclone by name (and listing images)
Opening a Cyclone by port (and listing images)
Opening multiple Cyclones (and listing images)
Image Management Examples (Adding/Removing)
Adding a programming image to a Cyclone
Removing a programming image from a Cyclone
Erasing all images in a Cyclone
Adding multiple images into multiple Cyclones
Programming Launch Examples
Launching a programming image on a Cyclone
Launching the same image simultaneously on different Cyclones, selected by name
Launching different images simultaneously on different Cyclones, selected by number
Programming unique data
-specifyoverlaydata=[cyclone number],[address],[data]
-specifyoverlaystring=[cyclone number],[address],[string]
cycloneControlConsole.exe -cyclone=Skynet1,Skynet2 -specifyoverlaydata=1,8,54,65,72,6D,69,6E,61,74,6F,72 -specifyoverlaydata=2,8,54,65,72,6D,69,6E,61,74,6F,72 -launchimage=Green
Reading/Writing Cyclone/Image Properties
Fetching a list of property categories from the Cyclone
Reading the list of property names/values in a category
Reading image properties such as next serial number and CRC
Setting a Cyclone’s name by writing the ‘cyclonename’ property
Managing Encrypted SAP Images
Using ImageKey Commands
Additional Notes/Features
Recovering success/error result from python/bash/batch/etc
cyclonecontrolconsole -cyclone=Agnes -launchimage=green_serial
if ERRORLEVEL 1 goto errorOccurred
echo Successfully programmed!
goto done
:errorOccurred
echo Programming FAILED!!!!!
:done
#!/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
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
Cyclone Control Suite - Download and Licensing
Conclusion