Cyclone Control Suite - Overview

For Cyclone LC, Cyclone FX, Cyclone MultiChannel

Users who wish to control, configure, and automate one or more Cyclone units have several options available via the Cyclone Control Suite. All of these options are available to Windows users, and many are also available to macOS/Linux users.

The Cyclone Control Suite is a collection of automated control software tools developed to support PC-based control of Cyclone stand-alone programmers.

Ways to control a Cyclone include programming launch, results recovery, management of images resident on a Cyclone, addition of unique programming data for each target, as well as recovery of descriptive errors.

The Cyclone Control Suite is included as a standard feature with all touchscreen Cyclones.

Components

The Cyclone Control Suite consists of three major components:

1. Cyclone Control SDK – This is a Software Development Kit with a comprehensive API allowing multiple Cyclones to be managed simultaneously from a user-developed custom application that loads the provided Cyclone Control library file. The library file can be loaded from many programming languages that are able to load such a file (C/C++, Delphi, C#, Java, Python, etc) as well as environments like LabVIEW. Examples and interface code are provided in C/C++ (MSVC and GCC), Delphi/FPC, and more. See Cyclone Control SDK.
2. Cyclone Control Console – This is a powerful command-line application that can be launched from a script, a command-line, or another application and allows control of one or more Cyclones simultaneously. The command-line application displays comprehensive status messages and also returns an error code which can be recovered from the calling application. See Cyclone Control Console.
3. Cyclone Control GUI – This is an interactive GUI based application which provides an easy way to control Cyclones and manage images resident in the Cyclones. Given its graphical nature, it is very easy to explore Cyclone Control Suite capabilities to intuitively control or interact with a Cyclone. See Cyclone Control GUI.

The Console and GUI were both built using the SDK and are good examples of the types of applications that the SDK can be used to build.

Additional sample applications come as part of the installation. They contain defined build scripts that can be used to build the sample application without any modifications.

Standard Features

The three control applications all provide the following Standard features for all Cyclones:

• Cyclone control via multiple connection types:
  • USB, Serial, WiFi (if supported), or Ethernet
• Select and Launch Images by Name or Enumeration
• Recover programming result and descriptive error information
• Use automatically counting local (Cyclone stored) serial numbers
• Read/write Cyclone properties
• Read Image and target Properties and Status
• Remote Display Access and the ability to “touch” the screen
• Add/Remove/Update multiple images in the Cyclone (Console, SDK)
• Simultaneously (Gang) Control multiple Cyclones:
  • USB, Serial, WiFi (if supported), or Ethernet
• Program (and Read) Dynamic Data in addition to fixed image data
• Overlay Data

A Note on Overlay Data

There are scenarios where, in addition to the static data within the programming image, there's a need to program unique data specific to each individual target. PEmicro refers to target-specific data in general as "Dynamic Data". There is a type of Dynamic Data, called "Overlay Data", that the user can provide when programming is launched which is uniquely programmed into each target. In such cases, the user initiates the programming process on a Cyclone (or a set of Cyclones) through the Cyclone Control Console or Cyclone Control SDK. As part of this launch command, dynamic data for each target is provided, enabling the programming of targets with a combination of the static image data and the overlay data.

For more information about how the overlay data procedure is carried out during programming, please refer to Overlay Data.

PEmicro Compatible Hardware

The following lists the PEmicro hardware that is compatible with the Cyclone Control Suite. To ensure proper operations, PEmicro recommends upgrading all Cyclone units to the latest firmware.

• Cyclone FX
• Cyclone LC
• Cyclone MultiChannel

Programming Dynamic Data

Users may wish to program dynamic data - serial numbers, MAC addresses, testing results, etc. - into their devices for any number of reasons. Cyclone programming offers a few approaches to programming unique data which provide the user with useful options.

Cyclone production programming images are comprehensive archives containing all of the essential information required to program a set of data into a target device. This information encompasses application binaries, programming algorithms, configuration settings, serialization specifics, programming instructions, and more. These archives are encrypted and designed to resist corruption. Utilizing these programming images offers an efficient and dependable method for programming a substantial amount of identical data into multiple target devices. Interested users can view a closer look at programming images.

However, there are scenarios where, in addition to the static data within the programming image, there is a need to provide data at the time programming is launched. Sometimes that data is common to a production batch, such as a date code, lot code, or manufacturing location. In other cases, the data is unique to each individual target, such as a serial number or MAC address. PEmicro refers to launch-time programming data in general as "Dynamic Data". There is a type of Dynamic Data, called "Overlay Data", that the user can provide when programming is launched and temporarily combine with the static data in the programming image. In such cases, the user initiates the programming process on a Cyclone (or a set of Cyclones) through the Cyclone Control Console or Cyclone Control SDK. As part of this launch command, overlay data is provided, enabling the programming of targets with a combination of the static image data and the launch-time overlay data. In the following sections we will demonstrate how to effectively use Overlay Data in the programming process for both the Console and SDK, including Cyclone MultiChannel use cases.

Overlay Data

As mentioned above, Overlay Data here refers to the concept of overlaying one set of data on top of another before programming. This enables the user to add launch-time data as part of the programming process without rebuilding the programming image. That launch-time data may be the same for every target in a batch or unique for each target being programmed. The overlay data can be provided programmatically using the Cyclone Control SDK, or on the command line using the Cyclone Control Console. Examples are provided for each below. The data itself can be in either hexadecimal format or string format; there are separate commands for each in both the Control SDK and the Control Console.

Figure: Overlay Data Concept

When using an overlay function, the function passes the launch-time data that the user wants to program to a specific Cyclone handle (identifier). Prior to programming, that data will be overlaid on top of the static data in the user’s Programming Image. The user needs to provide:

• Which Cyclone should add the specified overlay data (multiple Cyclones may be launched)
• The memory address where the overlay data will be written
• The overlay data itself

The Cyclone, as part of the launch process, will combine the provided overlay data with the programming image's static data for the next programming launch. Static and overlay data are combined before programming so that devices which have ECC only have flash locations programmed a single time. Overlay data does not affect the stored programming image itself and is discarded after launch regardless of success/failure programming. For Cyclone MultiChannel programmers, overlay data applies to the active channel set by default, and can also be specified separately for individual channels when each target needs a unique value.

Overlay data can be added to the image static data at execution time only if allowed by the security settings stored in the programming image. To allow overlay data, make sure the "Allow Overlay Data" setting is enabled (default is allowed) when the image is created. This setting is found on the Image Settings tab of the Cyclone Image Creation Utility.

Figure: Providing Space For Overlay Data

The scenario where overlay data is programmed into memory space not programmed by the static data in an image is the more common overlay scenario. However, there is an image setting which can optionally allow static data in the image to be overridden with overlay data provided at the same addresses as data in the image. The setting "Allow Overlay Data to Overwrite Image" (the default is "not allowed") controls whether overlaying on top of image data at the same address is allowed. This doesn't affect this image itself and simply allows a temporary override of data to be programmed at certain addresses. This data is discarded after every program (so to continually override data in an image it must be provided each launch).

Figure: Configuration Allows Data To Be Overwritten

A user might want to enable "Allow Overlay Data to Overwrite Image" if, for example, their base image contains a default IP address somewhere in memory that could be overwritten on a board-by-board basis.

Below are examples for how the basic overlay commands are used in both the SDK and the Console. Please refer to the appropriate Cyclone Control chapter for more granular information about overlay data command functions and parameters.

Note

One distinction of which to be aware, between the SDK and Console, is that when the SDK specifies overlay data for a specific Cyclone, that overlay data will continue to be used for each program launch until cleared by the clearOverlayProgramData(...) call, or until the connection to the Cyclone is closed. The Console, on the other hand, will always clear the overlay data upon exit of the application.

Cyclone Control SDK

bool specifyOverlayProgramData(
    uint32_t cycloneHandle,
    uint32_t targetAddress,
    uint32_t dataLength,
    char* buffer
);

The function has to be called prior to startImageExecution. The first parameter is the handle of the Cyclone. The second parameter is the address where the overlaying of the data starts. The third parameter is the number of bytes to overlay, and the fourth parameter is a pointer to the bytes holding the data.

uint8_t data[] = {0x50,0x45,0x4D,0x49,0x43,0x52,0x4F}; // "PEMICRO"
specifyOverlayProgramData(cycloneHandle, 0x1080, sizeof(data), data); // Specify overlay data to be used when launching image
startImageExecution(cycloneHandle, 1);                                // Provide the overlay data to the Cyclone and launch programming
clearOverlayProgramData(cycloneHandle);                               // Clear overlay program data

Cyclone Control Console Example

Here is the equivalent if the console is used to provide data at launch time:

CycloneControlConsole.exe -cyclone=USB1 -specifyOverlayData=1,1080,50,45,4D,49,43,52,4F -launchimage=1

Cyclone MultiChannel Overlay Data

On a Cyclone MultiChannel programmer, overlay data is applied to the active channel set by default. If channels 11, 12, 13, and 14 are active, a single overlay command applies the same overlay bytes to all four channels. This is useful for data that should be identical on every target programmed in the batch, such as a production date, lot code, or manufacturing location.

For example, the following Console command selects channels 11, 12, 13, and 14, applies the same overlay bytes to all active channels, and launches image 1:

CycloneControlConsole.exe -cyclone=USB1 -setactivechannels=11,12,13,14 -specifyOverlayData=1,1080,32,30,32,36,30,35,32,36 -launchimage=1

The same all-active-channel operation using the SDK would look like this:

uint8_t lotCode[] = {0x32,0x30,0x32,0x36,0x30,0x35,0x32,0x36}; // "20260526"

clearOverlayProgramData(cycloneHandle);
setChannelList(cycloneHandle, ActiveChannelsListType, "11,12,13,14");
specifyOverlayProgramData(cycloneHandle, 0x1080, sizeof(lotCode), lotCode);
startImageExecution(cycloneHandle, 1);
clearOverlayProgramData(cycloneHandle);

In other cases, such as serial numbers or MAC addresses, it is more common for each channel to program unique data. To do that, specify overlay data separately for each channel before launching. In the Console, bracketed channel lists can be added to the overlay command so each active channel receives a different value. The following example programs image 1 on channels 11, 12, 13, and 14 while providing a different 4-byte value at address 0x1080 for each channel:

CycloneControlConsole.exe -cyclone=USB1 -setactivechannels=11,12,13,14 -specifyOverlayData[11]=1,1080,00,00,00,11 -specifyOverlayData[12]=1,1080,00,00,00,12 -specifyOverlayData[13]=1,1080,00,00,00,13 -specifyOverlayData[14]=1,1080,00,00,00,14 -launchimage=1

Using the SDK, the same per-channel behavior is achieved by changing the active channel list with setChannelList before each call to specifyOverlayProgramData. Each overlay entry is stored with the channel context that is active when it is specified. After all per-channel overlay entries have been specified, set the active channel list back to the full group and launch programming:

uint8_t serial11[] = {0x00,0x00,0x00,0x11};
uint8_t serial12[] = {0x00,0x00,0x00,0x12};
uint8_t serial13[] = {0x00,0x00,0x00,0x13};
uint8_t serial14[] = {0x00,0x00,0x00,0x14};

clearOverlayProgramData(cycloneHandle);

setChannelList(cycloneHandle, ActiveChannelsListType, "11");
specifyOverlayProgramData(cycloneHandle, 0x1080, sizeof(serial11), serial11);

setChannelList(cycloneHandle, ActiveChannelsListType, "12");
specifyOverlayProgramData(cycloneHandle, 0x1080, sizeof(serial12), serial12);

setChannelList(cycloneHandle, ActiveChannelsListType, "13");
specifyOverlayProgramData(cycloneHandle, 0x1080, sizeof(serial13), serial13);

setChannelList(cycloneHandle, ActiveChannelsListType, "14");
specifyOverlayProgramData(cycloneHandle, 0x1080, sizeof(serial14), serial14);

setChannelList(cycloneHandle, ActiveChannelsListType, "11,12,13,14");
startImageExecution(cycloneHandle, 1);
clearOverlayProgramData(cycloneHandle);