BUILDING:
Copy picp.tgz to the target directory then open and decompress the archive with:
     tar -xzf picp.tgz

Change to the picp directory:
     cd picp

Build the application:
     make

INSTALLING:
Type make install.  This will try to copy the executable to /usr/local/bin.  If this isn't where your local executables live, either change the Makefile or copy the executable yourself.  You may need to be root to copy into the /usr/local/bin directory.

INVOKING:
picp requires as command line arguments a serial device, a PIC device, and one or more flags.  In general,
     picp ttydevice picdevice [-q] [-h] [-v] [-f] [-s [size]] [-b[picd]] [-e[picd]] [[-r|-w][picd] [value]]
where:
     ttydevice is the serial port to which the PICSTART Plus is attached (e.g., /dev/ttyS0)
     picdevice is the name of the PIC to be operated on (view help for a complete list)
     -q suppresses most messages and just returns the essential information
     -h displays help along with a complete list of supported parts
     -v displays the version number returned by the PICSTART Plus itself
     -f causes verify errors while programming to be ignored
     -s [size] displays a hash mark status bar while programming or erasing
     -b blank checks the requested region
     -e erases the requested region (flash devices only)
     -r reads the requested region
     -w writes to the requested region
     possible regions:
         p = program memory space
         i = ID locations
         c = configuration word
         d = data memory space
         o = oscillator calibration space

For the following discussions, the PICSTART Plus is assumed to be connected to /dev/ttyS0 and the PIC device is taken to be a PIC16F84.

PICSTART Plus VERSION:
To verify communications with the PICSTART Plus, enter the serial device it is attached to and the name of any supported PIC device, plus -v to report the version number:
     picp /dev/ttyS0 16f84 -v

If all is well, the firmware version number of the PICSTART Plus will be returned.  If the version number of the firmware in your PICSTART is too old, an error message will be returned, prompting you to contact Microchip to obtain the latest firmware for your PICSTART Plus.  The PICSTART Plus firmware runs on a PIC17C44-25.

BLANK CHECKING:
To blank check the device, enter:
     picp /dev/ttyS0 16f84 -b
This will check all regions which exist on the device and report whether each is blank or not.

Specific regions can be checked individually by adding their specifiers to the -b argument:
     picp /dev/ttyS0 16f84 -bp
This example will only blank check the program space.  More than one specifier may be added to a single argument:
     picp /dev/ttyS0 16f84 -bpcd
In this case, the program space, the configuration bits, and the data space will be blank checked.

READING:
To read from the device's program space, enter:
     picp /dev/ttyS0 16f84 -rp
The contents of the program space will be dumped to the terminal in Intel Hex format.  Optionally, you may specify a file to write the results to:
     picp /dev/ttyS0 16f84 -rp file.hex
The contents of the program space will be dumped in Intel Hex format to a file named file.hex.  If a file named file.hex already exists (and the user has proper permissions) it will be overwritten.

To read the device's ID locations, enter:
     picp /dev/ttyS0 16f84 -ri

To read the device's configuration bits, enter:
     picp /dev/ttyS0 16f84 -rc

To read the device's data memory space (if present), enter:
     picp /dev/ttyS0 16f84 -rd
As with the program space, a file name to dump the output to may optionally be added as the next argument.

More than one region may be requested in a single argument, such as:
     picp /dev/ttyS0 16f84 -rci
This will return the configuration bits and the contents of the ID locations.

ERASING:
To erase a device's program region (flash devices only), enter:
     picp /dev/ttyS0 16f84 -ep
Any combination of regions may be specified in the -e argument.  After an erase operation an implicit blank check is performed on the specified region so that the erase operation returns the proper result (fail or not fail).

WRITING:
To write a device's configuration bits, enter:
     picp /dev/ttyS0 16f84 -wc 0x3ffe
This will try to write the value 0x3ffe to the device's configuration word.  If it fails to verify it will return with a non-zero (failed) result.  The configuration word value may be specified in hexadecimal, decimal, or binary:
  0xnnnn or 0Xnnnn (leading 0x or 0X) -- hexadecimal
  0bnnnnnnnnnnnnnnnn or 0Bnnnnnnnnnnnnnnnn (leading 0b or 0B) -- binary
  anything else -- decimal

The configuration word may also be written along with the program space with the command:
      picp /dev/ttyS0 16f84 -wp infile.hex
if the Intel Hex file named infile.hex contains a value for the configuration word at the proper address for the specified device.

STATUS BAR:
The write and erase operations on program or data spaces can take a little while, so a status bar is available in the form of a line of hash marks (#).  The status bar is invoked with:
     picp /dev/ttyS0 16f84 -s 30 -wp input.hex
Since the arguments are intrepreted from left to right, the -s argument must preceed the -w argument or it won't be interpreted until after the write is complete.  If the argument following -s is not another flag (i.e., doesn't have a leading '-') it is interpreted as the number of hash marks to put up in a complete status bar.  If no number is provided the default value of 20 is used.  As the write progresses hash marks will be put to the terminal at uniform intervals until the specified number of hash marks are displayed and the write is complete.  The width of the bar is dependent on the actual amount of data written -- picp only writes the areas specified by the input data and skips regions which are not defined, so the bar may actually be shorter than the length specified.

STDIN/STDOUT AND PIPING:
stdin and stdout are used to enable piping of picp with other applications.  As a useless example:
     picp /dev/ttyS0 16f84 -b | grep "not blank"
will only display the lines relating to regions which are not blank.

Likewise:
     cat input.hex | picp /dev/ttyS0 16f84 -wp
will yield the same result as:
     picp /dev/ttyS0 16f84 -wp input.hex

ORDER OF OPERATION:
Arguments are interpreted and executed in order, from left to right.  This permits a sequence of operations to be performed with a single command, such as:
     picp /dev/ttyS0 16f84 -ep -wp input.hex -wc 0x0005 -rp output.hex
This will first attempt to erase the program space, then write to it from a file named input.hex, then write the value 0x0005 to the configuration bits, then read the program space back out and save it to a file named output.hex.  If any operation fails, the remaining operations are aborted.  Thus, if the erase fails, the write won't occur.  If an operation fails picp will return a non-zero result.

If a modifier such as -s is inserted like this:
     picp /dev/ttyS0 16f84 -ep -s -wp input.hex -wc 0x0005 -rp output.hex
it is important to note that the status bar will appear for the write but not for the erase, since the -s argument is to the right of the -ep argument.  To add status bars to both operations, type:
     picp /dev/ttyS0 16f84 -s -ep -wp input.hex -wc 0x0005 -rp output.hex

REMAINING ITEMS:
The database of PIC descriptions is not quite complete.  The flags indicating which regions are present on a given device (e.g., EEPROM data space) are only defined for a few devices.  All others devices are assumed (for now) to have all regions, which may mean that, for instance, blank checking may return a result on a region that doesn't actually exist in the part.  It's generally not harmful but it can be confusing.

The majority of PIC devices supported have not been tested.  While every effort was taken to ensure accuracy, errors may be present in the PIC description database.  If you encounter a device which appears to be incorrect, please let us know so it can be fixed in the next release.
 

FEEDBACK:
Please send comments, bug reports, suggestions, etc. to apines@cosmodog.com.