Cyclone Control SDK

For Cyclone LC, Cyclone FX, Cyclone MultiChannel

The Cyclone Control SDK allows a Windows/macOS/Linux user to interact with the Cyclone via a library file (such as Windows’ .dll, macOS’ .dylib, or Linux’ .so files).

Overview

The Cyclone Control SDK is one of the three components that comprise the Cyclone Control Suite. Its library allows the user to create an application on the PC that can directly control one or more PEmicro Cyclone units. These interface routines are designed to be compiled into visual and non-visual applications running on Windows, macOS, or Linux operating systems. macOS/Linux SDK files are contained in a separate .tar file (see Compiling).

The actual interface routines are located in the “cyclonecontrolsdk” library file. This library file is callable from almost any 32-bit / 64-bit Windows, macOS, or Linux development environment. Since the way the library file is called varies depending on the compiler used, PEmicro provides the library interface code and sample applications for each of the following compilers.

Note

PEmicro’s blog offers articles with detailed setup instructions for some of the options below; the user may visit the links below where applicable:

Embarcadero Delphi (Pascal)
GCC
Microsoft Visual C
Microsoft Visual C#
NI LabVIEW 2018
Python
Rust
Visual Basic .NET

Windows 32-Bit and 64-Bit Support

The SDK supports both 32-bit and 64-bit applications. The user will note a deploy folder for all Windows deliverables at: INSTALLDIR\cycloneControl\controlsdk\deploy.

Within this deploy folder, the 32-bit DLL is inside the win32 sub-folder, and the 64-bit DLL is inside the win64 sub-folder.

Getting Started with the Cyclone Control Library File (Windows Users)

This section outlines the steps you need to take to begin developing your own custom application and offers tips and suggestions to get the Cyclone Control Library File working with your PEmicro hardware smoothly.

Example Programs

The Windows SDK installer includes example source code under:

INSTALLDIR\cycloneControl\controlsdk\examples

This folder is the installed equivalent of the development source folder C:\products\delphi\sap_control_dll\WindowsExamples.

Most language folders include a general API example. This is the best starting point for learning the normal SDK flow: load or bind to the SDK library, enumerate ports, open a Cyclone, list images, launch an image, poll for completion, report errors, and disconnect.

MultiChannel-capable language folders also include a MultiChannel example. This is the best starting point for Cyclone MultiChannel applications because it shows how to autodetect a Cyclone, list images, read the connected channel list, set the Active channel list, launch image 1, and report both the aggregate programming result and each channel's result through getChannelErrorCode.

The examples are organized by language and toolchain:

INSTALLDIR\cycloneControl\controlsdk\examples\c\
INSTALLDIR\cycloneControl\controlsdk\examples\cpp\
INSTALLDIR\cycloneControl\controlsdk\examples\labview2018
INSTALLDIR\cycloneControl\controlsdk\examples\msvc
INSTALLDIR\cycloneControl\controlsdk\examples\msvcsharp
INSTALLDIR\cycloneControl\controlsdk\examples\pascal\
INSTALLDIR\cycloneControl\controlsdk\examples\python
INSTALLDIR\cycloneControl\controlsdk\examples\rust
INSTALLDIR\cycloneControl\controlsdk\examples\visualbasic

The general API examples are:

C: examples\c\api_example.c
C++: examples\cpp\main.cpp
Microsoft Visual C++: examples\msvc\api_example\api_example.cpp
C#: examples\msvcsharp\visual_sap_control
Delphi/Pascal: examples\pascal\api_example.dpr
Python: examples\python\api_example.py
Rust: examples\rust\src\api_example.rs
Visual Basic .NET: examples\visualbasic\visualbasic\api_example.vb
LabVIEW: examples\labview2018\user.lib\cyclonecontrolsdk\cyclonecontrolsdk.lvlib

The MultiChannel examples are:

C: examples\c\multichannel_example.c
C++: examples\cpp\multichannel_example.cpp
C#: examples\msvcsharp\multichannel_example
Delphi/Pascal: examples\pascal\multichannel_example.dpr
Python: examples\python\multichannel_example.py
Rust: examples\rust\src\multichannel_example.rs

Use an SDK library file that matches the bitness of the example process. For example, a 64-bit Python, C#, C/C++, Rust, or Delphi/Pascal executable must load the 64-bit CycloneControlSDK.dll; a 32-bit executable must load the 32-bit DLL.

Start with the general API example if your application only needs to control one or more Cyclones at the image level. Start with the MultiChannel example if your application needs to choose active channels or report channel-by-channel results on a Cyclone MultiChannel. The MultiChannel examples require a Cyclone MultiChannel with at least one programming image loaded.

Starting Your Own Project

To gain access to the functions available in the library file the following files need to be added to the new project workspace:

Delphi Projects

INSTALLDIR\cycloneControl\controlsdk\examples\pascal\cyclone_control_api.pas

All other source files which will call functions from the library file should include the above file using the Delphi “uses” command.

C Projects

INSTALLDIR\cycloneControl\controlsdk\examples\c\cyclone_control_api.h

INSTALLDIR\cycloneControl\controlsdk\examples\c\cyclone_control_api.c

All other source files which will call functions from the library file should include the above header file with the C #include directive.

C++ Projects

INSTALLDIR\cycloneControl\controlsdk\examples\cpp\cyclone_control_api.h

INSTALLDIR\cycloneControl\controlsdk\examples\cpp\cyclone_control_api.cpp

All other source files which will call functions from the library file should include the above header file with the C++ #include directive.

Microsoft Visual C++ Projects

INSTALLDIR\cycloneControl\controlsdk\examples\msvc\api_example\cyclone_control_api.h

INSTALLDIR\cycloneControl\controlsdk\examples\msvc\api_example\cyclone_control_api.cpp

C# Projects

INSTALLDIR\cycloneControl\controlsdk\examples\msvcsharp\visual_sap_control\cyclone_control_api.cs

NI LabVIEW 2018 Projects

INSTALLDIR\cycloneControl\controlsdk\examples\labview2018\user.lib\cyclonecontrolsdk\cyclonecontrolsdk.lvlib

INSTALLDIR\cycloneControl\controlsdk\examples\labview2018\user.lib\cyclonecontrolsdk\VIs\*.vi

The pre-built VIs that we provide include modifications for error handling using error clusters. Please visit our blog post “Automated Flash Programming with LabVIEW” for more information on how to develop your own LabVIEW project.

Python Projects

INSTALLDIR\cycloneControl\controlsdk\examples\python\cycloneControlSDK.py

INSTALLDIR\cycloneControl\controlsdk\examples\python\cycloneControlSDKConstants.py

Rust Projects

INSTALLDIR\cycloneControl\controlsdk\examples\rust\src\cyclone_control_sdk.rs

INSTALLDIR\cycloneControl\controlsdk\examples\rust\src\cyclone_control_sdk_constants.rs

Visual Basic .NET Projects

INSTALLDIR\cycloneControl\controlsdk\examples\visualbasic\visualbasic\api_example.vb

Getting Started with the Cyclone Control Library File - macOS/Linux Users

This section outlines the steps needed to begin developing a custom application and offers tips and suggestions to get the Cyclone Control SDK library working smoothly with PEmicro hardware.

SDK Contents

macOS/Linux SDK files are distributed separately from the Windows installer. They are not installed under INSTALLDIR\cycloneControl\controlsdk\examples by the Windows installer.

If you are using a macOS/Linux SDK package, it is structured along the following directories:

Linux: C and C++ example files, the “cyclonecontrolconsole” command line utility, CycloneControlGUI, and the “libcyclonecontrolsdk.so” library
macOS: C and C++ example files, the “cyclonecontrolconsole” command line utility, CycloneControlGUI, and the “libcyclonecontrolsdk.dylib” library
Firmware: The latest firmware releases
User manuals: The user manual for the Cyclone programmer.

Example Programs

Located in the macOS and Linux directories of the separate macOS/Linux SDK package, you will find C and C++ example programs that you can use as a reference for your own application. The examples are located in the following directories:

INSTALLDIR/macOS/c : C example files for macOS

INSTALLDIR/macOS/cpp : C++ example files for macOS

INSTALLDIR/linux/c : C example files for Linux

INSTALLDIR/linux/cpp : C example files for Linux

These example programs are a valuable reference to use when starting your own custom application.

Starting Your Own Project

The Cyclone Control Console (cyclonecontrolconsole) comes ready to use. To use it, you can simply invoke a command-line command such as:

./cyclonecontrolconsole -cyclone=usb1 -listimages

./cyclonecontrolconsole -cyclone=10.1.2.3 -launchimage=1

The first command will query a Cyclone unit connected via a USB cable and list any programming images that are on board.

The second command will remotely launch the first programming image that is on a Cyclone with IP number 10.1.2.3.

For a full description please see PEcloud Functions.

Compiling

In order to compile (or use the Makefile), you will need to have the appropriate compiler (such as gcc or g++) available. These compilers are often native to Linux. Mac users will need to have Xcode and its command-line utilities installed.

How To Build

The examples show how you can write a custom application using the SDK library. To build the example files, change directory into the appropriate folder (such as "cd example\cpp") and invoke the Makefile by calling "make" from a command line.

Please note that the Makefile only builds the example file, it does not copy the files necessary to immediately use the compiled program. To do that, please perform a "make install", this will copy the appropriate firmware files as well as the libcyclonecontrolsdk library, into a "deploy" folder, thereby making the custom program readily usable.

Once you have performed "make" and "make install", you can cd into the deploy directory and invoke the program as follows:

./apiExample -cyclone=usb1 -listimages

This will show the programming images that are on a Cyclone connected through a USB cable.

Running An Application On macOS

By default, macOS does not allow applications from unidentified developers to run on the system. This would cause a message stating that the application "cannot be opened because the developer cannot be verified." There are two ways to resolve this issue:

You can simply navigate to the file on an explorer, right click on the executable, and select the "Open with" option to open the application with Terminal.app. You will then be able to open the application.
You can completely disable this feature through the System Preferences menu, although it is not a recommended option.

Initialization

Loading the DLL (C/C++ Projects only)

Before calling any routines from the DLL, the DLL must be loaded into memory. To do this, the following function has been provided in the included header files. Refer to Chapter 4 of this manual for a detailed description of this function.

loadLibrary( );

For Delphi (Pascal) and C# users, this process is transparent for the user and no action is required.

Enumerate all ports

After loading the DLL, a call to the following function is required in order to properly initialize all devices. This function should only be called once, typically at the beginning of the application.

enumerateAllPorts( );

Connect to the PEmicro hardware interface

The next step is to establish communications with the PEmicro Cyclone unit. This is accomplished with the following function call:

connectToCyclone( );

Refer to Connect To Cyclone for a detailed description of this function. This call returns the handle to the Cyclone unit which is used in all other routines in the DLL to identify the Cyclone. Note that the special case of a return value of 0 indicates an error contacting the Cyclone. This function will be called once for each Cyclone.

Finalization

Before closing the application, it is recommended that the session with the PEmicro hardware be terminated and the DLL unloaded from memory.

These calls should always be made before the application closes:

disconnectFromAllCyclones( );

unloadLibrary();

Note that the “unloadLibrary” call is only required for C/C++ applications. For the Delphi and C# example projects, the DLL is automatically unloaded when the application closes.

Initial Cyclone Setup

The Cyclone Image Creation Utility software, which is included with each Cyclone, is used to create the standalone images that will be stored in the non-volatile memory of the Cyclone.

Note

Mac/Linux users will need a Windows platform for the image creation and configuration process.

These programming images contain the FLASH / EEPROM programming algorithms, the actual binary data to be programmed, the sequence of programming operations, and user specified Cyclone settings.

Prior to using the Cyclone Control Suite, these standalone images need to be created. Please refer to the user’s manual of your Cyclone unit for more information on standalone images and image creation.

Typical Usage

Figure: Typical programming procedure flow chart

TypicalUsageNew

The figure above describes the most common sequence of calls to the DLL after successfully connecting to the Cyclone unit.

Initiate programming operations. “startImageExecution” carries out the programming operations defined in the stand-alone image stored on the Cyclone unit.
Wait for programming completion. Note that no error checking is provided by the “checkCycloneExecutionStatus” call. A result of 0 will be returned even if an error has occurred or if communication with the Cyclone is lost.
Retrieve the error code from the Cyclone unit to determine if the programming was successful.

External Memory Storage Support

Some Cyclones support external memory storage. The Cyclone Control SDK and Cyclone Control Console both support images residing on external memory cards. The parameter “selectedMediaType” is used to select between Cyclone internal Flash and external memory.

Image numbers will go in ascending order starting with image number 1. Internal images will be counted first and external image numbers will start after the last internal image number. Image number 1 will refer to the first image in the internal memory if there are any images in the Cyclone internal memory, if there are no internal images, image 1 will refer to the first image in the external memory.

Modifying images residing in external memory will only be available on Cyclones with that capability (i.e. an active SDHC port).

Application Programming Interface (API)

This section describes the API of the Cyclone Control SDK library in detail. A C/C++ function prototype is given here, and header files are provided for various languages. The user may reference the list of languages (and links to articles describing how to use these with the SDK) provided in the Overview.

Constants

Name	32-bit Value
Name	32-bit Value
CyclonePortType_USB	5
CyclonePortType_Ethernet (*)	6 (*)
CyclonePortType_Serial	7

CycloneInformation_IP_Address	1
CycloneInformation_Name	2
CycloneInformation_Generic_Port_Number	3
CycloneInformation_Cyclone_Type_String	4

MEDIA_INTERNAL	1
MEDIA_EXTERNAL	2

(*) For WiFi communications (if supported), users should use the same values as for Ethernet.

Important Note For MultiChannel Programming

Certain commands use the Active channel list set by setChannelList to determine which channels they operate on:

selectLocalImageForExecution
prepareActiveChannelsForLaunch
startExecutionOfSelectedImage
startImageExecution
clearOverlayProgramData
specifyOverlayProgramData

DLL Loading / Unloading Calls

loadLibrary

bool loadLibrary(char *filepath);

This function loads the CycloneControlSDK.dll into memory and gives the user access to all of the functions available in the library. This routine must be called before any of the other routines can be called.

Parameter	Description
@returnvalue	True if the load was successful, false otherwise.

unloadLibrary

void unloadLibrary(void);

This function unloads the DLL loaded with loadLibrary( ). This call should be made before the application starts to unload itself.

enumerateAllPorts

void enumerateAllPorts(void);

This function performs all necessary initialization in order to successfully communicate with a Cyclone. The function is called once before the first call to “connectToCyclone”.

disconnectFromAllCyclones

void disconnectFromAllCyclones(void);

This function closes all open Cyclones (if any) and frees all dynamic memory used by the DLL. The function is called before the user application is closed.

version

char *version(void);

This call returns a pointer to a null-terminated string that contains the version number of the DLL.

Parameter	Description
@returnvalue	A pointer to a null-terminated string containing the version number of the DLL.

queryNumberOfAutodetectedCyclones

uint32_t queryNumberOfAutodetectedCyclones(void);

This function returns the number of Cyclones connected locally on USB and on your local network.

Parameter	Description
@returnvalue	The number of Cyclones.

queryInformationOfAutodetectedCyclone

char *queryInformationOfAutodetectedCyclone(int32_t autodetectIndex, int32_t informationType);

Parameter	Description
@parameter autodetectIndex	Specifies the index of the detected Cyclone by the function queryNumberOfAutodetectedCyclones(). The valid range for this parameter is from 1 to the number of Cyclones detected.
@parameter informationType	Specifies the property of the Cyclone to return. The possible values are: `CycloneInformation_IP_Address`, `CycloneInformation_Name`, `CycloneInformation_Generic_Port_Number`, and `CycloneInformation_Cyclone_Type_String`.
@returnvalue	A pointer to a null-terminated string containing the property value of the specified Cyclone.

Cyclone Connecting / Disconnecting Calls

connectToCyclone

uint32_t connectToCyclone(char *nameIpOrPortIdentifier) ;

This function opens a session with a Cyclone and tests the connection. The handle returned by this function is passed as a parameter to other functions provided by the DLL. If you connect to a Cyclone that already has a handle, the same handle is returned. If there is a failure contacting the Cyclone, the function returns a 0.

Note that the DLL does not support multiple Cyclones connected via the serial port. If you require more than one Cyclone to use a serial port connection, PEmicro recommends using the RS232 communication protocols.

Parameter

Description

@parameter nameIPOrPortIdentifier

A pointer to a null-terminated string which uniquely identifies the Cyclone connected to the host PC.
If identifying by IP address, the string should be in the format of xxx.xxx.xxx.xxx, where xxx = 0…255.
If identifying by name, the string should contain the name of the Cyclone.
If identifying by port and the Cyclone is connected by USB, the string should be USB# where # is 1…8. If the Cyclone is connected by Ethernet, the string should be in the format of xxx.xxx.xxx.xxx, where xxx = 0…255.
If the Cyclone is connected by Serial, the string should be COM1.

@returnvalue

The handle to the opened Cyclone unit. A return value of 0 indicates a failure to connect to the specified Cyclone unit.

connectToMultipleCyclones

bool connectToMultipleCyclones(char *nameIpOrPortIdentifierArray, void **cycloneHandleArrayPointer, int32_t *numberOfCycloneOpensAttempted);

This function returns an array of handles to opened Cyclones from a null-terminated string of comma-delimited identifiers.

Parameter	Description
@parameter nameIpOrPortIdentifierArray	A null-terminated string containing one or more Cyclone identifiers (name, IP address, or port number) delimited by commas. Example: USB1,209.1.10.2,Orion,COM1 If identifying by IP address, the string should be in the format of xxx.xxx.xxx.xxx, where xxx = 0…255. If identifying by port and the Cyclone is connected by USB, the string should be USB# where # is 1…8. If the Cyclone is connected by Serial, the string should be COM1.
@parameter cycloneHandleArrayPointer	A pointer to receive the address of an array of Cyclone handles. Each element of the array corresponds to the position of the identifier in the previous parameter. If the function connected to the Cyclone, the value of the array element corresponds to its handle; otherwise it is 0.
@parameter numberOfCycloneOpensAttempted	This value will be modified with the number of Cyclones that the function attempted to open. It is also the number of elements in the returned handle array.
@returnvalue	True if every Cyclone was identified and has a valid handle. False if there were any errors identifying or connecting to any of the Cyclones.

setLocalMachineIpNumber

void setLocalMachineIpNumber(char* ipNumber);

If a PC has multiple network interface cards, this function sets the IP address of the network card to use to communicate with the Cyclones. This is called prior to calling any other functions.

Parameter	Description
@parameter ipNumber	A pointer to a null-terminated character string in the format xxx.xxx.xxx.xxx, where xxx = 0…255, representing the IP address of the network card.

resetCyclone

bool resetCyclone(uint32_t cycloneHandle, uint32_t resetDelayInMs);

This function performs a hard reset of the Cyclone. It is the same as pressing the reset button. This is considered a legacy call and does not need to be called by the application.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone that will be reset.
@parameter resetDelayInMs	The reset delay, specified in milliseconds. The delay should be at least 5500 ms.
@returnvalue	True if reset was successful, False otherwise

Controlling Cyclone Programming

startImageExecution

bool startImageExecution(uint32_t cycloneHandle, uint32_t imageId);

This function starts execution of the specified programming image on the selected Cyclone.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone that will execute the image.
@parameter imageId	The image number to launch. The valid range is from 1 to the total number of images in the Cyclone, with the count starting from internal memory and then external memory.
@returnvalue	True if image execution was started successfully. Otherwise returns false.

startExecutionOfSelectedImage

bool startExecutionOfSelectedImage(uint32_t cycloneHandle);

This function attempts to execute programming of the selected image.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to initiate the connection.
@returnvalue	Returns true if programming execution of the selected image was initiated. Otherwise returns false.

checkCycloneExecutionStatus

uint32_t checkCycloneExecutionStatus(uint32_t cycloneHandle);

Checks to see if the Cyclone has completed a programming operation started with the “startImageExecution” function.

After this function returns a completed value, call getNumberOfErrors, getErrorCode, and getDescriptionOfErrorCode to determine the programmer-level result. On a Cyclone MultiChannel programmer, call getChannelErrorCode for each relevant channel only if getNumberOfErrors returns a value greater than 0. A result of 0 from checkCycloneExecutionStatus only means that execution is no longer running; it does not indicate whether programming succeeded.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to perform a status check on.
@returnvalue	1 = Currently programming 0 = Completed (with or without error)

dynamicReadBytes

bool dynamicReadBytes(uint32_t cycloneHandle, uint32_t targetAddress, uint16_t dataLength, void *buffer);

This function reads a specified number of bytes from a specified memory address of the target processor. This call is only valid after first having made a call to the “startImageExecution” function in the sequence of commands.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone that will perform the dynamic read.
@parameter targetAddress	The first memory address of the target processor where the data will be read.
@parameter dataLength	The number of total bytes to read from the target processor
@parameter buffer	A pointer to the array where the data read will be stored. This array must have been allocated prior to calling this function.
@returnvalue	True if the data was successfully, read False otherwise

getNumberOfErrors

uint32_t getNumberOfErrors(uint32_t cycloneHandle);

This function returns a count of all the programmer-level errors recorded in the DLL and in the Cyclone. For Cyclone MultiChannel programmers, this count is not a count of failed channels. A single programming operation can record more than one programmer-level error, such as a general programming failure and a user-cancelled operation.

If this function returns 0 after a Cyclone MultiChannel operation completes, all channels in that operation completed successfully and the application does not need to call getChannelErrorCode. If this function returns a value greater than 0, call getErrorCode to retrieve the programmer-level errors, then call getChannelErrorCode for each relevant channel to determine which specific channels failed.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to get a count of the errors.
@returnvalue	The number of errors in the DLL and in the Cyclone.

getErrorCode

int32_t getErrorCode(uint32_t cycloneHandle, uint32_t errorNum);

This function returns the specified programmer-level error code recorded in the DLL or in the Cyclone. It should be called when getNumberOfErrors() is greater than or equal to 1. For Cyclone MultiChannel programmers, these errors describe the overall programming operation. They do not identify which channel or channels failed; use getChannelErrorCode for channel-specific results.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to retrieve the error code.
@parameter errorNum	This specifies the error number. The valid range for this parameter is from 1 to the total number of errors.
@returnvalue	The error code of the DLL or Cyclone

getLastErrorAddr

uint32_t getLastErrorAddr(uint32_t cycloneHandle);

If the “getErrorCode” function returns a non-zero value (indicating an error has occurred), this routine can be used to query the address where the error occurred.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone from which to request the error address.
@returnvalue	The memory address where the last programming error occurred.

getDescriptionOfErrorCode

char *getDescriptionOfErrorCode(uint32_t cycloneHandle, int32_t errorCode);

This function returns a description of the error code.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to retrieve the error code description.
@parameter errorCode	The error code to check.
@returnvalue	A pointer to a null-terminated character string that contains the error code description.

clearOverlayProgramData

bool clearOverlayProgramData(uint32_t cycloneHandle);

This function clears all dynamic overlay data for the specified Cyclone handle. It is recommended to call this function before specifyOverlayProgramData.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to clear dynamic overlay data.
@returnvalue	True if the dynamic overlay data was cleared successfully. False otherwise.

specifyOverlayProgramData

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

This function passes the dynamic data that the user wants to program to a specified Cyclone handle. Prior to programming, the dynamic data will be overlaid onto the data in the user’s s-record. Must be called prior to startImageExecution.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to begin dynamic overlay data programming.
@parameter targetAddress	The first memory address of the target processor where the dynamic overlay data should be written.
@parameter dataLength	The total number of bytes written.
@parameter buffer	A pointer to the array which holds the data to be written.
@returnvalue	True if the dynamic overlay data was added successfully. False otherwise.

Configuration / Image Maintenance Calls

getImageDescription

char *getImageDescription(uint32_t cycloneHandle, uint32_t imageId) ;

This function returns the description of a particular image stored on the Cyclone (internal Flash or external memory card). This description is specified by the user when the image is created.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to get an image description.
@parameter imageId	Used to select which image stored on the Cyclone to read the description from. The valid range of this parameter is from 1 to the total number of images in the Cyclone with the count starting from internal memory and then external memory. If a Cyclone only stores one image, this parameter should be set to 1.
@returnvalue	A pointer to a null-terminated character string which contains the image description

compareImageInCycloneWithFile

bool compareImageInCycloneWithFile(uint32_t cycloneHandle, char *aFile, uint32_t imageId);

This function compares a programming image stored on the Cyclone with the specified SAP image file.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone containing the image to compare.
@parameter aFile	A pointer to a null-terminated character string containing the full path to the programming file to compare.
@parameter imageId	The image number stored on the Cyclone.
@returnvalue	True if the stored image matches the specified file. Otherwise returns false.

selectCloudImageForExecution

bool selectCloudImageForExecution(uint32_t cycloneHandle, uint32_t imageId);

This function attempts to select a PEcloud-distributed image as the next image to be executed.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone connected to PEcloud.
@parameter imageId	The ID number of the PEcloud-distributed image to select.
@returnvalue	Returns true if the specified PEcloud-distributed image was found and selected. Otherwise returns false.

selectLocalImageForExecution

bool selectLocalImageForExecution(uint32_t cycloneHandle, uint32_t imageId);

This function attempts to select a programming Image as the default Image to be programmed.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to initiate the connection.
@parameter imageID	The ID number of the programming image to select.
@returnvalue	Returns true if specified Image was found and selected. Otherwise returns false.

formatCycloneMemorySpace

bool formatCycloneMemorySpace(uint32_t cycloneHandle, uint32_t selectedMediaType);

This function erases all images stored on the selected media type.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone that will have its images erased
@parameter selectedMediaType	This parameter selects between Cyclone internal Flash (selectedMediaType = 1) or external memory (selectedMediaType =2).
@returnvalue	True if the erasure was successful, False otherwise

eraseCycloneImage

bool eraseCycloneImage(uint32_t cycloneHandle, uint32_t imageId);

This function erases the specified image that is stored on the Cyclone. This function is not supported by legacy Cyclones.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone that will have its image erased
@parameter imageId	Selects the image on the Cyclone to use. The valid range of this parameter is from 1 to the total number of images in the Cyclone with the count starting from internal memory and then external memory. If a Cyclone only stores one image, this parameter is 1.
@returnvalue	True if the erasure was successful, False otherwise

addCycloneImage

uint32_t addCycloneImage(uint32_t cycloneHandle, uint32_t selectedMediaType, bool replaceImageOfSameDescription, char *aFile);

This function adds a specified programming image into the selected media type. The image files have a .SAP file extension and are created with the Cyclone Image Creation Utility. If the Cyclone’s storage limits are reached, this routine will return an error.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone that will accept the new image
@parameter selectedMediaType	This parameter selects between Cyclone internal Flash (selectedMediaType = 1) or external memory (selectedMediaType =2).
@parameter replaceImageOfSameDescription	Set to True if you want the image to overwrite any existing images with the same description Set to False if you do not want the image to overwrite any existing images with the same description. An error will occur.
@parameter aFile	A pointer to a null-terminated character string which contains the full path to the programming file to be added.
@returnvalue	The image number of the image that was just added. This number is used as the “imageId” parameter for some function calls. A return value of “0” indicates an error has occurred during the process.

countCycloneImages

uint32_t countCycloneImages(uint32_t cycloneHandle);

This function returns the number of stand-alone programming images currently stored in the internal Flash and the external memory card of the Cyclone.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to query for the image count
@returnvalue	The total number of images stored in internal and external memory.

getPropertyValue

char *getPropertyValue(uint32_t cycloneHandle, uint32_t resourceOrImageId, char *categoryName, char *propertyName);

This function reads a property value of the Cyclone or a stored programming image. Examples of properties are Cyclone Name, Cyclone IP Address, Image Name or Image media type. There are different categories with different properties. Refer to the header file for a list of valid category and property names. The function getPropertyList will return a list of valid properties for each category.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone from which to read the property.
@parameter resourceOrImageId	The id for image properties is the image id on the Cyclone. The id for Cyclone or Network properties is 0.
@parameter categoryName	A pointer to a null-terminated character string that contains the category of the property that will be read.
@parameter propertyName	A pointer to a null-terminated character string that contains the name of the property that will be read.
@returnvalue	A pointer to a null-terminated character string that contains the value of the property.

setPropertyValue

bool setPropertyValue(uint32_t cycloneHandle, uint32_t resourceOrImageId, char * categoryName, char *propertyName, char * newValue);

This function changes the property of the Cyclone to the value specified. Only certain properties can be changed using this call. This function will return false if the property was not changed. Refer to the header file for a list of valid category and property names. The function getPropertyList will return a list of valid properties for each category.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone from which to read the property.
@parameter resourceOrImageId	The id for image properties is the image id on the Cyclone. The id for Cyclone or Network properties is 0.
@parameter categoryName	A pointer to a null-terminated character string that contains the category of the property that will be modified.
@parameter propertyName	A pointer to a null-terminated character string that contains the name of the property that will be modified.
@parameter newValue	A pointer to a null-terminated character string that contains the new value of the property.
@returnvalue	True if the data was successfully, set False otherwise

getPropertyList

char *getPropertyList(uint32_t cycloneHandle, uint32_t resourceOrImageId, char *categoryName);

This function returns a list of valid category and property names that can be used with the “getPropertyValue” and “setPropertyValue” functions. Refer to the header file for a list of valid category and property names.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone that will return the property list.
@parameter resourceOrImageId	The id for image properties is the image id on the Cyclone. The id for Cyclone or Network properties is 0.
@parameter categoryName	A pointer to a null-terminated character string that contains the category of the property list.
@returnvalue	A pointer to a null-terminated character string that contains a list of property names.

Ethernet or WiFi Calls

Note

References to WiFi for the calls in this section apply only to Cyclone models with WiFi support.

setNetworkParameters

uint32_t setNetworkParameters(uint32_t cycloneHandle, uint8_t DHCP, char* ipAddress, char* netMask, char* netGateway, char* dnsAddress, uint8_t connectionType);

When connecting to a WiFi network for the first time, its DHCP setting is in dynamic mode by default. This function is used to change the DHCP and other network parameters to different values for the WiFi network the Cyclone is currently connected to. The setNetworkParameters, getProperty, and setProperty calls can all be used to change Ethernet settings. However, to change WiFi network parameters, only setNetworkParameters may be used.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone for which to change the network parameters.
@parameter DHCP	The value that determines whether the network will be in Static DHCP or Dynamic DHCP. A value of 0 sets it to static and a value of 1 sets it to Dynamic. If Dynamic is chosen, the values of the rest of the parameters are ignored.
@parameter ipAddress	The new IP address to set the Cyclone to as a null-terminated char array in static DHCP mode.
@parameter netMask	The new network mask to set the Cyclone to as a null-terminated char array in static DHCP mode
@parameter netGateway	The new network gateway to which to set the Cyclone as a null-terminated char array in static DHCP mode.
@parameter dnsAddress	The new DNS address to set the Cyclone to as a null-terminated char array in static DHCP mode.
@parameter connectionType	The value that determines if the network parameters above will be set for WiFi or for Ethernet. Can be 0 to modify Ethernet or 1 for WiFi.
@returnvalue	0: Success. 1: Specified Cyclone is not connected or Cyclone has disconnected. You must connect to the Cyclone before you can use this function. 2: Invalid choice for DHCP. DHCP must be 0 for Static or 1 for Dynamic 3: Invalid connectionType: connectionType must be 0 for Ethernet and 1 for WiFi 4: Invalid values for IP address. IP must be a valid IP address. 5: Invalid values for netMask. The network mask must have valid values. 6: Invalid values for netGateway. The network gateway must have valid values. 7: Invalid values for dnsAddress. The DNS address must have valid values. 8: The Cyclone was unable to set these network parameter values.

connectToWifiNetwork

bool connectToWifiNetwork(uint32_t cycloneHandle, char* SSID, char* Password, char* BSSID);

Connects the specified Cyclone to a network that is in range and has the specified SSID.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to connect to the network.
@parameter SSID	A pointer to the null-terminated character array containing the SSID of the network you wish to connect to. The maximum length of an SSID is 32 characters. If the SSID is exactly 32 characters long, no null terminator is required.
@parameter Password	A pointer to the null-terminated character array containing the password for the network you wish to connect to. The maximum length of a password is 64 characters. If the password is exactly 64 characters long, no null terminator is required.
@parameter BSSID	A pointer to a null-terminated character array containing the BSSID in hex. Use an empty string to connect by SSID only.
@returnvalue	True if successful and false otherwise

scanWifiNetworks

bool scanWifiNetworks(uint32_t cycloneHandle, int* NumberofNetworks);

Scans for WiFi networks in range and gives the number of scanned networks (as NumberofNetworks). The Cyclone will have up to 15 of the strongest networks stored in a list internally..

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone for which to scan for networks.
@parameter NumberofNetworks	A pointer to an integer where the function will put the number of found networks into
@returnvalue	True if successful and false otherwise

getScannedNetwork

bool getScannedNetwork(uint32_t cycloneHandle, uint32_t networkIndex, char* SSID, char* RSSI, char* BSSID);

Gets the SSID, RSSI, and BSSID for a scanned network index. This function can be looped through the scanned networks to see what networks were stored (up to the top 15 strongest networks relative to the Cyclone).

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone from which to get the scanned network.
@parameter networkIndex	This is the scanned network from which to return the values.
@parameter SSID	A pointer to a char array that will store the network name. SSIDs will have a maximum length of 32 characters. If the SSID length is less than 32 characters then it will be null-terminated. Otherwise, it will be 32 characters long.
@parameter RSSI	A pointer to a char array that will store the RSSI strength as a string, including the sign, if negative. RSSI length will have a maximum of 5 characters with the null terminator.
@parameter BSSID	A pointer to a char array that will store the BSSID in hex. The BSSID will be 12 hex characters in length plus a null character for 13 characters.
@returnvalue	True if successful and false otherwise

enableAndRestartWifi

bool enableAndRestartWifi(uint32_t cycloneHandle);

Turns on the WiFi chip. If it is already on it will restart it instead.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone for which to turn on/restart WiFi.
@returnvalue	True if successful and false otherwise

turnOffWifi

bool turnOffWifi(uint32_t cycloneHandle);

Turns off the WiFi chip within the Cyclone.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone for which to turn off the WiFi chip.
@returnvalue	True if successful and false otherwise

eraseStoredWifiNetworks

bool eraseStoredWifiNetworks(uint32_t cycloneHandle);

Erases all the stored networks on the Cyclone.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone from which to erase networks.
@returnvalue	True if successful and false otherwise

disconnectAndForgetNetwork

bool cycloneHasWifi(uint32_t cycloneHandle);

Disconnects from the network the cyclone is connected to and removes the network from the stored memory.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to disconnect/forget.
@returnvalue	True if successful and false otherwise

cycloneHasWifi

bool disconnectAndForgetNetwork(uint32_t cycloneHandle);

Checks the Cyclone to see if it has WiFi capabilities..

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to check for WiFi capability
@returnvalue	True if the Cyclone is WiFi capable, and false otherwise

Features Calls

getFirmwareVersion

char *getFirmwareVersion(uint32_t cycloneHandle);

This function reads the firmware version of the selected Cyclone.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone of which to read the firmware version.
@returnvalue	Returns a pointer to a null-terminated character string containing the firmware version.

cycloneSpecialFeatures

bool cycloneSpecialFeatures(uint32_t featureNum, bool setFeature, uint32_t paramValue1, uint32_t paramValue2, uint32_t paramValue3, void *paramReference1, void *paramReference2);

This function is used for executing special features described by the featureNum parameter. Refer to the parameter specifications below for details.

Parameter	Description
@parameter featureNum	CYCLONE_GET_IMAGE_DESCRIPTION_FROM_FILE
@parameter setFeature	Indicates whether the image file has been decoded. If previous operations has already decoded the file, then set it to true. Otherwise set it to false.
@parameter paramValue1	Ignored, set it to 0.
@parameter paramValue2	Ignored, set it to 0.
@parameter paramValue3	Ignored, set it to 0.
@parameter paramReference1	A pointer to a pointer to a null-terminated character string that contains the image description of the programming file.
@parameter paramReference2	A pointer to a null-terminated character string which contains the full path to the specified programming file.
@returnvalue	True if the image description was read, False otherwise

Parameter	Description
@parameter featureNum	CYCLONE_GET_IMAGE_CRC32_FROM_FILE
@parameter setFeature	Indicates whether the image file has been decoded. If previous operations has already decoded the file, then set it to true. Otherwise set it to false.
@parameter paramValue1	Ignored, set it to 0.
@parameter paramValue2	Ignored, set it to 0.
@parameter paramValue3	Ignored, set it to 0.
@parameter paramReference1	A pointer to an unsigned 32-bit value containing the CRC32 of the programming file.
@parameter paramReference2	A pointer to a null-terminated character string which contains the full path to the specified programming file.
@returnvalue	True if the CRC32 was read, False otherwise

Parameter	Description
@parameter featureNum	CYCLONE_GET_IMAGE_SETTINGS_FROM_FILE
@parameter setFeature	Indicates whether the image file has been decoded. If previous operations has already decoded the file, then set it to true. Otherwise set it to false.
@parameter paramValue1	The type of setting to extract {configuration script=1, image unique id etc.=2, serial numbers=3, additional settings=4, crc_exclusive settings=5}.
@parameter paramValue2	Ignored, set it to 0.
@parameter paramValue3	Ignored, set it to 0.
@parameter paramReference1	A pointer to a pointer to a null-terminated character string that contains the settings of the programming file.
@parameter paramReference2	A pointer to a null-terminated character string which contains the full path to the specified programming file.
@returnvalue	True if the image settings was read, False otherwise

Parameter	Description
@parameter featureNum	CYCLONE_GET_IMAGE_COMMAND_LINE_PARAMS_FROM_FILE
@parameter setFeature	Indicates whether the image file has been decoded. If previous operations has already decoded the file, then set it to true. Otherwise set it to false.
@parameter paramValue1	Ignored, set it to 0.
@parameter paramValue2	Ignored, set it to 0.
@parameter paramValue3	Ignored, set it to 0.
@parameter paramReference1	A pointer to a pointer to a null-terminated character string that contains the command-line parameters of the programming file.
@parameter paramReference2	A pointer to a null-terminated character string which contains the full path to the specified programming file.
@returnvalue	True if the command line parameters was read, False otherwise

Parameter	Description
@parameter featureNum	CYCLONE_GET_IMAGE_SCRIPT_FILE_FROM_FILE
@parameter setFeature	Indicates whether the image file has been decoded. If previous operations has already decoded the file, then set it to true. Otherwise set it to false.
@parameter paramValue1	Ignored, set it to 0.
@parameter paramValue2	Ignored, set it to 0.
@parameter paramValue3	Ignored, set it to 0.
@parameter paramReference1	A pointer to a null-terminated character string that contains the name of the script file.
@parameter paramReference2	A pointer to a null-terminated character string which contains the full path to the specified programming file.
@returnvalue	True if the script file was read, False otherwise

Parameter	Description
@parameter featureNum	CYCLONE_TOGGLE_POWER_NO_DEBUG
@parameter setFeature	Ignored, set it to false.
@parameter paramValue1	Ignored, set it to 0.
@parameter paramValue2	Ignored, set it to 0.
@parameter paramValue3	Ignored, set it to 0.
@parameter paramReference1	Ignored, set it to null.
@parameter paramReference2	Ignored, set it to null.
@returnvalue	True if the power was toggled. False otherwise

Parameter	Description
@parameter featureNum	CYCLONE_SET_ACTIVE_SECURITY_CODE
@parameter setFeature	Ignored, set it to true.
@parameter paramValue1	The security code type (e.g. MON08, Renesas, PPC Nexus 64 bit, PPC Nexus 256 bit ignored, set it to 0).
@parameter paramValue2	The length of the security code bytes.
@parameter paramValue3	Ignored, set it to 0.
@parameter paramReference1	A pointer to an array containing the security code bytes.
@parameter paramReference2	A pointer to a null-terminated character string containing the security type string (such as 'MON08', 'RENESAS', 'PPCNEXUS').
@returnvalue	True if the security code was set, False otherwise

PEcloud Functions

These functions relate to the PEcloud service. The CloudImage API names in this section refer to images distributed through PEcloud. This is separate from whether an image is cloud-connected for execution control and result logging; images stored locally on the Cyclone are selected through the local image APIs.

initiateConnectionToCloud

bool initiateConnectionToCloud(uint32_t cycloneHandle);

This function attempts to establish an online connection to PEcloud.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to initiate the connection.
@returnvalue	Returns a boolean value. True means a connected to PEcloud has been established; false means this connection was not established.

countCloudVirtualFactories

uint32_t countCloudVirtualFactories(uint32_t cycloneHandle);

This function counts the Virtual Factories in the connected PEcloud account.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone connected to PEcloud.
@returnvalue	Returns the number of Virtual Factories in the connected PEcloud account

getCloudVirtualFactoryDescription

char *getCloudVirtualFactoryDescription(uint32_t cycloneHandle, uint32_t factoryIndex );

This function retrieves the description for a specific Virtual Factory in the connected PEcloud account.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone connected to PEcloud.
@parameter factoryIndex	The index value of the Virtual Factory to reference.
@returnvalue	Returns the description of the Virtual Factory referenced by the factory index.

countCloudImages

uint32_t countCloudImages(uint32_t cycloneHandle, uint32_t factoryIndex);

This function counts the number of PEcloud-distributed images in the specified Virtual Factory.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone connected to PEcloud.
@parameter factoryIndex	The index value of the Virtual Factory to reference.
@returnvalue	Returns the number of PEcloud-distributed images in the specified Virtual Factory.

getCloudImageId

uint32_t getCloudImageId(uint32_t cycloneHandle, uint32_t factoryIndex, uint32_t imageIndex);

This function returns the ID number of the PEcloud-distributed image in the associated Virtual Factory based on its index number.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone connected to PEcloud.
@parameter factoryIndex	The index value of the Virtual Factory to reference.
@parameter imageIndex	The index value of the PEcloud-distributed image.
@returnvalue	Returns the PEcloud-distributed image ID.

getCloudImageDescription

char *getCloudImageDescription(uint32_t cycloneHandle, uint32_t imageId);

This function returns the description of the specified PEcloud-distributed image.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone connected to PEcloud.
@parameter imageId	The PEcloud-distributed image ID number.
@returnvalue	Returns the description of the specified PEcloud-distributed image.

Additional PECloud Commands

For selectCloudImageForExecution, refer to Configuration / Image Maintenance Calls. For startExecutionOfSelectedImage, refer to Controlling Cyclone Programming.

Cyclone MultiChannel Programmer Functions

Note

Applies only to Cyclone MultiChannel programmers.

The MultiChannel SDK calls use the following public channel-list types:

List Type Constant	Value	Used By	Description
`ActiveChannelsListType`	0	`setChannelList`, `getChannelList`	The Active channel list. MultiChannel launch and image-selection calls use this list to determine which channels they operate on.
`ConnectedChannelsListType`	3	`getChannelList` only	Returns channels that are currently connected.
`ActiveOrConnectedChannelsListType`	4	`getChannelList` only	Returns channels that are Active, connected, or both. This is useful for status displays.

setChannelList modifies only ActiveChannelsListType. The connected and active-or-connected lists are read-only views returned by getChannelList.

checkIfCycloneIsMultichannel

bool checkIfCycloneIsMultichannel(uint32_t cycloneHandle);

This function determines whether the specified Cyclone supports MultiChannel programming.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone to check for MultiChannel capability.
@returnvalue	True if the specified Cyclone supports MultiChannel programming. Otherwise returns false.

setChannelList

bool setChannelList(uint32_t cycloneHandle, uint32_t listType, char *channelList);

This function sets a channel list on a Cyclone MultiChannel programmer. The channel list is a comma-separated string of channel numbers, such as 11,12,13,14.

Use ActiveChannelsListType to choose the channels that later MultiChannel operations should use.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone MultiChannel to update.
@parameter listType	The list to set. Use `ActiveChannelsListType`. `ConnectedChannelsListType` and `ActiveOrConnectedChannelsListType` are read-only and are not changed by this function.
@parameter channelList	A null-terminated, comma-separated list of channel numbers. For example: `11,12,13,14`.
@returnvalue	True if the channel list was set successfully. Otherwise returns false.

getChannelList

char *getChannelList(uint32_t cycloneHandle, uint32_t listType);

This function returns a comma-separated channel list from a Cyclone MultiChannel programmer. The returned list depends on listType.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone MultiChannel from which to read a channel list.
@parameter listType	The list to read. Valid values are `ActiveChannelsListType`, `ConnectedChannelsListType`, and `ActiveOrConnectedChannelsListType`.
@returnvalue	A pointer to a null-terminated, comma-separated list of channel numbers. Returns an empty string if the Cyclone is not a MultiChannel programmer or if the requested list is empty.

getChannelErrorCode

int32_t getChannelErrorCode(uint32_t cycloneHandle, uint32_t channelNumber);

This function returns the most recent error code for a specific channel on a Cyclone MultiChannel programmer. Call this after an operation such as programming launch or channel preparation has completed and getNumberOfErrors indicates that an error occurred. Unlike the programmer-level error list returned through getErrorCode, each channel has only a single channel-specific error code. A return value of 0 indicates that the channel completed successfully.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone MultiChannel to query.
@parameter channelNumber	The published channel number to query, such as `11`, `12`, `31`, or `34`.
@returnvalue	The channel-specific error code. A return value of `0` indicates success for that channel. If the channel error could not be retrieved, the function returns the SDK error code for unable to retrieve error information.

prepareActiveChannelsForLaunch

bool prepareActiveChannelsForLaunch(uint32_t cycloneHandle);

This function prepares the selected Active channels for a later programming launch by storing and validating the channel-selected images on the channel hardware, but it does not start target programming.

Calling this function is optional. The Cyclone MultiChannel automatically performs the same channel preparation when programming is launched with startExecutionOfSelectedImage or startImageExecution. This function is provided so an application can move channel-preparation time to an earlier configuration step, rather than incurring that time during the first launch.

If this function returns True, the operation has been started. Call checkCycloneExecutionStatus until it returns 0, then use getNumberOfErrors, getErrorCode, and getChannelErrorCode as needed to determine whether preparation completed successfully.

Parameter	Description
@parameter cycloneHandle	The handle of the Cyclone MultiChannel to prepare for launch.
@returnvalue	Returns true if channel preparation was initiated. Otherwise returns false.