Wisp628 communication protocol

wesp

Wisp628
communication protocol
wesp

introduction

The communication protocol used by the Wisp628 programmer conforms to the WBus definition, but the multi-drop feature of WBus is not used. This is the reason for some concepts and commands (like the 'activation' of the programmer) that might seem a bit out of place in a one-to-one communication protocol.

The protocol uses the asynchronous serial format, 8 data bits, no parity, 1 stop bit, at 19200 baud. Only three lines (ground, transmit, receive) are used. No hardware handshake signals are used. The highest (MSB) bit of received data is ignored. The programmer's serial interface uses a female DB9 connector, which can be plugged directly into a PC's male DB9 connector. When (more likely) a serial cable is used it must be a straight ('extension') cable, not a crossed ('null modem') cable.

The protocol requires the PC to send only the digits '0' .. '9' and the letters 'a' .. 'z'. The digits '0' .. '9' and the letters 'a' .. 'f' are used for data, the other letters are commands. The data that applies to a command is sent before the command.

The protocol requires that (with a few exceptions) the programmer echoes each character sent by the PC, and the PC sends the next character only when it has received the echo for the previous one. The programmer converts the character to uppercase and clears the highest (MSB) bit before echoing it. The programmer echoes a command character after it has succesfully completed a command. When a command fails a '?' character is echoed instead to indicate the failure.

To get data from the programmer a command is sent that instructs the programmer to put the data in a buffer. Next a sequence of next commands is used to retrieve the data, character by character, from the buffer. The data can contain any printable character.

The programmer can be in three states: sleep, attention, active, and passthrough. The sleep state is supported by the programmer but has no function for one-to-one communication. A break condition on the serial line forces the programmer from the sleep or passthrough state to the attention state. The hello command forces the programmer to the active state, which is the state required by most commands. The passthrough command sets the programmer in passthrough state. This state can only be left by a serial line break.

The passthrough state is used to 'connect' the serial line directly to the target PICmicro, for instance for debugging. In this state the programmer itself ignores the data on the serial line completely, except that a break condition ends the passthrough. The communication between the host and the target PICmicro can use any data format and baudrate, except that
a break condition must be avoided

baudrates above 19k2 might not be reliable because passthrough is implemented in software.

For experimenting, debugging etc. the wisp.exe program has the talk command that activates the programmer and then presents a simple interface to the user where he can type characters to be sent to the programmer and see the response.

commands

The relevant commands are described, with the states in which the command is recognised by the programmer. When the letters 'a' .. 'f' appear in the format they stand for data values, as explained with the command. All other letters in the format stand for themselves.

command break

format break condition

states sleep, passthrough

A break on the serial line of at least 80 ms forces the programmer from the sleep or passthrough state to the attention state. After a break the programmer will respond to a hello command.

command go

format 0000g

states active

A go command causes the programmer to end programming the target and to release the targets /MCLR (reset) line, thus causing the target to start running it stored program.

command hello

format 0000h

states attention, active

A hello command forces the programmer to the active state, provided that it was either in the active or attention state. (Use a break to get the programmer into one of these states.) Depending on the state of the programmer the characters of the hello command can either be echoed by the programmer or not. When no echo is received an interval of at least 80 ms must be observed between sending the characters of the hello command.

command increment

format i

states active

An increment command causes the programmer to increment the current location.
This command is best used with the programming algorithms 1 and 2 when sequential locations are programmed. For programming algorithm 3 the read and write commands are auto-incrementing. The jump command can be used (and must be used with algorithm 3) to select a random address (instead of incrementing up to the desired address).

command jump

format abcdefm

states active

An jump command causes the programmer to set the current location to the value 'abcdef'.
This command is supported only by algorithm 3. For algorithms 1 and 2 the increment command must be used to change the current addrees.

command lazy write

format a..fl (note: the last character is the letter l, not the number)

states active

A lazy write command causes the programmer to read from the target the data at the current location. If it is equal to the specified data nothing is done. If it is not equal the data is written to the current location (see write command). A lazy write command requires a previous program command.
Lazy writing can speed up programming of when programming algorithm 1, 2 or 4 is used. For programming algorithm 3 a lazy write behaves the same as a normal write.

The current firmware handles lazy write as a normal write. This might change in the future.

command next

format n

states active

The next command is used to retrieve the next data character from the programmer's data buffer. The programmer responds with the next data character.
This command is used after a command that stores data in this buffer. When a string is retrieved from the data buffer it can either be preceded by a space and be terminated by a space (both spaces are not considered part of the string), or start with a non-space, and be exactly four characters in length.

command passtrough

format 00abp

states active

The passthrough command is used to put the programmer in passthrough mode.
The a value selects the lines (of the programmers target DB15M connector) and polarity used for the communication between the programmer and the target PICmicro.

ab = '00' : line 3 for programmer-to-target, line 4 for target-to-programmer, RS232 polarity (used when the PICmicro would connect to the RS232 lines without an inverting buffer)

ab = '01' : line 3 for programmer-to-target, line 4 for target-to-programmer, TTL polarity (as used by the PICmirco UART)

ab = '02' : line 7 for programmer-to-target, line 8 for target-to-programmer, RS232 polarity (used when the PICmicro would connect to the RS232 lines without an inverting buffer)

ab = '03' : line 7 for programmer-to-target, line 8 for target-to-programmer, TTL polarity (as used by the PICmirco UART)

When the PICmicro communicates using its UART the passthrough command should be 0003p, line 7 should be connected to the target's UART RxD pin, and line 8 to the target's UART TxD pin.

The passthrough command can also be used to switch the programmer to a different baudrate, without entering the passthrough mode. The confirmation (the 'p') will be sent back at the new baudrate. A break (framing error) will switch the baudrate back to the default.

ab = '04' : switch to 9k6

ab = '14' : switch to 19k2 (which is the power-up default)

ab = '24' : switch to 38k4

ab = '34' : switch to 57k6

ab = '44' : switch to 115k2

command program

format aabcx

states active

The program command causes the programmer to start programming. It applies the Vpp (programming enable) voltage to the target PICmicro so the target enters programming mode. A suitable (c, d or f) program command must be used before a read or write command is used.
The value of c selects the memory region that is programmed. The current location is set to the first location of the selected region.
c = 'c' : enter programming mode for code memory

c = 'd' : enter programming mode for eeprom data memory

c = 'e' : erase the target (needed to remove copy protection)

c = 'f' : enter programming mode for configuration memory (device ID, fuses)

The value of b selects the programming (read and write) algorithms.
b = '0' : read and write algorithms for 16x84, 16f62x and 16f87x, works for reading 16f7x, 16f87xA, 16f81x, 12fxxx

b = '1' : read, write, erase algorithms for 16f7x (writes one location at a time)

b = '2' : read, write, erase algorithms for 16f87xA (writes one location at a time)

b = '3' : read, write, erase algorithms for 18fxxx (writes 8 bytes at a time)

b = '4' : read, write, erase algorithms for 12fxxx

b = '5' : as '0', but reads 4 locations = 8 bytes at a time, auto-increments on read

b = '6' : as '3', but reads 8 locations = 8 bytes at a time, auto-increments on read

b = '7' : read, write, erase algorithms for 16f81x (writes 4 locations = 8 bytes at a time, autoincrementing)

The value of aa selects (where appropriate) the delay used.
aa = '00' : use a suitable default that will work but might be somewhat slow

aa = ... : for writes this is interpreted as the write delay (two hex nibbles), for other commands it is ignored.

command read

format r

states active

The read command causes the programmer to read, form the target, the value at current location, and copy its value (as hexadecimal nibbles) to the data buffer, from which it can be retrieved by next commands. A read command requires a previous program command.
The number of bytes read depends on the programming algorithm and the memory area. EEPROM data memory is always read one byte at a time. Algorithms 1 and 2 read program and configuration memory 14 bits at a time. Algorithm 3 reads program and configuration memory one byte at a time.
For algorithms 1 and 2 the current location is not affected by a read command. For algorithm 3 the current location is incremented by the amount of data read.

command type

format t

states active

The type command causes the programmer to copy its type name string (Wisp628) to its data buffer, from which it can be retrieved by next commands.

command version

format v

states active

The query command causes the programmer to copy its version string to its data buffer, from which it can be retrieved by next commands.

command write

format a..fw

states active

A write command causes the programmer to write the value a..f (interpreted as hexadecimal nibbles) to the current location in the target. A write command requires a previous program command.
The number of bytes written depends on the programming algorithm and the memory area. EEPROM data memory is always written one byte at a time. Algorithms 1 and 2 write program and configuration memory 14 bits at a time. Algorithm 3 writes configuration memory byte wise, but writes program memory 8 bytes at a time.
For algorithms 1 and 2 the current location is not affected by a write command. For algorithm 3 the current location is incremented by the amount of data written.

examples

Below a typical program - run sequence is shown. Note that only the data sent by the host is shown (in bold).

preparation:
- break (to get the programmer to either attention or active mode)
- 0000h (to get the programmer to active mode)
- tnnnnnnnn (get device type to check presence, and verify programmer type)
- vnnnnnnnn (get the programmer's version to check tool/hardware compatibility)
- 00ex (optional: erase chip to remove code protection)
- 00fxiiiiiirnnnn (optional: get target ID to determine target presence and type)
00acx (enter programming mode for the program memory, select appropriate value for a), now for all code locations that must be programmed:
- abcdl (lazy write, select appropriate values for abcd, skip for locations that must not be programmed)
- i (increment to next location)
dx (enter programming mode for the data memory, select appropriate value for a), for all data locations that must be programmed:
- abl (lazy write, select appropriate values for abcd, skip for locations that must not be programmed)
- i (increment to next location)
fx (enter programming mode for the configuration memory), for all configuration locations that must be programmed:
- abcdl (lazy write, select appropriate values for abcd, skip for locations that must not be programmed)
- i (increment to next location)
(optional) to verify succesfull programming the content of the target can be read back and compared.
0011p (start the target, connect the serial communication to the UART)

http://www.voti.nl/wisp628/protocol.html
Copyright (c) 2002, 2005 Van Ooijen Technische Informatica / Wouter van Ooijen
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A local copy of version 1.1 of the license can be found here.

command	break
format	break condition
states	sleep, passthrough
A break on the serial line of at least 80 ms forces the programmer from the sleep or passthrough state to the attention state. After a break the programmer will respond to a hello command.

command	go
format	0000g
states	active
A go command causes the programmer to end programming the target and to release the targets /MCLR (reset) line, thus causing the target to start running it stored program.

command	hello
format	0000h
states	attention, active
A hello command forces the programmer to the active state, provided that it was either in the active or attention state. (Use a break to get the programmer into one of these states.) Depending on the state of the programmer the characters of the hello command can either be echoed by the programmer or not. When no echo is received an interval of at least 80 ms must be observed between sending the characters of the hello command.

command	increment
format	i
states	active
An increment command causes the programmer to increment the current location. This command is best used with the programming algorithms 1 and 2 when sequential locations are programmed. For programming algorithm 3 the read and write commands are auto-incrementing. The jump command can be used (and must be used with algorithm 3) to select a random address (instead of incrementing up to the desired address).

command	jump
format	abcdefm
states	active
An jump command causes the programmer to set the current location to the value 'abcdef'. This command is supported only by algorithm 3. For algorithms 1 and 2 the increment command must be used to change the current addrees.

command	lazy write
format	a..fl (note: the last character is the letter l, not the number)
states	active
A lazy write command causes the programmer to read from the target the data at the current location. If it is equal to the specified data nothing is done. If it is not equal the data is written to the current location (see write command). A lazy write command requires a previous program command. Lazy writing can speed up programming of when programming algorithm 1, 2 or 4 is used. For programming algorithm 3 a lazy write behaves the same as a normal write. The current firmware handles lazy write as a normal write. This might change in the future.

command	next
format	n
states	active
The next command is used to retrieve the next data character from the programmer's data buffer. The programmer responds with the next data character. This command is used after a command that stores data in this buffer. When a string is retrieved from the data buffer it can either be preceded by a space and be terminated by a space (both spaces are not considered part of the string), or start with a non-space, and be exactly four characters in length.

command	read
format	r
states	active
The read command causes the programmer to read, form the target, the value at current location, and copy its value (as hexadecimal nibbles) to the data buffer, from which it can be retrieved by next commands. A read command requires a previous program command. The number of bytes read depends on the programming algorithm and the memory area. EEPROM data memory is always read one byte at a time. Algorithms 1 and 2 read program and configuration memory 14 bits at a time. Algorithm 3 reads program and configuration memory one byte at a time. For algorithms 1 and 2 the current location is not affected by a read command. For algorithm 3 the current location is incremented by the amount of data read.

command	type
format	t
states	active
The type command causes the programmer to copy its type name string (Wisp628) to its data buffer, from which it can be retrieved by next commands.

command	version
format	v
states	active
The query command causes the programmer to copy its version string to its data buffer, from which it can be retrieved by next commands.

command	write
format	a..fw
states	active
A write command causes the programmer to write the value a..f (interpreted as hexadecimal nibbles) to the current location in the target. A write command requires a previous program command. The number of bytes written depends on the programming algorithm and the memory area. EEPROM data memory is always written one byte at a time. Algorithms 1 and 2 write program and configuration memory 14 bits at a time. Algorithm 3 writes configuration memory byte wise, but writes program memory 8 bytes at a time. For algorithms 1 and 2 the current location is not affected by a write command. For algorithm 3 the current location is incremented by the amount of data written.