PEmicro Cyclone Series User manual

Cyclone Automated Control Package
Developer‟s Manual
Copyright 2016, P&E Microcomputer Systems, Inc. All rights reserved.
Visit us on the web at http://www.pemicro.com

Cyclone Automated Control Package
2
Document Version History
Version
Date
Notes
5.89
29 April 2016
Added information about Cyclone Universal
and Cyclone Universal FX
5.73
10 December 2015
Updated Document Version History
Updated “P&E Software Licensing System”
5.52
4 August 2015
Updated MSVC# Project
Updated
“check_STARTED_cyclonepromax_status”
5.33
10 April 2015
Updated “connect_to_cyclonepromax()”
1.6
25 June 2014
Updated “add_image_to_cyclone” and
“update_image_with_file”
Updated “connect_to_cyclonepromax” and
Launch to support PORT_NUM
1.5
30 December 2009
Added documentation for Compact Flash
support
Added documentation for
“set_cyclonepromax_media_type”
1.4
2 October 2008
Added documentation for “set_COM_port”
function
Updated software license
1.3
1 July 2008
Added documentation for the included
Cyclone Launch application
1.2
14 April 2008
Added documentation for C# support
1.1
13 March 2008
Added documentation for software licensing
Added documentation for “close_all_ports”
function
1.0
10 January 2008
Initial document

Cyclone Automated Control Package
3
CONTENTS
1 Introduction........................................................................................................5
1.1 Introduction to Cyclone Launch...................................................................5
1.2 Introduction to the Cyclone Control DLL......................................................6
1.3 Introduction to RS232 / Ethernet Communication Protocols........................6
1.4 Library Files Included..................................................................................7
1.5 P&E Compatible Hardware..........................................................................7
1.6 Versions ......................................................................................................8
2 Software License ...............................................................................................9
2.1 License for Basic and Professional Editions................................................9
2.2 License for Enterprise Edition....................................................................10
2.3 P&E Software Licensing System...............................................................11
3 Getting Started with the Cyclone Control DLL..................................................12
3.1 Example Programs....................................................................................12
3.2 Starting your own project...........................................................................12
3.3 Initialization................................................................................................14
3.4 Finalization................................................................................................15
3.5 Initial Cyclone Setup..................................................................................15
3.6 Typical Usage............................................................................................16
3.7 External Memory Storage Support............................................................17
4 Application Programming Interface (API).........................................................18
4.1 Constants..................................................................................................18
4.2 DLL Loading / Unloading Calls..................................................................19
4.2.1 load_dll..........................................................................................19
4.2.2 unload_dll......................................................................................19
4.2.3 enumerate_all_ports......................................................................20
4.2.4 close_all_ports...............................................................................20
4.2.5 version...........................................................................................20
4.3 Cyclone Connecting / Disconnecting Calls................................................21
4.3.1 connect_to_cyclonepromax...........................................................21
4.3.2 connect_to_cyclonepromax_by_ip ................................................23
4.3.3 disconnect_from_cyclonepromax..................................................24
4.3.4 set_local_machine_ip_number......................................................24
4.3.5 set_COM_port...............................................................................25
4.4 Controlling Cyclone Programming.............................................................26
4.4.1 START_execute_all_commands...................................................26
4.4.2 START_dynamic_program_bytes..................................................27
4.4.3 check_STARTED_cyclonepromax_status.....................................28
4.4.4 dynamic_read_bytes .....................................................................29
4.4.5 get_last_error_code.......................................................................30
4.4.6 get_last_error_addr.......................................................................30
4.4.7 pro_set_active_security_code.......................................................31
4.5 Configuration / Image Maintenance Calls..................................................32

Cyclone Automated Control Package
4
4.5.1 reset_cyclonepromax ....................................................................32
4.5.2 get_firmware_version....................................................................32
4.5.3 get_image_description ..................................................................33
4.5.4 compare_image_with_file..............................................................34
4.5.5 erase_all_cyclone_images ............................................................35
4.5.6 add_image_to_cyclone..................................................................36
4.5.7 update_image_with_file.................................................................37
4.5.8 count_cyclonepromax_images......................................................37
4.5.9 toggle_power_no_background_entrance ......................................38
4.5.10 set_cyclonepromax_media_type...................................................39
5 List of Error Codes...........................................................................................40
6 Cyclone Launch...............................................................................................43
6.1 Startup.......................................................................................................44
6.2 Command-Line Parameter Examples .......................................................45
6.3 Configuration Script File............................................................................46
6.3.1 SETUP Commands.............................................................................46
6.3.2 Operation Commands that Control All Connected Cyclones ..............49
6.3.3 Operation Commands that Control a Single Cyclone..........................50
6.4 Examples...................................................................................................52
6.4.1 Typical Usage.....................................................................................52
6.4.2 Controlling Multiple Cyclones..............................................................53
6.4.3 Programming dynamic data................................................................54
6.4.4 Executing more than 1 image on the same Cyclone...........................55
6.4.5 Image Management............................................................................56
6.5 DOS Error Codes......................................................................................57
6.6 Sample Batch File .....................................................................................60
7 Cyclone Communication Protocols..................................................................61

Cyclone Automated Control Package
5
1 Introduction
Thank you for installing P&E‟s Cyclone Automated Control Package! You
now have a set of tools that will allow you to automate your production
programming process like never before. Included in this package are:
The Cyclone Launch application, which allows control of P&E Cyclone
units through the usage of simple batch and script files
A dynamic link library (DLL) which allows custom software applications to
control one or more P&E Cyclone units
RS232 and Ethernet communication protocols (Enterprise Edition only)
No documentation, source code, or application extensions which come
with this development package may be distributed, in whole or in part, without
prior written permission from P&E. All documentation in this package is Copyright
2008, P&E Microcomputer Systems, Inc. All rights reserved.
1.1 Introduction to Cyclone Launch
The Cyclone Launch application allows a developer to use simple ASCII
script files to control Cyclone operations from the PC. Once the script files are
configured, a simple batch file can be created to initiate programming operations
on multiple Cyclone units. Cyclone Launch also supports features such as stand-
alone image maintenance and dynamic data programming, thus providing a
powerful, yet easy to use interface. Cyclone Launch is ideal for getting your
automated production environment up and running in a very short amount of
time.

Cyclone Automated Control Package
6
1.2 Introduction to the Cyclone Control DLL
The dynamic link library included in this package allows you to create an
application on the PC that can directly control one or more P&E Cyclone units.
These interface routines are designed to be compiled into visual and non visual
applications running on Windows operating systems.
The actual interface routines are located in the
“CYCLONE_CONTROL.DLL” 32 bit DLL file. The DLL is callable from almost any
32-bit / 64-bit Windows development environment. Since the way the DLL is
called varies depending on the compiler used, you are provided with the DLL
interface code and sample applications for each of the following compilers:
Borland Delphi 2.0+ (Pascal) - Visual Application
Microsoft Visual C++ 5.0+ - Visual MFC Application
Microsoft Visual C# 2005+ - Visual Application
The sample applications come with project and workspaces defined for
ease of use. Simply open the project/workspace in your compiler and you should
be able to build the sample application without any modifications. The sample
applications come precompiled with ICONS, so you can run them before jumping
into the code. The callable interface routines are defined in:
INSTALLDIR\Delphi20\multiple_cyclone_programming.pas
INSTALLDIR\msvc50\multiple_cyclone_programming.h
INSTALLDIR\msvcsharp2005\visual_sap_control\
multiple_cyclone_programming.cs
1.3 Introduction to RS232 / Ethernet Communication Protocols
The RS232 and Ethernet Communication protocols included with the
Enterprise Edition allow a developer to manually send individual command
packets to control each Cyclone unit. This is ideal for setups that do not have
access to a PC or production environments that do not run Microsoft Windows
based computers.

Cyclone Automated Control Package
7
1.4 Library Files Included
Due to the various calling conventions that currently exist, P&E provides the
developer with two different versions of the Cyclone Control DLL. The example
programs include header files which use the “cdecl” calling convention. The user
must modify these header files if they wish to use the “stdcall” version of the
library.
Library file
Calling Convention
cyclone_control.dll
cdecl
cyclone_control_cdecl.dll1
cdecl
cyclone_control_stdcall.dll
stdcall
1Note that “cyclone_control_cdecl.dll” is identical to “cyclone_control.dll”
1.5 P&E Compatible Hardware
The following lists the P&E hardware compatible with the Cyclone Automated
Control Package. To ensure proper operations, P&E recommends upgrading all
Cyclone units to the latest firmware.
Cyclone Universal FX
Cyclone Universal
Cyclone PRO
Cyclone MAX
Cyclone for ARM
Cyclone for Renesas
Cyclone for STMicro

Cyclone Automated Control Package
8
1.6 Versions
The Cyclone Automated Control Package product is split into three
separate versions. While this manual is written to support all three versions, it is
important to note the following limitations:
UBasic Edition
DLL only supports controlling a single Cyclone unit
DLL will only execute the first image stored on a Cyclone (using the
START_execute_all_commands function call)
DLL does not support the “START_dynamic_program_bytes” function
DLL does not support the “compare_image_with_file” function
DLL does not support the “erase_all_cyclone_images” function
DLL does not support the “add_image_to_cyclone” function
DLL does not support the “update_image_with_file” function
RS232 / Ethernet communication protocols are not included
UProfessional Edition
DLL supports controlling of up to 3 Cyclone units simultaneously
DLL supports all available function calls
RS232/ Ethernet communication protocols are not included
Requires Compact Flash License (sold separately) to modify images on
external Compact Flash cards
Supports the modification of images on external SDHC cards on Cyclones
with this feature.
UEnterprise Edition
DLL supports controlling of an unlimited number of Cyclone units
simultaneously
DLL supports all available function calls
RS232/ Ethernet communication protocols are included
DLL does NOT require Compact Flash License (sold separately) to modify
images on external Compact Flash cards. License is still required to
modify images on external Compact Flash cards when you use the
Cyclone Image Managerment utility GUI
Supports the modification of images on external SDHC cards on Cyclones
with this feature.

Cyclone Automated Control Package
9
2 Software License
2.1 License for Basic and Professional Editions
This software and accompanying documentation are protected by United States
Copyright law and also by International Treaty provisions. Any use of this
software in violation of copyright law or the terms of this agreement will be
prosecuted.
This software is copyrighted by P&E Microcomputer Systems, Inc. Copyright
notices have been included in the software.
P&E Microcomputer Systems authorizes you to make archival copies of this
software for the sole purpose of back-up and protecting your investment from
loss. Under no circumstances may you copy this software or documentation for
the purpose of distribution to others. Under no conditions may you remove the
copyright notices from this software or documentation.
This software may be used by one person on up to two different computers,
provided that the software is never used on the two computers at the same time.
P&E expects that group programming projects making use of this software will
purchase a copy of the software and documentation for each user in the group.
Contact P&E for volume discounts and site licensing agreements.
With respect to the physical media provided within, P&E Microcomputer Systems
warrants the same to be free of defects in materials and workmanship for a
period of 30 days from the date of receipt. If you notify us within the warranty
period, P&E Microcomputer Systems will update the defective media at no cost.
P&E Microcomputer Systems does not assume any liability for the use of this
software beyond the original purchase price of the software. In no event will P&E
Microcomputer Systems be liable for additional damages, including any lost
profits, lost savings or other incidental or consequential damages arising out of
the use or inability to use these programs, even if P&E Microcomputer Systems
has been advised of the possibility of such damage.

Cyclone Automated Control Package
10
2.2 License for Enterprise Edition
This software and accompanying documentation are protected by United States
Copyright law and also by International Treaty provisions. Any use of this
software in violation of copyright law or the terms of this agreement will be
prosecuted.
This software is copyrighted by P&E Microcomputer Systems, Inc. Copyright
notices have been included in the software.
This software may be installed on up to five computers.
P&E Microcomputer Systems authorizes you to make archival copies of this
software for the sole purpose of back-up and protecting your investment from
loss. Under no circumstances may you copy this software or documentation for
the purpose of distribution to others. Under no conditions may you remove the
copyright notices from this software or documentation.
With respect to the physical media provided within, P&E Microcomputer Systems
warrants the same to be free of defects in materials and workmanship for a
period of 30 days from the date of receipt. If you notify us within the warranty
period, P&E Microcomputer Systems will update the defective media at no cost.
P&E Microcomputer Systems does not assume any liability for the use of this
software beyond the original purchase price of the software. In no event will P&E
Microcomputer Systems be liable for additional damages, including any lost
profits, lost savings or other incidental or consequential damages arising out of
the use or inability to use these programs, even if P&E Microcomputer Systems
has been advised of the possibility of such damage.

Cyclone Automated Control Package
11
2.3 P&E Software Licensing System
When Cyclone Launch or the Cyclone Control DLL is used for the first
time, a popup form will be shown prompting the user to enter the relevant
information to activate the software. Please refer to the original packaging for the
necessary installation code. Please follow the on-screen instructions to activate
the product.
In a situation where you would like to change versions, (e.g. upgrading
from Basic edition to Professional edition) please perform the following
procedure:
1. Uninstall the current version of the software
2. Search your PC for the “pemicro.lic” file*. Backup or delete this file.
3. Install the new version of the software
4. Proceed with the software activation process using the new installation
code that you should have received
* The “pemicro.lic” file is found in the same directory where the DLL resides.
Normally this is found in the Windows System Folder:
\WINDOWS\SYSTEM for Windows 95, Windows 98, Windows ME
\WINNT\SYSTEM32 for Windows 2000, Windows NT
\WINDOWS\SYSTEM32 for 32 bit versions of Windows XP, Windows
Vista, Windows 7, Windows 8, Windows 10
\WINDOWS\SYSWOW64 for 64 bit versions of Windows XP, Windows
Vista, Windows 7, Windows 8, Windows 10
If the user account that is activating the software does not have the required
elevated privileges to modify the System Folder, the pemicro.lic file may be
redirected to the VirtualStore System Folder by User Account Control. This may
be found at
“\USERS\%USERNAME%\APPDATA\LOCAL\VIRTUALSTORE\WINDOWS\”

Cyclone Automated Control Package
12
3 Getting Started with the Cyclone Control DLL
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 DLL working with your P&E hardware smoothly.
3.1 Example Programs
Located in the installation directory of the package, you will find three
example programs that you can use as a reference for your own application. The
examples are located in the following directories:
INSTALLDIR\Delphi20 - Delphi 2.0+ Example Visual Application
INSTALLDIR\msvc50 - MSVC 5.0+ Example MFC Visual Application
INSTALLDIR\msvcsharp2005 - MSVC# 2005+ Example Visual Application
These example programs are a valuable reference to use when starting
your own custom application.
3.2 Starting your own project
To gain access to the functions available in the DLL, the following files
need to be added to the new project workspace:
UDelphi 2.0+ Projects
INSTALLDIR\Delphi20\multiple_cyclone_programming.pas
All other source files which will call functions from the DLL should include the
above file using the Delphi “uses” command.
UMSVC 5.0+ Projects
INSTALLDIR\msvc50\multiple_cyclone_programming.h
INSTALLDIR\msvc50\multiple_cyclone_programming.cpp
All other source files which will call functions from the DLL should include the
above header file with the C/C++ #include directive.

Cyclone Automated Control Package
13
UMSVC# 2005+ Projects
INSTALLDIR\msvcsharp2005\multiple_cyclone_programming.cs
Once added to the project workspace, the namespace of the class may optionally
be modified to match the namespace of your project.
The project (visual_sap_control.sln) has been tested in Microsoft Visual Studio
Community 2015. To build and execute the project you must configure the
compiler to build for the x86 platform only under Build --> Configuration Manager.

Cyclone Automated Control Package
14
3.3 Initialization
ULoading 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.
load_dll( )
For Delphi (Pascal) and C# users, this process is transparent for the user and no
action is required.
UEnumerate 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.
enumerate_all_ports( )
UConnect to the P&E hardware interface
The next step is to establish communications with the P&E Cyclone unit.
This is accomplished with the following function call:
connect_to_cyclonepromax( )
Refer to Chapter 4 of this manual 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.

Cyclone Automated Control Package
15
3.4 Finalization
Before closing the application, it is recommended that the session with the
P&E hardware be terminated and the DLL unloaded from memory.
These calls should always be made before the application closes:
disconnect_from_cyclonepromax( );
close_all_ports( );
unload_dll( );
Note that the “unload_dll” call is only required for C/C++ applications. For the
Delphi and C# example projects, the DLL is automatically unloaded when the
application closes.
3.5 Initial Cyclone Setup
The Cyclone Image Creation Utility software, which is included with each
Cyclone unit, is used to create the standalone images that will be stored in the
non-volatile memory of the Cyclone. These 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 Automated Control Package, 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.

Cyclone Automated Control Package
16
3.6 Typical Usage
Figure 3-1: Typical programming procedure flow chart
Figure 3-1 describes the most common sequence of calls to the DLL after
successfully connecting to the Cyclone unit.
Step 1:Initiate programming operations. “START_execute_all_commands”
carries out the programming operations defined in the stand-alone image stored
on the Cyclone unit. “START_dynamic_program_bytes” allows the user to
manually specify the data as well as the memory address of the programming.
Step 2 : Wait for programming completion. Note that no error checking is
provided by the “check_STARTED_cyclonepromax_status” call. A result of 0 will
be returned even if an error has occurred or if communication with the Cyclone is
lost.
Step 3 : Retrieve the error code from the Cyclone unit to determine if the
programming was successful.

Cyclone Automated Control Package
17
3.7 External Memory Storage Support
Some Cyclones support external memory storage (either Compact Flash or
SDHC). The Cyclone Control DLL and Cyclone Launch both support images
residing on external memory cards. The following functions/commands are used
to switch between Cyclone internal Flash and external memory:
Cyclone Control DLL : set_cyclonepromax_media_type
Cyclone Launch : MEDIATYPE=n and ALLMEDIATYPE=n
Image numbers will overlap between the two media types. Image number 1 will
refer to either the first image on internal Flash or the first image on the external
memory card, depending on the previously selected media type.
When you attempt to modify the images on the Compact Flash card (eg. erasing
or adding images) for the first time, the user will be prompted to enter the
Installation Code for a valid Compact Flash license (sold separately). This step is
NOT required for the Enterprise edition of the Cyclone Automated Control
Package.

Cyclone Automated Control Package
18
4 Application Programming Interface (API)
This chapter describes the API of the “CYCLONE_CONTROL.DLL” in
detail. Note that certain functions in the API are not supported in the Basic
Edition of the DLL. Please refer to section 1.6 of this manual for more details.
In each section, the function prototypes are given in the following order:
Delphi
C/C++
C#
4.1 Constants
Name
32-bit Value
PortType_USB
5
PortType_Ethernet
6
PortType_Serial
7
Open_by_IP_Address
1
Open_by_Name
2
Open_by_Port_Num
3
Media_Flash
1
Media_CompactFlash1
2
1Note that Media_CompactFlash is also used for SDHC cards

Cyclone Automated Control Package
19
4.2 DLL Loading / Unloading Calls
4.2.1 load_dll
bool load_dll(void);
Loads the CYCLONE_CONTROL.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. This routine is
only required for C/C++ applications and is defined in the file
“multiple_cyclone_programming.cpp”.
@returnvalue
True if the load was successful
False otherwise
4.2.2 unload_dll
void unload_dll (void);
Unloads the DLL loaded with load_dll( ). This call should be made before
the application starts to unload itself. This routine is only required for
C/C++ applications and is defined in the file
“multiple_cyclone_programming.cpp”

Cyclone Automated Control Package
20
4.2.3 enumerate_all_ports
procedure enumerate_all_ports;
void enumerate_all_ports(void);
void enumerate_all_ports(void);
Performs all necessary initialization in order to successfully communicate
with a Cyclone unit. This function needs to be called once, before the first
call to “connect_to_cyclonepromax”.
4.2.4 close_all_ports
procedure close_all_ports;
void close_all_ports(void);
void close_all_ports(void);
This call closes all open Cyclone units (if any) and frees all dynamic
memory used by the DLL. This function should be called before the user
application is closed.
4.2.5 version
function version : pchar;
char * version(void);
String version(void);
@returnvalue
Returns a pointer to a null-terminated
string containing the version number of the
DLL.