 
                  PP: GENERIC PIC16X8X PROGRAMMER SOFTWARE 
                  ======================================== 
 
                               David Tait 
                          david.tait@man.ac.uk 
                       http://www.man.ac.uk/~mbhstdj 
 
 
Introduction 
------------ 
 
This document describes some simple MS-DOS based software for programming 
Microchip PIC16x8x (i.e. the 16F83, 16F84 and 16C84) microcontrollers.  
Different versions of the software are available depending on the interface 
between the programming hardware and the PC.  What is described here is 
the common front-end or hardware independent part.  Throughout this 
document the software is called "pp" although the actual name may depend on 
the hardware specific variant.  Also depending on the hardware driver 
certain features mentioned here may not be available.  For example, some 
hardware cannot read back information from the PIC and therefore it is 
impossible to use features that rely on this capability. 
 
 
Overview 
-------- 
 
The purpose of the software is to take an image of a PIC program from a 
file produced by an assembler or compiler and download it to the PIC.  The 
image should be in a hex file: the most common hex file format is 
designated INHX8M by Microchip but an older style called INHX16 is still 
common.  The software can read data from either type of hex file.  There 
are four separate areas of a PIC that can be programmed: 
 
     o  Program memory      This is where the PIC program goes (the 
                            PIC starts execution at location 0 of 
                            program memory).  There are 1024 14-bit 
                            words of program memory (the 16F83 has 512). 
 
     o  Data memory         64 bytes of EEPROM memory. 
 
     o  ID locations        4 words of memory which can be used to tag 
                            the PIC by storing a unique number there. 
                            (there are few other locations called "test 
                            memory" in this area). 
 
     o  Configuration word  Used to select PIC oscillator setup and  
                            enable or disable the watchdog, power-up  
                            timer and code protection. 
 
 
The hex file can contain information about any or all of these areas and 
the software will program them accordingly.  Embedding all the information 
in the hex file makes life very simple.  In this case all you need to do to 
program a PIC with the hex file "prog.hex" is type: 
 
     pp prog.hex 
 
How simple can you get?  (Actually, if you are working on the same project 
for a while it's likely that you are repeatedly downloading the same hex 
file.  In this case you can write a batch file called "p.bat" with the 
contents: 
 
     @echo off 
     pp prog.hex 
 
and then all you need to type is: 
 
     p 
 
which really is difficult to beat for simplicity.  More about using  
batch files later).  Most PIC development tools have the means to embed  
all the necessary information in the hex file.  For example, MPASM,  
Microchip's free assembler, includes the three directives, __CONFIG,  
__IDLOCS and DE, to define configuration, ID and data memory  
respectively.  In fact, the only way to use pp to program data memory  
and the ID locations is to embed information about these areas in the  
hex file.  However, as it is so vital, the software does provide another  
way to define the configuration word if it is not included in the file.   
(The programs in pichex01.zip, which should be available where you found  
this stuff, contains utilities to build integrated hex files for the  
16C84 if your development tools don't.) 
 
The software lets you erase the PIC (i.e. set the PIC contents back to  
its unprogrammed state).  Use this function sparingly; it isn't  
necessary to erase the entire PIC before it is reprogrammed because each  
word is overwritten during programming.  The software is designed so  
that it only overwrites locations which are different to those in the  
hex file  (which means that if you try to program the PIC twice with the  
same hex file nothing is overwritten the second time).  Erasing the PIC  
can slow down the programming process as it will force all memory to be  
updated.  Another point to consider is the finite lifetime of the PIC; a  
16x8x can only be reprogrammed a finite number of times (minimum 100 but  
1000 typically) therefore minimising the number of times each location  
is reprogrammed can extend the useful life of the PIC.  There are times  
when the PIC must be erased however.  In particular the erase function  
can be used to defeat code protection: part of the config word is used  
to prevent the PIC contents from being read which in turn prevents  
people from cloning your PIC.  The contents of a code protected PIC  
cannot be overwritten but by erasing the PIC, code protection is removed  
thus making the PIC available for reprogramming again. 
 
The PIC contents can be dumped to a hex file or compared with (verified  
against) another hex file.  The verify feature is only useful if the PIC  
is not code protected although the software does verify as it goes along.   
It is important that the PIC is verified under the same conditions as it  
was programmed: if the software was used to define the config word during  
programming it must also be used to do the same during verification.  If  
you don't do this verification will probably fail when the configuration  
word is compared. 
 
 
Using the software 
------------------ 
 
If all is well when you type pp you should see a banner similar to this  
one: 
 
PIC16F84 Programmer  Version 0.5  Copyright (C) 1994-1998 David Tait. 
 
Usage: pp  [ -lxhrwpcdevgosn! ]  hexfile 
 
      Config:   l = LP,   x = XT,     h = HS,      r = RC 
                w = WDTE, p = PWRTE,  c = code protect 
      Others:   d = dump, e = erase,  v = verify,  g = go 
                o = old,  s = silent, n = no read, ! = no wait 
      Defaults: RC, /WDTE, /PWRTE, unprotected, 
                no erase, stop, new, verbose, read, wait 
 
Bug reports to david.tait@man.ac.uk 
 
This is meant to indicate that pp is invoked with a command line that  
consists of an optional set of switches signalled by the prefix '-'  
(though '/' works as well if you prefer) followed by a filename.  The  
switches are used to either define the configuration word (overriding  
the config specified in the file) or invoke a programmer function or  
both.  Some valid command lines might be: 
 
      pp prog.hex 
      pp -l -w prog.hex              LP oscillator and watchdog enabled 
      pp -d new.hex                  dump PIC to new.hex 
      pp -ec prog.hex                erase and code-protect 
 
This shows how switches can be defined individually (-l -w) or as a  
block (-ec).  Some switch combinations don't make sense or may be  
contradictory and the exact action is not obvious.  For example: 
 
      pp -xr prog.hex 
 
tells the programmer to select both the RC oscillator and the XT oscillator 
configuration.  Contradictions like this are resolved by obeying the last 
switch specified (in this case the RC oscillator is selected).
 
Before using the software to program a PIC it may be necessary to inform 
the hardware driver about the specific hardware attached.  This is 
typically done using MS-DOS environment variables (details are in the 
hardware specific documentation).  An easy way to do this is to run pp  
from a batch file which sets up the environment variables as required.  
Here's a typical example which I'll call mypp.bat: 
 
    @echo off 
    set ppsetup=3 
    pp -n %1 %2 %3 %4 
    set ppsetup= 
    
Here the ppsetup variable tells the driver something about the hardware,  
then pp is invoked with a fixed switch (-n in this case) and other  
arguments are taken from the command line and when pp exits ppsetup is
removed from the environment.  The batch program can be run just like pp 
itself: 
 
    mypp -xw prog.hex      set ppsetup=3 then run pp -n -xw prog.hex 
 
Though pp is not designed to be used with Windows it can be run in a DOS  
box.  The best way to do this with Windows 3.1 is to create a batch file  
appropriate to your setup then use the PIF editor to create a PIF file  
to run the batch program.  The PIF file should specify exclusive  
execution and windowed display but if you want to see any error messages
it should not specify close window on exit; the defaults are OK otherwise.   
File Manager can then be used to drag the PIF file onto a folder to make  
an icon which you can simply double-click to run pp with the command line
entered with the PIF editor.  I don't use Windows 95 but perhaps something 
equivalent can be done, otherwise just run the batch file or pp itself from 
within a Win95 DOS box. 

After any hardware specific environment variables have been set the  
software should be run once before trying to program a PIC.  This will  
let the driver initialise the hardware. 
 
 
Switches 
-------- 
 
This section gives a detailed listing of all the switches used by pp.  As 
mentioned previously, embedding information in the hex file means you don't 
have to use any switches to program a PIC.  However, if the configuration 
information is not contained in the file then it should be defined on the 
command line (switches -lxhrwpo) otherwise a default word is written to the 
PIC and this is unlikely to be the one you want.  Dumping, erasing and 
verification are invoked by switches -d, -e and -v respectively.  Finally, 
some switches (-gsn!) change the behaviour of the program. 
 
 
Configuration switches  
 
The first few switches are used to set the 14-bit configuration word. In  
the 16F83/84 the config word is organised like this: 
 
     CC CCCC CCCC PWOO 
 
where the bits marked C are used to enable/disable code protection, the  
P bit (Microchip calls it PWRTE) controls the power-up timer, the W bit 
(or WDTE) enables/disables the watchdog timer and the two bits marked OO  
define the PIC oscillator configuration.  By default (i.e. if neither 
the hex file nor the command line switches define the config word) pp 
uses 11 1111 1111 1011 (3FFB hex); this corresponds to no code  
protection, power-up timer disabled, watchdog disabled and RC  
oscillator.  The 16C84 has a slightly different layout: 
 
     -- ---- ---C PWOO 
 
where the bits marked - are don't care (though they read back as 1).   
Another difference is that the sense of P is inverted (i.e. 1 enables  
the power-up timer).  Thus if 3FFB hex is written to a 16C84 it  
would select no code-protection, power-up timer enabled, watchdog  
disabled and RC oscillator. The config switches are used to define the  
C, P, W and O bits as follows: 
 
     -l       select the LP (low power) oscillator mode 
 
     -x       select the XT (crystal) oscillator mode 
 
     -h       select the HS (high speed) oscillator mode 
 
     -r       select the RC (resistor/capacitor) oscillator mode 
 
     -w       enable watchdog timer 
 
     -p       enable the power-up timer 
 
     -c       enable code protection 
 
There are a few cases to consider.  If any of the above switches are  
specified on the command line then the config word defined in the hex  
file is totally ignored (overridden).  If none of the above are  
specified then the file config is used.  If none are specified, and the  
config word is not defined by the file, the default word is used.   To  
take care of the differences between the 16F83/84 and 16C84 another  
switch is available: 
 
     -o       assume old style (16C84) config layout 
 
The -o switch is only really needed if you are programming a 16C84 and 
must enable the power-up timer on the command line (using -p).  It does 
have a couple of other side effects though: using -o means only the low 
order five bits of the config word are verified (all bits are  
programmed); usually the software prints a precis of the config word  
(like "CP-X" meaning code protection and power-up timer enabled and XT  
oscillator selected) and the precis will lie about the P bit if the -o  
switch is not used appropriately.  If the default word is used to define 
the config (because neither the command line nor the file say what it 
should be) then -o inverts the P bit (i.e. the default word becomes 3FF3 
hex).  The -o switch on its own DOES NOT override or change a file-specified 
config word.  Thus, provided the hex file defines the correct style of 
config (and sets all high order config bits to 1) you can just forget about 
-o regardless of whether you are programming a 16F84 or a 16C84.  There is 
no switch to indicate a 16F83 is being programmed and it's up to you to 
make sure you don't try to write more than 512 words of program memory 
in this case. 
 
 
Dumping, erasing and verifying 
 
Other programmer functions are requested using the following switches: 
 
     -d       dump the PIC contents to the given file. 
 
     -e       erase the PIC 
 
     -v       compare PIC contents with the given file 
 
Usually -d is used on its own (or with one of the behavioural switches 
described later).  If the file specified to receive the dump already  
exists the dump is aborted.  If any parts of the PIC are in their  
unprogrammed state they are not dumped, however, unprogrammed holes in  
the program or data memory are dumped.  If the PIC is entirely blank the  
dump file is not created.  The -e switch can be used with or without a  
file argument; in the first case the PIC is erased then programmed and  
in the second case it is simply erased.  The -v switch reads the PIC and  
compares it with what should have been programmed according to both the  
file and the other configuration switches.  Verification halts at the  
first difference found and the config word is compared last. 
 
 
Switches changing program behaviour 
 
The remaining switches are used to change the normal program behaviour.  
The exact effect depends on the hardware driver.  These switches are: 
 
     -g       go - tells the driver to enable PIC execution 
 
     -s       run silently 
 
     -n       no read - don't read from the hardware 
 
     -!       no wait - program the PIC without waiting for interaction 
 
If the hardware can program the PIC in-circuit (Microchip call this in- 
circuit serial programming or ICSP) the -g switch tells the hardware to  
let the PIC run after programming, or, if no file argument is specified,  
simply enable the PIC to run.  By default the PIC is held in reset after  
programming.  If the driver doesn't support ICSP the action of -g is  
undefined and it's best not to use it.  Usually pp gives some indication  
of progress and prints error messages (verbose mode) but -s suppresses  
this behaviour.  If the -s switch is used success or failure is  
signalled using the ERRORLEVEL return value (0 if all is OK, 1 for  
error).  As described earlier the PIC is read before it is programmed  
but not all hardware can support this.  The -n switch tells pp that the  
hardware can't read from the PIC.  This switch is essential for some  
hardware.  Even if the hardware is supposed to be capable of reading  
from the PIC the -n switch is useful for debugging.  For example, try -n  
if the programmer gives "verify failed during programming" errors.   
Obviously -n is not compatible with -d or -v.  Some hardware needs to  
know when the PIC is ready to be programmed and asks the user to confirm  
this condition.  Using -! will skip the confirmation step (note -s  
asserts -! too). 
 
 
Summary 
------- 
 
The software described in this document can be used to program PIC16x8x  
microcontrollers when used with suitable hardware.  If all you want to  
do is program a PIC and the configuration word is defined in the hex  
file then the only command line argument needed is the filename of the  
hex file.  Running the program from within a batch file makes it  
possible to customise the program behaviour (it is even easy to use a  
batch file to make a chatty version that prompts for the hex filename  
and any command lines switches).  Ultimately if you don't like anything  
about the way pp works the source is provided so that you can change it  
for yourself.   
 
 

V-0.2  19 April 1998
