Cyclone Control Suite

The Cyclone Control SDK is one of the three main components of the Cyclone Control Suite that also includes the Cyclone Control Console and the Cyclone Control GUI.

The CYCLONE LC user manual and CYCLONE FX user manual contain a full list and descriptions of the Cyclone Control SDK application programming interface in detail.

What's Included with the Cyclone Control Suite

- C# project and solution (msvcsharp.sln and source files)

- Library (CycloneControlSDK.dll)

- C# header file (cyclone_control_api.cs)

Introduction

This blog post assumes that the reader is already familiar with the process to create standalone programming (SAP) images. If the reader is not, please refer to the Image Creation Utility section of the Cyclone and Cyclone FX users manual.

The code in this blog post was developed in Microsoft Visual Studio Community 2017.

The material here is presented in the following sections:

1. Example - Connecting to a Cyclone
2. Example - Managing Images
3. Example - Gang Operation of Three Cyclones
4. Example - Serial Numbers And Dynamic Data
5. Example - Reading/Writing Properties
6. Cyclone Control SDK and Licensing
7. Conclusion

1. Example - Connecting to a Cyclone

The SDK provides developers with a dynamic link library (DLL) to export the functions of the API. Once the DLL is linked, the custom application can directly control Cyclones for stand alone operations.

The path of the DLL is defined in the header file by the constant DLL_FILENAME.

The first step is to call enumerateAllPorts() to scan and initialize your ports for Cyclones.

This is an example of how to open a Cyclone and execute a stand alone image that has already been configured onto the Cyclone using the SDK.

1. Open the desired Cyclone by specifying its name (“Fixture1Cyclone1”). The handle of the Cyclone is returned and is used to identify the Cyclone in all subsequent function calls.
2. Send a command to the Cyclone to begin the programming operations specified in image with ID# 1.
3. Wait for the Cyclone to complete the programming operations before proceeding.
4. Check to see if any errors occurred during programming and display the error code.
5. Terminate connection to Cyclone.

The Cyclone can also be opened by port number  (“USB1”, “ETHERNET1”, or “COM1”) or the IP address (“192.168.1.10”) of the Cyclone if the connection is ethernet. There is no guarantee that a Cyclone will always enumerate with the same port number. If you're managing multiple units, it is recommended to specify them by name or IP address.

2. Example - Managing Images

The SDK also has the ability to manage images directly. You can add new images or erase existing images. In this example, the code updates the image stored on the Cyclone to a new image that has the latest version of our product's firmware. It first checks if the image on the Cyclone matches the specified SAP file. If there is a mismatch, it erases the existing image and adds the latest.

1. Open the desired Cyclone by specifying its name (“Fixture1Cyclone1”). 
2. Compare the SAP file ("C:\KL25Z128\KL25Z128.SAP") with image ID# 1 
3. If there is a mismatch, erase image ID# 1. Then add the image to the Cyclone.
4. Check to see if any errors occurred while adding the image and display the error code.

3. Example - Gang Operation of Three Cyclones

We have discussed some uses of the SDK with a single Cyclone unit in previous examples. Since the host PC only sends minimal data to control each Cyclone, a single PC is capable of controlling multiple Cyclone units simultaneously.

In this example, the host PC is connected to 3 separate Cyclone units. The programming image is added and then programming operations are started simultaneously. This will work even if all the Cyclones are connected on a mix of different ports. The while loop waits for their completion before proceeding to check for errors. In essence, the host is programming 3 separate devices in parallel and this can be easily extended up to 100 Cyclone units in a network.

4. Example - Serial Numbers And Dynamic Data

The SDK can also program dynamic data such as serial numbers, date codes, encryption keys after the static data has been programmed by the SAP image. In this example, the application calls the function startDynamicDataProgram and provides the 2 byte serial number in a byte array. 

There are three placeholder functions that are used to simplify the example but are not provided by the SDK - getSerialNumber(), incrementSerialNumber(), and saveSerialNumberToFile(). Similar to the first example, the application connects to one Cyclone and executes a SAP image. After the image is done, the error code is checked. Then the serial number is retrieved from a file and programmed to address 0x1000 of the target. The serial number is then incremented and written back to the file.

1. Open the desired Cyclone by specifying its name (“Fixture1Cyclone1”). 
2. Send a command to the Cyclone to begin the programming operations specified in image with ID# 1.
3. Wait for the Cyclone to complete the programming operations before proceeding.
4. Check to see if any errors occurred during programming and display the error code.
5. Retrieve serial number and program dynamic data array.
6. Check to see if any errors occurred during serialization and display the error code.
7. Increment and save new serial number.
8. Terminate connection to Cyclone.

5. Example - Reading/Writing Properties

Your Cyclone or its resident images have settings, configuration, and other information stored as properties. The getPropertyList function returns a list properties that is available for a property category. Properties can be viewed with the getPropertyValue function. Some properties can also be modified with the setPropertyValue function.

Many other functions in the API return a pointer to a C-style(null terminated) string. Due to the differences between C and C# strings, the header contains wrapper functions to make the API easier to use in your C# application. For those function that involve strings, it is recommended you call the public wrapper functions of the private functions.

6. Cyclone Control SDK and Licensing

PEmicro's Cyclone Control SDK is part of the Cyclone Control Suite, which is included as a standard feature with all models of Cyclone. No additional license is required.

7. Conclusion

PEmicro is confident that the addition of a Microsoft Visual C# example project to the Cyclone Control SDK will allow application engineers and developers to decrease development time and improve results.