Editing Bootloader Development

Developing Bootloader for the [{{SERVER}}/DsPIC30F_5011_Development_Board DsPIC30F 5011 Development Board]

==Concepts==
*Programming with ICSP (In-Circuit Self Programming) is useful when the target board is produced in batch. The producer can download a program even when the chip is on the target board.
*However, ICSP requires an external programmer (e.g. ICD2).
*To allow the user to change the program after production but without the need of an external programmer, bootloader becomes useful.
*Bootloader is a small program installed via ICSP. Every time the device is reset, the bootloader is run first. The bootloader first detects the default serial channel whether the user wishes to download a new program to the device. If so, the bootloader will pause there, and wait for the user to download the hex file from the PC. The hex file is written to the device via RTSP (Run-time Self Programming) instructions in the bootloader. If a new download is not necessary, the bootloader redirects to the previously installed user's program.
*The disadvantage of bootloaders is that they consume some of the memory of the device.


{| border="1" cellspacing="0" cellpadding="5"
|+ Free bootloaders for dsPIC
! Developer
! Source
! Platform
! User Guide
! Remarks
|- valign="top"
| [http://www.ingenia-cat.com/index.php?lang=en ingenia]
| Assembly
| Windows
| -
| 
*Works for all dsPIC supporting RTSP
*Auto baudrate detection
*Use about 1.15% of the flash memory space (0xAFFF-0xAE00)/(0xAFFF-0x0100)
*Development of Linux platform is underway
*Modification of code for dsPIC30F5011 is successful
|-valign="top"
| [http://www.etc.ugal.ro/cchiculita/software/picbootloader.htm Tiny]
| [http://www.etc.ugal.ro/cchiculita/software/tinybld191.zip Assembly]
| Windows
| [http://www.etc.ugal.ro/cchiculita/software/tinybldusage.htm Web]
| 
*By default, only supports 601X, 601X, 401X, 2010
*Smaller code size than ingenia, but not as easy to modify
|-valign="top"
| [http://www.via.si/software/dsPIC_bootloader/ Elektronika]
| [http://www.via.si/software/dsPIC_bootloader/data/ Hex]
| Windows
| [http://www.via.si/software/dsPIC_bootloader/data/README.txt txt]
| 
*Only works for dsPIC30F6014 serial port UART2 at baudrate 57600
|-
|}


==dsPicBootloader==
*The bootloader developed by ingenia was open source (unavailable now) and it has been modified to suit our development. Hereafter, the modified version is called dsPicBootloader.
*Repository for download: [http://chungyan5.no-ip.org/vc dsPicBootloader]
**Download projects: "dspic_bootloader" and "intel_hex_parser"
*Before v1.05.00, the bootloader employs the following settings:
# Use U2ART channel
# Start up using internal FRC, phase-lock-loop x16
# Watchdog timer disabled
# Clock switching disabled
# Primary oscillator disabled
# OSC2 Pin functions as digital I/O
*From v1.05.00 onwards, dsPicBootloader employs the following settings:
# Use U2ART channel
# Start up using internal FRC, phase-lock-loop x16, without auto-switching of clock source
# Watchdog timer disabled
# Clock switching enabled
# Primary oscillator enabled
*From v1.06.00 onwards, configuration registers can be overwritten.


==dsPicProgrammer (Java-based Multi-Platformed)==
*Ingenia developed a programmer (PC-side) that works only in Windows environment. The project for Linux environment is currently suspended.
*A simple programmer (hereafter called dsPicProgrammer) written in Java and based on the library developed by [http://www.rxtx.org/ RXTX] has been developed here. The programmer supports both Linux and Windows environments, and may be used as a substitution for the official programmer developed by ingenia.
*Repository for download: [http://chungyan5.no-ip.org/vc dsPicProgrammer]
**Download project: "dspicProgrammer"
*The programmer has the following specification and limitations:
#Can be used on both Linux and Windows platforms.
#Adjustable baudrate (9600bps to 115200bps<sup>[1]</sup>).
#Support programming of dsPIC30F5011, dsPIC33FJ128GP306, dsPIC33FJ256GP506<sup>[2]</sup> devices (Developers may add your devices).
#Protection against overwriting bootloader codes on devices.
#Detection if application program does not have its reset() at user's code start address.
#Reprogramming can be done without powering down the target board. By default, the target board is reset by sending a BREAK character. Users can implement their own reset algorithm by replacing the BreakReset() function.
#Target board will run the user's program after programming is done.
#Configuration registers can be changed<sup>[3]</sup>.
#Can be used with USB-Serial Cables. Below is a list of tested cable:
::[http://www.prolific.com.tw/eng/Products.asp?ID=59 Prolific PL-2303 USB to Serial Bridge Controller]: [http://www.prolific.com.tw/eng/downloads.asp?ID=31 Driver download]
::[http://www.bafo.com BAFO Technologies BF-810 USB Serial Adapter]:[http://www.bafo.com/menu-support.asp Driver download]
::[http://www.z-tek.com.cn/en/index.asp Z-TEK ZE400 USB 2.0 TO RS232 Cable]:[http://www.z-tek.com.cn/en/download.asp?driver_lei=windows Driver download]
'''NOTE:'''<br>
[1] before version 1.5.2, the baudrate bounded at 57600bps.<br>
[2] only dsPIC30 devices are compatible with the ingenia's programmer. For dsPIC33 devices, the protocol has been modified due to the increased flash size, and the dsPIC33 bootloader can only work with dsPicProgrammer.<br>
[3] before version 1.6.0, configuration registers cannot be changed.


==Special Consideration==
*The bootloader assumes that the user program starts at address 0x100 (dspic30) or 0x200 (dspic33). This is usually the case, but there are always exceptions.
*To ensure that the user program always starts at the correct address, you can create a customized linker script and customized reset() function as follows:
:*Copy and modify the file named "crt0.s" from the directory "C:\Program Files\Microchip\MPLAB C30\src\pic30" to the project directory and include it.
    .section .reset, code      //previously .section .libc, code 
:*Copy and modify the linkerscript for the device (e.g. p30f5011.gld) to the project directory and include it.
   .text __CODE_BASE :
   {
      *(.reset);              //<-insert this line here
      *(.handle);
      *(.libc) *(.libm) *(.libdsp);  /* keep together in this order */
      *(.lib*);
      *(.text);
   } >program


==Communication Protocol==

           +-------------------+             +-------------------+----------------+
           |  dsPicProgrammer  |             |  dsPicBootloader  | User's Program |
           +-------------------+             +-------------------+----------------+
           |       PC          |             |             Target dsPic           |
           +-------------------+             +------------------------------------+
           |     COM PORT      |=============|                 UART               |
           +-------------------+             +------------------------------------+

* '''Stage 1: User's Configuration'''
**Select a COM port channel
**Select a baudrate
**Select the user hex file
          java -jar dsPicProgrammer.jar COM1 19200 foo.hex
* '''Stage 2: Resetting Target Device'''
**dsPicProgrammer sends a Break character (pull UART-TX to low logic, which is normally high).
**User's program on dsPic detects the break character and reset the chip
::NOTE: The user's program is expected to have the following code in order to enable this function. Otherwise, the target board must be restarted manually.
   void _ISR _U2RXInterrupt(void)
   {
       //No Framming error
       if( U2STAbits.FERR == 0)
       {
           //Normal procedure
       }
       //Framming error
       else
       {
           if ( U2STAbits.URXDA ){
               unsigned char data;
               data = (unsigned char) U2RXREG;
               if(data == 0x00){
                   // A break char has been received: 
                   //  U2RX has been pulled to zero for more than 13 bits
                   //  This is used to reboot the pic
                   mdelay(800);    //wait for break character to clear
                   asm("reset");   //software reset
               }
           }        
       }
       _U2RXIF = 0;        //Clear the flag
   }
* '''Stage 3: Entering Ingenia's Protocol'''
** Transmission is conducted in 8N1, i.e. 8-bit, no parity, 1 stop-bit
** Communication Protocol is reviewed in [http://www.ingenia-cat.com/reference/pdf/iBL.UG.V1.2.pdf ingenia bootloader user's guide] section 2.1.3. The following summarizes the key steps on the PC side (Refer also to section 2.2.2).
:#Autobaud rate detection: dsPicProgrammer continuously sends a character "U" [0x55] via COM port and waits for an acknowledgment character "U", [ACK] = [0x55]
:#Version Control: dsPicProgrammer sends the command character [0x03]. On success, dsPicProgrammer receives 3 characters i) Major Version ii) Minor Version iii) Acknowledgment [0x55]
:#Device ID Monitoring: dsPicProgrammer sends the read command character [0x01] + 24-bit address [High][Medium][Low] (0xFF0000). Then, it receives 4-byte data [High][Medium][Low][ACK]
:#Load the user hex file and check integrity
:#Start Programming: dsPicProgrammer issues the write command character [0x02] + 24-bit address [High][Medium][Low]+ Number of bytes [High][Low] + [data 0] + [data 1] + ... + [data N-1] + [CRC]=(INTEL HEX8 Checksum - Sum modulo 256) and receives [ACK] or [NACK] = [0xFF]
:NOTE: Writing is in row mode access (i.e. erase and write a whole row, each row has 32 instructions, or 96 bytes because each instruction has 24 bits)
* '''Stage 4: Goto User's Program'''
**dsPicProgrammer sends the goto user code command [0x0F]