Users Guide and Command Reference for Xwisp2

© Copyright 2006..2010 by Rob Hamerling

Released under the FREEBSD license

This document is partially based on the Wisp documentation by Wouter van Ooijen, used with his permission.


Contents


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:

The Xwisp2 packages contains executables for several platforms:

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:

A third configuration file (xwisp2_12.cfg) is also available, but the 12-bit core chips are not yet supported by Xwisp2.

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:

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:

Some other primitive operations are:

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

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.

With a USB serial converter under Linux you may have to specify:
When you experience errors with your USB to serial converter, you might try a lower baudrate than the default of 115200:

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:

Note: From version 1.9.4 XWisp2 sets by default RTS=ON at startup. With older versions of XWisp2 it was needed to specify also:

For problem determination you might want to use:

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:

rc Description
8 Not enough memory for buffer(s).
10 Detected target deviceID does not exist in configuration files.
20 Target could not be identified.
21 Communications error with programmer.
23 Unable to communicate with programmer.
36 Invalid data value in hex file, or data from target.

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:

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:

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:

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:
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: 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:

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: 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.