README

Pikme PIC Bootloader

"The World's Simplest PIC Booloader"

Version 20060722

The goal of this program is to have a very fast turn-around programmer
while developing an application.  The idea is to burn the bootloader
(just one time) into the PIC chip with a hardware programmer. Then
thereafter download the application (over and over as you work on it)
via the serial line without needing to involve the hardware
programmer.  Since the bootloader only uses one-half of an I/O pin on
the PIC, it can be left connected to the host PC's serial port all the
time (providing your application does not need to use that pin).

The goal is NOT to provide a production-quality, use-in-the-field,
guaranteed not to fail, bootloader.  The trade off is a very simple
circuit using only one-half of an I/O pin and accept the risk of
downloading blind.

Installation:

        Assuming you have some sort of PIC hardware programmer, use it
        to burn the bootloader hex file (named boot.hex) into a
        PIC16F819 chip.  At this point, the bootloader is installed in
        the PIC.

        On the host PC, to run the downloader program (which sends
        your application code's hex file to the PIC), you need to have
        Python (version 2.2 or later) and the Python serial module
        installed.  

        On a Debian Linux system, you almost certainly already have
        Python installed.  The serial module can be installed by
        running (as root)

              apt-get install python-serial

        or by using whatever Debian package manager you usually use
        (such as aptitude or synaptic).

        For other Unix/Linux systems, you may have a similar ability
        to install the serial package for your system.  Otherwise or
        for Windows, see http://pyserial.sourceforge.net for the
        serial module.

Serial Connection:

        See pinouts.txt.  The serial-input to the bootloader is
        bit-banged rather than requiring a hardware serial port in the
        PIC.  Further, it is what I call "inverted TTL serial".  That
        is, the PC sends out ordinary RS232 serial, where a high
        voltage (say 3V to 15V) represents a zero or start bit and
        where a low voltage (say -3V to -15V) represents a stop on one
        bit.  Ordinarly, that would be connected to an inverter and
        level shifter circuit (e.g. a MAX232 chip) to feed it into the
        PIC as "TTL serial" (where 5 V represents a stop or one bit
        and where 0 V represents a start or zero bit).  However, in
        *this* bootloader, no such inverter/level shifter circuit is
        needed.  Instead, it is all done in software.  The PIC serial
        input routine interprets a logic high on the serial input pin
        as a zero/start bit and interprets a logic low on the serial
        input pin as a one/stop bit.

        There is one slight catch.  If we use the RA5/Vpp/MCLR* pin, a
        voltage that is *too* high could be interpreted as the signal
        to go into high-voltage programming mode.  This voltage (known
        as Vpp) is nominally 13 V.  However, 10 or 11 V might be
        enough.  If the PC serial port swings from -12 V to +12 V,
        then there would be trouble.  If it swings only between -5 V
        and +5 V, no problem.

        So, depending on your PC's serial port, you might need to
        scale the voltage to a safe level.  A simple two-resistor
        voltage divider is sufficient.  I use a small 10K
        potentiometer on the serial connecter but not on the actual
        PIC development board -- no need to duplicate this on every
        PIC board.  See pinouts.txt for an ascii schematic.

        I adjust the pot (potentiometer) just once, with a voltmeter,
        and with the serial connector *not* connected to the PIC.  The
        idle state is a negative voltage (because of the diode clamp
        on the PIC pin on the negative side).  I adjust the pot so the
        negative voltage is no more than about -5 V, figuring this
        will limit the positive swing to a reasonable voltage.  A
        laptop serial port, if it swings only up to about 5 V (7? 8?)
        would not need this circuit.

        Also, if you choose a different pin than RA5, check the data
        sheet.  It probably has diode clamps on both the positive and
        the negative sides and so would not need the voltage divider.

The essential files are

  -- boot.hex   
     burn this into the target PIC using a hardware programmer
     
  -- picbl.py
     run this on the host PC to download your application's hex file 
     to the PIC via the serial port.  Start picbl.py and power up
     the target PIC within a second or two of each other.  If the 
     bootloader detects the serial line wiggling within a short 
     time, it will try to sync up with picbl.py.

     Examples:

        Suppose your application is named dummy1.asm and you
        have assembled it to produce the Intel hex file dummy1.hex.
        Suppose you wish to use the first serial port (known as
        COM1: under Windows or as /dev/ttyS0 under Linux).

              python picbl.py dummy1.hex 0
     
        Suppose your application is named dummy2.asm and you
        have assembled it to produce the Intel hex file dummy2.hex.
        Suppose you wish to use the second serial port (known as
        COM2: under Windows or as /dev/ttyS1 under Linux).

              python picbl.py dummy2.hex 1

     The downloader picbl.py can start a background loop to echo
     anything sent back to the PC via the serial.  See the lines

             #startEchoing()
             serialPort.close()

     near the end of picbl.py. Uncomment the startEchoing() line
     and comment out the serialPort.close() line if you wish 
     picbl.py to echo incoming serial characters.  (Note, the
     bootloader does not transmit anything to the PC, but your
     application might.)

     This could be modified to be a terminal program to echo what you
     type to the PIC and print whatever the PIC sends to the PIC.  For
     now, this is a minimum "echoer" so that if your application
     prints characters to the serial port, they will be echoed to the
     screen.  To make use of this facility, add the '-i' command line
     option when running Python, so that it goes into interactive mode
     after downloading the program, e.g.

              python -i picbl.py dummy1.hex 0

     then, to kill it, type 

              stop() RET
  
     (where RET means to press the Return key) and then type C-d
     (where C-d mean to press the 'd' key while holding down the
     Control key).

Additional files are:

     -- boot.asm
     the source code for the bootloader.  Feel free to modify it to
     suit your needs then assemble it to produce a new bootloader.
     The command I use to assemble it with gpasm is

          gpasm -I../include boot.asm

     but you should adjust it depending on where you put the
     macros.inc file.  If you leave the macros.inc file in the
     same directory as boot.asm, you would assemble boot.asm with
     the command

          gpasm boot.asm


     -- macros.inc
     This holds the PIC assembly language code for a number of macros
     used in boot.asm.

     -- skeleton.asm
     This is a template file you can use as a basis for your
     application.  It mainly shows the necessary 'org' statements
     and where your application code should go.

     -- pinouts.txt
     this shows how to use 2 resistors or a small potentiometer to
     scale the PC's serial port voltage so it will not accidentally
     force the PIC chip into high-voltage programming mode.  This may
     or may not be needed, depending on your PC's serial port and on
     which pin on the PIC you choose as the serial input pin.


The source code is commented extensively.  See picbl.py and boot.asm.
Also, there is some documentation on my web site at

            http://pygmy.utoh.org/pikme     


If you have any trouble running picbl.py, you might need to change the
first line which is set up to run on my system using Python version
2.4

        #!/usr/bin/env python2.4

You might wish to change it to something like one of the following:

        #!/usr/bin/env python
        #!/usr/bin/env python2.5
        #!/usr/bin/env python2.3
        #!/usr/bin/python
        #!/usr/bin/python2.4

or to delete it altogether.

If you make picbl.py executable, and if you have that first line set
up correctly, then under Unix/Linux, you can run it with

              picbl.py dummy1.hex 0

rather than
              python picbl.py dummy1.hex 0
     


-- 
Frank

Frank Sergeant
frank@pygmy.utoh.org
http://pygmy.utoh.org
