PEmicro CPROG32Z Flash Programming Software User Guide

PEmicro CPROG32Z Flash Programming Software

Product Information

The CPROG32Z is a programming software used to program microcontrollers. It requires a hardware interface to connect the PC and target MCU (microcontroller unit) via a debug ribbon cable. The programming software can be run from the Windows Command prompt or by calling the CPROG32Z executable with the correct command line parameters. The allowed command line parameters are:

• [?/!] – Use the ‘?’ or ‘!’ character option to cause the
  command-line programmer to wait and display the result of programming in the PROG32Z window.

• [filename] – A file containing programming commands and comments, default = prog.cfg.

• [/PARAMn=s] – A command-line parameter which can modify the executing script by replacing special tags (/PARAMn).

• [INTERFACE=x] – The hardware interface type (USBMULTILINK,
  PARALLEL, Ethernet IP address) used to connect the PC and target MCU.

• [PORT=y] – The port number or name used to connect the PC and target MCU.

• [showports] – Displays a list of connected hardware.

Product Usage Instructions

To use the CPROG32Z programming software, follow these steps:

1. Connect the hardware interface between your PC and the target MCU via the debug ribbon cable.
2. Start the programming software by running it from the Windows Command prompt or by calling the CPROG32Z executable with the correct command line parameters.
3. Use the allowed command line parameters to modify the executing script if necessary.
4. Select the hardware interface type and port number or name used to connect the PC and target MCU.
5. Program the microcontroller using the programming software.

Example command line parameters:

• CPROG32Z ?

• CPROG32Z [filename] /PARAMn=s INTERFACE=USBMULTILINK
  PORT=USB1

• CPROG32Z [filename] INTERFACE=CYCLONE PORT=10.0.1.223 NAME=”Joe’s Cyclone”

• CPROG32Z [filename] INTERFACE=USBMULTILINK PORT=PE5650030

• CPROG32Z [filename] INTERFACE=CYCLONE PORT=COM1

Introduction
CPROG32Z is a Windows command-line version of the PROG32Z software which programs Flash, EEPROM, EPROM, etc. through a PEmicro hardware interface to a supported NXP 683xx processor. The hardware interfaces are available from PEmicro. Once your interface hardware is properly connected between your PC and target device, you may launch the CPROG32Z executable from the command line. In addition to the executable, multiple command-line parameters must also be passed in order to configure which PEmicro hardware interface CPROG32Z should attempt to connect to, and to configure how that hardware interface will connect to the target device. These parameters include the name of the configuration (.CFG) file, as well as startup commands such as the name of the hardware interface or the port to which  the interface is connected. Introduction
CPROG32Z is a Windows command-line version of the PROG32Z software which
programs Flash, EEPROM, EPROM, etc. through a PEmicro hardware interface to a
supported NXP 683xx processor. The hardware interfaces are available from
PEmicro.
Once your interface hardware is properly connected between your PC and target device, you may launch the CPROG32Z executable from the command line. In addition to the executable, multiple command-line parameters must also be passed in order to configure which PEmicro hardware interface CPROG32Z should attempt to connect to, and to configure how that hardware interface will connect to the target device. These parameters include the name of the configuration (.CFG) file, as well as startup commands such as the name of the hardware interface or the port to which the interface is connected.

Startup

• Connect the hardware interface between your PC and the target MCU via the  debug ribbon cable.

• Start the programming software by running it from the Windows Command prompt or by calling the CPROG32Z executable with the correct command line parameters. Allowed command line parameters are:

  • CPROG32Z [?/!] [filename] [/PARAMn=s] [v] [reset_delay n] [bdm_speed n]
    [hideapp] [freq n] [Interface=x] [port=y] [showports] [nosync]
    [/logfile logfilename] where :

  • [?/!] Use the ‘?’ or’ ‘!’ character option to cause the command-line programmer to wait and display the result of programming in the PROG32Z window. ‘?’ will always display the result, ‘!’ will display the result only if an error occurred. If the user does not use a batch file to test error level, this provides a method to display the programming result. This option should be the FIRST command-line option.

  • [filename] A file containing programming commands and comments, default = prog.cfg. See Section 7 – Example Programming Script File for an example.

  • [/PARAMn=s] A command-line parameter which can modify the executing script by replacing special tags (/PARAMn). This can be used to replace any part of the script including programming commands, filenames, and parameters. Valid values of n are 0..9. s is a string which will replace any occurrence of /PARAMn in the script file. Section 8 – Using Command- Line Parameters in a Script has an example for usage.

  • [INTERFACE=x] Where x is one of the following: (See examples section)
    USBMULTILINK (This setting also supports OSBDM) PARALLEL (Parallel Port or BDM Lightning [Legacy])

  • [PORT=y] Where the value of y is one of the following (see the showports command-line parameter for a list of connected hardware; always specify the “interface” type as well):

  • USBx Where x = 1,2,3, or 4. Represents an enumeration number for each piece of hardware starting at 1. Useful if trying to connect to a Cyclone or Multilink product. If only one piece of hardware is connected, it will always enumerate as USB1.
    An example to select the first Multilink found is:  INTERFACE=USBMULTILINK PORT=USB1

  • #.#.#.# Ethernet IP address #.#.#.#. Each # symbol represents a decimal number between 0 and 255. Valid for Cyclone and Tracelink interfaces.
    Connection is via Ethernet.
    INTERFACE=CYCLONE PORT=10.0.1.223

  • NAME Some products, such as the Cyclone and Tracelink, support assigning a name to the unit, such as “Joe’s Max”. The Cyclone may be referred to by it’s assigned name. If there are any spaces in the name, the whole parameter should be enclosed in double quotes (this is a Windows requirement, not a PEmicro requirement).
    Examples : INTERFACE=CYCLONE PORT=MyCyclone99 INTERFACE=CYCLONE “PORT=Joe’s Cyclone”

  • UNIQUEID USB Multilink products all have a unique serial number assigned to them, such as PE5650030. The Multilink may be referred to this number.

  • This is useful in the case where multiple units are connected to the same PC.
    Examples: INTERFACE=USBMULTILINK PORT=PE5650030

  • COMx Where x = 1,2,3, or 4. Represents a COM port number. Valid for Cyclone interfaces. To connect to a Cyclone on COM1 : INTERFACE=CYCLONE PORT=COM1 x Where x = 1,2,3, or 4. Represents a parallel port number To select a parallel interface on Parallel Port #1 : INTERFACE=PARALLEL PORT=1

  • PCIx Where x = 1,2,3, or 4. Represents a BDM Lightning card number. (Note: this is a legacy product)
    To select a parallel cable on BDM Lightning #1 : INTERFACE=PARALLEL PORT=PCI1
    [showports] The command-line programmer outputs all available ports to a text file and then terminates (regardless of other commandline parameters). This information output to the text file includes the parameters needed to contact attached programming hardware as well as a description of the hardware interface. The default output filename is ports.txt and is created in the same folder as CPROG.
    The output can also be directed to a different file.
    Example : SHOWPORTS=C:\MYPORTS.TXT
    This list does not show parallel port or COM port options
    which are also available. Below is an example of the output
    for various hardware interfaces connected to the PC (Note
    that there are different ways to address the same unit; the
    data for each interface may be followed by a [DUPLICATE] line which shows a different label for the same interface).
    Showports Output Example:
    INTERFACE=USBMULTILINK PORT=PE5650030 ; USB1 : Multilink Universal FX Rev A (PE5650030)[PortNum=21] INTERFACE=USBMULTILINK PORT=USB1 ; USB1 : Multilink Universal FX Rev A (PE5650030)[PortNum=21][DUPLICATE]

  • [nosync] This prevents the programmer from verifying that the communications to the target is valid on startup. Verification involves reading and writing the D0 data register. This is useful for some newer versions of the 68F375 processor which may have a problem during this type of verification.

  • [v] Causes the programmer not to check the range of S-record addresses before programming or verifying. This speeds up the programming process. The option should be used with care as all out of range s-records will be ignored.

  • [reset_delay n] Specifies a delay after the programmer resets the target that we check to see if the part has properly gone into background debug mode. This is useful if the target has a reset driver which hold the MCU in reset after the programmer releases the reset line. The n value is a delay in milliseconds.

  • [bdm_speed n] This option allows the user to set the BDM shift clock speed of PEmicro’s debug interface. This integer value may be used|
    to determine the speed of communications according to the
    following equations:
    USB-ML-16/32 : (1000000/(N+1)) Hz – Legacy product
    USB Multilink Universal FX : (25000000/(N+1)) Hz
    BDM Lightning : (33000000/(2*N+5)) Hz – Legacy product The value n should be between 0 and 31. This shift clock takes effect after the commands in the top of the programming algorithm are executed so that these commands can increase the target frequency and allow a faster shift clock. This clock can’t generally exceed a div 4 of the processor bus frequency.

  • [hideapp] This will cause the command-line programmer to not display a visual presence while running with the exception of appearing on the taskbar. 32-bit applications only!

  • [freq n] By default, the PROG32Z software tries to determine automatically how fast the target is running by loading a delay routine in the processor and timing how long it takes to execute. On some machines, this may yield inconsistent results which may affect algorithms which program flash internal to an MCU. PEmicro provides a command-line mechanism allowing the user to inform the PROG32Z software exactly how fast the target processor is running. In this way, the timing in the algorithms will be precise. On the command-line, you specify the INTERNAL clock frequency in Hertz following the ‘FREQ’ identifier. Note that in general if you are using a flash device external to the MCU, this timing parameter is not needed as the flash handles the timing itself.

  • [/logfile logfilename] This option opens a logfile of the name “logfilename” which will cause any information which is written to the status window to also be written to this file. The “logfilename” should be a full path name such as
    c:\mydir\mysubdir\mylog.log.
    Command Line Examples:
    CPROG32Z C:\ENGINE.CFG INTERFACE=USBMULTILINK PORT=PE5650030
    Opens CPROG32Z with the following options:

  • – Run the C:\ENGINE.CFG script

  • – Interface is first USB Multilink Universal FX with serial number PE5650030

  • – Autodetect communications frequency (io_delay_cnt not set)

  • CPROG32Z C:\ENGINE.CFG Interface=USBMULTILINK Port=USB1
    Opens CPROG32Z with the following options: – Run the C:\ENGINE.CFG script – Interface is USB Multilink Universal FX, first interface detected.

Programming Commands
Programming commands all start with a two character sequence followed by white space (blanks or tabs). Lines starting with characters which are not commands are listed as REMarks. The term filename means a full DOS path to a file. Commands use the same two letter codes as used in the interactive programmers PROG32Z. The same .32P files used by PROG32Z are used to set up for a particular device to be programmed. If a user function is specified for a particular device, its two character command and the meaning or user_par are specified in the .32P file. Note: The command parameters starting_addr, ending_addr, base_addr, byte, word, and user_par use a default hexadecimal format.

• BM – Blank check module.
• BR starting_addr ending_addr
  • – Blank check range. CHANGEV n.nn –
  • (Cyclone only) Change the voltage provided to the target, where n.nn represents a value between 0.00 and 5.00, inclusive. When the command executes the Cyclone will immediately change to that voltage. If the Cyclone relays are off prior to calling this command, then the relays will turn on and set the new voltage value when this command is executed. Note that too low of a voltage value may put the device into low-power mode which can lose debug communication altogether. Make sure the Cyclone’s jumper settings are set correctly to send the power to the right ports.
• EB starting_addr ending_addr – Erase byte range.
• EW starting_addr ending_addr – Erase word range.
• EM – Erase module.
• PB starting_addr byte … byte – Program bytes.
• PW starting_addr word … word – Program words.
• PM – Program module.
• CM filename base_addr – Choose module .32P file. Note: Certain modules may require a base address to be specified.
• VM – Verify module.
• VR starting_addr ending_addr – Verify range.
• UM filename – Upload module.
• UR starting_addr ending_addr filename – Upload range.
• SS filename – Specify S record.
• SM starting_addr ending_addr – Show module.
• RELAYSOFF – (Multilnk FX & Cyclone only) Turn off the relays that provide power to the target, including a power down delay if specified. Especially useful for users who want to power cycle   their board before running tests, allow their bootloader to run, or have the application code run after programming.
• RELAYSON – (Multilnk FX & Cyclone only) Turn on the relays to provide power to the target, including a power up delay if specified. The voltage supplied will be based on the last voltage setting specified. For Cyclone users, the CHANGEV command can  change the voltage value. Especially useful for users who want to power cycle their board before running tests, allow their bootloader to run, or have the application code run after programming.
• HE – Help (look at cprog.doc file).
• QU – Quit.
• RE – Reset chip.
• GO – Starts device running. Can be used as final command if you want the device to run for testing. Should be immediately preceded by an ‘RE’ command.
• DE timeinms – Delays “timeinms” milliseconds
• xx user _par – Only for user function specified in .32P file.

Configuration Commands For Startup
Configuration commands are all processed before the programmer attempts to contact the target. The whole configuration file is parsed for these commands prior to attempting communications. This section gives an overview of using these configuration commands to do different type of configuration.
Note : The default base for configuration command parameters is decimal. An overview of the configuration commands is as follows:

• CUSTOMTRIMREF nnnnnnnn.nn
  Desired internal reference clock frequency for the “PT; Program Trim” command. This  frequency overrides the default internal reference clock frequency. Valid values for “n” depend on the particular device being programmed. Please refer to the electrical specifications of your device for valid internal reference frequency clock range.
  Where:
  nnnnnnnn.nn: Frequency in Hertz with two decimal places

• PROVIDEPOWER n
  Determines whether interface should provide power to the target. NOTE: Not all hardware interfaces support this command. Valid values of n are:

  • 0 : Interface does not provide power to target. (default)
  • 1 : Enable Interface provides power to target.
    ( NOTE : Is the same as legacy option :

• :USEPRORELAYS n)POWERDOWNDELAY n
  Amount of time to delay when the power to the target is turned off for the targets power supply to drop to below 0.1v. n is the time in milliseconds.

• : POWERUPDELAY n
  Amount of time to delay when the power to the target is turned on OR the target is reset, and before the software attempts to talk to the target. This time can be a combination of power on time and reset time (especially if a reset driver is used). n is the time in milliseconds.

• : POWEROFFONEXIT n
  Determines whether power provided to the target should be turned off when the CPROG32Z application terminates. NOTE: Not all hardware interfaces support this command. Valid values of n are:

  • 0 : Turn power off upon exit (default)
  • 1 : Keep power on upon exit

Verification Overview

There are several commands available that can be used to verify the contents of the flash on the device after programming it. The most widely used command is “VC
;Verify CRC of Object File to Module”. The “VC” command will instruct CPROG32Z to first calculate a 16-bit CRC value from the chosen object file. CPROG32Z will then load code into the RAM of the device and instruct the device to calculate a 16 bit CRC value from the contents in FLASH of the device. Only valid address ranges in the object file are calculated on the device. Once the 16-bit CRC value from the object file and the device are available, CPROG32Z compares them. An error is thrown if the two values do not match.
Alternatively, the “VM ;Verify Module” command can be used to perform a byte by byte verification between the chosen object file and the device. Typically, the VM command will take longer to perform than VC command since CPROG32Z has to read the contents of FLASH of the device byte by byte. There are also two other commands that can be used for verification. The “SC ;Show Module CRC” instructs CPROG32Z to load code into the RAM of the device and instruct the device to calculate a 16-bit CRC value from the contents of the entire FLASH of the device, which includes blank regions. Once the 16-bit CRC value has been calculated, CPROG32Z will display the value in the status window. The “VV ;Verify Module CRC to Value” command is similar to the “SC” command. The difference is that instead of displaying the calculated 16-bit CRC value, CPROG32Z will compare the calculated value against a 16-bit CRC value given by the user.

DOS Error Returns

DOS error returns are provided so they may be tested in .BAT files. The error codes used are:

• 0 – Program completed with no errors.
• 1 – Cancelled by user.
• 2 – Error reading S record file.
• 3 – Verify error.
• 4 – Verify cancelled by user.
• 5 – S record file is not selected.
• 6 – Starting address is not in module.
• 7 – Ending address is not in module or is less than starting address. 8 – Unable to open file for uploading.
• 9 – File write error during upload.
• 10 – Upload cancelled by user.
• 11 – Error opening .32P file.
• 12 – Error reading .32P file.
• 13 – Device did not initialize.
• 14 – Error loading .32P file.
• 15 – Error enabling module just selected.
• 16 – Specified S record file not found.
• 17 – Insufficient buffer space specified by .32P to hold a file S-record. 18 – Error during programming.
• 19 – Start address does not point into module.
• 20 – Error during last byte programming.
• 21 – Programming address no longer in module.
• 22 – Start address is not on an aligned word boundary.
• 23 – Error during last word programming.
• 24 – Module could not be erased.
• 25 – Module word not erased.
• 26 – Selected .32P file does not implement byte checking.
• 27 – Module byte not erased.
• 28 – Word erase starting address must be even.
• 29 – Word erase ending address must be even.
• 30 – User parameter is not in the range.
• 31 – Error during .32P specified function.
• 32 – Specified port is not available or error opening port.
• 33 – Command is inactive for this .32P file.
• 34 – Cannot enter background mode. Check connections.
• 35 – Not able to access processor. Try a software reset.
• 36 – Invalid .32P file.
• 37 – Not able to access processor RAM. Try a software reset.
• 38 – Initialization cancelled by user.
• 39 – Error converting hexadecimal command number.
• 40 – Configuration file not specified and file prog.cfg does not exist.
• 41 – .32P file does not exist.
• 42 – Error in io_delay number on command line.
• 43 – Invalid command line parameter.
• 44 – Error specifying decimal delay in milliseconds.
• 47 – Error in script file.
• 49 – Cable not detected
• 50 – S-Record file does not contain valid data.
• 51 – Checksum Verification failure – S-record data does not match MCU memory. 52 – Sorting must be enabled to verify flash checksum.
• 53 – S-Records not all in range of module. (see “v” command line parameter)
• 54 – Error detected in settings on command line for port/interface
• 60 – Error calculating device CRC value
• 61 – Error – Device CRC does not match value given
• 70 – Error – CPROG is already running
• 71 – Error – Must specify both the INTERFACE and PORT on the command line
• 72 – The selected target processor is not supported by the current hardware interface.

Example Programming Script File

The programming script file should be a pure ASCII file with one command per line. This is the CFG file in the previous examples.
An example is:

• CM C:\PEMICRO\333__48K.32P 0 EM: Erase the module
• BM: Blank Check the module
• SS C:\PEMICRO\TEST.S19: Specify the S19 to use
• PM: Program the module with the S19
• VM: ;Verify the module again

Note : The path names of files that are relative to the CPROG executable can also be used.

Using Command-Line Parameters in a Script

A command-line parameter in the form of /PARAMn=s can be used to insert text into the script file in place of special tags. This can be used to replace any part of the script including programming commands, filenames, and parameters. Valid values of n are 0..9. s is a string which will replace any occurrence of /PARAMn in the script file.
As an example, the following generic script could be used for programming with exactly the same functionality of the example script in Section 7 – Example Programming Script File:

CM /PARAM1 EM: CM /PARAM1 EM
BM: BM
SS /PARAM2 PM: SS /PARAM2 PM
/PARAM3 : /PARAM3

The following parameters would be added to the CPROG command line:
“/PARAM1=C:\PEMICRO\9B32_32K.32P 0″
/PARAM2=C:\PEMICRO\TEST.S19
/PARAM3=VM
NOTE : Since the /PARAM1 parameter has a space in its value, the entire parameter needs to be enclosed in double quotations. This indicates to Windows that it is a single parameter. In this instance, a base address of 0x0 is included on the Choose Module line in the script, therefore /PARAM1 must be specified on the command line like this:
“/PARAM1=C:\PEMICRO\9B32_32K.32P 0″
So the complete example command line would be (note that this is continuous; no line breaks):
C:\PEMICRO\CPROG32Z INTERFACE=USBMULTILINK PORT=PE5650030 BDM_SPEED 0 C:\PROJECT\GENERIC.CFG
“/PARAM1=C:\PEMICRO\333__48K.32P 0″ /PARAM/
param2=C:\PEMICRO\TEST.S19 /PARAM3=VM

Sample Batch File

Here is an example of calling the command-line programmer and testing its error code return in a simple batch file. Sample batch files are given for both Windows 95/98/XP and Windows 2000/NT/XP/Vista/7/8/10.
Windows NT/2000/Vista/7/8/10:
C:\PROJECT\CPROG32Z C:\PROJECT\ENGINE.CFG
INTERFACE=USBMULTILINK PORT=USB1
if errorlevel 1 goto bad
goto good
:bad
ECHO BAD BAD BAD BAD BAD BAD BAD BAD
:good
ECHO done

Windows 95/98/ME/XP:

START /W C:\PROJECT\CPROG32Z C:\PROJECT\ENGINE.CFG
INTERFACE=USBMULTILINK PORT=USB1
if errorlevel 1 goto bad
goto good
:bad
ECHO BAD BAD BAD BAD BAD BAD BAD BAD
:good
ECHO done
Note: The path names of files that are relative to the CPROG executable can also be used.

Information

For more information on CPROG32Z and PROG32Z please contact us:

• P&E Microcomputer Systems, Inc. 98 Galen St. Watertown, MA 02472-4502 USA
• VOICE : 617-923-0053
  FAX : 617-923-0808
  WEB : http://www.pemicro.com

To view our entire library of.32P modules, go to the Support page of PEmicro’s website at www.pemicro.com/support.

References

• PEmicro - 40+ years innovating in the embedded systems space. Flash Programmers, Cloud-based, Automated, Gang Programmers, and more...
• PEmicro | Experts in Embedded tools for Flash Programming and Development

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>