
                   TinyBld2  -  by Rob Hamerling
                  ===============================
                  Tiny Bootloader support program

        Copyright (c) 2008..2012, R. Hamerling. All rights reserved.

 Released under the FreeBSD license:

 ***************************************************************************
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.
 * Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.
 ***************************************************************************


 TinyBld2 is a program supporting the Tiny Bootloader of Claudiu Chiculita
 See http://www.etc.ugal.ro/cchiculita/software/picbootloader.htm


 Major difference of TinyBld2 compared to the original TinyBldWin
 -----------------------------------------------------------------
 TinyBld2 is a CLI (CommandLine Interface) program, running under
 eComStation, Linux and Windows. It supports the following features
 of TinyBootloader:
 - writing program and data (EEPROM) memory,
   for 18F also writing ID bytes and configuration memory
 - erasing code  memory (but preserving TinyBootloader code!)
 - erasing data (EEPROM) memory,
   for 18F also erasing ID bytes and configuration memory
 - reset of PIC with RTS signal


 Deliverables
 ------------
 - Readme file (this file)
 - eComStation (OS/2) executable tinybld2.exe
 - Linux executable tinybld2
 - Windows executable tinybld2w.exe
 - The original TinyBootloader configuration file 'piccodes.ini'
 - For those who want to recompile TinyBld2:
   * Source material in C-language.
   * Makefiles for Open Watcom C/C++ compiler (Wmake)
   * Buildlevel Rexx script for Bldlevel signature of eComStation executable.


 Installation
 ------------
 eComStation (OS/2)
    - Create a directory for tinybld2, for example:
        md [bootdrive]:\programs\tinybld2
    - Unzip the Tinybld2 package in this directory.
      Alternatively you could unzip the package in any directory of your PATH.
    - Copy your hex files to this directory (for convenience).

 Linux
    - Extract the ZIP-file in a (temporary) directory of your choice.
      Copy tinybld2 executable and piccode.ini to a user directory,
      (preferrably a directory in PATH environment), e.g.
        cp tinybld2 /usr/local/bin
        chmod u+ /usr/local/bin/tinybld2
        mkdir /etc/tinybld2            { or usr/local/share/tinybld2 }
        cp piccodes.ini /etc/tinybld2  {  "          "               }
      These commands may require root or super user privilege.
    - Copy your .hex files to this directory (for convenience).
    - You may have to alter the attributes of your serial port,
      for example with:
         chmod 666 /dev/ttyS0    (may require root privilege).

 MacOS and FreeBSD
    - There is no executable for MacOS and FreeBSD delivered with this
      package. MacOS and FreeBSD users will have to download the source
      package and build the tinybld2 executable for themselves.
    - Other directives are like those for Linux.

 Windows
    - Create a directory for tinybld2, for example under "c:\Program Files\".
      Alternatively select an existing programs directory which is in
      your Path environment variable.
    - UnZip the ZIP-file in the selected directory.
    - Copy your .hex files to this directory (for convenience).


 The place of 'piccodes.ini'
 --------------------------
 TinyBld2 needs information about the target PIC. It tries to detect
 the ID of TinyBootloader in the target PIC, with which it searches
 the PIC properties in a file 'piccodes.ini'.  This file can be stored
 in several places. TinyBld2 searches this file:
 - in the current working directory
 - in a directory of the PATH environment variable (does not work for Linux)
 - the environment variable TINYBLD2
 - the directory of the tinybld2 executable
 - in some platform specific directories:
   eComSation: <bootdrive>:\programs
               <bootdrive>:\programs\tinybld2
   Linux:      /etc
               /etc/tinybld2
               /usr/local/bin
               /usr/local/share/tinybld2
   Windows:    c:\Program Files\tinybld2
               c:\Program Files\Common Files\tinybld2
 When neither of these possibilities suite you, then put it anywhere on your
 system and specify it in the environment variable TINYBLD2:
   *  set TINYBLD2=x:\my_special_directory\piccodes.ini
   *  export TINYBLD2=/dev/local/my_special_directory/piccodes.ini
 Note: In this case the file needs not be called 'piccodes.ini'!


 Hex File Transfer Procedure
 ---------------------------
 Follow the procedure below to transfer firmware (in the form of a .hex
 file) to a target PIC.  The target PICmicro is supposed to be preloaded
 with the Tiny Bootloader (via another PIC programmer).
 - Connect target board to a serial port of the PC.
 - Start TinyBld2 from a Command Prompt, for example:
     > tinybld2 16f886_blink    { with Windows: tinybld2w }
   The extension '.hex' (lower case) will be added when not specified.
   TinyBld2 tries now to contact the target
 - Reset the target board in either of 3 ways:
   + (power-off and) power on
   + pushing a reset button which pulls MCLR down to 0V
   + using the reset-by-RTS method (see below).
   As soon as contact has been established with Tiny Bootloader in the
   target PIC, the transfer of the application program (hex file) begins.
   When the target could not be contacted within 30 seconds TinyBld2
   terminates.


 Commandline Syntax and Arguments
 --------------------------------
 The command syntax is:

  tinybld2 <hexfile> [-p<port>] [-s<speed>] [-r<pulse>] [-l<logfile>] [-e] [-c] [-q] [-t]

 All options (preceded with '-' character) may be specified in any sequence,
 option-letters may be in upper or lower case, and an option value may be
 concatenated to the option-letter or specified as separate item.
 When no arguments are passed to TinyBld2 it will show a few help lines.

    Option -p
    ---------
 The default serial port is COM1 for OS/2 or Windows, /dev/ttyS0 for
 Linux. When another port is used you may specify it on the commandline with
 the option '-p'. For example when you use COM8 (possibly via a USB-serial
 adapter) the command would look like:
     > tinybld2 16f886_blink -p com8
 Note: When this 'com8' gives errors under Windows, try the following notation
 (in this example for COM12):
     > tinybld2 16f886_blink -p \\.\com12

    Option -s
    ---------
 Communications between TinyBld2 and the TinyBootloader in the target PIC
 can only be established when both use the same line speed.
 When your TinyBootloader uses a different linespeed than the TinyBld2 default
 of 115200 bps, you must specify the proper speed at the commandline with
 the option '-s', for example:
     > tinybld2 16f886_blink -s 19200

    Option -r
    ---------
 RTS is normally set ON during programming. This may be used to reset the
 target PIC and requires a one-shot circuit between RTS and MCLR. The target
 will be reset and TinyBootloader will get control.
 When no contact with TinyBootloader could be made TinyBld2 will retry the
 reset by turning RTS off for a while and then on again. The retries will be
 continued for 30 seconds at most, then TinyBld2 gives up.
 TinyBld2 can control the RTS signal in several ways:
 1. Initially set RTS=ON and stay ON during programming.
    With retries set RTS=OFF for a while and then ON again (negative pulse).
 2. Initially set RTS=OFF and stay OFF during programming.
    With retries set RTS=ON for a while and then OFF again (positive pulse).
 3. Keep RTS=OFF all the time and no reset pulses.
 When you have an RTS reset circuit on your target board the choice between
 method 1 and 2 depends on the type of circuit. For an inverting circuit
 choose 1, for a non-inverting circuit choose 2. When in doubt: simply
 experiment!
 The behaviour of the RTS line can be altered with the option '-r'.
 The duration of the pulse may be specified in number of milliseconds, the
 type of pulse with its sign. A positive number results in positive pulses,
 a negative number in negative pulses. With a zero or without number no
 reset pulses are generated. Examples of specifications:
     -r -100      RTS normally ON, negative reset pulse of 100 ms (RTS=OFF)
                  (this is the default behaviour of TinyBld2).
     -r 200       RTS normally OFF, positive reset pulse (RTS=ON) of 200 ms.
     -r 0         RTS permanently OFF, no reset pulse (use manual reset).
     -r           Same as -r 0
 The default value of -100 ms has proven to work for many target boards, a
 shorter value may also work.
 You may have to experiment with longer values when TinyBld2 does not
 succeed in getting in contact with TinyBootloader in the target PIC.
 After a pulse TinyBld2 pauzes the number of milliseconds equal to the pulse
 duration before sending the contact character to TinyBootloader, This is to
 give the target time to restart. This implies that the pulse may not be
 longer than about 1000 ms, because when TinyBootloader doesn't receive the
 contact character within a second after reset it passes control to the PIC
 application.
 Note: The RTS signal levels above refer to the behaviour of the serial port
       (RS232 level). The RTS signal is generally converted to TTL level with
       a MAX232 chip or alike which also inverts polarity. In that case
       RTS=OFF is a negative voltage on the serial port, but +5V behind the
       MAX232, and RTS=ON on the serial port becomes 0V behind the MAX232.

    Option -l
    ---------
 The datatraffic between TinyBld2 and TinyBootloader may be logged by
 specifying '-l' option, optionally followed by a file specification.
 When no log file is specified the name of the hex file will be used with
 the extension 'log'. For example with:
     > tinybld2 16f886_blink -l
 A file '16f886_blink.log' will contain a formatted data transfer history.
 Note: When also no hex filename is specified there will be no logging!

    Option -e
    ---------
 Program memory of the target can be erased with the -e option. Erasing is
 normally not necessary, but could be useful to remove old code.
 The erase operation is not literally a bulk erase of all program memory,
 but a replacement of all program memory with 'FF' (exception that
 TinybootLoader is preserved and low memory is filled with a "goto
 TinyBootloader" instruction). Therefore it is a more time consuming
 operation than you might expect! Possible use:
    > tinybld2 -e

    Option -c
    ---------
 TinyBootloader for the 18F is able to program the configuration words.
 However this may have a bad influence on the working of Tiny Bootloader,
 therefore this feature is disabled by default. It maybe enabled with the
 option '-C'. When you are a_b_s_o_l_u_t_e_l_y sure that your hex file
 contains proper configuration settings, these will be transferred with:
    > tinybld2 18f2550_blink -c
 Make sure that at least no oscillator-related settings are changed!
 Since TinyBld2 transfers only configuration bytes which are not equal 0xFF,
 replace the bytes which you don't want to change by 'FF'.

    Option -q
    ---------
 Run quietly, without any console output.
 Can be useful when invoking Tinybld2 from another program such as an IDE.
 Note: When the -q option is specified Tinybld2 terminates without
 waiting for user input even after an error condition.

    Option -t
    ---------
 When Tinybld2 terminates prematurely because of an error condition it
 waits for user input to finish (press Enter to continue...).
 When the -t option is specified it terminates unconditionally without
 waiting for user input.
 Note: The -q option has a similar effect.


 Supported Platforms
 -------------------
 TinyBld2 was originally developed for eComStation (OS/2), but has been
 prepared from the beginning to be adapted to other platforms, in particular
 Linux and Windows. The OS-dependent code is concentrated in tinybld2os.c
 (and somewhat in tinybld2.h). This module has a structure for inserting
 platform-dependent code and data with selection on compile-time.
 Tinybld2 will probably work also on other platforms like Mac and FreeBSD,
 but no binary executables are delivered. Users have to build these for
 themselves from the source package.


 Requirements
 -------------
 - OS/2 Warp version 2.1, eComStation 1.0, Linux, Windows W98SE and
   more recent versions of all these.
 - Standard serial communications port (COM1, COM2, /dev/ttyS0, etc).
   or a virtual serial port, for example with USB to serial adapter.
 - A target board with MicroChip PIC and a proper serial port interface
   (like with a MAX232) and PIC capable of self-writing program memory,
   preloaded with the Tiny Bootloader.
 - A serial cable between PC and target board.
 - For JalV2 programs a compiler option must be used to generate the
   instructions in low memory required by TinyBootloader, in particular:
   + for 16F: '-long-start'
   + for 18F: '-loader18 4'
   NOTE: This is only needed when the program does not use an interrupt
         service routine.
   For other compilers and Assemblers a similar provision must be made.
   See the documentation of TinyBootloader for details.


 Limitations
 -----------
 - Only 16F and 18F are currently supported.
 - 18[L]FxxJxx series and extended midranges PICs are not supported
   (there is no TinyBootloader for these published yet!).


 Known problems
 --------------
 None.


 To Do
 -----
 - (suggestions?)


 Comments and Problem reports
 ----------------------------
 Comments and suggestions for improvements are welcome. When you have a
 problem to report, please describe as accurately as possible the symptoms,
 and hardware and software you were using.


 Rob Hamerling
 E-mail:   robhamerling@gmail.com
 homepage: http://www.robh.nl/

