UMCBuilderDocumentation

SwordfishUser.UMCBuilderDocumentation History

Hide minor edits - Show changes to output

August 21, 2011, at 12:57 PM by David Barker -
Changed line 39 from:
!!![PATH]
to:
!!!PATH
Changed line 51 from:
!!![TEMPLATE]
to:
!!!TEMPLATE
Changed line 63 from:
!!![MCU]
to:
!!!MCU
Changed line 75 from:
!!![USART]
to:
!!!USART
Changed line 87 from:
!!![CONFIG] 
to:
!!!CONFIG 
Changed line 101 from:
!!![USERCODE]
to:
!!!USERCODE
August 21, 2011, at 12:56 PM by David Barker -
Added lines 111-112:

For more USERCODE examples, please see [[UMCUserConfig | here]]
August 21, 2011, at 12:04 PM by David Barker -
August 21, 2011, at 12:04 PM by David Barker -
Changed lines 44-45 from:
!!!!Example
to:
'''Example'''
Changed lines 57-58 from:
!!!!Example
to:
'''Example'''
Changed lines 69-70 from:
!!!!Example
to:
'''Example'''
Changed lines 81-82 from:
!!!!Example
to:
'''Example'''
Changed lines 90-91 from:
!!!!Example
to:
'''Example'''
Changed lines 106-107 from:
!!!!Example
to:
'''Example'''
August 21, 2011, at 12:03 PM by David Barker -
Changed lines 1-2 from:
!!!Introduction
to:
!!Introduction
Changed lines 5-6 from:
!!!Configuration File
to:
!!Configuration File
Changed lines 29-30 from:
!!!Main Application
to:
!!Main Application
Changed lines 37-39 from:
!!!Configuration Options

!!!![PATH]
to:
!!Configuration Options

!!![PATH]
Changed line 51 from:
!!!![TEMPLATE]
to:
!!![TEMPLATE]
Changed line 63 from:
!!!![MCU]
to:
!!![MCU]
Changed line 75 from:
!!!![USART]
to:
!!![USART]
Changed line 87 from:
!!!![CONFIG] 
to:
!!![CONFIG] 
Changed line 101 from:
!!!![USERCODE]
to:
!!![USERCODE]
Changed lines 106-107 from:
!!!Example
to:
!!!!Example
August 21, 2011, at 12:01 PM by David Barker -
Changed lines 44-48 from:
Example

[PATH]
output=$app\firmware
to:
!!!!Example

 [PATH]
 output=$app\firmware
Changed lines 51-54 from:
[TEMPLATE]
PIC16=<mandatory 16F asm template file>
PIC18=<mandatory 18F asm template file>
to:
!!!![TEMPLATE]
*PIC16=<mandatory 16F asm template file>
*PIC18=<mandatory 18F asm template file>
Changed lines 57-66 from:
Example

[TEMPLATE]
PIC16=..\src\16F\umc_loader.asm
PIC18=..\src\18F\umc_loader.asm

[MCU]
Device=<mandatory device name>
OSC=<mandatory OSC frequency>
to:
!!!!Example

 [TEMPLATE]
 PIC16=..\src\16F\umc_loader.asm
 PIC18=..\src\18F\umc_loader.asm

!!!![MCU]
*Device=<mandatory device name>
*OSC=<mandatory OSC frequency>
Changed lines 69-78 from:
Example

[MCU]
Device=18F452
OSC=20000000

[USART]
BAUDRATE=<optional baudrate setting>
BRG16=<optional 0 or 1>
to:
!!!!Example

 [MCU]
 Device=18F452
 OSC=20000000

!!!![USART]
*BAUDRATE=<optional baudrate setting>
*BRG16=<optional 0 or 1>
Changed lines 81-98 from:
Example

[USART]
BAUDRATE=19200
BRG16=1

[CONFIG] 
<one or more configuration fuse settings>

Example

[CONFIG] 
config  OSC    = HS
config  PWRT    = OFF
config  WDT    = OFF
config  LVP    = OFF
config  DEBUG  = OFF
to:
!!!!Example

 [USART]
 BAUDRATE=19200
 BRG16=1

!!!![CONFIG] 
*<one or more configuration fuse settings>

!!!!Example

 [CONFIG] 
 config  OSC    = HS
 config  PWRT    = OFF
 config  WDT    = OFF
 config  LVP    = OFF
 config  DEBUG  = OFF
Changed lines 101-103 from:
[USERCODE]
<optional user code statements>
to:
!!!![USERCODE]
*<optional user code statements>
Changed lines 106-110 from:
Example

[USERCODE]
bsf ADCON1, PCFG5  ; 18F1220 example code
bsf ADCON1, PCFG6  ; 18F1220 example code
to:
!!!Example

 [USERCODE]
 bsf ADCON1, PCFG5  ; 18F1220 example code
 bsf ADCON1, PCFG6  ; 18F1220 example code
August 21, 2011, at 11:59 AM by David Barker -
Added lines 1-110:
!!!Introduction

The UMC builder application is a small utility that automates the creation of UMC loader *.hex files.

!!!Configuration File

At the centre of the builder application is the configuration file. This is a simple *.ini file which defines the essential elements needed to build a working loader *.hex file. For example:

 ; source code files...
 [TEMPLATE]
 PIC16=..\src\16F\umc_loader.asm
 PIC18=..\src\18F\umc_loader.asm

 ; device name and OSC...
 [MCU]
 Device=18F452
 OSC=20000000

 ; device configuration settings...
 [CONFIG] 
 config  OSC    = HS
 config  PWRT    = OFF
 config  WDT    = OFF
 config  LVP    = OFF
 config  DEBUG  = OFF

The above shows a working, but minimal configuration. More options are shown later in this document.

!!!Main Application

To build your loader *.hex file, simply invoke "umcbuild.exe" with the name of the *.ini file you want to use. For example,

 umcbuild.exe "c:\myfiles\config.ini"

Alternatively, if you place an *.ini file called "umcbuild.ini" in the same folder as the main application then you just need to double click on the "umcbuild.exe" application to start the build process.
 
!!!Configuration Options

!!!![PATH]
*MPASM=<optional path to mpasm>
*DB=<optional path to MPLAB device files>
*Output=<optional path to output folder>

Example

[PATH]
output=$app\firmware

will place all output files (asm, hex etc) in the folder defined by "output". If this option is not used, output files are placed in the users "documents" folder under "umcbuild". The paths to MPASM and DB are not normally needed. If you have a working MPLAB installation on your machine, the application will detect and set these paths automatically.

[TEMPLATE]
• PIC16=<mandatory 16F asm template file>
• PIC18=<mandatory 18F asm template file>

These are mandatory values and must point to one of the *.asm files supplied with the UMC loader application.

Example

[TEMPLATE]
PIC16=..\src\16F\umc_loader.asm
PIC18=..\src\18F\umc_loader.asm

[MCU]
• Device=<mandatory device name>
• OSC=<mandatory OSC frequency>

These are mandatory values are used to set the device name and oscillator frequency.

Example

[MCU]
Device=18F452
OSC=20000000

[USART]
• BAUDRATE=<optional baudrate setting>
• BRG16=<optional 0 or 1>

An optional set of values used to configure the baud rate generator. If no value is given for baudrate, 115200 is used by default for all oscillator frequencies above 20MHz. For frequencies less than 20MHz, 19200 baud is used by default. The BRG16 value defaults to OFF (0) but can be switched on in this section. Note that setting BRG16 to true (1) requires a device with a 16 bit SPBRG register (refer to your device datasheet). Additional code may also be needed to configure a device if this option is used in the USERCODE section. Unless you want to run your bootloader with low baudrates and high clock frequencies, it is usually best to leave this option switched OFF.

Example

[USART]
BAUDRATE=19200
BRG16=1

[CONFIG] 
• <one or more configuration fuse settings>

Example

[CONFIG] 
config  OSC    = HS
config  PWRT    = OFF
config  WDT    = OFF
config  LVP    = OFF
config  DEBUG  = OFF

This section is used to set you device configuration fuses. Setting device fuses is beyond the scope of this document as there is so much variation between devices. For more information on configuration fuses, you should refer to your device datasheet.
 
[USERCODE]
• <optional user code statements>

This area is used to place optional startup code. For example, some devices require their TX and RX pins be explicitly set to DIGITAL or you may need to configure your device to use its internal oscillator.

Example

[USERCODE]
bsf ADCON1, PCFG5  ; 18F1220 example code
bsf ADCON1, PCFG6  ; 18F1220 example code