WISP tool : DOS command line interface
for WISP and WLoader

introduction and downloads

targets

When used with the WISP programmer this tool supports all target chips supported by the WISP programmer.

When used with the Wisp628 programmer this tool supports the following target chips:

12F629, 12F675

16F630, 16F676

16C84, 16F84, 16F84A

16F627, 16F628

16F73, 16F74, 16F76, 16F77

16F870, 16F871, 16F872, 16F873, 16F874, 16F876, 16F877

commands

The commands that can be used on the wisp command line are shown. Each command is executed in sequence, so commands that affect (modify) behaviour of other commands (like port, which selects the serial port to be used) must be put before the affected commands. Commands and parameters are not case-sensitive, except for file names (when used on a case sensitive file system).

Three commands present the user with a primitive terminal interface.

Talk activates the connected hardware (WISP, Wisp628 or WLoader) and lets the user interact with it.

TTY puts the connected hardware in passthrough mode so the user can interact with the target PICmicro, or when WLoader is used, with the application program

Term just interfaces the user to the serial line, without activating the connected hardware. This command can be used with any connected device, not just WISP, Wisp628 or WLoader.

For transfer of data from a file to the target and vice versa a memory buffer is used. The primitive commands transfer data to and from this buffer:

load from file to buffer and save from buffer to file;

put from buffer to target and get from target to buffer

Verify verifies the target against the buffer.

Write and read are compound commands: write does a load (file to buffer) and a put (buffer to target), read does a get (target to buffer) and a save (buffer to file). Most users will prefer the go command, which erases the target, writes a file to it, and puts it in run mode.

Three commands can be used to arrange for the contents of the memory buffer to be modified before it is used: patch, fuses and protection. Patch can be used to modify any location(s), fuses can be used to modify the fuses word as a whole, protection modifies parts of the fuses word in a target-dependent way. The modifications are carried out in this order: patch, fuses, protection. Note that patch commands add up, unless a path off clears the list of patches.

The target command can be used to specify the type of the target chip. Recent PICmicro chip types have a device ID word, which can be read to indentify the chip type. The older 16c84 and 16f84 chips do not contain such an ID word. When no target command is used the program will try to determine the target from the ID word of the chip. When no recogniseable ID word can be read an error message is produced. When a target chip is specified the program will also read the ID word, and produce an error message when it does not match the specified type.

The program can produce a large number of error messages. A timeout or serial line status error indicates that it did not receive a proper response from the device. The most likely cause is a communication problem ( wrong serial port used, no direct hardware access available, serial cable not connected, bad connectors, cable too long, too many devices on the line) or a problem with the device (no power, 16f877 running the application instead of WLoader, multiple devices connected and no ID specified, a firmware error). An echo error indicates that the target did respond but noty the way the tool expected. This can for instance be caused by a bad connection between the programmer and the target chip.

Note that with WLoader, the target must be reset (with the serial line connected) before it responds to the wisp tool. An automatic remote reset is supported by bringing the DTR line high (inactive) for 100 ms, and waiting 100 ms before the first communication with the device is started. The target circuit could use the DTR line to reset the target using a single transistor and a few resistors.

For each command the hardware line specifies the hardware (Wisp628, WISP, WLoader) the command can be used with.

All value parameters are by default decimal. Prefix a dollar character for a hexadecimal value.

command		BEEP
hardware		no hardware required
	This command causes the program to give an audible indication of success or failure (using the PC's speaker) when the program terminates.

command		BURN x
hardware		WISP, WLoader
	This command writes the ID x to the connected device. The WISP programmer stores the ID in its EEPROM, the WLoader firmware stores it inside its own code section.

command		CALIBRATE
hardware		WISP
	This command is used to calibrate the VCC settings of a WISP programmer. A voltmeter is required. This has to be done once, the calibration data is stored in the EEPROM in the WISP's 16x84.

command		CHECK
hardware		Wisp628, WISP, WLoader
	This command verifies whether an image has been written correctly by reading it back from the target and comparing it to the image.

command		DUMP
hardware		Wisp628, WISP, WLoader
	This command dumps (to the screen) the content of the image.

command		ERASE
hardware		Wisp628, WISP, WLoader
	This command erases the target (code, data and configuration). This command removes the code and data protection from flash PICs. The WLoader firmware ignores this command because it can neither set the code protection, nor erase it.

command		FLUSH
hardware		no hardware required
	In combination with LOG this command flushes the log file after every write. This slows the process down even more than just LOG, but can be usefull for debugging.

command		FUSES value
hardware		no hardware required
	This command specifies that in a subsequent command that uses the buffer content the configuration fuses value will be   value = FILE : used as is   value = IGNORE : skipped   otherwise : the specified value. WLoader can not write to the configuration word, but it does check that the loaded configuration word matches the actual configuration word.

command		GET
hardware		Wisp628, WISP, WLoader
	This command reads the content of the target into the buffer.

command		GO file
hardware		Wisp628, WISP, WLoader
	This 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.

command		HEX
hardware		no hardware required
	This command causes a subsequent talk, term or tty command to show, after each received character, the hexadecimal value of the character in square brackets.

command		ID value
hardware		no hardware required
	This command specifies the device ID value used when the connected hardware is activated. The default is 0000, which is the catch-all ID to which a device will always respond. This command must be used when multiple devices are connected to one serial port. In that case each device must be programmed with a different ID (burn command), and the appropritate ID must be used to activate one device.

command		LAZY
hardware		no hardware required
	This command switches to lazy writing: the device will first read a location's content and writes it only when the content differs from the new value. This can speed up writing. The default is normal (write always) writing.

command		LOAD file
hardware		no hardware required
	This command reads the hex file file and puts its content in the buffer.

command		LOG file
hardware		no hardware required
	Log every activity to file file. This slows then procedess down considerably. This command is usefull for debugging.

command		NOPRESERVE
hardware		Wisp628
	By default the erase, put, go etc. commands preseve the oscillator calibration and bandgap values, for the chips for which this is appropriate. This command allows you to override these values (using the patch command).

command		PASS mode
hardware		Wisp628, WISP, WLoader
	This command puts the target in run mode and enables serial line passthrough. This is usefull when another terminal program will be used to talk to the target. The TTY command might is more convenient because it enables build-in TTY emulation. Refer to the TTY command for an explnation of the mode parameter. Note that the mode parameter is mandatory.

command		PATCH arg
hardware		no hardware required
	This command either clears that patch lits (arg=OFF) or adds a patch to the patchlist (arg=A=D, where A=address and D=data). The patchlist is applied to (a copy of) the buffer before it is used. Note that in a hex file (or in the buffer) the eeprom data is at $2100.

command		PAUSE message
hardware		no hardware required
	This command prints the message (which must be one word!) and waits for the user to press .

command		PORT port
hardware		no hardware required
	This command specifies the serial port that is used by subsequent commands. The recognised ports are [COM][1|2|3|4]. The default is COM1. For convenience COM1 ... COM4 are also recognised as commands.

command		PORT baudrate
hardware		no hardware required
	This command specifies the baudrate to be used to talk to the hardware. The default is 19200 baud. When a baudrate < 10 is specified it will be interpreted as a serial port.

command		PROTECT protection
hardware		no hardware required
	setting = [ ON | OFF | FILE ] This command determines the code protection in the configuration word, which can be set to always ON, always OFF or left unmodified (default). WLoader can not write to the configuration word, but it does check that the loaded configuration word matches the actual configuration word.

command		PUT
hardware		Wisp628, WISP, WLoader
	This command writes the buffer content to the target. Only those locations which do not contain the 'erased' value (code 0x3FF, data 0xFF) are written.

command		READ file
hardware		Wisp628, WISP, WLoader
	This command gets the target's contents and puts this data in the indicated hex-file. The hex file will contain only entries for those locations which are not in the erased state (code 0x3FF, data 0xFF).

command		RUN
hardware		Wisp628, WISP, WLoader
	This command resets the target and put it in run mode. When the target is WLoader the application program is started (resetting the target would just re-activate WLoader).

command		SAVE file
hardware		no hardware required
	This command saves the buffer to the file file. gets the target's contents and puts this data in the indicated hex-file. The hex file will contain only entries for those locations which are not in the erased state (code 0x3FF, data 0xFF).

command		SELECT arg
hardware		no hardware required
	This command determines which parts of the buffer (code, data, fuses) are used and which are ignored. The arg is interpreted letter by letter. A '+' (default) switches the action to 'select', a '-' switches to 'ignore'. A letter 'C", 'D' or 'F' applies the action to the Code, Data or Fuses part.

command		TALK
hardware		Wisp628, WISP, WLoader
	This command lets you talk to the device: it emulates a simple TTY interface, allowing you to enter characters to be sent to the device and see the response. Note that this command lets you talk to the device (Wisp628, WISP, or WLoader firmware) after it has been activated. To interface to the serial line (without activating the device) use term, to interface to the target (or WLoader application) use tty.

command		TARGET target
hardware		no hardware required
	target = [ auto | 16c84 | 16f84 | 16f84a | 16f627 | 16f628 | 16f73 | 16f74 | 16f76 | 16f77 | 16f870 | 16f871 | 16f872 | 16f873 | 16f874 | 16f876 | 16f877 ] This command specifies the target device. The default is auto. The '16' prefix can be omitted.

command		TERM baudrate
hardware		no hardware required
	This command lets you talk to the serial line: it emulates a simple TTY interface, allowing you to enter characters to be sent on the line and see any response received. The baudrate must be an integer or contain a single k to indicate the thousands (300 .. 19200, or k3 .. 19k2). Note that this command lets you talk to raw serial line. To interface to the device (after it has been activated) use talk, to interface to the target (or WLoader application) use tty.

command		TEST
hardware		Wisp628, WISP, WLoader
	This command tests the target's programmability with 6 different patterns.

command		TIME
hardware		no hardware required
	This command shows the current system time.

command		TTY mode baudrate
hardware		Wisp628, WISP, WLoader
	This command lets you interface to the target PICmicro or, when using WLoader, to the application program: it emulates a simple TTY interface, allowing you to enter characters to be sent to the target and see any response received. The baudrate must be an integer or contain a single k to indicate the thousands (300 .. 19200, or k3 .. 19k2). This command is usefull for debugging your application program, without the need to leave your PC. Note that this command lets you interface to the target PICmicro. To interface to the raw serial line use term. To interface to the device (after it has been activated) use talk. The mode argument is optional. For a Wisp628 programmer it determines how the programmer passes the serial line to the target:   mode = B67T (default) target pin B6 is the targets serial input, pin B7 is its output, the polarity is the same as on an RS232/V.24 line (as if the target uses a non-inverting interface)   mode = B67I B6 is input, B7 is its output, the polarity is the the inverse of a RS232/V.24 line (as if the target uses an inverting interface, like a MAX232)   mode = AUXT the programmers auxillary lines are used, using true polarity   mode = AUXI the programmers auxillary lines are used, using inverted polarity

command		VCC low high
hardware		WISP
	This command sets the voltages at which verification will be done by a verify, check or go commands. By default verification is done only at 5.0 Volt (prototype mode). This command is usefull only when a WISP programmer is used and it has been calibrated and supplies the VCC to the target.

command		VERBOSE
hardware		no hardware required
	This command causes the program to log every operation to the screen. This makes the programming process terribly slow, but it can be usefull to track communication problems.

command		VERIFY
hardware		Wisp628, WISP, WLoader
	This command verifies that the contents of the target corresponds to the indicated file. Locations which are not specified in the file are not verified.

command		WAIT milliseconds
hardware		no hardware required
	This command waits (at least) the indicated number of milliseconds. Interference from the host system's OS might cause a longer delay that the amount indicated.

command		WRITE file
hardware		Wisp628, WISP, WLoader
	This command writes the indicated file to the target. Locations which are not specified in the hex file are left in the original state.

examples

There are an awfull lot of commands, but don't be intimidated. For most users the go command, maybe prefixed with com2, will be the only command(s) they will ever need.

wisp go blink877
	This command line erases the target, writes (programs) the file blink877.hex to it, verifies the succesfull programming, and starts the target. This command line assumes that the first serial port (COM1) is used, that only one device is connected to it, and that the target PICmicro has a recogniseable device ID (which is the case for all except the obsolete 16c84 and 16f84).

wisp com2 go blink877
	When you do not use COM1 you must prefix the correct serial port before the other commands.

wisp target c84 go blink84
	When you use a 16c84 or 16f84 you must specify the chip before the other commands.

wisp go myapp tty 9k6
	For debugging you might want see debug output from your application in the target, or even give it commands. Note that the TTY command does not specify a mode, so it uses the default mode of target B6=to PC, B7=from PC, true polarity.

wisp vcc 4.8 5.2 go x.hex
	When you use a calibrated WISP (not a Wisp628) programmer this command line will write the file x.hex to the target and verfy the succesfull writing at 4.8V and 5.2V. This is suitable for production programming when the target hardware uses a 7805-type regulator.

wisp load patch $2107=$47 save x
	This command line reads the file x.hex, changes the value at location $2107 (the 7th location of the eeprom data) to $47 (capital G) and saves the modified file. No programming hardware is involved.

wisp erase norestore patch $3ff=$31c2 patch $2007=$21FF put
	This is the command to use when you must restore the oscillator calibration (instruction at address $3FF) and bandgap bits (highest 2 bits of the fuses value at $2007), for instance a 12F chip. Note that you must supply the values. This will not be necessary in normal operation, because the erase, put, go etc. commands perserve these values.

HISTORY