Users Guide and Command Reference for Xwisp2

Contents

• Introduction
• Supported Target PICmicros
• Command Overview
• Commandline Examples
• Environment Variable XWISP2
• Configuration Words
• Problem Determination
• Command Reference

Introduction

XWisp2 is a support program for the Wisp648 Picmicro programmer of VOTI (Wouter van Ooijen).

Xwisp2 was originally developed for IBM OS/2 and eComStation (the reincarnation of IBM OS/2 Warp) as alternative for the original Xwisp tool by Wouter. Reason of this was that an interface routine for the serial port was missing in the OS/2 version of Python. In a later stadium of Xwisp2 it was extended to other computer platforms, in particular for Linux, FreeBSD, MacOS, Windows (W98 and later). Thanks to the cross-platform Open Watcom C/C++ compiler the eComStation, Linux and Windows versions of Xwisp2 can all be built under eComStation.

The major differences between this Xwisp2 and the original Xwisp tool:

• Xwisp2 is a single autonomic executable, Xwisp requires Python
• Xwisp2 supports a (large) subset of the functions of XWisp
• Specifications of new PICs can be added by the user

The Xwisp2 packages contains executables for several platforms:

• xwisp2.exe - eComStation
• xwisp2u - Linux
• xwisp2w.exe - Windows
• xwisp2wf.exe - Windows (for USB-serial converter with FTDI chip and FTDI API).

Apart from some minor differences all flavours have the same functionality and when the name Xwisp2 is used in this document it applies to all of its variants.

Supported Target PICmicros

Currently about 160 PICmicros are supported, and from time to time new chips are added to this collection. So you might call it a moving target! The second screen of the HELP command shows a list of targets currently supported by Xwisp2.

The file xwisp2.cfg is the main configuration file where the programming parameters for the different PICmicros are defined. The actual specifications are in separate files, included by the main file. There are currently two of these configuration files:

• xwisp2_14.cfg for the 14-bits core (most 12Fxxx and 16Fxxx chips)
• xwisp2_16.cfg for the 16-bits core (18fxxxx chips)

Included in the XWisp2 packages is a utility xwlist (Linux: xwlistu, Windows: xwlistw), which will show a list of all parameters of all PICmicros in the configuration files, including unspecified defaults.

You may browse the configuration files, these are plain ASCII text files. The main file xwisp2.cfg contains information how the parameters have to be specified, so theoretically you could change parameters or even add new PICmicros yourself. But success requires thorough understanding of the "Programming Specifications" of the target, the working of the Wisp648 firmware and the way Xwisp2 and Wisp648 firmware co-operate. This applies especially to the selection of the Programming Algorithm.

Which PICmicros are actually supported by Xwisp2 depends also on the firmware level of the Wisp648 programmer. Not surprisingly the more recent the firmware the more targets are supported! Where possible and applicable Xwisp2 adapts its behaviour to the firmware level of the Wisp648 it has detected. When the combination of Xwisp2 and Wisp648 firmware level will probably not work together successfully for the actual target PICmicro, Xwisp2 will issue a warning message or possibly terminate.

Command Overview

Xwisp2 is a commandline program. Normally it is started from a commandline (terminal) session, but it might also be called by another program, script or batch file. The operations it has to perform are controlled by 'commands' which are specified as commandline arguments when starting Xwisp2.

Some Xwisp2 commands are stand-alone, others are accompanied by a keyword or a value. It is important to understand that:

• The commands are executed left to right in the sequence of specification on the commandline.
• Commands which are meant to modify behaviour of other commands (for example port to select the serial port) should be put in front of the commands to be influenced.
• Xwisp2 interrupts execution after the first command which didn't terminate successfully, or after an unrecognised command or invalid corresponding value or keyword. Subsequent commands will be ignored.

In this section the most common of the available commands are described briefly to make you familiar with the work with Xwisp2. The commands supported by Xwisp2 are described in detail in the Command Reference section.

Programming Operations

For transfer of data from a file to the target and vice versa a memory buffer is used. Primitive operations to transfer data to and from this buffer are:

• Load from file to buffer.
• Save from buffer to file.
• Put from buffer to target.
• Get from target to buffer.

Some other primitive operations are:

• Erase: bulk erase target device.
• Check: compare buffer against target.
• Run: exit programming state (reset/restart target device).

There are also several compound commands available which combine two or more primitive operations, such as:

• Write performs a Load file to buffer followed by a Put buffer to target.
• Read performs a Get target to buffer followed by a Save buffer to file.
• Verify performs a file to buffer followed by a Check buffer against target.
• Go performs an Erase of the target, a Write of the file to the target, a Check of buffer against target and finally a Run to restart the target device.

GO is probably the most widely used for normal programming, since it combines all the necessary operations to replace the old target contents with new and to start the execution of the new code.

Note: For all commands which need access to the target device the target is put in 'programming mode' (the /MCLR will be at approximately 12V). This mode can only be ended with a Run command or a power recycle. So in most cases your last command will be Run!

Some Additional Commands

Under certain circumstances or for specific purposes you may need additional commands, for example:
When you want to use another than the default serial port of your computer, you need the Port command to specify the alternative serial port.

• Port 2 selects COM2 (eComStation and Windows variants of Xwisp2), /dev/ttyS2 (Linux) or /dev/ttyd2 (FreeBSD).

• Port /dev/ttyUSB0 or a similar name.

• Port /dev/ttyUSB0 Baud 57600 will use a baudrate of 57.6 Kbps.

The speed of the Galva-Wisp programmer it limited to 19200 bps. Since XWisp2 switches by default to high speed when it detects a Wisp648 programmer with recent firmware version (at least 1.28), it is needed to specify for this programmer:

• Baud 19200 to set the Baudrate to 19.2 Kbps.

For problem determination you might want to use:

• Verbose to see more progress messages.
• Log zzz to obtain a log of the programming activity in file zzz.log.

Consult the Command Reference section for details of these commands and a couple of other yet unmentioned commands.

Commandline Examples

Don't be intimidated by the many commands. For most users the go command, maybe preceded with port 2, will be the only command ever needed.

xwisp2 go blink877

This command line erases the target, loads the file blink877.hex into the memory buffer, writes the buffer to the target, checks if the programming was successful and starts the target (if all goes well!).
This command line assumes that the first serial port is used (COM1, /dev/ttyS0 or /dev/ttyd0), and that the device ID of the target PICmicro can be autodetected (which will be the case for all flash PICmicros except the obsolete 16C84 and 16F84).
The 'go' command may be omitted when a file specification is the only commandline argument and the filespec is not a recognised command, so the command xwisp2 blink877 will work evenly well.

xwisp2 port 2 go blink877

When you don't use the default serial port you must specify the actual serial port to be used in front of any other port-specific commands. In this case serial port COM2 is selected (with eComStation or Windows) or /dev/ttyS2 (with Linux) or /dev/ttyd2 (with FreeBSD).
You may equally well specify 'port Com2' or 'port /dev/ttyS2' or any other name of a serial port known to your system.
Note: The 'go' command cannot be omitted in this case!

xwisp2 baud 19200 rts on go blink877

With the Galva-Wisp programmer the baudrate and RTS settings must be specified as indicated, and in front of other commands which require access to the programmer like 'go' in this case.

Environment Variable XWISP2

The environment variable XWISP2 may specify a series of commands like otherwise specified on the commandline. The commands in the environment string will be executed ahead of the commands on the commandline. This may be useful to specify your preferred default runtime environment like the serial port, baudrate or other settings, you won't have to repeat these commands all the time.
Example of an environment variable specification with eComStation or Windows:

  set XWISP2=port 2 baudrate 19200 rts on

Do not specify spaces between 'XWISP2' and the '=' character!

Similarly with Linux:

  export XWISP2="port 2 baudrate 19200 rts on"

Be sure to specify 'XWISP2' in upper case!

Configuration Words

Microchip recommmends in almost every datasheet that the hex file should contain the configuration word(s). Unfortunately not all users, compilers and assemblers follow the rules. Omitting configuration settings from the hex file may cause trouble with programming PICmicros because the defaults may not be as you think they are: datasheet specifications may differ from reality, revisions may have different defaults, etc.

Programming devices and supporting software like Xwisp2 have there own vision about defaults for non-specified configuration words! Xwisp2 uses as default the value of the FuseFixedZero parameter in xwisp_14.cfg or xwisp2_16.cfg.

Never trust defaults, and make sure your hex files always contain the complete configuration settings! Obeying this recommendation may save you quite some valuable time for the analysis of unexpected behaviour of your target caused by wrong assumptions about defaults.

Problem Determination

Xwisp2 produces progress messages and maybe warning or error messages. These messages should be self explanatory. The most common returncodes (rc) are:

In most cases errors are caused by an improper connection, either between the computer running Xwisp2 and the Wisp648 programmer, or between the Wisp648 programmer and the target board.

A timeout or serial line status error indicates that Xwisp2 did not receive a proper response from the Wisp648 programmer. The most likely cause is a communication problem:

• wrong serial port used
• serial port in use by another (terminal) program
• serial cable not connected
• bad connectors
• cable too long
• no power

When no programmer (or other data-echoing device!) is connected to the used port, or you have selected the wrong port, xwisp2w for Windows seems to 'hang' and may have to be terminated with 'Ctrl-C' or 'Ctrl-Break'.

A read, write or Wbus command error indicates that the target may have responded but not in a way Xwisp2 expected. This can be caused for instance by a bad connection between the programmer and the target circuit. It may also be a result of a wrong target circuit configuration. Examples of such faults are:

• pullup resistor of /MCLR of the target to Vdd is less than 33K or missing
• PGC (ICSPCLK) or PGD (ICSPDAT) pins are too heavily loaded (e.g. with a LED)
• /MCLR, PGC or PGD pins are wrongly wired to the Wisp648 programmer connector (or not at all)
• target power is insufficient: voltage to low (must be 5V) or has not enough capacity (target circuit must power the Wisp648 too!)

When experiencing programming problems the first thing to do is adding the commands verbose and log file as the first arguments to your commandline (after the Xwisp2 command itself of course). These commands will cause Xwisp2 to produce more detailed progress reports and a log of activity between Wisp648 and the target.

Note: Xwisp2 will issue a warning message when it detects a target which cannot be handled properly by the actual firmware level of the Wisp648 programmer. Nevertheless Xwisp2 proceeds, but will fail most likely to transfer the program to the target. This behaviour won't harm your target, except that it may be erased and/or programmed only partially.

Command Reference

Xwisp2 supports a large subset of the commands of the original Xwisp and Wisp. Some 'old' commands are not supported by Xwisp2, some may have a slightly different result. The commands supported by Xwisp2 (and only those) are documented below.

Commands and parameters are case independent, except for file names when used on a case sensitive file system like Linux.

Command parameters are never optional. When a command requires a value or keyword, this must be specified with the command even when the default is desired. So better omit the command when the default value is desired! But it maybe useful when calling Xwisp2 from a script or another program!

Notation of command parameters:

• Keyword parameters are described in uppercase, but may be specified on the commandline in lower case or mixed case.
• A value is described as a word between brackets < and >, but should be specified on the commandline without the brackets.
• A choice of one out of several parameters is indicated with square brackets: [ and ].

BAUD   <value>

The Baud command sets the baudrate of the serial port to the specified (decimal) value.
Xwisp2 and Wisp648 always start communications at 19200 bps. Baudrate will be increased automatically to 115200 during programming. In some cases this is not desired and a lower baudrate should be used. Some examples:

• When you use a USB-serial converter between PC and Wisp648 and you experience communications errors a lower baud may help. A value of 57600 will do in most cases.
• When you use the Galva-Wisp programmer a value of 19200 is required.

BEEP

The Beep command causes Xwisp2 to give an audible indication of success or failure - using the PC's speaker - when the program terminates. A series of beeps with rising frequency means successful completion, a series of beeps with lowering frequency means unsuccessful completion. By default Xwisp2 executes silently.
Note: The Linux version of Xwisp2 doesn't beep!

CHECK

The Check command compares the contents of the buffer with the contents of the target. Locations which are supposed to be erased (code: 0x03FFF/0xFFFF, data: 0xFF) in the buffer are not compared with the contents of the target, unless the Full command precedes the check command. In that case all of memory is checked. Check terminates at the first non-matching location.
See also the Verify command.

DELAY   <value>

With the Delay command you can specify the programming delay to be used by Wisp648 (the Tprog value in the Microchip Programming Specifications). The value is expressed in units of 0.1 milliseconds, for example a value '100' represents 10 milliseconds delay.
Normally you won't need to use Delay, the default will be OK. The Xwisp2_xx.cfg file may contain an alternative (usually lower) value, which might be too aggressive for your specific target. In that case you may try to slow down programming with a larger Delay value.

DTR   [ ON | OFF ]

The DTR command sets the DTR signal of the serial port high (ON) or low (OFF). Normally Xwisp2 starts up with DTR low, flips it briefly to high at startup, and keeps it low during the rest of programming. With the DTR command you may control the DTR signal as you like. The DTR command should be used after port selection.
DTR will be low after Xwisp2 terminated, except when finishing in passthrough mode.

DUMP

The Dump command shows the content of the image on your screen in hexadecimal notation. The screen output may be redirected to a file, but in that case the Save command might be more appropriate.

DUPLEX   [ HALF | FULL ]

The Duplex command selects the mode in which Xwisp2 communicates with the Wisp648 programmer. With FULL (default) both ends may send at the same time, with HALF only one end may send at a time.
You may need this command only with low quality connections (long wires) between PC and Wisp648. It would be better to improve the connection!

ERASE

The Erase command completely (bulk-)erases the target (code-, data- and configuration memory). This will also remove the code and data protection. After Erase the all of memory will contain the 'erased' value (code: 0x03FFF/0xFFFF, data: 0xFF).

FORCE   <device>

The Force command overrides the auto-detected target device with the specified target device.
See also the Target command.

FULL

When the Full command is specified in combination with a Check command or a compound command containing a Check operation will ensure that all of memory is verified, including locations which are not in the hex file. These locations are assumed to contain the 'erased' value (code: 0x03FFF/0xFFFF, data: 0xFF).

FUSES   [ FILE | IGNORE | <value> ]

With the Fuses command you can modify the fuses word as follows:

• FILE: use the settings in the hex file
• IGNORE: skip fuses
• Use <value> (4 hexadecimal digits) as fuses contents. This variant is applicable only to 14-bits PICmicros and only for the first word of configuration memory.

Note:Protect can be used to modify the protection bits of configuration memory in a target-dependent way. Modifications are carried out in the order (1) fuses, (2) protection.

GET

The Get command reads the content of the target into the buffer.

GO   <file>

The Go command combines the erase, write, check and run commands: the target is erased, the indicated <file> is written and verified, and the target is put in run mode.

HELP

The Help command shows a number of help screens:

1. A brief command reference summary
2. A list of supported PICmicro targets
3. Some commandline examples

Aliases of the HELP command are '?', '-?' and '/?'. The help screens are also shown when Xwisp2 is called without parameters.

LOAD   <file>

The Load command reads the hex file <file> and puts its contents into the buffer.

LOG   <file>

With the Log command details of the programming activity is written to the file <file>. This command maybe useful for problem determination.

PASS   [ B67T | B67I | AUXT | AUXI ]

The Pass command puts the target in run mode and enables serial line passthrough. This is useful when another terminal program will be used to communicate with the target without the need to remove the Wisp648 programmer.
The mode argument determines for the Wisp648 programmer how the programmer passes the serial line to the target:

• B6T target pin PGC (frequently B6) is the targets serial input, target pin PGD (frequently B7) its serial output. The polarity is the same as on an RS232/V.24 line (as if the target uses a non-inverting interface).
• B6I PGC (B6) is serial input, PGD (B7) serial output. The polarity is the the inverse of a RS232/V.24 line (as if the target uses an inverting interface like a MAX232).
• AUXT the programmers auxiliary lines are used, using true polarity (see note 2).
• AUXI the programmers auxiliary lines are used, using inverted polarity (see note 2).

Notes:

1. The auxiliary lines are wires 7 an 8 of the connection between Wisp648 and target (wire 7 for data from Wisp648 to target, wire 8 for data from target to Wisp648). These wires should be connected to the corresponding pins of the target (wire 7 to the RX-pin, wire 8 to the TX pin), and of course your program in the target should be prepared to communicate!

PAUSE   <message>

The Pause command prints the <message> and waits for the user to press the <Enter> or <Return> key. The <message> may be a single word (no embedded blanks), or it may be multiple words enclosed in double quotes, for example:

        pause "Please wait at least 5 seconds!"
      

Your message will automatically be followed on the next line by

        >>>Press 'Enter' to continue:
      

Notes:

1. Xwisp2 will issue a Pause by itself before terminating when it encountered an error condition.
2. You may consider to specify a Pause at the end of your commandline to see the final results, especially when you call Xwisp2 from another program, script or batch file.

PORT   <port>

With the Port command you can specify a number or name for the serial port to be used by subsequent commands.
When specified as a number the default name will be modified. For example: when specified as '2' the port name will become COM2 with eComStation and Windows, /dev/ttyS2 with Linux, or /dev/ttyd2 with FreeBSD.
For xwisp2wf (with FTDI API) the port number represents the index number of the USB serial converter to be used, default: 0. Xwisp2wf currently supports a range 0..3 for the index value.

When not specified as a number it will be used as port name, replacing completely the default name. This is not a valid specification for xwisp2wf.
Note: Xwisp2wf determines the device name by reading the USB device description string.

PROTECT   [ ON | OFF | FILE ]

With the Protect command the code and data protection can be set ON (all protection bits reset to 0), OFF (all protection bits set to 1) or taken from the hex file (default).
With ON and OFF all of the Code Protection and Data Protection (for the 16-bits family also the Boot Block Protection bits) are set or reset. The protection bitmask is specified in the Xwisp2 configuration file.
Note: The block write protection bits and table read protection bits of the targets of the 16-bits family are not touched!
See also the Fuses command.

PUT

The Put command writes the buffer content to the target. Only those locations which do not contain the 'erased' value will be written (code: 0x03FFF/0xFFFF, data: 0xFF).

QUIET

The Quiet command suppresses all console output (to the screen). This includes requests for user-interaction ("Press 'Enter' to continue") which means the program proceeds without waiting. There is no command to undo this action, once processed the program proceeds silently till the end.

READ   <file>

The Read command reads the contents of target memory into the memory buffer and writes it to the <file> in Intel hex format. The hex file will contain only entries for those locations which do not contain the 'erased' value (code: 0x3FFF/0xFFFF, data: 0xFF).

RTS   [ ON | OFF ]

The RTS command sets RTS high (ON) or low (OFF). Normally Xwisp2 starts with RTS high and keeps it high during programming. With the RTS command you may control the RTS signal as you like.
The RTS command should be used after port selection.
RTS will be low after Xwisp2 has terminated, except when finishing in passthrough mode.

RUN

The Run command resets the target and puts it in run mode (removes the high programming voltage from /MCLR).

SAVE   <file>

The Save command writes the contents of the buffer to <file>. The file (in Intel hex notation) will contain only entries for those locations which are not in the erased state (code: 0x3FFF/0xFFFF, data: 0xFF).
See also the Dump command.

SELECT   <arg>

The Select command determines which part(s) of the buffer (code, data, ID-bytes, fuses) are to be included or excluded.
The <arg> has the format [+|-][C][D][F][I] and is interpreted left to right character-by-character.
The characters '+' and '-' determine the action (include or exclude), the letters determine the memory region to which the action applies. A '+'-character (default) resets the selection to 'none' and switches the action to 'include', a '-'-character resets the selection to 'all' and switches the action to 'exclude'. When a '+' or '-' appears in the middle of the <arg>string the previous selection will be undone.
One or more of the characters 'C', 'D', 'F' and 'I' determine the action to the Code, Data, Fuses or ID-memory.
Some examples:

        select +cd
      

Includes code (program) and data (EEPROM) memory regions, excludes ID and Fuses memory regions.

        select -fi
      

Excludes fuses and ID memory regions, includes program and data memory regions (thus this example has the same effect as +cd).

TARGET   [ AUTO | <device> | ? ]

With the Target command you can specify the name or alias to identify the target PICmicro.
Most PICmicro devices with flash memory, except the obsolete 16C84 and 16F84, have a device ID word which can be read to identify the target chip (even when the chip is read protected). With the specification of a '?' character you can query the actual target without starting any programming operation.
Before any programming operation Xwisp2 will always try to indentify the actual target PICmicro type. Depending on the conditions Xwisp2 will act as follows:

• When the Target command is not used or specified with AUTO and the target device ID is recognised (is listed in one of the xwisp2_xx.cfg files) Xwisp2 will proceed normally and use the properties of the detected chip.
• When the Target command is not used or specified with AUTO and the target device ID is not recognised Xwisp2 will display an error message and terminate.
• When the Target specifies a PICmicro which conflicts with the detected target Xwisp2 will display a warning message and will proceed with the properties of the detected target (as if AUTO was specified).
  Use the Force command when you insist on using the properties of the specified target.

In normal practice the Target command is only required when programming a PIC16C84 or PIC16F84.

TIME

The Time command will show the current system time.

UNATTENDED

The Unattended command suppresses user-interaction ("Press 'Enter' to continue") which means the program proceeds without showing this message and without waiting for the user interaction.

VERBOSE

The Verbose command causes the program to display more progress messages of the operation to the screen. This command can be useful when experiencing programming failures.

VERIFY   <file>

The Verify command compares the contents of the target with the contents of the specified <file>. Locations which are not specified in the <file> are not compared unless the Full command precedes the verify command, in which case all of memory is verified. Locations in the target which are not specified in the hex file are assumed to contain the 'erased' value (code: 0x03FFF/0xFFFF, data: 0xFF). Verify terminates at the first non matching location.
See also the Check command.

WAIT   <milliseconds>

The Wait command waits (at least) the specified number of milliseconds.

WRITE   <file>

The Write command transfers the indicated <file> to the target. Locations of the target which are not specified in the hex file are left unchanged.