Pista
v0.70, 2005-08-27
Introduction
Pista is a user interface to the popular PICSTART Plus
PIC programmer. Pista is written entirely in PERL. It is intended to
be used under Linux but probably any *nix like operating system may run it.
(The word Pista rhymes with PIcSTArt, but actually it is the
Hungarian equivalent of the nickname Steve. ;-)
I hope later it may be extended to handle other serial programmers
like ProMate or PicWriter.
Concept
Pista works like an interactive shell. After starting up it gives you a prompt
and waits for user commands.
Its main job is to copy data between
Intel hex files, PIC chips, the user's terminal, and internal buffers
back and forth. Other functions are data comparison, checksum computation
and erasing chips.
Pista uses Term::ReadLine PERL package for user I/O.
If you have Term::ReadLine::GNU or Term::ReadLine::Perl
installed then full command line editing and history is supported.
On the other hand Pista is also intended to be a backend of a GUI program
with all bells and whistles. The graphical frontend just have to open a pipe
to Pista and to send command through it. Replies of Pista look
like answers from an SMTP, FTP, or NNTP server: an easy to parse
three digit code followed by some human readable text.
Objects
The main operation of Pista is copying data between objects.
An object may be a hex file, an internal buffer, a PIC chip or the user's
terminal.
File is an ordinary disk file in ihex32 format.
Buffer is an internal non-persistent storage area.
Buffers are identified by names, similar to filenames.
You may think buffers as temporary files. Content of buffers gets lost
when program exits.
PIC is the actual chip inserted in your programmer's ZIF socket.
Copying data into pic actually writes your chip.
Terminal is your TTY device. It is suitable to enter or
to dump data in "huma^H^H^H^Hnerd readable" form.
In 2003 Microhip introduced a new Flash based version of PICSTART Plus.
(Processor upgrade kit for older devices is available.)
If you have such a hardware you can upgrade firmware on the fly.
Therefore a new object called firmware is added to Pista v0.40a.
See below.
Sections
Objects have one or more sections of prog, cal,
userid, devid, conf, eeprom.
These corresponds to code area, calibration space, user ID, device ID,
configuration word(s) and data area in PIC chips (if implemented).
Naming conventions
PIC and terminal objects are called pic: and term:
respectively.
Buffers and files have similar designation buf: and file:
followed by their names. For your convenience in most cases
"file:" can be omitted unless in case of ambiguity.
(This feature will be removed as soon as I destroy a precious file
accidentally. ;-)
Examples of valid object specifications:
| Specification | Object
|
| file:/tmp/foo.hex | Disk file /tmp/foo.hex
|
| ../src/bar.hex | Disk file ../src/bar.hex
|
| buf:saved_config | A buffer named saved_config
|
| pic: | The chip in ZIF socket
|
| buf:pic: | A buffer named pic: (See note)
|
| file:buf:pic: | Disk file buf:pic:
(a quite pathological case ;-)
|
| ./buf:pic: | The same as above
|
Note: It is not decided yet if other than alphanumeric chars are allowed
in buffer names.
Note: It is not decided yet if unnamed buffer (buf:) is a
valid object.
Ranges
Sections may be copied (erased, blank checked etc.)
in the same step or individually.
PICSTART Plus usually handles these sections as indivisible
units except program memory which may be read or written partially.
Other similar programmer devices or later versions of PICSTART Plus
may be more intelligent. Therefore Pista allows to select parts
of the sections.
A list of (partial) sections is a range.
A range specification is comma separated list of
section[/address_range]
Where address_range is one of these:
abs_start-
abs_start-abs_end
abs_start+len
+rel_start-
+rel_start+len
(Decimal, hexadecimal or octal numbers are all accepted.)
- If no address_range is given (this is the usual case)
Pista sets start and end address according the specification of the
currently selected PIC device.
-
abs_start and abs_end are absolute memory addresses.
-
len is the length of the selected area.
-
If nor abs_end neither len is given the end of the area
is set according the specification of the currently selected PIC device.
-
rel_start is the offset from the actual start of the given section.
Ranges affected by the current operation is set by the --range
command line option. Examples of valid range specifications:
| Specification
| Operation affects
|
| --range=prog
| the entire program area
|
| --range=prog/0x280+32
| program memory from 0x280 to 0x29f
|
| --range=prog,cal
| program memory and calibration area
|
| --range=userid/+3+1
| fourth word of user ID
|
--range=eeprom
| the whole EEPROM
| |
If no range specification is given, the current operation
affects all possible memory areas (i.e. same as
--range=prog,cal,userid,devid,eeprom,conf).
Commands
- programmer [options] programmer_type
[arguments ...]
- Select programmer type. Currently the only possible programmer_type
is picstart . Its mandatory argument is the serial line e.g.
/dev/ttyS0 .
Possible options: --debug enables debugging, --noprogress
disables progress meter.
- device pic_type
- Select PIC type for the subsequent operations.
- idcheck
- Read Device ID and check if corresponds to the pic_type
selected previously.
- show buffers|programmer|version|device
- Show list of buffers, programmer type, program version or PIC type respectively.
- copy [--noblank] [--range=range]
[--force] srcobj dstobj
- Copy selected range of data from srcobj to dstobj.
If option --noblank is given blank words (according to current
pic_type specifications) are discarded during copy.
In normal cases calibration area and some special bits in config
should be preserved. However if you want to do overwrite these bits
you need the option --force.
Actually command should be called merge because it leaves
out of range memory areas untouched. So you can change a single word in
a PIC as well as overwrite a selected part of a hex file.
If you want replace the entire section erase it before.
- compare [--range=range] srcobj dstobj
(not implemented yet)
- Compare content of two objects.
- blankcheck [--range=range] [srcobj]
(partially implemented)
- Check if selected range of srcobj is blank.
In case of pic: object "blank" means what do you think: all ones.
Otherwise the selected area must contain "undefined" values.
Default srcobj is pic: .
Default range is prog,cal,conf,eeprom
As of version 0.52b
- the only possible srcobj is pic:
- each section of range must start at the lowest possible address
- erase [--range=range] [--force]
dstobj
- Erase selected parts of dstobj (if possible).
Erasing overwrite the selected region with the "blank" value whatever it means
(see above).
Calibration area and some special factory preset bits in config words
will be restored after erase operation unless --force option is given.
- delete dstobj
- If dstobj is pic: deleting is equal to chip erase.
Calibration area will be restored automatically.
file: disk file will be removed.
In case of buf: the buffer will be destroyed.
Due to dangerous nature of this command unqalified dstobj is not
assumed to be a file: by default.
- checksum [--range=range] srcobj
(partially implemented)
- Compute checksum for the selected region.
The response contains raw 16 bit sum for all possible sections plus
the "officially" computed checksum as described in chip documentations.
(It is computed as if chip is code unprotected.)
As of version 0.52b
- the only possible srcobj is pic:
- cd [dir]
- Change current working directory.
- ! shell_cmd
- Give shell_cmd to /bin/sh to execute.
- . filename
- Read lines from filename and regards them as user commands.
This is the convenient way to execute commands in batch.
Program initialization is done in a similar way executing
$HOME/.pistarc .
- help [command]
- List available commands or dislplay command syntax.
If a command is preceded by pipe (|) character
its output will be passed to a filter given by PAGER
environment variable. If no PAGER given "less -F -X" used.
Initialization
Commands found in $HOME/.pistarc will be executed automatically
after startup.
Command line options
- --backend
--batch
- At startup Pista checks if standard input is connected to a terminal.
If yes it goes to interactive mode by enabling readline functions.
However if commands come from a pipe program has two choices.
Option --batch forces to abort command processing if any error
occurs. This mode can be used in scripts and Makefiles.
(It is similar to -e options of Bourne shell.)
Just simply echo series of commands into stdin of Pista.
In backend mode commands come from frontend program one by one. Frontend
can evaluate result codes and can make decisions in case of error.
If stdin is not a terminal and nor --backend neither --batch
option is given batch mode is assumed.
- --no-init
--init rcfile
- By default Pista executes command from $HOME/.pistarc
at startup time. You can disable this feature by --no-init option.
Default rcfile can be changed with --init.
Makefile examples
You can feed commands on stdin. Makefile syntax
is a bit strict. It is not trivial to produce a multiline string.
A possible way is starting a subshell to run a series of echo
commands:
picprog: foo.hex
(echo programmer picstart ; \
echo device 16f877 ; \
echo copy foo.hex pic: )| \
pista --no-init --batch
GNU Make allows you to define functions. This makes Makefile readable a bit:
define write_pic
(echo programmer picstart ; \
echo device 16f877 ; \
echo copy $^ pic: )| \
pista --no-init --batch
endef
picprog: bar.hex
$(write_pic)
TODO
- Implementing missing commands
- Checking code protection bits before any R/W operations
- Adding 'readline' word completion. (I should understand it before. ;-)
Firmware upgrade
Pista v0.40a or higher can download firmware upgrade into
Flash processor of PICSTART Plus. Follow instructions below:
- Set programmer type:
programmer picstart [ serial_port ]
- Select PIC18F6720:
device 18f6720
- Copy HEX file containing latest Microchip firmware into PICSTART PLus:
copy disk_file_name firmware:
File can be downloaded from www.microchip.com. However you
may spend a lot of time with searching. At the last resort look for the
latest MPLAB IDE. This package usually contains PICSTART Plus firmware too.
(File pspls41006.hex shipped with MPLAB IDE 6.43.)
However in this case you have to install it on a vindoze machine
then search file in $INSTALLROOT/Programmers dir.
(Hey! Were you willing to install a vindoze program? You probably
don't need Pista. ;-)
Write the webmaster
and ask him to distribute 4.0+ PICSTART Plus
firmware separately.
- Reset programmer and check new firmware version:
programmer picstart [ serial_port ]
Note: The early editions of the Flash firmware and loader
have some flow control problems. (Actually it does not signal
if cannot accept more input so character overrun may occur.)
This can result corrupted or broken Flash image that makes
PICSTART Plus unusable. Don't panic. The loader code of 18F6720
remains intact and you can retry the download operation.
Miscellanous
Gabor