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 Kevin Perreault


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

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 dynamic data after image programming

Programming different dynamic data into multiple targets from different Cyclones

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

Additional Notes/Features

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

Order of execution of command-line parameters

Cyclone Control Suite - download and licensing

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 ‘Colossus’ by name and listing the images in it.

Note : The name of a Cyclone can be set from the LCD 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=agnes,colossus,hal9000) or use multiple -cyclone parameters (such as -cyclone=agnes -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:

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 () : Red Image v1.0

   Image 2 () : Green Image v1.0

   Image 3 () : Blue Image v1.0

   Image 4 () : Red Image Barcode v1.0

   Image 5 () : Green Image Barcode v1.0

   Image 6 () : Blue Image Barcode v1.0

   Image 7 () : Run Test Application v1.02

   Image 8 () : 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:

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 “JP04”. The next time programming is launched, the target will be programmed with serial number “JP04” and the Cyclone will automatically increment the serial number to “JP05”. 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, ‘JP04’ is programmed into the target and the serial number stored for the the image changes to ‘JP05’:

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 :

There are three Cyclones found on both on the USB and Ethernet Buses of the PC. Let’s query the “cycloneproperties” category of the Cyclone named Colossus:

As expected, the “cyclonename” is Colossus. 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 get :

As we can see, the Cyclone formerly known as “Colossus” is now addressable as “Skynet”. If we decided to terminate that name, we could rename it to be WOPR instead (notice that we open it as Skynet to change it) :

Not interested in playing a game? We can set the name back to Colossus…

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 features of the Cyclone Control Suite require either:

The blog post examples 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,  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 (22)
Cyclone FX (24)
Multilink (12)
Multilink FX (7)
GDB Server (9)
Prog ACMP (3)
Interface Library Routines (3)


Manufacturer
ARM (21)
NXP (32)
Atmel (2)
Cypress (1)
Maxim (1)
Nordic Semiconductor (1)
Silicon Labs (1)
Toshiba (1)
Renesas (5)


Categories
Production Programming (37)
Debug (15)
Automated Control (8)
Miscellaneous (33)



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