© Copyright 2006..2010 by Rob Hamerling
This document is partially based on the Wisp documentation
by Wouter van Ooijen, used with his permission.
XWisp2 is a support program for the
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
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
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.
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.
- 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
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
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.
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.
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.
With a USB serial converter under Linux you may have to specify:
- Port 2 selects COM2 (eComStation and Windows variants of
Xwisp2), /dev/ttyS2 (Linux) or /dev/ttyd2 (FreeBSD).
- Port /dev/ttyUSB0 or a similar name.
When you experience errors with your USB to serial converter, you might
try a lower baudrate than the default of 115200:
- Port /dev/ttyUSB0 Baud 57600 will use a baudrate of 57.6 Kbps.
The speed of the
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:
- 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
Consult the Command Reference section for details of
these commands and a couple of other yet unmentioned commands.
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
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.
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
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!
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
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
Xwisp2 produces progress messages and maybe warning or error messages.
These messages should be self explanatory.
The most common returncodes (rc) are:
| 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:
- 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
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
- PGC (ICSPCLK) or PGD (ICSPDAT) pins are too heavily loaded
(e.g. with a LED)
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
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.
Xwisp2 supports a large subset of the commands of the original Xwisp and
Some 'old' commands are not supported by Xwisp2, some may have a slightly
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
In some cases this is not desired and a lower baudrate should be used.
- 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
programmer a value of 19200 is required.
- The Beep command causes Xwisp2 to give an audible indication of
success or failure - using the PC's speaker - when the program
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!
- 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
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
- DTR [ ON | OFF ]
- The DTR command sets the DTR signal of the serial port high (ON) or
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.
- The Dump command shows the content of the image on your screen in
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!
- 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.
- 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.
- 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.
- 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
- The Help command shows a number of help screens:
Aliases of the HELP command are '?', '-?' and '/?'.
The help screens are also shown when Xwisp2 is called without parameters.
- A brief command reference summary
- A list of supported PICmicro targets
- Some commandline examples
- 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
This is useful when another terminal program will be used to
communicate with the target without the need to remove the Wisp648
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).
- 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
- 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:
- Xwisp2 will issue a Pause by itself before terminating when it
encountered an error condition.
- 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
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.
- 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).
- 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
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.
- 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
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.
Includes code (program) and data (EEPROM) memory regions, excludes
ID and Fuses memory regions.
Excludes fuses and ID memory regions, includes program and data memory
(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.
- 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
Use the Force command when you insist on
using the properties of the specified target.
- The Time command will show the current system time.
- 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.
- 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
- 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