1. Getting Started with FP/GP-ARM DLL

1.1. Introduction

This document describes the FlashPro-ARM and GangPro-ARM API-DLL, and explains how to use it. The API-DLL is a dynamic library that can control multiple Flash Programming Adapters (FPAs) simultaneously. It is intended for users that need to use multiple ARM FPAs to program a board with multiple ARM microcontroller units (MCUs). An example hardware setup is shown below:

1.2. Software Installation

FlashPro-ARM or GangPro-ARM Programmer package contains:

1. One FlashPro-ARM or GangPro-ARM programming adapter.

2. One 6 feet long USB-A to USB-B cable.

3. FlashPro-ARM programmer allows to program one target device from one adapter.

4. GangPro-ARM programmer allows to program up to six(6) target devices from one adapter.

5. FPA to ARM 14-pin to 20-pin adapter (PE036X01) and ribbon cable.

6. Programming software can be installed by downloading the ARM package from: https://www.elprotronic.com/pages/downloads

7. A GangSplitter-ARM can be optionally purchased to provide the hardware connections to connect six JTAG/SWD cables to one adapter. GangSplitter-ARM product: https://www.elprotronic.com/products/gangsplitter-arm layout: GANG_ARM_Splitter.pdf

8. Customizable sockets that can program raw chips are also available here: https://www.elprotronic.com/collections/universal-socket-boards

The FlashPro-ARM/GangPro-ARM software runs under Windows (x86/x64) and Linux (amd64/armhf). Follow instructions below to install the software:

1. The USB-FPA 6.1 adapter (grey) only supports the Windows x86 installer. The XStream-Iso, and XStreamPro-Iso adapters (black) support all installers.

2. Download Windows installer (ARM-win.zip), Ubuntu Linux installer (ARM-amd64.tgz), or Raspbian Linux installer (ARM-armhf.tgz)

3. For Linux installation, follow included README.txt file which will provide instructions on how to run .deb auto installer package.

4. For Windows, run setup.exe and the setup wizard appears automatically. Click Install to begin the process.

5. Once the installation program starts, on-screen instructions will guide you through the remainder of the installation. You must accept the license agreement before using this software.

1.3. Driver Installation

The Linux installation relies on the default libusb-1.0 packages that can be installed using apt.

The Windows installation will install the Elprotronic USB driver files in Windows directories "Windows\inf" and "Windows\system32\drivers".

1. Plug in the FlashPro-ARM/GangPro-ARM Programmer to the PC USB Port, using provided cable extender (USB-A to USB-B).

2. For Windows XP, Vista, 7, 8, 10. The "New hardware has been found - USB-FPA-BOOT" window should be displayed. Follow wizard instructions to install the drivers.

   1. In the first Wizard dialog screen (see Figure 3.1) select the "Yes, this time only" option.

      
      Figure 1.3: New Hardware Wizard, step 1. Select "Yes, this time only."

   2. In the second Wizard dialog screen (see Figure 3.2) select the "Install the software automatically (Recommended)" option and press NEXT button.

      
      Figure 1.4: New Hardware Wizard, step 2. Select "Install the software automatically.

   3. Software will search for the USB-FPA-BOOT driver. It can take a few minutes to find the necessary files. When the driver is found then the following warning will be displayed (Figure 3.3).

      
      Figure 1.5: New Hardware Wizard, step 3. Ignore this warning.

   4. Ignore this message and press button "Continue Anyway". The first USB-FPA-BOOT driver should be installed and the following message will be displayed (Figure 3.4).

      
      Figure 1.6: New Hardware Wizard, step 4. USB-FPA-BOOT driver installed.

   5. Press the "Finish" button.

      
      Figure 1.7: New Hardware Wizard, step5. USB-FPA (Elprotronic) driver installed.

      After a few seconds, a second "New hardware" window will appear regarding the adapter with the name (Elprotronic). Repeat procedures described above to install the Elprotronic driver (see Figure 3.5). If for any reason the wizard cannot find the USB driver's location then use the manual browse option to locate driver files in the software directory "C:\Program Files (x86)\Elprotronic\Drivers USB-FPA\XP,Vista,Win-7,8,10".
      For Windows 2000, 98-SE, ME. The "New hardware has been found" window will be displayed instead. Follow wizard instructions to install the drivers.

      1. Press "Next" when the Device Wizard Driver screen appears.

      2. Select the following option on the wizard screen: select a suitable driver for my device (recommended) and press "Next".

      3. Select the third option – "Specify a location" for a location of the driver files.

      4. In the application software directory "C:\Program Files (x86)\Elprotronic\Drivers USB-FPAnW2K, W98SE, WinME" and press "Next".

      5. Driver installation process will start.

3. Driver installation procedures should be done twice to install two USB drivers - the Boot driver and the Application driver.

4. Reboot computer if necessary.

1.4. Hardware Setup

Connect programmer to target device:

1. Connect the programming adapter to the PC USB Port or via USB-HUB using provided cable extender (USB-A to USB-B) (see Figure 1.1 or 1.2).

2. Target Connection:

   1. Plug in 14-pin ribbon cable to FlashPro-ARM programmer and then the ARM 14-pin to 20-pin adapter (PN: PE036X01) to the end of the ribbon cable. Connect target device to the 20-pin end of the adapter. Make sure that pin 1 on your device board's header is connected to pin 1 of the socket connector (red cable).

   2. Alternatively, connect the GangPro-ARM programmer to the GangSplitter-ARM, and then connect each GangSplitter-ARM socket to target device using a 20-pin ARM ribbon cable.

1.5. DLL Overview

The FlashPro-ARM/GangPro-ARM DLL setup is implemented using two DLLs, the Multi API-DLL and the API-DLL. One instance of the top-level Multi API-DLL controls multiple instances of the API-DLL. The Multi API-DLL manages all global meta-data and control flow while the API-DLL controls one adapter individually. The user interacts only with the Multi API-DLL.

Initializing multiple FPAs using the Multi API-DLL is straightforward. The top-level function F_OpenInstancesAndFPAs() accepts a string or file input path that specifies the index and serial numbers (SNs) of all the FPAs the user wishes to control. With this input the Multi API-DLL will create enough API-DLL instances to manage all FPAs automatically. Afterwards, the Multi API-DLL has several functions which allow the user to select which FPA is controlled (or all at once), and issue commands that will be automatically forwarded to the corresponding API-DLL. Currently, up to 64 individual FPAs can be controlled using the Multi API-DLL (these would normally be connected using USB hubs connected to the host computer’s USB port).

1.6. Setting up DLL Demo Environment

After installation, the relevant files are found in the directory:

• 32-bit installation (x86): C:\Program Files (x86)\Elprotronic\ARM, or

• 64-bit installation (x64): C:\Program Files\Elprotronic\ARM,

The relative directories FlashPro-ARM and GangPro-ARM will contain the FlashPro-ARM and GangPro-ARM executables.

The API-DLL directory contains all the demo applications, and the bin and debug directories that have the Multi API-DLL and API-DLL files.

The easiest way to get started using the DLL is to run the executable code examples. To run the examples:

1. Copy the ARM directory out of the Program Files directory to a work directory. The target directory should be a place where files can be freely modified without administrator privileges. This is important for compiling Visual Studio examples and because as mentioned in the previous section, the Multi API-DLL will attempt to create enough copies of the API-DLLs to have one for each adapter. If there are more than one adapter, then the Multi API-DLL will fail in creating FlashProARM-FPA2.dll or GangProARM-FPA2.dll within the Program Files directory (those files get placed in the hidden C:\Users\AppData directory) and those adapters will not respond.

2. Start any of the executables, for example FP-ARM-Demo-C#.exe, or GP-ARM-Demo-C++.exe

3. If using one adapter, press the “Open One Instance and FPA (“*# *”)” button followed by Initialization button.
   

4. 

   Next Open Setup File and Open Code File as in the Main GUI.

5. Subsequently use the Auto Program or other buttons to call DLL functions.

1.7. Running Demo Applications

The FlashPro-ARM and GangPro-ARM installation package has demos in C++, C#, Python and Labview. The projects have already been compiled and the executables are available in the API-DLL\bin\ and API-DLL\debug directories. The demo projects have been configured such that they will build their executables to the bin directory for release build and debug directory for debug build. Debug symbols for FlashPro-ARM or GangPro-ARM libraries are not available.

The code examples provided illustrate how to use most, but not all available DLL functions.
The pull-down menus that list MCU vendors, families, groups, and names are intended to be used
for each individual FPA separately (index 1 to 64), not for FPA index 0 (ALL FPAs) since each
FPA can be configured to program different vendors depending on configuration.

1.7.1. C/C++ Basic demo code sequence

C/C++ Basic Demo Code Sequence

Any application using the library will call most of the following functions. First, any one adapter is found, and initialized. Assuming at least one adapter was found (F_OpenInstancesAndFPAs returns > 0), the config and code files are loaded to select the MCU and data to be programmed. Finally, the procedure F_AutoProgram will run the full programming sequence of Erase, Blank Check, Write, Verify, and optionally Lock the MCU.

//Open adapters - this binds adapter(s) to this application. Any adapters not opened here could potentially be opened by another application in parallel.
F_OpenInstancesAndFPAs("*# *");//find any adapter, opens only one
//F_OpenInstancesAndFPAs("*# FPA-1 20171645 FPA-2 20210120 ");//open two adapters over USB
//F_OpenInstancesAndFPAs("*# FPAETH-IP-1 192.168.0.101 FPAETH-IP-2 192.168.0.102);//open two adapters over LAN (XStreamPro-Iso only)
//F_OpenInstancesAndFPAs( <path to FPAs-setup.ini file> );//read configuration from file

//Select adapter index for accepting commands
F_Set_FPA_index (0); //select all opened adapters for sending commands
//F_Set_FPA_index (1); //select only adapter 1 for sending commands
//F_Set_FPA_index (2); //select only adapter 2 for sending commands

F_Initialization();  //initialize selected adapter(s)
F_ConfigFileLoad( <path to config file> ); //config file can be easily created in the GUI, or parameters can be set using F_Set_Config_Value_By_Name

//If the configuration file above already has a valid code path, the following function(s) is(are) not necessary
F_ReadCodeFile( <path to code file> ); //flush code buffer, read first code file. Can be used for *.hex, *.txt, *.srec, *.sxx etc.
//F_ReadCodeFile_BaseAddr( <path to code file>, UINT32 baseAddr ) //same as above but designed for *.bin files. Function will add baseAddr to code address. Can also be used to shift regular code files.
//F_AppendCodeFile( <path to code file> ); //append code file, does not flush code buffer.
//F_AppendCodeFile_BaseAddr( <path to code file>, UINT32 baseAddr ) //same as F_ReadCodeFile_BaseAddr but used for appending
  
//Factory erase target (optional)
//F_Clear_Locked_Device();

//Erase, Blank Check, Write and Verify code programmed to target(s)
F_AutoProgram();

//Print output
cout << F_Report_Message() << endl;
	

Running the aforementioned code snippet within the FP-ARM-Demo-C#.exe produces the following result:

Running the aforementioned code snippet within the GP-ARM-PB-Demo-C++.exe produces the following result:

The aforementioned code snippet works both with the FlashPro-ARM and GangPro-ARM libraries because those functions are common to both adapters. For specific functions exclusive to the FlashPro-ARM or GangPro-ARM please consult the DLL functions chapter within this guide.

1.7.2. Required files

The following files should be placed within the current working directory of the application executable:

• FlashPro-ARM

  • FlashProARM-FPAsel.dll, and FlashProARM-FPA1.dll

• GangPro-ARM

  • GangProARM-FPAsel.dll, and GangProARM-FPA1.dll

1.7.3. C++ Demo Specifics

When a C++ demo application is created, the following files should be added to the project:

• FlashPro-ARM

  • FlashProARM-Dll.h - header file (from \include)

  • FlashProARM-FPAsel.lib - Multi API lib file (from \bin or \debug)

• GangPro-ARM

  • GangProARM-Dll.h - header file (from \include)

  • GangProARM-FPAsel.lib - Multi API lib file (from \bin or \debug)

• ARM-Errors-list.h - Errors list definitions (from \include)

The source code is also available for the provided demo executables; if converting from the current Visual Studio 2005 project, to newer versions, sometimes incorrect conversions can break intended GUI dimensions.

1.7.4. C# Demo Specifics

When the C# demo application is created, the following files should be added to the project (taken from any C# demo directory):

• FlashPro-ARM

  • FLASHPROARM_API.cs - DLL Import definitions

  • FLASHPROARM_DLL.cs - Definitions used by DLL

• GangPro-ARM

  • GANGPROARM_API.cs - DLL Import definitions

  • GANGPROARM_DLL.cs - Definitions used by DLL

The source code is also available for the provided demo executables; if converting from the current Visual Studio 2005 project, to newer versions, sometimes incorrect conversions can break intended GUI dimensions.

1.7.5. Python Basic demo code sequence

Python Basic Demo Code Sequence

This example is found in API-DLL\FP-GP-ARM-Demo-Py in the installation directory.

• If running 64-bit Python (default installation), use the x64 ARM-win setup (X-ProARM-xvxx-Setup_x64)

• If running 32-bit Python, use the x86 ARM-win setup (X-ProARM-xvxx-Setup_x86)

• For Linux the default Python installation will work with the amd64 or armhf builds.

Any application using the library will call most of the following functions. First, any one adapter is found, and initialized. Assuming at least one adapter was found (F_OpenInstancesAndFPAs returns > 0), the config and code files are loaded to select the MCU and data to be programmed. Finally, the procedure F_AutoProgram will run the full programming sequence of Erase, Blank Check, Write, Verify, and optionally Lock the MCU.

import os
import sys
import ctypes

#FP-ARM - comment this out and uncomment GP-ARM to use demo for GangPro-ARM
if (sys.platform == "win32"):
    libname = "./FlashProARM-FPAsel.dll"
else:
    libname = "libmultifparm.so"
#GP-ARM - commented out - comment this out and uncomment FP-ARM to use demo for FlashPro-ARM
#if (sys.platform == "win32"):
#    libname = "./GangProARM-FPAsel.dll"
#else:
#    libname = "libmultigparm.so"

init_file = bytes('FPAs-setup.ini', 'utf-8')
if (sys.platform == "win32"):
    config_file_path = bytes('ConfigFiles\\EFR32BG12P433F1024.cfg', 'utf-8')
    code_file_path = bytes('CodeFiles\\SL-512k.txt', 'utf-8')
else:
    config_file_path = bytes('ConfigFiles/EFR32BG12P433F1024.cfg', 'utf-8')
    code_file_path = bytes('CodeFiles/SL-512k.txt', 'utf-8')

#Load library
lib = ctypes.cdll.LoadLibrary(libname)

# Get number of connected adapters
instances = lib.F_OpenInstancesAndFPAs(init_file)
print("Connected adapters: {}".format(instances))

# Init all adapters
result = lib.F_Set_FPA_index(0)
print("F_Set_FPA_index(0): {}".format(result))
result = lib.F_Initialization()
print("F_Initialization: {}".format(result))

# Get adapters serial numbers
serials = []
for instance in range(1, instances+1):
    serials.append(lib.F_Get_FPA_SN(instance))
print(serials)

result = lib.F_ConfigFileLoad(config_file_path)
print("F_ConfigFileLoad: {}".format(result))
result = lib.F_ReadCodeFile(code_file_path)
print("F_ReadCodeFile: {}".format(result))

# Select one adapter
result = lib.F_Set_FPA_index(1)
print("F_Set_FPA_index(1): {}".format(result))

# Verify Access (not required with Auto Program)
result = lib.F_Verify_Access_to_MCU()
print("F_Verify_Access_to_MCU: {}".format(result))

# Auto Program
result = lib.F_AutoProgram(0)
print("F_AutoProgram: {}".format(result))

# Print Auto Program text output (same as GUI)
# max length REPORT_MESSAGE_MAX_SIZE 2000
report_s   = ctypes.create_string_buffer(2000)
lib.F_ReportMessage(report_s)
s = report_s.value.decode()
print(s)

Running the aforementioned code snippet with Python 3.8.3 produces the following result:

1.8. Data and Control Flow

The Multi API-DLL (FlashProARM-FPAsel.dll, and GangProARM-FPAsel.dll) forwards calls coming from application software to individual API-DLL instances (FlashProARM-FPA1.dll to FlashProARM-FPA64.dll, and GangProARM-FPA1.dll to GangProARM-FPA64.dll respectively). A representation of the control and data flow is shown in Figure 1.8 and Figure 1.9. The desired destination FPA can be selected using the function F_Set_FPA_index( fpa ) where indices 1 to 64 select only one desired FPA. Select index 0 when ALL FPAs should be selected.

The selected FPA index modified by the F_Set_FPA_index( fpa ) function can be modified at any time. By default, the FPA index is 1 and if only one FPA is used then FPA index does not need to be modified. When FPA index 1 to 64 is used, then the result of any forwarded function call will be directly returned to application software from the single API-DLL instance being invoked transparently. When FPA index 0 is used (ALL-FPAs) and results are the same from all FPAs, then the same result is passed back to application software. If results are not the same, then the Multi API-DLL will return value FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF). To obtain individual results per API-DLL instance use the function F_LastStatus( FPA ). This function will read back the results of the previously called API-DLL function, which was stored internally in the Multi API-DLL's result buffer. This temporary result buffer will be overwritten on the next call to each API-DLL instance.